lijiaoqiao/docs/subapi_design_comprehensive_review_findings_v1_2026-03-17.md

Subapi 集成与替换方案全面评审报告（Skills 专业评审版，v1）

• 评审日期：2026-03-17
• 评审方式：线上文档/代码证据审查（不进行线下评审）
• 评审目标：验证“可集成 subapi、可逐步替换、可达企业级商用 LLM 网关目标”的可执行性与风险闭环
• 评审技能视角：
  • security：安全与合规红线
  • api-design：协议契约与版本兼容
  • backend：架构可运维性与可靠性
  • writing-clearly-and-concisely：问题可执行表达

1. 评审结论

当前结论：CONDITIONAL GO（有条件推进）

必须先关闭以下门槛，才可进入外部专家 Round-1 正式博弈：

1. 关闭全部 P0（本报告共 2 项）。
2. 将 P1 中影响评审可信度的项（FND-P1-01/02/03/04）纳入强制整改排期与负责人。
3. 完成专家名册扩展（产品专家、重构项目专家、技术专家）并发出定向邀请。

2. Findings（按严重级别）

2.1 P0（阻断级）

编号	问题	证据	风险	建议整改
FND-P0-01	设计要求了“内网隔离 + mTLS”，但两周任务单未把这两项作为显式交付任务。	设计要求见 subapi_integration_compat_security_reliability_design_v1_2026-03-17.md:90-93；任务单仅覆盖 egress 与配置硬化，未见 mTLS/内网暴露关闭任务：subapi_integration_risk_controls_execution_tasks_v1_2026-03-17.md:58-76。	若缺少东西向链路强认证与暴露面收敛，subapi 作为外部模块会成为横向移动入口，安全基线与审计责任不可闭环。	新增 SEC-007（subapi 内网隔离与公网不可达验证）+ SEC-008（网关<->subapi mTLS 双向证书与轮换演练），并设为 Week Gate 必过项。
FND-P0-02	query key 策略在“契约文档、设计文档、上游代码事实”三处存在边界歧义，存在误放行风险。	契约仍保留 /v1beta/* query key 兼容：subapi_connector_contract_v1_2026-03-17.md:52,56；我方设计要求北向入口禁止 query key、仅做内转：subapi_integration_compat_security_reliability_design_v1_2026-03-17.md:105-107；上游 Gemini 中间件确实允许特定路径 query key：api_key_auth_google.go:146-157。	如果网关边界策略不严，外部客户端可绕过 header-only 规范，导致密钥泄露面扩大、日志污染和审计判责困难。	在接口契约增加“北向/南向边界规则”专章；新增强制测试 SEC-009：外部 query key 全拒绝、内部改写链路可用且可审计。

2.2 P1（高优先级）

编号	问题	证据	风险	建议整改
FND-P1-01	接管率 SQL 的主路径过滤与 Connector 契约存在冲突，口径有漂移风险。	主路径 SQL 包含 inbound_endpoint IS NULL 及 alias /responses：router_core_takeover_metrics_sql_dashboard_v1_2026-03-17.md:75-83；而 Connector 契约明确禁止 alias：subapi_connector_contract_v1_2026-03-17.md:42-44。	验收口径可能混入非 canonical 流量或历史脏数据，影响 >=60% / 100% 决策可信度。	固化 canonical-only 主路径过滤；把 alias 流量单独做异常面板，不计入验收分母。
FND-P1-02	cn_platforms 在 SQL 中仍以示例硬编码，缺少配置中心强绑定。	多处示例硬编码 ARRAY['antigravity']：router_core_takeover_metrics_sql_dashboard_v1_2026-03-17.md:110,166,225,333；虽有文字提示“不应硬编码”：...:101,374。	国内供应商清单变更后会导致统计失真，直接影响 cn_takeover=100% 验收。	新增配置表 gateway_provider_taxonomy，由 SQL 读取，禁止脚本内硬编码。
FND-P1-03	Wave Gate 没有把“路由标记覆盖率”纳入 Go 条件，评审可能在低覆盖数据上推进。	标记覆盖率 KPI 目标 >=99.9%：router_core_takeover_metrics_sql_dashboard_v1_2026-03-17.md:384；但 Wave-CN/Wave-Global Go 条件未包含该项：router_core_s2_acceptance_test_cases_v1_2026-03-17.md:99-107。	数据覆盖不足时，接管率结论不可靠，容易误升波或误回切。	在 Wave Gate 增加硬条件：route_mark_coverage_pct >= 99.9%，否则一律 Stop。
FND-P1-04	专家评审轮次文件已补充预审输入，但仍缺“owner/截止日期/证据链接”的实填项。	预审输入已加入：round1_architecture_review.md:6-15、round2_compat_billing_review.md:6-15、round3_security_compliance_review.md:6-15、round4_reliability_wargame_review.md:6-15；正式问题清单区仍待会后填实：round1...:24-35 等。	若会后不立即回填，问题闭环会断档，影响 EXP-006 决议可信度。	会后 4 小时内必须完成 owner/due date/证据链接回填，并纳入评审秘书检查清单。
FND-P1-05	迁移方案有技术灰度，但缺少客户成功侧“迁移中断沟通与赔付/SLA”机制。	迁移目标强调留存与成功率：llm_gateway_subapi_evolution_plan_v2_2026-03-17.md:107-119；未定义客户沟通/SLA 补救机制。	迁移期若出现协议回归或账务争议，商业层面容易出现升级投诉和续费风险。	新增 PROD-001 客户迁移事件分级与告知模板、PROD-002 账务争议 SLA 与赔付边界。
FND-P1-06	任务单职责仍是角色占位，未落到实名与备份人。	角色占位说明：subapi_integration_risk_controls_execution_tasks_v1_2026-03-17.md:20-31。	发生 P0 时可能出现授权链路不清、恢复动作延迟。	启动会上完成实名 RACI + backup owner，并写入任务单 v1.1。

2.3 P2（建议优化）

编号	问题	证据	风险	建议整改
FND-P2-01	术语“subapi/sub2api”混用，跨文档追踪成本偏高。	多份文档并存两种命名：例如 sub2api_integration_readiness_checklist_2026-03-16.md:1-4 与 llm_gateway_subapi_evolution_plan_v2_2026-03-17.md:15-16。	评审/实施时易产生“同名异义”沟通误差。	统一术语字典：对外叫 subapi，代码与仓库名保持 sub2api，在文档页首固定声明。
FND-P2-02	专家执行台账字段粒度不足，难以快速看清“优先级+邀请状态+轮次覆盖”。	旧名册/台账字段偏基础：review/experts_roster_2026-03-18.md:9-20、review/invitation_dispatch_tracker_2026-03-17.md:8-19。	邀请执行过程不够透明，不利于秘书做催办与替补。	扩展为“专家类型/优先级/邀请状态/预计轮次/是否已签 NDA”。（本次已更新）

3. 整改任务映射（新增与绑定）

Finding	任务ID	类型	截止日期	验收标准
FND-P0-01	SEC-007	新增	2026-03-20	subapi 对公网不可达，且有网络策略与扫描证据
FND-P0-01	SEC-008	新增	2026-03-24	mTLS 双向认证联通，证书轮换演练通过
FND-P0-02	SEC-009	新增	2026-03-21	外部 query key 全拒绝；内部改写链路可观测
FND-P1-01	COMP-007	新增	2026-03-22	主路径 SQL 与 canonical 契约一致，alias 单列监控
FND-P1-02	COMP-008	新增	2026-03-22	cn_platforms 改为配置表驱动
FND-P1-03	COMP-009	新增	2026-03-23	Wave Gate 加入覆盖率硬门槛并生效
FND-P1-04	EXP-002~005	绑定	2026-03-19 起	四轮评审均有会前问题清单与会后闭环
FND-P1-05	PROD-001/002	新增	2026-03-24	发布客户沟通与赔付/SLA 流程文档
FND-P1-06	PMO-001	新增	2026-03-18	任务单实名 owner + backup owner 完成

4. 专家博弈输入建议（会前统一口径）

1. 先审 P0，再谈路线优选：P0 不闭环时不进入扩流讨论。
2. Round-1 必问三题：锁定风险、止血路径、替换可逆性。
3. Round-2 必核数据口径：canonical 分母、覆盖率门槛、CN 平台清单来源。
4. Round-3 必做攻防演练：query key 绕过、SSRF、内网访问阻断、审计追踪。
5. Round-4 必做恢复演练：10 分钟触发回切、30 分钟恢复、账务一致性验收。

5. 当前执行状态（本次已完成）

1. 已完成 skills 内部全面评审并形成分级 findings。
2. 已更新专家名册与邀请跟踪字段，显式纳入产品专家、重构项目专家、技术专家。
3. 已生成逐人邀请文本，可直接发送。

6. 三角色联合复审回链（2026-03-18）

1. 已补充三角色联合评审文档：subapi_role_based_review_wargame_optimization_v1_2026-03-18.md。
2. 已将用户代表、测试专家、网关专家纳入专家名册与邀请跟踪（E13/E14/E15）。
3. 已将联合评审任务映射到执行任务单（UXR-*、TST-*、GAT-*、EXP-007）。