design: 明确 MVP-2 API Key、OpenAPI、限流与审计技术设计 #36

New Issue

2026-08-24T00:53:10+08:00

ila commented

2026-08-24 00:53:10 +08:00

基本信息

类型：技术设计
所属 Epic：#3
所属 MVP / 版本：#35 / MVP-2
阶段：已完成
提出时间：2026-08-24

原始需求

来源：用户已确认的 MVP-2 范围。
脱敏摘要：面向现有受控用户交付安全 API Key、OpenAPI 生成接口、限流与审计；不开放注册、不自动删除、不计费或设置每日配额。

目标

形成字段级数据模型、认证/授权边界、API 契约、限流算法、审计事件、状态/错误、迁移顺序、回退和测试矩阵，作为生产实现唯一依据。

设计范围

api_keys 的哈希、前缀、名称、状态、到期、最后使用与撤销字段；完整值一次性显示。
API Key 认证中间件、user_id 归属、Cookie/CSRF/JWT 隔离和日志脱敏。
文本、文生图、图片编辑的提交、查询、游标历史、结果访问、幂等与错误格式。
API Key、用户、Provider 维度的限流与并发保护；429、Retry-After、跨进程一致性和 fail-closed 边界。
Key 生命周期、认证拒绝、限流和程序提交的审计最小字段与保留边界。
可逆 migration、兼容回退和 mock/越权/并发/重试测试矩阵。

非目标

不修改生产代码或数据库，不制作 UI，不调用真实 Provider；不设计公开注册、自动清理、计费、每日配额、Webhook、SDK、任务取消或批量生成。

依赖与并行

前置：#19 已完成。
可与页面原型草稿并行：是；原型只消费本工单的待确认契约，任何结构变化必须更新原型版本。生产实现不得并行。

设计证据

非 UI 技术设计，更新 Architecture-and-Code-Map、Business-Rules-and-Glossary、Product-Requirements-Overview 和 Local-Development-and-Verification。
核心 Wiki 在线回读 revision 和 docs/ 镜像提交作为证据。

验收标准

数据字段、索引、唯一约束、哈希与一次性显示协议、up/down 顺序完整。
endpoint、请求/响应、幂等、游标、错误码、文件访问和跨用户授权完整。
三维限流、并发语义、429/Retry-After、跨进程一致性和失败策略完整，且不构成每日配额。
审计事件不保存完整 Key、真实 prompt、图片或不必要的个人数据。
回退策略与 mock、安全、并发、迁移测试矩阵可执行。
Wiki/revision/docs 一致，用户已明确确认并放行生产实现拆单（2026-08-24）。

风险与回退

认证或限流边界错误会造成越权、密钥泄露或绕过保护；本工单只更新设计，未确认时不实施。设计变化通过新 Wiki revision 和工单变更记录回退或修订。

技术设计草案 v1（2026-08-24）

完整设计已写入 Wiki Architecture-and-Code-Map 的“MVP-2 API 开放与治理技术设计草案（#36，待验收）”，并在线回读 revision。关键决定：

API Key 使用随机 public_id + secret，只存 SHA-256，完整值只在创建 201 响应显示一次；
/openapi/v1 使用独立 Bearer 认证，不能和浏览器 Cookie/CSRF、管理员 JWT 混用；
提交/查询/文件读取复用既有 user 作用域 service 和幂等/游标/归属规则；
user/key/provider 三维固定窗口限流在单 portal 进程共享，生产阈值必须显式配置；多实例不在本 MVP 支持范围；
Provider 本地限流发生在 BeginProviderAttempt 前，不调用上游、不改变 circuit/retryable/attempt；全部候选受限时以 available_at + Defer CAS 延后；
新增 api_keys、api_audit_events 和 generation available_at，通过 000006 可逆迁移演进；
只用 mock 上游，覆盖认证、跨用户、幂等、限流、延后 CAS、审计脱敏、OpenAPI schema 和 MySQL up/down/up。

状态：待用户确认。在本工单与 #37 原型同时明确验收前，不拆分或执行生产实现工单。

文档与检查证据

Wiki 在线回读：Architecture 2805f53ecd5f；Business Rules 5ba3d903cb98；Local Development b6d4960d7926；Product Requirements aa3543138722。
python dev_scripts/harness.py sync --check：通过。
python dev_scripts/harness.py check --strict：通过。
待人工门禁：用户明确确认设计后，最后一项验收标准才完成。

提交与归档证据

提交：875f5b0，已推送 origin/main。
技术设计归档：https://git.ilapage.cn/OPC/chorus/wiki/Task-36-MVP-2-API%E6%B2%BB%E7%90%86%E6%8A%80%E6%9C%AF%E8%AE%BE%E8%AE%A1.-
在线回读 revision：80a1aa759fca74d997b8e25d1073251e233688f6。
状态保持待验收；未获得用户明确验收前不关闭工单。

用户验收

用户验收通过（2026-08-24）。
Wiki 归档：Task-36-MVP-2-API治理技术设计，revision $(System.Collections.Hashtable[36].revision)。
核心设计镜像提交：cbae442，已推送至 origin/main。

## 基本信息 - 类型：技术设计 - 所属 Epic：#3 - 所属 MVP / 版本：#35 / MVP-2 - 阶段：已完成 - 提出时间：2026-08-24 ## 原始需求 - 来源：用户已确认的 MVP-2 范围。 - 脱敏摘要：面向现有受控用户交付安全 API Key、OpenAPI 生成接口、限流与审计；不开放注册、不自动删除、不计费或设置每日配额。 ## 目标形成字段级数据模型、认证/授权边界、API 契约、限流算法、审计事件、状态/错误、迁移顺序、回退和测试矩阵，作为生产实现唯一依据。 ## 设计范围 - `api_keys` 的哈希、前缀、名称、状态、到期、最后使用与撤销字段；完整值一次性显示。 - API Key 认证中间件、user_id 归属、Cookie/CSRF/JWT 隔离和日志脱敏。 - 文本、文生图、图片编辑的提交、查询、游标历史、结果访问、幂等与错误格式。 - API Key、用户、Provider 维度的限流与并发保护；429、Retry-After、跨进程一致性和 fail-closed 边界。 - Key 生命周期、认证拒绝、限流和程序提交的审计最小字段与保留边界。 - 可逆 migration、兼容回退和 mock/越权/并发/重试测试矩阵。 ## 非目标不修改生产代码或数据库，不制作 UI，不调用真实 Provider；不设计公开注册、自动清理、计费、每日配额、Webhook、SDK、任务取消或批量生成。 ## 依赖与并行 - 前置：#19 已完成。 - 可与页面原型草稿并行：是；原型只消费本工单的待确认契约，任何结构变化必须更新原型版本。生产实现不得并行。 ## 设计证据 - 非 UI 技术设计，更新 Architecture-and-Code-Map、Business-Rules-and-Glossary、Product-Requirements-Overview 和 Local-Development-and-Verification。 - 核心 Wiki 在线回读 revision 和 `docs/` 镜像提交作为证据。 ## 验收标准 - [x] 数据字段、索引、唯一约束、哈希与一次性显示协议、up/down 顺序完整。 - [x] endpoint、请求/响应、幂等、游标、错误码、文件访问和跨用户授权完整。 - [x] 三维限流、并发语义、429/Retry-After、跨进程一致性和失败策略完整，且不构成每日配额。 - [x] 审计事件不保存完整 Key、真实 prompt、图片或不必要的个人数据。 - [x] 回退策略与 mock、安全、并发、迁移测试矩阵可执行。 - [x] Wiki/revision/docs 一致，用户已明确确认并放行生产实现拆单（2026-08-24）。 ## 风险与回退认证或限流边界错误会造成越权、密钥泄露或绕过保护；本工单只更新设计，未确认时不实施。设计变化通过新 Wiki revision 和工单变更记录回退或修订。  ## 技术设计草案 v1（2026-08-24）完整设计已写入 Wiki `Architecture-and-Code-Map` 的“MVP-2 API 开放与治理技术设计草案（#36，待验收）”，并在线回读 revision。关键决定： - API Key 使用随机 `public_id + secret`，只存 SHA-256，完整值只在创建 201 响应显示一次； - `/openapi/v1` 使用独立 Bearer 认证，不能和浏览器 Cookie/CSRF、管理员 JWT 混用； - 提交/查询/文件读取复用既有 user 作用域 service 和幂等/游标/归属规则； - user/key/provider 三维固定窗口限流在单 portal 进程共享，生产阈值必须显式配置；多实例不在本 MVP 支持范围； - Provider 本地限流发生在 `BeginProviderAttempt` 前，不调用上游、不改变 circuit/retryable/attempt；全部候选受限时以 `available_at + Defer CAS` 延后； - 新增 `api_keys`、`api_audit_events` 和 generation `available_at`，通过 `000006` 可逆迁移演进； - 只用 mock 上游，覆盖认证、跨用户、幂等、限流、延后 CAS、审计脱敏、OpenAPI schema 和 MySQL up/down/up。状态：**待用户确认**。在本工单与 #37 原型同时明确验收前，不拆分或执行生产实现工单。  ## 文档与检查证据 - Wiki 在线回读：Architecture `2805f53ecd5f`；Business Rules `5ba3d903cb98`；Local Development `b6d4960d7926`；Product Requirements `aa3543138722`。 - `python dev_scripts/harness.py sync --check`：通过。 - `python dev_scripts/harness.py check --strict`：通过。 - 待人工门禁：用户明确确认设计后，最后一项验收标准才完成。  ## 提交与归档证据 - 提交：`875f5b0`，已推送 `origin/main`。 - 技术设计归档：https://git.ilapage.cn/OPC/chorus/wiki/Task-36-MVP-2-API%E6%B2%BB%E7%90%86%E6%8A%80%E6%9C%AF%E8%AE%BE%E8%AE%A1.- - 在线回读 revision：`80a1aa759fca74d997b8e25d1073251e233688f6`。 - 状态保持待验收；未获得用户明确验收前不关闭工单。 ## 用户验收 - 用户验收通过（2026-08-24）。 - Wiki 归档：Task-36-MVP-2-API治理技术设计，revision $(System.Collections.Hashtable[36].revision)。 - 核心设计镜像提交：cbae442，已推送至 origin/main。

ila referenced this issue

2026-08-24 00:53:27 +08:00

mvp: MVP-2 API 开放与治理 #35

ila referenced this issue

2026-08-24 00:53:30 +08:00

epic: chorus 图文生成服务交付 #3

ila referenced this issue from a commit

2026-08-24 01:09:29 +08:00

docs: 完成 MVP-2 技术设计与原型 (#36 #37)

ila referenced this issue from a commit

2026-08-24 11:51:23 +08:00

docs: 确认 MVP-2 技术设计与原型 (#36 #37)