AI合同平台

当前状态：V1.1 可运行试点版（非“仅骨架”）。

当前仓库已经具备可运行的前后端主链路，并且核心模块已有后端回归测试与前端构建验证，不再是初始脚手架阶段。

当前能力范围（代码已具备）

• 认证：登录、注册、当前用户
• 合同审查：创建审查（文本/文件）、列表、详情、报告下载
• Chat 审查助手：SSE 流式对话、review context 联动
• 知识库：知识库与文档管理、生命周期字段（含失败原因/下一步动作）
• 合同生成：模板变量填充、生成、历史与详情
• 管理后台：用户、规则、模板、文件、租户设置、审计日志
• 权限语义基线：关键 API 已补 ROUTE_PERMISSION_SCOPE / ROUTE_PERMISSION_ACTIONS

当前验证口径

当前文档统一按三层理解：

1. 已形成闭环：已通过浏览器或联调实际走通
2. 已验证页面/数据加载：页面可打开、列表可加载，但未全部做动作级 CRUD 验收
3. 待继续动作级验证：代码已具备基础能力，但仍需继续做更细的交互和异常路径验证

当前已形成闭环

• 登录 / 登录态恢复 / 进入首页工作台
• 合同审查：发起审查 → 审查详情 → 结果展示 → 报告信息加载
• Review → Chat：从审查详情带上下文进入问答并返回回答
• 合同生成：模板选择 → 变量填写 → 预览 → 生成 → 历史 → 详情 → 文件资产联动
• 知识库创建
• 租户设置更新
• 审计日志加载

当前已验证页面/数据加载

• 用户管理
• 规则管理
• 模板管理
• 文件管理

本地目录

frontend/
backend/
database/
infra/
scripts/
docs/
project-docs/

启动前准备

1. 本地依赖（如需要）

docker compose up -d

2. 后端虚拟环境

cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. 数据库迁移

当前后端依赖 Alembic migration 与最新 schema 保持一致，尤其包括：

• backend/migrations/versions/20260423_0014_add_error_message_to_knowledge_base_documents.py

执行方式：

cd backend
PYTHONPATH="/Users/yuqei/Documents/ai-contract-platform/backend" .venv/bin/alembic upgrade head

启动后端（FastAPI）

cd backend
source .venv/bin/activate
PYTHONPATH="/Users/yuqei/Documents/ai-contract-platform/backend" uvicorn app.main:app --host 0.0.0.0 --port 8000

默认地址：http://127.0.0.1:8000

启动前端（Next.js）

开发模式

cd frontend
npm install
npm run dev

生产模式（推荐用于联调 / 浏览器验收）

cd frontend
npm install
npm run build
npm run start -- --hostname 0.0.0.0 --port 3003

推荐入口：

http://127.0.0.1:3003/login

服务器 Docker 运行（当前推荐）

已确认 Docker 与 Git 在服务器：192.168.3.90。

当前更推荐直接在服务器上使用 Docker 方式运行整套环境，而不是继续依赖本机 dev 运行态。

推荐入口：

http://192.168.3.90:3003/login

推荐方式：

docker compose -f docker-compose.yml up -d --build

说明：

• frontend 暴露端口：3003
• backend 暴露端口：8001
• MinIO endpoint 已在 compose 中指向：192.168.3.90:9000
• 浏览器验收优先使用服务器生产模式入口，不建议再以本地 dev/HMR 结果作为最终验收口径

## 已验证覆盖（当前基线）

### 后端测试已覆盖模块

- auth：`test_auth_api.py`、`test_auth_service.py`
- reviews：`test_reviews_api.py`、`test_review_service.py`、`test_review_service_rules.py`
- chat/rag：`test_chat_api.py`、`test_rag_service.py`
- knowledge bases：`test_knowledge_bases_api.py`
- contracts：`test_contracts_api.py`
- files：`test_files_api.py`
- users：`test_users_api.py`
- review rules：`test_review_rules_api.py`、`test_review_rule_service.py`
- templates：`test_templates_api.py`、`test_template_service.py`
- tenant settings：`test_tenant_settings_api.py`
- audit logs：`test_audit_logs_api.py`、`test_audit_log_service.py`
- permission metadata：`test_permission_metadata.py`

### 前端验证

- `npm -C frontend run build` 可通过
- 推荐使用生产模式页面进行浏览器验收，避免 dev/HMR 干扰

## 说明

更完整的状态口径请查看：

- `project-docs/当前统一需求基线-2026-04-21.md`
- `project-docs/当前进度报告-2026-04-22.md`
- `project-docs/交付差距报告-2026-04-22.md`
- `project-docs/当前闭环与页面验证清单-2026-04-23.md`