# 通用货品台账系统表结构设计 v1

更新时间：2026-06-12 01:34

## 1. 现场检查到的现有表单结构

### 1.1 国博上下游采购与补货台账

项目路径：

```text
/Users/bot1/Volumes/root_for_ai/AI工作区/国博_合同台账_供应商采购补货梳理_20260610_2117
```

已检查到的关键数据：

| 表单/工作表 | 数据行 | 主要字段 |
|---|---:|---|
| 合同基础信息 | 11 | contract_file, signing_entity, supplier, contract_date, document_type |
| 产品采购明细 | 17 | signing_entity, supplier, contract_date, product_name_raw, unit_price, unit, purchase_quantity, subtotal, material, product_name_standard_draft |
| 产品累计采购汇总 | 15 | product_name_standard_draft, total_purchase_quantity_draft, signing_entities, suppliers, contract_files |
| 下游供应商采购表 | 22 | 下游公司, 我方签约主体, 合同日期, 商品名称, 原始商品名称, 采购数量, 单位, 采购单价, 采购金额小计 |
| 国博上游采购订单 | 19 | source_file, order_no, order_date, upstream_customer, purchase_order_supplier_name, product_name_raw, unit, order_quantity, unit_price_to_guobo, amount_to_guobo |
| 国博上游采购表 | 20 | 上游公司/客户, 采购单显示供货方, 采购单文件, 商品名称, 单品采购总量, 国博采购单价, 馆内/线下, 天猫, 京东, 抖音, 渠道合计 |
| 国博渠道需求明细 | 71 | source_file, order_no, order_date, product_name_raw, raw_channel, standard_channel, original_order_channel_quantity, adjusted_channel_quantity |
| 供应商采购 vs 国博需求核对 | 19 | supplier_purchase_quantity_total, guobo_total_demand_quantity, difference_supplier_minus_guobo, self_stock_candidate_qty, shortage_qty |
| 公司自留产品库候选 | 7 | product_name_standard_draft, our_signing_entity, supplier, inbound_quantity, claimed_or_gifted_quantity, remaining_quantity |
| 上游核算问题清单 | 15 | 问题类型, 产品, 数量, 说明 |

关键数量核对：

| 指标 | 当前值 |
|---|---:|
| 国博上游采购订单 | 4 份 |
| 上游订单明细行 | 19 条 |
| 上游订单累计数量 | 12,670 |
| 上游订单累计金额 | 374,148 元 |
| 渠道分配明细 | 71 条 |
| 供应商采购不足/待补 | 4 款，缺口合计 1,750 |
| 公司自留库存候选 | 7 款，候选数量合计 1,450 |

### 1.2 公司产品样品库

项目路径：

```text
/Users/bot1/Volumes/root_for_ai/AI工作区/通用_公司产品样品库_秘色破茧云汉寻真_20260611_1035
```

| 工作表 | 数据行 | 主要字段 |
|---|---:|---|
| 公司汇总 | 3 | 公司主体, 项目/IP, SKU数, 入库总数, 累计出库数, 当前库存数, 已核算库存成本 |
| 样品库存总表 | 13 | 样品ID, 公司主体, 项目/IP, 产品名称, 规格/款式, 单位, 入库数量, 累计出库数量, 当前库存数量, 单位成本含税, 来源文件 |
| 出入库流水 | 25 | 流水ID, 日期, 公司主体, 项目/IP, 样品ID, 产品名称, 方向, 数量, 出库人/经办人, 去处/对象, 用途/场景, 是否可退回 |
| 国博正差额来源 | 7 | 产品名称, 供应商采购量, 国博累计需求量, 正差额/样品数, 原始签约主体, 供应商, 来源合同, 国博来源 |
| 云汉手机贴处理 | 7 | 款式, 采购入库, 发西泠印社, 钱丽云暂领试销, 当前库存, 单件成本含税, 当前库存成本 |

### 1.3 云汉寻真发货签收

项目路径：

```text
/Users/bot1/Volumes/root_for_ai/AI工作区/良渚_云汉寻真_3D悬浮手机贴西泠发货签收_20260611_0919
```

| 工作表 | 数据行 | 主要字段 |
|---|---:|---|
| 西泠签收单 | 12 | 发货方, 收货/销售方, 发货日期, 产品明细, 数量, 签收栏 |
| 内部成本核对 | 8 | 项目, 公司主体, 产品名称/图案, 入库数量, 单件成本, 本次发出数量, 发出后剩余数量 |

## 2. 业务对象拆分

建议按以下业务对象建模：

1. **组织/对象**：我方公司、供应商、上游客户、渠道、仓库、收货方、申领人。
2. **项目/IP**：国博项目、良渚项目、云汉寻真手机贴等。
3. **产品/SKU**：标准商品名、原始商品名、别名、规格、单位。
4. **源文件/证据**：上传文件、合同、采购单、签收表、Excel 台账，保存路径和 hash。
5. **业务单据**：供应商采购合同、国博上游采购订单、补充需求、签收/发货单。
6. **单据明细**：每个商品的数量、单价、金额、到货期、状态。
7. **渠道分配**：馆内/线下、天猫、京东、抖音、西泠印社等渠道数量。
8. **库存账户**：公司主体 + 项目/IP + 库存类型。
9. **库存流水**：入库、出库、借出、归还、礼赠、调拨、报废。
10. **计算快照**：供应商采购 vs 上游需求、缺口、自留库存候选、渠道合计差异。
11. **机器人写入审计**：MCP 写入批次、字段校验问题、人工确认状态。

## 3. 推荐主表

### 3.1 `parties`：组织/对象表

用于统一保存公司、供应商、客户、渠道、仓库、个人等对象。

| 字段 | 类型 | 说明 |
|---|---|---|
| id | uuid | 主键 |
| party_code | text | 稳定编码，如 PT-2026-0001 |
| display_name | text | 名称 |
| party_type | text | own_company, supplier, customer, channel, warehouse, person, platform |
| legal_name | text | 法定/完整名称 |
| short_name | text | 简称 |
| contact_masked | text | 脱敏联系方式 |
| notes | text | 备注 |

### 3.2 `projects`：项目/IP 表

| 字段 | 类型 | 说明 |
|---|---|---|
| id | uuid | 主键 |
| project_code | text | 项目编码 |
| name | text | 项目名称 |
| ip_name | text | IP 或业务线，如 国博、良渚 |
| owner_party_id | uuid | 管理主体，如秘色破茧、云汉寻真 |
| status | text | active, archived, paused |

### 3.3 `products`：产品/SKU 主数据

| 字段 | 类型 | 说明 |
|---|---|---|
| id | uuid | 主键 |
| sku_code | text | 内部 SKU 编码 |
| standard_name | text | 标准商品名称 |
| raw_name_default | text | 默认原始名称 |
| category | text | 品类 |
| spec | text | 规格/款式 |
| default_unit | text | 默认单位 |
| barcode_69 | text | 69码，可为空 |
| guobo_code | text | 国博编码，可为空 |
| status | text | active, inactive, draft |

### 3.4 `product_aliases`：产品别名表

用于处理“原始商品名称”和“标准商品名称草案”的关系。

| 字段 | 类型 | 说明 |
|---|---|---|
| product_id | uuid | 产品 |
| alias_name | text | 原始名/别名 |
| alias_type | text | raw_name, spoken_name, sheet_name, old_name |
| source_file_id | uuid | 来源证据 |
| confidence | numeric | 置信度 |
| verification_status | text | pending, confirmed, rejected |

### 3.5 `source_files`：源文件/证据表

对应现有的文件接收清单、上游订单接收清单、文本提取清单。

| 字段 | 类型 | 说明 |
|---|---|---|
| id | uuid | 主键 |
| original_filename | text | 原始文件名 |
| stored_path | text | 项目内保存路径 |
| source_cache_path | text | 上传缓存路径，可为空 |
| sha256 | text | 文件 hash |
| byte_size | bigint | 文件大小 |
| mime_type | text | 文件类型 |
| material_type | text | contract, purchase_order, shipment_signoff, ledger, extraction_csv |
| received_at | timestamptz | 接收时间 |
| extraction_status | text | pending, parsed, failed, skipped |

### 3.6 `business_documents`：业务单据表

统一保存合同、订单、补充需求、签收单等文件级业务单据。

| 字段 | 类型 | 说明 |
|---|---|---|
| id | uuid | 主键 |
| document_code | text | 业务单据编号 |
| document_type | text | supplier_contract, upstream_purchase_order, supplemental_demand, shipment_signoff, internal_ledger |
| source_file_id | uuid | 源文件 |
| project_id | uuid | 项目/IP |
| own_party_id | uuid | 我方主体 |
| counterparty_id | uuid | 对方主体 |
| document_no | text | 合同号/采购单号 |
| document_date | date | 单据日期 |
| status | text | draft, confirmed, superseded |
| raw_payload | jsonb | 原始解析结果 |

### 3.7 `purchase_orders`：采购/需求单头表

用于把上游国博采购订单、下游供应商采购、用户补充无单需求统一起来。

| 字段 | 类型 | 说明 |
|---|---|---|
| id | uuid | 主键 |
| order_code | text | 内部订单编码 |
| document_id | uuid | 对应业务单据 |
| project_id | uuid | 项目 |
| order_side | text | downstream_supplier_purchase, upstream_customer_order, internal_transfer, supplemental_demand |
| order_type | text | formal_order, contract_order, no_document_supplement, replenishment |
| buyer_party_id | uuid | 买方 |
| seller_party_id | uuid | 卖方/供货方 |
| order_no | text | 外部订单号 |
| order_date | date | 订单日期 |
| settlement_method | text | 结算方式 |
| expected_arrival | text | 到货时间/周期 |
| status | text | draft, confirmed, cancelled |

### 3.8 `order_lines`：订单明细表

| 字段 | 类型 | 说明 |
|---|---|---|
| id | uuid | 主键 |
| order_id | uuid | 单头 |
| line_no | integer | 行号 |
| product_id | uuid | 标准产品，可为空待确认 |
| product_name_raw | text | 原始名称 |
| product_name_standard_draft | text | 标准名草案 |
| quantity | numeric | 数量 |
| unit | text | 单位 |
| unit_price | numeric | 单价 |
| amount | numeric | 金额 |
| material | text | 材质/工艺 |
| evidence_note | text | 来源页/表位置 |
| verification_status | text | pending, confirmed, conflict |
| raw_payload | jsonb | 原始行数据 |

### 3.9 `channel_allocations`：渠道分配表

不要把渠道固定成列。国博现在有馆内/线下、天猫、京东、抖音，后续还会有西泠印社、其他线下销售方。

| 字段 | 类型 | 说明 |
|---|---|---|
| id | uuid | 主键 |
| order_line_id | uuid | 订单明细 |
| channel_party_id | uuid | 渠道对象，可为空 |
| raw_channel | text | 原始渠道名 |
| standard_channel | text | 标准渠道名 |
| original_quantity | numeric | 原单渠道数量 |
| adjustment_quantity | numeric | 调整数量 |
| adjusted_quantity | numeric | 调整后数量 |
| adjustment_reason | text | 调整原因 |
| evidence_note | text | 证据说明 |

### 3.10 `inventory_accounts`：库存账户表

按公司主体、项目、库存类型拆账户。

| 字段 | 类型 | 说明 |
|---|---|---|
| id | uuid | 主键 |
| account_code | text | 库存账户编码 |
| owner_party_id | uuid | 公司主体 |
| project_id | uuid | 项目 |
| account_type | text | sample_stock, sellable_stock, gift_stock, returnable_claim |
| warehouse_party_id | uuid | 仓库/保管对象，可为空 |
| status | text | active, closed |

### 3.11 `stock_items`：库存 SKU 表

对应样品库存总表中的“样品ID”。

| 字段 | 类型 | 说明 |
|---|---|---|
| id | uuid | 主键 |
| stock_item_code | text | 样品ID/库存 SKU 编码 |
| inventory_account_id | uuid | 库存账户 |
| product_id | uuid | 产品 |
| display_name | text | 库存显示名 |
| spec | text | 规格/款式 |
| unit | text | 单位 |
| unit_cost_tax_included | numeric | 含税单位成本 |
| source_policy | text | 来源口径 |
| status | text | active, inactive |

### 3.12 `stock_movements`：库存流水表

所有入库、出库、借出、归还、礼赠、调拨都追加流水，不直接改当前库存。

| 字段 | 类型 | 说明 |
|---|---|---|
| id | uuid | 主键 |
| movement_code | text | 流水编码 |
| stock_item_id | uuid | 库存 SKU |
| movement_date | date | 日期 |
| direction | text | in, out |
| movement_type | text | purchase_in, self_stock_in, shipment_out, claim_out, return_in, gift_out, transfer_out, transfer_in, adjustment |
| quantity | numeric | 正数数量 |
| unit | text | 单位 |
| handler_party_id | uuid | 经办/出库人 |
| counterparty_id | uuid | 去处/对象 |
| purpose | text | 用途/场景 |
| returnable | boolean | 是否可退回 |
| unit_cost_tax_included | numeric | 流水成本单价 |
| source_document_id | uuid | 来源单据 |
| evidence_file_id | uuid | 证据文件 |
| notes | text | 备注 |

### 3.13 `shipment_signoffs` / `shipment_signoff_lines`：发货签收表

用于前端生成签收单，也用于库存出库证据。

| 表 | 说明 |
|---|---|
| shipment_signoffs | 签收单头：发货方、收货方、发货日期、项目、用途、状态 |
| shipment_signoff_lines | 签收明细：产品、数量、单位、签收状态、关联库存流水 |

### 3.14 `reconciliation_runs` / `reconciliation_lines`：计算快照

用于保存供应商采购 vs 国博需求、自留库存、缺口等二次计算结果。

| 表 | 说明 |
|---|---|
| reconciliation_runs | 一次计算任务的元数据：计算类型、口径、输入范围、运行时间 |
| reconciliation_lines | 每个产品的计算结果：供应商采购量、上游需求量、差额、自留候选、缺口、状态 |

### 3.15 `validation_issues`：字段校验/待确认问题

机器人 MCP、导入脚本、后端计算都把不确定或冲突写到这里。

| 字段 | 类型 | 说明 |
|---|---|---|
| id | uuid | 主键 |
| issue_type | text | missing_field, conflict, quantity_mismatch, channel_mismatch, duplicate_file |
| severity | text | info, warning, error |
| related_table | text | 关联表 |
| related_id | uuid | 关联记录 |
| field_name | text | 字段名 |
| message | text | 问题说明 |
| status | text | open, resolved, ignored |

### 3.16 `agent_write_audit`：机器人写入审计

MCP 写库时必须留下审计记录。

| 字段 | 类型 | 说明 |
|---|---|---|
| id | uuid | 主键 |
| agent_profile | text | 机器人/profile |
| tool_name | text | MCP 工具名 |
| operation | text | create, update, import, compute |
| target_table | text | 目标表 |
| target_id | uuid | 目标记录 |
| request_payload | jsonb | 脱敏后的请求 |
| result_status | text | success, failed, needs_review |
| created_at | timestamptz | 时间 |

## 4. 关键关系

```text
parties 1---N projects
projects 1---N business_documents
source_files 1---N business_documents
business_documents 1---N purchase_orders
purchase_orders 1---N order_lines
order_lines 1---N channel_allocations
projects + parties 1---N inventory_accounts
inventory_accounts 1---N stock_items
stock_items 1---N stock_movements
purchase/order/stock 数据 N---N reconciliation_runs，通过 reconciliation_lines 保存快照
```

## 5. 现有表单到数据库映射

| 现有表单 | 建议落表 |
|---|---|
| 合同接收清单、国博上游订单接收清单、文本提取清单 | `source_files` |
| 合同基础信息 | `business_documents`, `purchase_orders`, `parties` |
| 产品采购明细、下游供应商采购表 | `purchase_orders(order_side=downstream_supplier_purchase)`, `order_lines` |
| 国博上游采购订单、国博上游采购表 | `purchase_orders(order_side=upstream_customer_order)`, `order_lines`, `channel_allocations` |
| 用户口述的无单补货需求 | `purchase_orders(order_side=supplemental_demand, order_type=no_document_supplement)`, `order_lines` |
| 国博渠道需求明细 | `channel_allocations` |
| 供应商采购 vs 国博需求核对 | `reconciliation_runs`, `reconciliation_lines` |
| 公司自留产品库、样品库存总表 | `inventory_accounts`, `stock_items`, `stock_movements` |
| 出入库流水 | `stock_movements` |
| 西泠签收单 | `shipment_signoffs`, `shipment_signoff_lines`, `stock_movements` |
| 上游核算问题清单、待补充事项 | `validation_issues` |

## 6. 前端页面建议

第一版前端建议分 6 个页面：

1. **源文件/导入中心**：查看文件接收、解析状态、hash、来源路径、待处理问题。
2. **上下游采购台账**：按项目、主体、供应商、产品、订单日期查看上下游订单和合同。
3. **渠道分配视图**：按产品查看馆内/线下、天猫、京东、抖音等渠道数量。
4. **样品/库存库**：按公司主体和项目查看当前库存，由库存流水实时计算。
5. **出入库/签收单**：创建签收单、登记出库、登记归还、礼赠、调拨。
6. **核对与问题中心**：查看缺口、自留库存候选、渠道合计不平、主体冲突、待确认字段。

## 7. MCP 工具建议

MCP 不建议直接暴露任意 SQL 写入。建议暴露稳定业务工具：

| MCP 工具 | 作用 |
|---|---|
| `register_source_file` | 登记源文件和 hash |
| `upsert_party` | 创建/匹配公司、供应商、渠道、个人 |
| `upsert_product_alias` | 登记产品标准名和原始名映射 |
| `create_purchase_order` | 创建上游/下游/补充需求单头 |
| `add_order_line` | 添加订单明细，校验数量、单位、金额 |
| `add_channel_allocation` | 添加渠道分配，校验渠道合计 |
| `create_stock_item` | 建库存 SKU |
| `add_stock_movement` | 登记入库/出库/借出/归还/礼赠等流水 |
| `create_shipment_signoff` | 生成签收单头和明细 |
| `run_reconciliation` | 运行供应商采购 vs 上游需求核对 |
| `list_validation_issues` | 查询待确认/冲突问题 |

MCP 写入前必须校验：

- `source_file_id` 或明确的人工输入证据不可缺。
- 产品名未确认时允许写 `product_name_standard_draft`，但 `verification_status` 必须是 `pending`。
- 渠道分配合计必须等于对应订单明细数量；不等时写 `validation_issues`，不要静默修正。
- 库存出库不能让库存小于 0，除非显式创建 `negative_stock_override` 审计记录。
- 所有写入都记录到 `agent_write_audit`。

## 8. 二次计算建议

第一批后端计算接口：

1. `supplier_purchase_totals(project_id)`：按产品汇总下游供应商采购量。
2. `upstream_demand_totals(project_id)`：按产品汇总国博/上游采购需求，含无单补充需求。
3. `channel_distribution(project_id)`：按产品和渠道汇总需求数量。
4. `supplier_vs_demand_reconciliation(project_id)`：计算差额、缺口、自留库存候选。
5. `current_stock(account_id)`：由 `stock_movements` 计算当前库存。
6. `stock_ledger(product_id/account_id)`：按产品/公司查看流水明细。

## 9. 当前 v1 边界

- 不直接迁移原始 Excel 文件，只先建立可迁移结构。
- 金额字段只做业务统计，不替代财务/税务系统。
- `source_cache_path` 是机器人缓存路径，后续可保留但不应作为长期唯一证据路径；长期以项目内 `stored_path` + `sha256` 为准。
- 当前国博“我方主体”有历史混合情况，数据库必须保留原始签约主体，不要只覆盖成一个主体。
- 样品库当前库存应由流水计算，现有 Excel 的“当前库存数量”只能作为迁移初始校验值。