# 云端同步与字段覆盖检查报告

时间：2026-06-12 02:00

## 1. 云端数据库位置

云服务器：`wwyl-cloud`（`ubuntu@175.27.229.243`）

数据库服务：PostgreSQL 16，本机监听 `127.0.0.1:5432`。

本次新建独立数据库，避免污染现有良渚电商数据库：

```text
database: goods_ledger
app role: ledger_app
cloud env: /srv/goods-ledger/.env
schema: /srv/goods-ledger/schema/postgres_ledger_schema_v1.sql
import data: /srv/goods-ledger/import/normalized_v1/
```

`.env` 内含数据库连接凭证，已在云端保存，聊天中不展示。

## 2. 已同步的数据范围

### 2.1 结构化业务表

| 表 | 云端行数 | 说明 |
|---|---:|---|
| parties | 19 | 公司、供应商、客户、渠道、个人、仓库等对象 |
| projects | 2 | 国博项目、良渚项目手机贴 |
| products | 25 | 产品/SKU 主数据 |
| product_aliases | 6 | 原始商品名与标准名映射 |
| source_files | 22 | 源文件/证据文件 |
| business_documents | 14 | 合同、采购单、签收单等业务单据 |
| purchase_orders | 13 | 上游/下游采购订单单头 |
| order_lines | 42 | 订单商品明细；下游 22 行、上游 20 行 |
| channel_allocations | 80 | 渠道分配；含下游合同渠道 8 行、上游渠道 72 行 |
| inventory_accounts | 2 | 秘色破茧国博样品库、云汉寻真良渚手机贴样品库 |
| stock_items | 13 | 样品库存 SKU |
| stock_movements | 25 | 出入库流水 |
| shipment_signoffs | 1 | 云汉寻真发西泠印社签收单 |
| shipment_signoff_lines | 6 | 签收单明细 |
| reconciliation_runs | 1 | 国博供应商采购 vs 上游需求核对批次 |
| reconciliation_lines | 19 | 国博核对明细 |
| validation_issues | 15 | 上游核算问题/待确认问题 |
| import_batches | 1 | 本次导入批次 |
| agent_write_audit | 1 | 导入审计 |

### 2.2 原始行归档表

为防止字段遗漏，额外建立了：

```text
raw_import_rows
```

它把所有源 Excel/CSV 的每一行按 JSONB 归档。

| 指标 | 数量 |
|---|---:|
| raw_import_rows | 636 |
| source_label | 7 类 |
| sheet_or_table | 44 个 |

这意味着：即使某个字段暂时没有提升为结构化业务列，也已经在 `raw_import_rows.row_payload` 中保留下来，后续可以无损补映射。

## 3. 云端验证结果

已执行云端查询验证：

```text
db=goods_ledger
normalized_tables=20
raw_rows=636
source_files=22
business_documents=14
purchase_orders=13
order_lines=42
downstream_lines=22
upstream_lines=20
channel_allocations=80
stock_items=13
stock_movements=25
shipment_lines=6
reconciliation_lines=19
open_validation_issues=15
```

质量检查：

```text
channel_alloc_diff_nonzero=0
negative_current_stock=0
ledger_app_select_products=25
ledger_app_select_raw=636
```

含义：

- 渠道分配数量与订单明细数量没有发现不平。
- 当前库存没有负数。
- 应用账号 `ledger_app` 可以读取主数据和原始归档表。

## 4. 字段覆盖判断

### 4.1 已结构化覆盖的字段

已结构化覆盖这些核心业务字段：

1. **主体/对象字段**
   - 我方签约主体
   - 下游供应商/下游公司
   - 上游客户/国博
   - 采购单显示供货方
   - 渠道/收货对象/经办人

2. **项目字段**
   - 国博项目
   - 良渚项目手机贴
   - 公司主体与项目/IP 关系

3. **产品字段**
   - 标准商品名称
   - 原始商品名称
   - 规格/款式
   - 单位
   - 产品别名/原始名映射

4. **源文件字段**
   - 原始文件名
   - 项目内保存路径
   - SHA256
   - 文件大小
   - 材料类型
   - 解析状态

5. **订单字段**
   - 上游/下游方向
   - 订单/合同文件
   - 订单编号
   - 订单日期
   - 买方/卖方
   - 数量
   - 单价
   - 金额
   - 原始行 payload

6. **渠道字段**
   - 原始渠道名
   - 标准渠道名
   - 原始渠道数量
   - 调整数量
   - 调整后数量
   - 渠道合计检查

7. **库存字段**
   - 库存账户
   - 样品ID/库存 SKU
   - 入库、出库、借出、归还、礼赠等流水类型
   - 经办人
   - 去处/对象
   - 是否可退回
   - 成本字段

8. **核对字段**
   - 供应商采购累计
   - 上游需求累计
   - 正差额/自留库存候选
   - 缺口
   - 计算状态
   - 关联来源

### 4.2 全量原始字段覆盖

以下源文件/工作表/CSV 的所有字段已经进入 `raw_import_rows.row_payload`：

- 国博供应商采购补货台账初版全工作表
- 下游供应商采购表
- 国博上游采购表
- 国博 6-7 月补货调拨测算表
- 公司产品样品库全工作表
- 云汉寻真西泠签收表
- 国博 work/extraction_tables 下的所有 CSV
- 国博 docs 下的接收清单/文本提取清单 CSV
- 通用事实台账 register 空表头框架

因此从“数据归档不丢字段”的角度看，已全覆盖。

## 5. 当前还没有完全结构化提升的字段

这些字段已经原样保存在 `raw_import_rows`，但暂未全部作为一等业务列使用。建议第二轮再提升：

| 字段/信息 | 当前状态 | 建议 |
|---|---|---|
| source_cache_path / receive_status / file_exists | 原始接收清单已归档；结构化 `source_files` 主要保留长期 stored_path + hash | 如要完整追踪上传缓存链路，可新增 `file_receipts` 表 |
| supplier_contract_no_on_order | 原始采购单提取 CSV 已归档；当前未单独结构化列 | 可加到 `purchase_orders.external_contract_no` 或 `business_documents.document_no_alt` |
| settlement_method | 表结构支持 `purchase_orders.settlement_method`，但本次结构化来源主要来自清爽版上游表，部分值在 raw 中 | 后续从 `国博上游采购订单_提取.csv` 回填 |
| arrival_date_or_period / 到货时间 | 部分已进 `expected_arrival`，不同表口径需统一 | 建议统一成 `expected_arrival_text`，未来再拆日期范围 |
| 国博编码 / 商品69码 | 表结构有 `products.guobo_code` 和 `products.barcode_69`，当前这批数据源里没有稳定字段 | 等新品信息表/价格单/编码图导入后填充 |
| 签收单版式、签字栏、标题合并单元格 | raw 已归档；结构化只保留签收单头和明细 | 前端导出签收单时再单独做模板层 |
| 6-7月补货调拨测算表 | raw 已归档；结果未独立建 replenishment_plan 表 | 如果后续经常做补货预测，建议新增 `replenishment_plans` 和 `replenishment_plan_lines` |
| 通用事实台账 register 空表头 | raw 已归档；无数据行 | 后续可作为 MCP 输出兼容格式，不影响当前业务入库 |

## 6. 是否有遗漏

本轮没有发现“完全没入库”的现有数据表。处理方式如下：

- 核心业务数据已进入规范化表。
- 所有源 Excel/CSV 行已进入 `raw_import_rows`。
- 还未完全结构化的字段已列在第 5 节，不属于丢失，只是还没提升为业务列。

真正需要后续补源的数据是：

1. 国博编码、商品69码等编码字段。
2. 更完整的收发货签字/物流单号/收货确认状态。
3. 后续用户口述的申领、归还、礼赠、销售试验流水。
4. 如果要做补货计划系统，6-7月补货测算需要单独计划表。

## 7. 下一步建议

1. 确认本次 `goods_ledger` 作为货品台账系统的云端正式库。
2. 第二轮补一张 `file_receipts` 表，用来完整保存上传缓存路径、接收状态、文件存在性。
3. 从 `raw_import_rows` 回填 `settlement_method`、`supplier_contract_no_on_order`、`arrival_date_or_period`。
4. 开发后端 API 前，先固定 MCP 写入接口：不要给机器人裸 SQL 权限。
5. 前端第一版先做只读看板：上下游采购、渠道分配、库存流水、核对问题中心。