Table of Contents

36 MVP-2 API 治理技术设计

背景与目标
最终方案
修改文件
验收结果
测试
遗留问题
相关提交
人工验收

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

36 MVP-2 API 治理技术设计

类型：技术设计
所属 Epic：#3
所属 MVP / 版本：#35 / MVP-2
状态：已完成
日期：2026-08-24
Gitea 工单：#36
Wiki 页面：Task-36-MVP-2-API治理技术设计

背景与目标

为已确认的 MVP-2 范围形成字段级 API Key、OpenAPI、三维限流、审计、迁移和验证设计；在设计与 UI 原型经用户确认前不实施生产代码。

最终方案

API Key 使用随机 public_id/secret，完整值只在创建成功时返回一次，数据库只存 SHA-256 和元数据。
/openapi/v1 采用独立 Bearer 认证，不能与浏览器 Cookie/CSRF 或管理员 JWT/Casbin 混用。
提交和查询复用既有 user 作用域生成 service；同步提交不调用上游。
用户/API Key/Provider 固定窗口限流在当前单 portal 进程共享；生产阈值显式配置，多实例不在 MVP-2 支持范围。
Provider 本地限流发生在 BeginProviderAttempt 前；全部候选受限时通过 available_at 和 Defer CAS 延后，不改变 retryable、attempt 或 circuit。
000006 规划新增 api_keys、api_audit_events、generations.available_at 和管理权限 seed，必须完成隔离 MySQL 8 up/down/up。

修改文件

docs/02-architecture-and-code-map.md：技术设计主文。
docs/03-business-rules-and-glossary.md：范围和待确认规则。
docs/04-local-development-and-verification.md：配置和单实例运行门禁。
docs/09-product-requirements-overview.md：MVP-2 状态与工单索引。

验收结果

验收标准	结果
数据、API、认证、幂等、跨用户授权与迁移顺序完整	通过
user/key/provider 限流及 Provider 延后语义不破坏 retryable 红线	通过
审计脱敏、回退和 mock/并发/迁移测试矩阵完整	通过
用户明确确认并放行生产实现	通过（2026-08-24）

测试

执行命令：python dev_scripts/harness.py sync --check
结果：核心 Wiki 镜像与线上 revision 一致。
执行命令：python dev_scripts/harness.py check --strict
结果：DevHarness 严格检查通过。
执行命令：git diff --check
结果：通过。
未验证部分：未实施或运行任何生产代码、migration 或真实 Provider 请求；本工单仅完成设计。

遗留问题

用户已确认 #36 与 #37；下一步按设计拆分生产实现单元工单。生产限流阈值仍需在实现/部署工单中显式配置。

人工验收

验收人：用户
验收时间：2026-08-24
结果：#36 验收通过，技术设计放行生产实现拆单。