docs: complete issue 43 task archive

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.-.md

@@ -1,42 +1,57 @@
 # 43 OpenAPI v1 认证与生成接口
 
-- 类型：需求 / 缺陷 / 重构
-- 所属 Epic：#
-- 所属 MVP / 版本：#
-- 状态：待验收 / 已完成
+- 类型：需求
+- 所属 Epic：#3
+- 所属 MVP / 版本：#35 / MVP-2
+- 状态：待验收
 - 日期：2026-08-24
 - Gitea 工单：https://git.ilapage.cn/OPC/chorus/issues/43
 - Wiki 页面：Task-43-OpenAPI-v1-认证与生成接口
-- Wiki revision：见本地镜像头
+- Wiki revision：以线上页面 `last_commit.sha` 为准
 
 ## 背景与目标
 
-<!-- 原来有什么问题，这次达到什么结果。 -->
+为现有受控终端用户提供独立 API Key Bearer 认证和版本化生成接口，同时复用已验证的 Portal 生成服务、异步 worker、HMAC 历史游标与文件归属规则。程序提交必须立即落库返回，不得在同步请求中调用 Provider。
 
 ## 最终方案
 
-<!-- 说明实际实现。与建单方案不同之处必须写清原因。 -->
+- 浏览器路由与 `/openapi/v1` 在 Gin 中使用不同 middleware 分组；OpenAPI 不创建或接受 Session Cookie，也不使用 CSRF、管理员 JWT 或 Query token。
+- API Key 按 public id 查找并常量时间验证 hash，在事务共享锁下确认 Key 可用和终端用户 active；无效、撤销、到期和停用统一返回 `401 invalid_api_key`。
+- 交付文本/图片提交、历史、详情、输入/输出/缩略图和受认证的 `openapi.json`。所有响应带请求 ID 并禁止缓存，文件 URL 使用 OpenAPI 路径。
+- `Idempotency-Key` 只允许单个 Header，限制为 8 至 128 个可打印 ASCII。相同完整请求重放 200；同键不同请求返回 409。图片重放比较 capability、Prompt、角色元数据和保存文件内容。
+- 仓库中的 `portal/openapi/openapi.json` 是 OpenAPI 3.1 契约源并嵌入 Portal 二进制；不提供 Swagger UI、SDK、同步等待、流式、批量、取消或 webhook。
 
 ## 修改文件
 
-- `<文件>`：<改动说明>
+- `portal/handler/openapi.go`、`portal/handler/router.go`：独立认证链和八条 OpenAPI 路由。
+- `portal/service/openapi.go`、`internal/core/apikey/repository.go`：Key 认证、事务锁和节流 last-used 写入。
+- `portal/service/idempotency.go`、`portal/service/service.go`：跨渠道严格幂等和图片内容比较。
+- `portal/openapi/openapi.json`、`spec.go`、`spec_test.go`：嵌入式 OpenAPI 3.1 契约与合约测试。
+- `portal/handler/mysql_integration_test.go`、`portal/service/validation_test.go`：负向认证、提交、游标和文件归属回归。
+- Architecture、Business Rules、Local Verification Wiki 与核心镜像：架构、调用规则和验证说明。
 
 ## 验收结果
 
 | 验收标准 | 结果 |
 |---|---|
-|  | 通过 / 未通过 |
+| 无效/撤销/到期 Key 统一 401，跨用户对象统一 404，认证链不混用 | 通过 |
+| 首次提交 202、相同重放 200、冲突 409，提交不调用上游 | 通过 |
+| JSON、multipart、HMAC cursor 和文件归属 | 通过 |
+| OpenAPI 3.1 与 Handler 路由合约 | 通过 |
+| 人工业务验收 | 待用户确认 |
 
 ## 测试
 
-- 执行命令：`<命令>`
-- 结果：
-- **未验证部分**：<!-- 必填；没有就写“无”。 -->
+- `go test ./...`、`go vet ./...`、`go build ./...`：通过。
+- `go -C admin test ./...`、`go -C admin build .`：通过。
+- 可丢弃 MySQL 8 库 `chorus_mvp2_openapi_test`：认证隔离、JSON/multipart、跨渠道幂等、cursor、详情和文件归属通过；测试后已删除。
+- `python dev_scripts/harness.py check --strict`、42 项 Harness 单测、`sync --check`、`git diff --check`：通过。
+- **未验证部分**：尚待用户人工业务验收；限流、审计和管理端治理不属于 #43。未调用真实 Provider。
 
 ## 遗留问题
 
-<!-- 没有就删除本节。 -->
+#43 范围内无已知遗留缺陷。限流、审计和管理端治理按 #44、#45、#46 推进。
 
 ## 相关提交
 
-- `<提交哈希>` <提交说明>
+- `04953bd` feat: 交付 OpenAPI v1 生成接口 (#43)