# V2 Contract API 持久化仓储闭环记录

日期：2026-06-23

## 本轮目标

按照《AI 合同平台 V2 重构版开发方案》的合同产品平台路线，把 Contract API 的合同列表、合同详情、工作台待办、审批时间线从内存数据推进到可持久化 SQL 仓储。

本轮不扩展前端流程，不改动接口返回结构，优先保证已经接入的“待我处理 / 下一步操作 / 合同详情”可以从稳定数据底座读取。

## 已完成

- 新增 SQLAlchemy 合同仓储，支持 SQLite 和 PostgreSQL 数据库 URL。
- 新增 `contracts` 表，保存合同基础信息、状态、下一步动作、正文摘要、下一步动作列表。
- 新增 `approval_timeline_items` 表，保存合同审批时间线。
- `create_app()` 已从默认内存仓储切换为 SQLAlchemy 仓储，并保留测试注入能力。
- 本地默认使用 SQLite：`sqlite+pysqlite:///.runtime/contract-api.sqlite3`。
- 生产可通过环境变量切换 PostgreSQL。
- 新增 Alembic 迁移：`20260623_0001_create_contract_workflow_tables.py`。
- 开发环境保留 seed demo data，用于当前 V2 前端主流程演示；生产建议关闭。

## 生产配置建议

```powershell
CONTRACT_API_DATABASE_URL=postgresql+psycopg://contract:contract@localhost:5432/yuqei_contract
CONTRACT_API_DATABASE_AUTO_CREATE=false
CONTRACT_API_SEED_DEMO_DATA=false
```

正式环境不要依赖自动建表，应先执行：

```powershell
cd yuqei-contract-platform/services/contract-api
python -m alembic upgrade head
```

## 验证结果

- `python -m pytest yuqei-contract-platform\services\contract-api\tests -q`：8 passed。
- `python -m compileall -q yuqei-contract-platform\services\contract-api\src`：通过。
- `python -m alembic upgrade head`：SQLite 本地迁移通过。

## 仍需继续

下一轮可以继续把 Contract API 从“读取真实业务状态”推进到“写入真实业务状态”：

- 新增合同草稿创建 / 更新接口。
- 新增提交审批、退回后重提接口。
- 新增审批处理接口，写入审批时间线。
- 前端工作台和合同详情的主动作按钮从只读状态切到调用真实写接口。