ai-contract-platform/project-docs/V2后端基础工程与本地开发底座记录-2026-06-22.md

V2 后端基础工程与本地开发底座记录

日期：2026-06-22

1. 本轮目标

承接 V2 重构任务编排中的 T0-4 和 T0-6，先建立可运行、可测试、可部署演进的后端基础工程，避免直接进入业务页面和 AI 复杂能力开发。

2. 已完成内容

Contract API

目录：yuqei-contract-platform/services/contract-api

已建立：

• FastAPI 应用入口。
• /health 和 /api/v1/health。
• Pydantic Settings 配置加载。
• 基础日志配置。
• .env.example。
• 单元测试。
• 服务 README。

AI Platform API

目录：yuqei-ai-platform/services/ai-platform-api

已建立：

• FastAPI 应用入口。
• /health 和 /api/v1/health。
• Pydantic Settings 配置加载。
• 基础日志配置。
• .env.example。
• 单元测试。
• 服务 README。

Worker

目录：yuqei-ai-platform/services/worker

已建立：

• worker 配置加载。
• 基础日志配置。
• --health 健康输出。
• .env.example。
• 单元测试。
• 服务 README。

本地开发底座

已建立：

• 根目录 pyproject.toml，统一 pytest 入口。
• yuqei-infra/compose/docker-compose.yml。
• yuqei-infra/compose/.env.example。
• 三个服务 Dockerfile。
• docs/architecture/local-development.md。
• V2 目录相关 .gitignore 规则。

3. 验证结果

已通过：

python -m pytest

结果：

6 passed

已通过：

git diff --check

说明：

• 当前机器未安装 Docker CLI，所以本轮未执行 docker compose config 或实际容器启动。
• Docker/Compose 文件已作为开发底座提交，后续在具备 Docker 的机器或服务器上执行启动验证。

4. 当前边界

本轮只建立工程底座，不包含：

• 数据库表结构和 Alembic migration。
• AI provider 真实调用。
• 法律知识库检索。
• 合同业务 API。
• 前端 Next.js 工程。

5. 下一步建议

继续执行 T0-5：初始化前端基础工程和设计系统底座。

优先顺序：

1. yuqei-contract-platform/apps/contract-web 初始化 Next.js/React/TypeScript。
2. yuqei-contract-platform/packages/design-system 建立 tokens、主导航、页面壳、工作台布局规范。
3. 建立前端本地启动、lint、typecheck、build 命令。
4. 前端健康页对接 contract-api 的 /health。
5. 再进入 S2/S3：AI Platform MVP 和 SDK MVP。