yuqei
a3bb78e06b
Security Quality Gate / npm audit, Bandit, pip-audit, detect-secrets (pull_request) Failing after 16m35s
146 lines
3.3 KiB
Markdown
146 lines
3.3 KiB
Markdown
# 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` 中的路由。
|