# AI合同平台

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

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

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

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

## 当前验证口径

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

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

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

### 当前已验证页面/数据加载
- 用户管理
- 规则管理
- 模板管理
- 文件管理

## 本地目录

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

## 启动前准备

### 1. 本地依赖（如需要）

```bash
docker compose up -d
```

### 2. 后端虚拟环境

```bash
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`

执行方式：

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

## 启动后端（FastAPI）

```bash
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）

### 开发模式

```bash
cd frontend
npm install
npm run dev
```

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

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

推荐入口：

```text
http://127.0.0.1:3003/login
```

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

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

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

推荐入口：

```text
http://192.168.3.90:3003/login
```

推荐方式：

```bash
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`