# 通用货品台账系统数据库表结构设计

本项目用于沉淀国博上下游采购台账、公司样品库、发货签收表、通用合同货品事实台账的数据库结构设计，为后续前端展示、机器人 MCP 规范录入、后端二次计算服务做基础。

## 已检查的数据来源

- `/Users/bot1/Volumes/root_for_ai/AI工作区/国博_合同台账_供应商采购补货梳理_20260610_2117`
  - 下游供应商采购表
  - 国博上游采购表
  - 国博渠道需求明细
  - 供应商采购 vs 国博需求核对
  - 公司自留产品库候选
  - 文件接收清单与解析汇总
- `/Users/bot1/Volumes/root_for_ai/AI工作区/通用_公司产品样品库_秘色破茧云汉寻真_20260611_1035`
  - 公司汇总
  - 样品库存总表
  - 出入库流水
  - 国博正差额来源
  - 云汉手机贴处理
- `/Users/bot1/Volumes/root_for_ai/AI工作区/良渚_云汉寻真_3D悬浮手机贴西泠发货签收_20260611_0919`
  - 西泠签收单
  - 内部成本核对
- `/Users/bot1/Volumes/root_for_ai/AI工作区/通用_合同货品记录_事实台账_20260610_1700/registers`
  - 当前为空表头框架，可作为迁移方向参考

## 交付文件

- `docs/表结构设计_v1.md`：业务表结构说明、字段口径、MCP/后端建议
- `schema/postgres_ledger_schema_v1.sql`：PostgreSQL DDL 草案

## 当前设计结论

系统采用“证据文件 → 业务单据 → 单据明细 → 渠道分配 → 库存流水 → 计算快照”的结构。

核心原则：

1. 原始文件和解析证据单独存，不把 Excel 文件名、缓存路径散落到所有业务表。
2. 上游需求、下游采购、补充需求都统一落到 `purchase_orders` + `order_lines`，用 `order_side` 和 `order_type` 区分。
3. 渠道数量单独落到 `channel_allocations`，不固定死在“天猫/京东/抖音/馆内”四列，后续新增渠道不用改表。
4. 样品库和库存不直接改当前余额，全部通过 `stock_movements` 追加流水，再用视图计算当前库存。
5. 供应商采购 vs 国博需求、自留库存、缺口等属于计算结果，落到 `reconciliation_runs` / `reconciliation_lines`，保留每次计算快照。
6. 机器人 MCP 写入必须走受控工具接口，写入前先校验必填字段、来源证据、数量平衡和渠道合计。