feat: add controlled pilot capacity quality gates

project-docs/AI合同平台-受控试点容量与分层质量评测报告-2026-08-26.md

@@ -0,0 +1,146 @@
+# AI 合同平台受控试点容量与分层质量评测报告
+
+- 日期：2026-08-26
+- 运行 ID：`stratified-v1-20260826`
+- 阶段：核心产品上线收口——受控试点容量与分层质量评测
+- 自动评测结论：**通过**
+- 法律内容人工验收：**未完成，不得视为已通过**
+- 发布建议：可继续内部和具名受控试点；不得据此开放公共注册或宣称法律意见、司法存证或正式生产模型能力已验收
+
+## 一、管理结论
+
+本阶段已经建立租户级模型任务准入、100 条分层真实样本、1/3/5/10 并发阶梯、自动输出门禁、确定性人工抽样、高风险必审、不可变复核反馈和运营后台下钻能力。
+
+本次 100 条样本全部由本地开发环境中的 `codex-cli-development / gpt-5.6-sol` 真实执行，未把 fallback、模拟响应或未运行质量门禁的任务计入基线。自动结构质量和既定容量门禁全部通过，但该门禁只证明输出结构、基本完整性和运行稳定性，不证明法律事实、法条时效性或具体案件结论正确。
+
+| 结论项 | 结果 | 判定 |
+| --- | ---: | --- |
+| 真实 Provider 样本 | 100 / 100 | 通过 |
+| 合同类型覆盖 | 10 类 × 每类 10 条 | 通过 |
+| 自动结构质量通过 | 100 / 100 | 通过 |
+| 10 并发准入拒绝 | 0 | 通过 |
+| 模型执行 P95 | 179,040 ms | 通过，接近 180 秒门限 |
+| fallback / 失败 / 受控重试 | 0 / 0 / 0 | 通过 |
+| 待具名人工复核 | 43 | 待完成 |
+| 已完成人工复核 | 0 | 未通过法律内容验收 |
+
+## 二、已落地能力
+
+### 2.1 租户与用户准入
+
+- 默认租户活动任务上限 10、单用户活动任务上限 3、租户队列上限 25。
+- 幂等键优先于容量判断；同一请求重试返回原任务，不重复占用名额。
+- 超限返回 HTTP 429 和 `Retry-After`，并提供租户活动/队列饱和度与运营告警。
+- 单 API 进程内使用同一临界区完成幂等查询、容量计数和写入，竞态测试中 20 个同时提交严格放行 10 个。
+- 当前限制是受控试点单 API 进程保证；扩展到多个 API 副本前，需要 Redis/Lua、数据库咨询锁或独立配额服务提供跨进程原子准入。
+
+### 2.2 分层质量数据
+
+每个任务可以携带运行 ID、样本 ID、合同类型、风险等级和行业标签。运营快照可以按评测运行过滤，并分别按合同类型、风险等级和行业计算样本量、自动通过率及人工复核进度。
+
+本次固定样本覆盖：采购、销售、劳动、租赁、保密、软件服务、建设工程、数据处理、股权交易和运输合同；每类 10 条，共 100 条。风险分层为高 40、中 40、低 20；行业覆盖制造、零售、通用、科技、建筑、金融和物流。
+
+### 2.3 人工复核闭环
+
+- 自动质量异常、高风险样本、确定性抽样和人工接管均进入统一复核队列。
+- 高风险样本 100% 必审；其他评测样本按默认 10% 确定性抽样，重复运行同一任务不会改变抽样决定。
+- 复核人必须具名，并记录事实一致性、引用可核验性、高风险遗漏、处置结论和说明。
+- 复核事件追加写入独立表；模型原输出不被静默覆盖。
+- 数据库写入在同一事务内同时保存复核事件并更新任务状态，避免出现“任务已完成但证据未落库”或相反状态。
+- 管理页面提供模型输出与引用预览、试点租户/运行 ID 下钻和显式复核确认框。
+
+## 三、真实容量曲线
+
+| 并发 | 提交 | 准入重试 | 排队 P95 | 执行 P95 | 波次耗时 |
+| ---: | ---: | ---: | ---: | ---: | ---: |
+| 1 | 1 | 0 | 2,266 ms | 170,774 ms | 176,577 ms |
+| 3 | 3 | 0 | 1,311 ms | 175,488 ms | 180,078 ms |
+| 5 | 5 | 0 | 1,101 ms | 163,726 ms | 164,504 ms |
+| 10 | 10 | 0 | 3,668 ms | 174,452 ms | 176,455 ms |
+
+全体 100 条样本：
+
+- 排队 P50 / P95：1,642 / 4,505 ms；最大 6,567 ms。
+- 模型执行 P50 / P95：156,712 / 179,040 ms；最大 221,713 ms。
+- 总耗时 P50 / P95：158,612 / 179,298 ms；最大 223,004 ms。
+- 3 条执行耗时超过 180 秒，其中 1 条超过 200 秒。P95 门禁通过，但长尾仍需治理。
+- 57 条任务以 `succeeded` 完成；43 条在模型真实成功和自动门禁通过后按策略进入 `awaiting_human`，不属于模型失败。
+- 每条输出至少包含 1 条引用；回答字符数最少 1,289，中位数约 1,977。这里只验证结构存在，不代表引用法律有效性已经人工核验。
+
+## 四、分层结果
+
+10 类合同均为 10/10 自动门禁通过。人工复核要求分布如下：
+
+| 合同类型 | 样本 | 自动通过 | 待人工复核 |
+| --- | ---: | ---: | ---: |
+| 采购 | 10 | 10 | 5 |
+| 销售 | 10 | 10 | 4 |
+| 劳动 | 10 | 10 | 4 |
+| 租赁 | 10 | 10 | 4 |
+| 保密 | 10 | 10 | 4 |
+| 软件服务 | 10 | 10 | 4 |
+| 建设工程 | 10 | 10 | 5 |
+| 数据处理 | 10 | 10 | 4 |
+| 股权交易 | 10 | 10 | 4 |
+| 运输 | 10 | 10 | 5 |
+
+风险分层中，高风险 40/40 全部进入人工复核；中风险 40 条抽中 2 条，低风险 20 条抽中 1 条，共 43 条。当前没有自动质量异常触发的复核，人工复核完成数为 0。
+
+## 五、门禁判定
+
+| 门禁 | 阈值 | 实测 | 判定 |
+| --- | --- | ---: | --- |
+| 真实样本数 | ≥ 100 | 100 | 通过 |
+| 合同类型覆盖 | 10 类且每类 ≥ 10 | 10 × 10 | 通过 |
+| 总体自动门禁通过率 | ≥ 80% | 100% | 通过 |
+| 各合同类型自动通过率 | ≥ 70% | 全部 100% | 通过 |
+| 模型执行 P95 | ≤ 180 秒 | 179.04 秒 | 通过，黄色边界 |
+| 10 并发准入拒绝 | 0 | 0 | 通过 |
+| 高风险人工复核完成 | 100% | 0 / 40 | 未完成 |
+| 全部抽检完成 | 100% | 0 / 43 | 未完成 |
+
+因此，本阶段只能签署“自动容量和结构质量门禁通过”，不能签署“法律内容质量通过”。
+
+## 六、运行与工程证据
+
+- PostgreSQL Alembic 已从 `20260826_0027` 升级到 `20260826_0028 (head)`；全新 SQLite 也已从零升级到同一 head。
+- 运行时 schema check 中数据库、版本、核心表、租户列和 30 个模型任务运营列均为 `ok`。
+- AI API、合同 API 和前端分别在 8101、8100、3000 启动；10 个独立 worker 参与容量运行。
+- AI API 全量测试、worker、Python SDK、合同代理、基础设施测试、Web 测试与 TypeScript 类型检查均通过；提交前会再次执行最终回归。
+- 两套 OpenAPI 3.1 文档均可被 YAML 解析，并已描述评测元数据、容量快照、复核队列、反馈对象和跨租户平台管理员下钻。
+- 源码密钥扫描的仓库全局结果仍因 38 个既有/未跟踪本地环境候选而失败；将扫描结果与本次 27 个变更文件交叉核对后，本次变更新增候选为 0。未修改或掩盖既有基线问题。
+- Chrome 只读 UAT 使用现有“UAT 法务”会话访问平台运营页，系统正确返回平台管理员权限不足，控制台无异常；未使用非管理员账号提交复核。平台管理员正向流程由自动化代理测试覆盖，仍建议由真实超级管理员完成一次最终界面确认。
+- 原始评测 JSON/Markdown 位于 `.runtime/controlled-pilot-stratified-quality/`，默认不进入 Git。证据只保存样本/任务/审计 ID、分层、状态、字符数、引用数和耗时，不保存问题正文或模型回答正文。
+
+## 七、已知限制与上线边界
+
+1. 100% 是自动结构门禁通过率，不是法律正确率。43 条具名复核未完成前，不应对外宣称内容质量已验收。
+2. 执行 P95 距 180 秒只剩 960 ms，且最大值 221.7 秒。受控试点应继续显示后台进度、允许取消和人工接管，不应恢复同步等待。
+3. 当前模型来源是开发期 Codex CLI 与个人订阅会话，不是可供真实客户使用的生产 Provider 合同、API 配额或服务等级协议。
+4. 本地运行时 anti-abuse 为 disabled；真实用户注册仍应保持关闭。公开试点前至少切换 observe/enforce，配置哈希密钥并验证每日调用/数据出口配额。
+5. PostgreSQL 当前缺少 `vector` 扩展和 `knowledge_chunks.embedding`，不阻断本次模型队列容量测试，但会限制真实知识库向量检索效果。
+6. 多 API 副本时，当前进程锁不能作为全局容量硬保证；必须先接入共享原子准入。
+7. 本阶段没有执行双云 KMS、外部不可变见证或司法效力验收，相关能力仍保持未执行状态。
+
+## 八、下一步修改方案
+
+### P0：受控试点放行前
+
+1. 指定至少两名具名法律复核人员，完成 40 个高风险样本和 3 个抽样样本；每条核对事实、现行法源、引用定位和重大遗漏。
+2. 导出 43 条结构化复核反馈，按合同类型统计 corrected/rejected、不可核验引用和高风险遗漏；任一类型出现重大遗漏时重新评测该类型 10 条。
+3. 对 3 条超过 180 秒的任务分析 Provider 耗时和提示词长度；将 P95 目标留出至少 10% 余量后再扩大租户并发。
+4. 用真实超级管理员登录运营页，下钻 `controlled-pilot-v1 / stratified-v1-20260826`，验证筛选、输出预览、显式确认和复核落库，但不得用测试人员身份替代法务结论。
+
+### P1：扩大到多租户前
+
+1. 将准入计数迁移到 Redis/Lua、数据库咨询锁或独立配额服务，并用两个 API 副本重复 20/50 并发竞态测试。
+2. 增加双人独立复核/仲裁数据模型，避免首位复核人完成后第二位无法提交独立结论。
+3. 建立按租户和合同类型的错误预算：fallback、失败、P95、重大遗漏、引用不可核验率分别告警。
+4. 接入具备企业 API 合同、配额、数据处理条款和国内可访问性的正式模型 Provider；个人订阅仅保留开发期使用。
+5. 补齐 pgvector、anti-abuse、正式合规材料和受控注册门禁后，再评估扩大试点。
+
+## 九、最终发布决定
+
+本阶段建议状态为：**自动容量与结构质量门禁 PASS；法律内容验收 PENDING；公共发布 BLOCKED**。
+
+允许继续的范围是内部开发和具名受控试点，租户活动任务不超过 10、单用户不超过 3，并保留后台任务、重试、fallback 和人工接管。完成 43 条人工复核及上述 P0 条件前，不开放真实用户自由注册，不将本地评测包装成第三方存证、司法效力或正式生产服务等级证明。