OPC/chorus
2
0
Fork 0
Code Issues 11 Pull Requests Actions Packages Projects Releases Wiki Activity

feat: 交付 OpenAPI v1 认证与生成接口 #43

New Issue
Closed
opened 2026-08-24 12:01:52 +08:00 by ila · 2 comments
ila commented 2026-08-24 12:01:52 +08:00
Owner
Copy Link
Copy Source

基本信息

  • 类型：需求
  • 所属 Epic：#3
  • 所属 MVP / 版本：#35 / MVP-2
  • 阶段：已完成

原始需求

  • 来源：用户对话与已验收 #36/#37
  • 提出时间：2026-08-24
  • 脱敏摘要：面向现有受控用户交付安全的 API Key、OpenAPI 生成接口、限流、审计和必要管理页面；不开放注册、不自动删除数据、不增加计费或每日配额。

设计与原型门禁

  • 修改类型：生产实现
  • 已确认技术设计：Wiki Architecture-and-Code-Map，revision 1e8fea6c058d6d23f4a40183dd51708c8a4dae84
  • 已确认原型：prototypes/37/v1/index.html，#37 revision b65c47e5f701f67a8a06972e4f3e02c1f7bbd554
  • 状态：已确认（用户，2026-08-24）

依赖与并行

  • 前置工单：#41
  • 是否允许并行：前置完成后可与 #42 并行。

要解决什么

交付独立 Bearer API Key 认证、版本化 /openapi/v1 生成/查询/文件访问接口及仓库内 OpenAPI 3.1 契约。

做什么 / 不做什么

  • 做：Bearer 认证；文本/图片提交、历史、详情、输入输出/缩略图访问；必填 Idempotency-Key；统一错误信封、X-Request-ID、no-store；OpenAPI schema 合约测试。
  • 不做：Swagger UI、SDK、webhook、批量、取消、流式、Cookie/JWT 回退；同步提交不得调用上游。

子项目影响

  • 影响：portal、OpenAPI 契约文件、复用既有 generation service。
  • 共享接口以 #36 为事实来源。

验收标准

  • 无效/撤销/到期 Key 统一 401，跨用户对象统一 404，三条认证链不混用。
  • 提交立即 202、幂等重放 200、冲突 409，提交链不调用上游。
  • JSON/multipart、历史 cursor 和文件归属测试完整。
  • OpenAPI 3.1 与 handler 合约测试一致。

文档影响

  • 已更新 Wiki Architecture、Business Rules、Local Development，并同步核心镜像。

风险和回退

认证或对象归属错误会越权；必须以负向测试和 mock 上游证明。回退路由不删除用户数据。

实施结果（2026-08-24）

  • 提交：04953bd（已推送 origin/main）。
  • /openapi/v1 使用独立 API Key middleware，不经过浏览器 session/CSRF，不接受 Cookie、Query token 或管理员 JWT 回退。
  • 实现文本/图片提交、历史、详情、输入、输出、缩略图和受认证 OpenAPI 3.1 契约；响应带 X-Request-ID 且禁止缓存。
  • 提交只从单个 Idempotency-Key Header 取值；相同请求重放 200，不同请求 409。图片冲突比较 capability、Prompt、角色元数据和已保存文件内容。
  • API Key 认证持共享行锁确认 Key 与 active 用户状态，撤销/到期/停用统一 401；last_used_at 最多每分钟更新一次。
  • 文档 revisions：Architecture a660cd26350c8f7d242788e28c6ecc01bcf31f4d；Business Rules e63946a4f4b0ca4acbad0a0ba0e75b9ed70db95a；Local Verification e8d57350c40ad6a6ac996b5a3e5903ca782a1d1c。

验证结果（2026-08-24）

  • go test ./...、go vet ./...、go build ./...：通过。
  • go -C admin test ./...、go -C admin build .：通过。
  • OpenAPI 3.1 合约测试：八条路径、方法、Bearer security 与嵌入产物通过。
  • 可丢弃 MySQL 8 库 chorus_mvp2_openapi_test：认证隔离、JSON/multipart、跨渠道幂等、409、cursor、跨用户详情和文件访问通过；测试后已删除。
  • python dev_scripts/harness.py check --strict、42 项 Harness 单测、sync --check、git diff --check：通过。
  • 未调用真实 Provider，未使用当前服务数据库；同步提交没有 Provider attempt。限流和审计分别由 #44/#45 交付。
## 基本信息 - 类型：需求 - 所属 Epic：#3 - 所属 MVP / 版本：#35 / MVP-2 - 阶段：已完成 ## 原始需求 - 来源：用户对话与已验收 #36/#37 - 提出时间：2026-08-24 - 脱敏摘要：面向现有受控用户交付安全的 API Key、OpenAPI 生成接口、限流、审计和必要管理页面；不开放注册、不自动删除数据、不增加计费或每日配额。 ## 设计与原型门禁 - 修改类型：生产实现 - 已确认技术设计：Wiki Architecture-and-Code-Map，revision `1e8fea6c058d6d23f4a40183dd51708c8a4dae84` - 已确认原型：`prototypes/37/v1/index.html`，#37 revision `b65c47e5f701f67a8a06972e4f3e02c1f7bbd554` - 状态：已确认（用户，2026-08-24） ## 依赖与并行 - 前置工单：#41 - 是否允许并行：前置完成后可与 #42 并行。 ## 要解决什么 交付独立 Bearer API Key 认证、版本化 /openapi/v1 生成/查询/文件访问接口及仓库内 OpenAPI 3.1 契约。 ## 做什么 / 不做什么 - 做：Bearer 认证；文本/图片提交、历史、详情、输入输出/缩略图访问；必填 Idempotency-Key；统一错误信封、X-Request-ID、no-store；OpenAPI schema 合约测试。 - 不做：Swagger UI、SDK、webhook、批量、取消、流式、Cookie/JWT 回退；同步提交不得调用上游。 ## 子项目影响 - 影响：portal、OpenAPI 契约文件、复用既有 generation service。 - 共享接口以 #36 为事实来源。 ## 验收标准 - [x] 无效/撤销/到期 Key 统一 401，跨用户对象统一 404，三条认证链不混用。 - [x] 提交立即 202、幂等重放 200、冲突 409，提交链不调用上游。 - [x] JSON/multipart、历史 cursor 和文件归属测试完整。 - [x] OpenAPI 3.1 与 handler 合约测试一致。 ## 文档影响 - [x] 已更新 Wiki Architecture、Business Rules、Local Development，并同步核心镜像。 ## 风险和回退 认证或对象归属错误会越权；必须以负向测试和 mock 上游证明。回退路由不删除用户数据。 ## 实施结果（2026-08-24） - 提交：`04953bd`（已推送 `origin/main`）。 - `/openapi/v1` 使用独立 API Key middleware，不经过浏览器 session/CSRF，不接受 Cookie、Query token 或管理员 JWT 回退。 - 实现文本/图片提交、历史、详情、输入、输出、缩略图和受认证 OpenAPI 3.1 契约；响应带 `X-Request-ID` 且禁止缓存。 - 提交只从单个 `Idempotency-Key` Header 取值；相同请求重放 200，不同请求 409。图片冲突比较 capability、Prompt、角色元数据和已保存文件内容。 - API Key 认证持共享行锁确认 Key 与 active 用户状态，撤销/到期/停用统一 401；`last_used_at` 最多每分钟更新一次。 - 文档 revisions：Architecture `a660cd26350c8f7d242788e28c6ecc01bcf31f4d`；Business Rules `e63946a4f4b0ca4acbad0a0ba0e75b9ed70db95a`；Local Verification `e8d57350c40ad6a6ac996b5a3e5903ca782a1d1c`。 ## 验证结果（2026-08-24） - `go test ./...`、`go vet ./...`、`go build ./...`：通过。 - `go -C admin test ./...`、`go -C admin build .`：通过。 - OpenAPI 3.1 合约测试：八条路径、方法、Bearer security 与嵌入产物通过。 - 可丢弃 MySQL 8 库 `chorus_mvp2_openapi_test`：认证隔离、JSON/multipart、跨渠道幂等、409、cursor、跨用户详情和文件访问通过；测试后已删除。 - `python dev_scripts/harness.py check --strict`、42 项 Harness 单测、`sync --check`、`git diff --check`：通过。 - 未调用真实 Provider，未使用当前服务数据库；同步提交没有 Provider attempt。限流和审计分别由 #44/#45 交付。
ila commented 2026-08-24 15:37:50 +08:00
Author
Owner
Copy Link
Copy Source

#43 已完成生产实现并进入待验收。

工单保持开启，等待用户验收。

#43 已完成生产实现并进入待验收。 - 实现提交：`04953bd`（已推送 `origin/main`） - 任务归档：https://git.ilapage.cn/OPC/chorus/wiki/Task-43-OpenAPI-v1-%E8%AE%A4%E8%AF%81%E4%B8%8E%E7%94%9F%E6%88%90%E6%8E%A5%E5%8F%A3.- - 归档 revision：`5e5c8cd889e42b6466ede62fc07ed732ec7653ff` - MySQL 8 隔离库和全量 Go 回归通过，隔离库已删除。 - 未调用真实 Provider；#43 不包含 #44 限流或 #45 审计。 工单保持开启，等待用户验收。
ila commented 2026-08-25 08:43:06 +08:00
Author
Owner
Copy Link
Copy Source

人工验收完成

  • 用户于 2026-08-25 明确确认 #43 验收通过。
  • Wiki 归档：Task-43-OpenAPI-v1-认证与生成接口
  • 归档 revision：72e4f2ed7e2f5bd4031d426bc39366183634338f
  • 核心 Wiki 镜像 sync --check：通过。
  • 实现提交：04953bd
  • 父工单 #35 与 Epic #3 已同步勾选。

本工单关闭；限流、审计和管理端治理继续由 #44、#45、#46 交付。

## 人工验收完成 - 用户于 2026-08-25 明确确认 #43 验收通过。 - Wiki 归档：`Task-43-OpenAPI-v1-认证与生成接口` - 归档 revision：`72e4f2ed7e2f5bd4031d426bc39366183634338f` - 核心 Wiki 镜像 `sync --check`：通过。 - 实现提交：`04953bd` - 父工单 #35 与 Epic #3 已同步勾选。 本工单关闭；限流、审计和管理端治理继续由 #44、#45、#46 交付。
ila closed this issue 2026-08-25 08:43:13 +08:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
admin ila
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: OPC/chorus#43