ai-contract-platform/project-docs/V2-contract-api-phase2-closeout-audit-2026-06-30.md

AI 合同平台 V2 Contract API Phase 2 收官审计

日期：2026-06-30

审计结论

Contract API 的 Phase 2 模块化拆分已经达到进入下一阶段前的收口标准：

• contracts.py 已退回兼容 facade，不再承载 SqlAlchemyContractRepository 类体。
• 生产仓储类已外置到 sqlalchemy_contract_repository.py。
• 本地 src/tests 已无 from yuqei_contract_api.contracts import ... 直接依赖。
• contracts.py.__all__ 兼容清单完整，无重复、无缺失。
• Contract API 包级编译、兼容导入检查和全量测试均通过。

Facade 审计

当前 contracts.py 状态：

__all__=261
unique=261
top_level_classes=[]
top_level_functions=[]
duplicates=[]
missing_count=0

说明：

• contracts.py 仍保留 DTO、repository、persistence helper、workflow helper 等历史公共导入面的 re-export。
• SqlAlchemyContractRepository 仍可从 yuqei_contract_api.contracts 导入，用于外部兼容。
• 新代码应优先从源模块导入，不应新增对 contracts.py facade 的内部依赖。

模块边界现状

生产仓储边界：

• sqlalchemy_contract_repository.py：生产 SQLAlchemy 仓储公开类。
• sqlalchemy_repository_wiring.py：engine、session、persistence repository、search orchestration 组装。
• sqlalchemy_query_orchestration.py：合同列表、详情、工作台、统一搜索读路径。
• sqlalchemy_seed_orchestration.py：默认数据 bootstrap 编排。
• sqlalchemy_clause_repair_orchestration.py：审查风险项条款修复编排。
• sqlalchemy_*_orchestration.py：文件、审查任务、模板、法律资产、审批、support/system/backup/transition 等子域编排。
• persistence/*：数据访问边界。
• api/*：FastAPI route 边界。
• domain.py、repository_base.py、workflow_helpers.py 等为共享领域/辅助层。

本地导入面检查：

rg "from yuqei_contract_api\\.contracts import|import yuqei_contract_api\\.contracts|yuqei_contract_api\\.contracts" src tests
=> no matches

兼容检查：

from yuqei_contract_api.sqlalchemy_contract_repository import SqlAlchemyContractRepository as Direct
from yuqei_contract_api.contracts import SqlAlchemyContractRepository as Facade
from yuqei_contract_api.repository_factory import build_contract_repository
assert Direct is Facade
assert isinstance(build_contract_repository("sqlite://", auto_create=True, seed_demo_data=False), Direct)

结果：通过。

测试覆盖清单

本次收官审计覆盖了以下测试组：

• test_contract_workflow.py：工作台、合同列表/详情、创建/更新、模板资产、条款/规则资产、模板生命周期、审批流、文件上传/预览/下载、统一搜索、AI 审查 worker、条款修复、法规变更影响、下载事件、SQLAlchemy 持久化。
• test_health.py：health、runtime config check、runtime schema check。
• test_backup.py：备份创建、列表、校验、恢复 dry-run、缺失备份。
• test_monitoring.py：trace id、健康指标、延迟指标、错误日志。
• test_audit_integrity.py：审计 hash chain、合同创建审计、完整性校验。
• test_permissions.py：角色权限矩阵和权限 API。
• test_tenant_isolation.py：租户隔离、tenant context、默认租户 fallback。
• test_legal_qa_proxy.py：legal QA proxy。

验证命令：

python -m compileall -q yuqei-contract-platform/services/contract-api/src/yuqei_contract_api
python -m pytest yuqei-contract-platform/services/contract-api/tests -q

结果：

passed

Phase 3 前置判断

可以进入 Phase 3 schema 硬化前的条件：

• 不再向 contracts.py 增加新业务逻辑。
• 新功能必须进入对应的 api/、persistence/、sqlalchemy_*_orchestration.py、domain.py 或专属服务模块。
• contracts.py 仅作为外部兼容 facade 保留。
• Phase 3 涉及数据库 schema 变更，必须先明确迁移目标库、迁移头、回滚策略和验证命令。

建议下一步：

1. 开始 Phase 3 设计评审，不直接写迁移。
2. 先输出 schema 硬化拆分清单：
   • contract_versions
   • approval_instances / approval_steps / approval_actions
   • UI 展示字段迁出策略
   • 风险项结构化
   • tenant / created_by / updated_by / deleted_at 补齐
3. 每组 schema 变更都配套 Alembic migration、空库到 head 验证、SQLite 单测兼容边界和 PostgreSQL smoke 验证。