# 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

新增接口：

```text
GET /api/v1/runtime/schema-check
```

检查项：

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

### AI Platform API

新增接口：

```text
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。

## 本地测试

已通过：

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

结果：

```text
14 passed
```

已通过：

```powershell
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 验证

执行部署：

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

最新通过产物：

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

远端验证结果：

Contract API schema check：

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

AI Platform schema check：

```text
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` 中的路由。