ai-contract-platform/project-docs/V2-runtime-schema-check-2026-06-28.md

AI 合同平台 V2 运行时 Schema Check 落地记录

日期：2026-06-28

背景

Phase 0 已经确认 yuqei-contract-v2-smoke 是当前 V2 dev/smoke 权威环境。Phase 1 的目标是让服务不只报告“进程活着”，还要能主动识别：

• 连错数据库。
• Alembic 迁移头落后。
• 核心表缺失。
• PostgreSQL 扩展缺失。
• staging/production 错用 SQLite。

新增能力

Contract API

新增接口：

GET /api/v1/runtime/schema-check

检查项：

• 数据库 backend 是否为 PostgreSQL。
• 当前数据库名是否为 yuqei_contract。
• contract_api_alembic_version 是否等于当前 Alembic head。
• 合同平台核心表是否存在。
• PostgreSQL 扩展 pg_trgm 是否已安装。

AI Platform API

新增接口：

GET /api/v1/runtime/schema-check

检查项：

• 数据库 backend 是否为 PostgreSQL。
• 当前数据库名是否为 yuqei_ai。
• ai_platform_alembic_version 是否等于当前 Alembic head。
• AI 平台核心表是否存在。
• PostgreSQL 扩展 pg_trgm、vector 是否已安装。

Docker Healthcheck

yuqei-infra/compose/docker-compose.yml 已将 API 容器 healthcheck 从普通 /health 升级为 schema ready：

• Contract API 检查 /api/v1/runtime/schema-check，要求 status == ok。
• AI Platform API 检查 /api/v1/runtime/schema-check，要求 status == ok。

这样 Docker 层能在迁移未跑、连错库、缺扩展时直接标记服务 unhealthy。

本地测试

已通过：

python -m pytest yuqei-contract-platform\services\contract-api\tests\test_health.py yuqei-ai-platform\services\ai-platform-api\tests\test_health.py -q

结果：

14 passed

已通过：

python -m compileall yuqei-contract-platform\services\contract-api\src\yuqei_contract_api yuqei-ai-platform\services\ai-platform-api\src\yuqei_ai_platform_api

Smoke 验证

执行部署：

.\yuqei-infra\scripts\deploy-v2-smoke-docker.ps1 -UseSshpass -AllowDirtyWorktree -KeepRemoteBackup -SkipSmoke

最新通过产物：

project-docs/qa-artifacts/v2-smoke-docker-deploy/2026-06-28T10-10-22

远端验证结果：

Contract API schema check：

status=ok
database=yuqei_contract
actual_head=20260628_0017
expected_head=20260628_0017
extensions=pg_trgm

AI Platform schema check：

status=ok
database=yuqei_ai
actual_head=20260624_0018
expected_head=20260624_0018
extensions=pg_trgm,vector

所有 smoke 核心容器均为 running / healthy：

• postgres
• redis
• minio
• contract-api
• ai-platform-api
• contract-web
• worker
• contract-review-worker

策略说明

本地/单测环境：

• SQLite 仍允许用于轻量测试。
• SQLite schema check 返回 warning，不作为正式验收依据。

staging/production 环境：

• 必须使用 PostgreSQL。
• 必须有 Alembic version table。
• 必须在当前 Alembic head。
• 必须具备核心表和必要 PostgreSQL 扩展。

当前结论

Phase 1 已完成。

系统现在可以主动识别数据库环境错误，不再只靠进程级 /health 判断服务是否可用。

下一步进入 Phase 2：后端模块化拆分，优先拆 contracts.py、AI repository.py 和两个 main.py 中的路由。