ai-contract-platform/project-docs/V2-production-infrastructure-provider-acceptance-2026-07-16.md

# AI 合同平台 V2 生产基础设施与真实 Provider 验收

日期：2026-07-16

## 本片边界

本片只准备生产基础设施并建立真实模型验收门，不部署生产数据、不启动 production compose、不修改 DNS、不切换阿里云前端流量。

## 已实现

1. 新增 backend-only production compose override：应用镜像必须使用 digest，生产卷名稳定，Contract Web 默认不在 3.90 启动。
2. PostgreSQL、Redis、MinIO、Contract API、AI Platform API 的宿主端口在生产只绑定 `127.0.0.1`。
3. 新增 HTTPS Nginx edge，统一提供 `/contract/` 和 `/ai/`，并覆盖客户端伪造的 `X-Forwarded-For`。
4. Provider key 使用 Docker secret 文件；secret ref 新增受限 `file://`，只允许读取配置的 `/run/secrets` 根目录。
5. `env:` secret ref 只允许 AI Provider/OCR 专用变量前缀，不能再读取数据库连接等任意进程环境变量。
6. 新增只读 production preflight，阻断 smoke/test 库、demo seed、fallback、公开内部端口、默认口令、可变镜像和缺失备份/TLS/Provider secret。
7. 新增 PostgreSQL、合同文件、MinIO 备份脚本和 SHA-256 manifest。
8. 新增只读完整性校验和一次性 `yuqei_restore_check_*` 数据库恢复演练。
9. 新增最小生产健康探针和 systemd timer，覆盖 schema、Provider、worker、备份新鲜度和磁盘水位。
10. 新增真实 Provider 验收脚本，覆盖 V1 Phase13 的 10 条法律问答和 8 条合同审查样本。
11. Web AI 管理代理增加服务端角色门禁：模型、Prompt、runtime 仅 `admin`；知识库、质量和 Trace 仅 `admin/legal`，普通已登录用户直接调用返回 `403`。

## Provider 验收判定

脚本 `yuqei-infra/scripts/run-ai-provider-acceptance.py` 分开输出：

- `failed`：Provider 调用失败、出现 fallback、输出为空、缺引用、未命中任何预期法律来源或审查严重度低于样本边界。
- `needs_legal_review`：技术调用全部成功，但样本尚未由具名法务复核并标记 `production_ready=true`。
- `passed`：技术门通过，且全部运行样本均已有具名法务签批。

当前 Phase13 清单仍是 `LEGAL_REVIEW`、`production_ready=false`，因此即使真实模型技术调用全绿，也只能进入 `needs_legal_review`，不能自动解除生产阻断。

模板生成和条款推荐当前是模板/发布快照/规则驱动的确定性链路，不调用模型；本轮真实 Provider 验收只覆盖运行时确实调用模型的法律问答和审查摘要。合同审查的结构化风险项仍由规则层生成，Provider 当前只参与摘要。上线文案不能把确定性能力描述为模型生成；如未来改为模型结构化风险抽取，需要新增独立 JSON schema、幻觉和风险召回验收。

运行命令：

```bash
# 1. 共享预发布收集技术包，不登记 acceptance_run_id
python3 yuqei-infra/scripts/run-ai-provider-acceptance.py \
  --mode collect \
  --base-url https://<shared-staging-domain>/ai \
  --service-key-file /etc/yuqei/secrets/ai-platform-service-key \
  --tenant-id default \
  --review-package-file /protected/provider-technical-review-package.json

# 2. 具名法务签署精确技术包后，验签、核验共享证据并登记/签发 receipt v2
python3 yuqei-infra/scripts/run-ai-provider-acceptance.py \
  --mode finalize \
  --base-url https://<shared-staging-domain>/ai \
  --service-key-file /etc/yuqei/secrets/ai-platform-service-key \
  --tenant-id default \
  --review-package-file /protected/provider-technical-review-package.json \
  --legal-approval-file /protected/named-legal-approval.json \
  --legal-keyring-file /protected/legal-trusted-keyring.json \
  --receipt-private-key-file /protected/provider-receipt-ed25519.pem \
  --receipt-key-id provider-acceptance-2026q3 \
  --target-release-id v2.0.0-rc.1 \
  --target-image-digest sha256:<64-hex-image-digest> \
  --receipt-output /release/provider-acceptance-receipt.json \
  --promotion-bundle-output /release/provider-promotion-bundle.json
```

报告默认写入 `.runtime/v2-ai-provider-acceptance/<timestamp>`，不记录 Provider key。只有显式提供覆盖 10 条问答、8 条审查和 10 张知识卡的结构化具名法务审批文件，并由具名法务 Ed25519 私钥对规范化技术包签署、由共享预发布受信 keyring 验签，且服务端重新读取共享证据并校验真实内容 hash 时，工具才向启用服务鉴权与 SQLAlchemy 持久化的共享预发布接口登记完整验收清单并返回真实 `acceptance_run_id`；通用 service key 或旧 HMAC 不能替代法务证明，否则保持 `needs_legal_review` 且不登记 ID。

## 当前状态（2026-08-11 更新）

1. `192.168.3.90` 的共享预发布已部署至 Alembic `20260810_0025`；AI Platform 使用真实动态 Provider `ccswitch` / `gpt-5.6-sol`，Provider 调用开启、fallback 关闭、服务鉴权和反滥用开启。此前“仍是旧版本、调用关闭、fallback 开启”的描述已失效。
2. 真实联网 `collect` 已完成 10 条法律问答和 8 条合同审查，技术结果 `18/18` 通过、问题数 `0`，状态严格保持 `needs_legal_review`。技术包位于共享预发布 `.runtime/v2-ai-provider-acceptance/2026-08-11-shared-staging-collect-final/provider-technical-review-package.json`，SHA-256 为 `ed1830430e8049397800cc75e9c24bac85a093a268bb669cf9d8db862adac9f2`。
3. 10 张知识卡与上述 18 条真实结果尚未由实际具名法务签署精确技术包；共享证据对象、法务 trusted keyring 和 receipt signing key 也尚未形成完整受保护输入。因此没有真实 `acceptance_run_id`、receipt v2 或 promotion bundle，禁止执行 `finalize`。
4. 生产基础设施仍未建立：`/etc/yuqei/production.env`、`/etc/yuqei/production-secrets`、`/var/lib/yuqei/preflight` 和异地备份挂载均不存在，production 容器数为 `0`；正式 TLS/DNS、不可变镜像和阿里云前端切流也没有验收证据。
5. 生产双节点 receipt/release/image digest canary、撤销传播 SLA 和 kill switch 演练尚未执行。服务器根盘当前使用率约 `91%`，仅余约 `18 GiB`，正式部署前必须完成容量治理和回滚空间确认。
6. support access 仍为 deny-only：真实 IdP/MFA、会话绑定、跨节点撤销、真实资源授权后读取、告警消费和具名隐私/法务门禁未完成；support access API 与身份执行器继续关闭。

在上述外部门禁具备前，production preflight 必须继续失败，系统保持共享预发布/UAT，不启动 production compose、不切生产流量。

## 2026-08-11 验证

- Python 全量：`454 passed, 3 skipped`；3 个 opt-in 项已在 `192.168.3.90:5432/yuqei_contract` 的随机隔离 schema 中单独 `3/3` 通过并清理。
- Contract Web typecheck 与 production build：通过，101 个路由生成成功；390×844 抽屉、`Esc`、关闭态键盘可达性、正文横向溢出和控制台均通过真实浏览器复核。
- 产品黄金套件：合同生成 23 条、条款推荐 8 条，共 `31/31` 技术通过，法务状态保持 `needs_legal_review`。
- 真实 Provider：`18/18` 技术通过、fallback `false`、问题 `0`，技术包 hash 已与远端文件重新计算结果一致。
- npm audit、pip-audit、Bandit 均为 0 漏洞/0 findings；待提交源码 secret 候选为 0。本地 Git 忽略的 `.env.local` 仍由开发者自行保管且不进入版本库。
- `git diff --check`、Next.js production build、PostgreSQL 事务/故障回滚/outbox/support access 并发门禁均通过。