# 合同与货品进出事实台账

本项目用于记录合同、采购、销售、个人私用货品进出相关的可核验事实。目标不是先做复杂系统，而是先把事实、凭证、数量和文件位置以统一规则沉淀下来，后续再升级为数据库、检索系统或自动化录入流程。

## 当前建议

采用“三层结构”：

1. **事实台账作为权威来源**：用结构化表格/数据库记录每一条事实，例如合同、货品、批次、数量、进出方向、日期、对方、凭证路径。
2. **附件文件夹作为证据库**：合同、采购单、销售单、物流单、聊天确认、图片等只作为证据材料保存，不直接依赖文件名判断事实。
3. **RAG 只做辅助召回**：暂不把完整合同和大量流水全部放进公共 RAG。先生成一份轻量索引摘要，供机器人快速找候选，再回到台账和原文件确认。

## 为什么不建议一开始全部进 RAG

- 合同和私人货品记录可能含有敏感信息。
- 数量、金额、日期、合同编号这类事实必须精确，RAG 更适合“模糊找资料”，不适合当唯一事实来源。
- 原文合同、扫描件和流水太多会让共享 RAG 变重，也可能污染其他任务的召回结果。

更稳的做法：**台账/数据库负责准确，RAG 负责查找入口**。

## 推荐 MVP

先维护以下文件：

```text
registers/contracts.csv          # 合同主表
registers/goods_movements.csv    # 货品进出明细
registers/parties.csv            # 供应商、客户、个人相关方
registers/items.csv              # 货品基础信息
```

后续当记录量变大后，可迁移为 SQLite/PostgreSQL；字段不变，数据可导入。

## 迁移友好设计

本项目从一开始按可迁移方式设计：

- 所有核心记录都有稳定 ID：`contract_id`、`item_id`、`movement_id`、`party_id`、`movement_id`。
- CSV 只做当前轻量载体，字段定义在 `schema/` 中单独维护。
- 所有表都有 `schema_version`，当前为 `fact-ledger-v1`。
- 证据文件路径优先使用项目内相对路径，方便整包移动。
- 证据文件可记录 `source_sha256`，便于迁移后校验文件是否一致。
- RAG 索引只从正式台账导出，不把 RAG 当权威数据库。

## 项目目录

```text
README.md
rules/
  使用规则.md
  存储规则.md
  RAG策略建议.md
  小样本录入流程.md
schema/
  SCHEMA_VERSION.md
  data_dictionary.md
  migration_plan.md
  tables.json
registers/
  contracts.csv
  goods_movements.csv
  parties.csv
  items.csv
  intake_queue.csv
evidence/
  _待录入/
  contracts/
  purchase/
  sales/
  personal_use/
  logistics/
exports/
  light_rag_index_schema.jsonl
```

## 下一步

1. 先确认字段是否满足记录需求。
2. 选 3–5 份合同或进出记录做小样本录入。
3. 验证能否按“货品、合同、数量、对方、日期、用途”快速查到事实。
4. 再决定是否做 SQLite/网页表单/机器人自动录入。