feat: 实现 MVP-1 portal 提交契约、Prompt 覆盖与游标历史 (#19) #25

New Issue

2026-08-21T16:07:30+08:00

ila commented

2026-08-21 16:07:30 +08:00

基本信息

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

原始需求

来源：用户对话与已确认 MVP-1 技术设计、管理端原型 #17、用户端原型 #18。
提出时间：2026-08-21
脱敏摘要：按已确认 MVP-1 范围建立生产实现单元工单。

文档影响

不影响长期文档，原因：
更新项目档案或本地开发与验证
更新架构与代码地图
更新业务规则与术语
更新常见修改或故障排查
更新其他 Wiki 页面：Product-Requirements-Overview

交付文档影响

无交付文档影响，原因：本工单交付内部实现，最终用户操作文档待功能集成后统一评估。
更新已有交付文档，受众与页面：
新增交付文档，受众与页面：

变更控制

不增加计费扣点、支付、配额、内容审核、公开注册、MVP-2 API Key/openapi 或其他已排除范围。
不使用真实 Provider 额度进行调试；自动化与开发使用 mock。
实施开始前复核依赖工单、工作区和已确认设计；完成后保持“待验收”，由用户明确验收后关闭。

依赖与并行

前置工单：#20、#21
是否允许并行：是；在路由核心和迁移完成后，可与 #22/#23 并行，不调用真实上游。

目标与范围

扩展 portal handler/service 以处理 image_generate、image_edit 的 multipart metadata、role_rule、每图 client_id/position/role/note、渲染 Prompt 快照，以及带 HMAC 的游标历史 API。

不实现浏览器交互页面，不修改登录模型、点数边界或开放注册。

已确认方案

image_generate 不接受图片；image_edit 至少一张且恰好一个 primary；metadata 与文件一一对应，position 从 0 连续唯一，role 固定 primary/reference，note 最多 500，role_rule 做 UTF-8/大小校验。Prompt 覆盖顺序固定为模板默认 → 非空用户 rule → 按 position 图片 role/note，最终
endered_prompt 一次性落库。历史使用 user_id 作用域 HMAC base64url cursor，不得退回 offset。

验收标准

提交校验和错误码覆盖 metadata/文件对应、能力、连续顺序、唯一 primary、长度与 MIME 边界。
rendered_prompt、路由/模板快照与输入角色备注在同步提交中落库，不调用上游。
游标稳定、篡改/过期 400、跨用户隔离、limit 上限和 has_more/next_cursor 有测试。
既有认证、生成状态机、幂等与点数只读边界未回归。

验证

运行 portal handler/service、MySQL 集成及跨用户授权测试。
使用 mock/本地测试文件，不带入真实用户图片或生成结果。

实施结果与证据（2026-08-22）

结果：实现已于 2026-08-23 通过用户验收；父工单 #19 与 Epic #3 已同步勾选 #25。
用户验收：2026-08-23，用户明确确认 #25 验收通过。
实现提交：c3e8f1f；验收文档提交：024a949，均已推送至 main。
实现：活动路由/模板快照、image_generate/image_edit metadata、files[<client_id>] 一一对应、Prompt 覆盖与输入 role/note、用户作用域 HMAC 游标历史；同步链路不调用上游。
幂等：重放先返回原 generation，路由停用后仍不重复保存文件；并发首提继续由队列事务和唯一键收敛。
自动验证：Go build/vet/全仓测试、portal service/handler race、稳定错误码测试全部通过。
MySQL：使用 admin/config/settings.yml 的本机 MySQL 8.4.8 连接创建隔离库 chorus_test，只通过版本化 up migrations 初始化；handler 集成连续运行和 race 运行通过。未修改 chorus 业务库。
核心 Wiki：Architecture revision abef747ecc01c1538c376d9c35a299d3bc4fb3c5；Product Requirements revision 789e2356d62592d8bd6e6d094036b9eaa99c3110；镜像已同步。
任务归档：Task-25-MVP-1-portal-提交契约与游标历史，revision e4391526ddfbd5327b37f5cd3efde6dc765cf73e；未导出 docs/task/。
未覆盖：#26 的浏览器页面和无限滚动交互不在本工单范围；未调用真实 Provider，未使用真实用户数据或图片。

## 基本信息 - 类型：需求 - 所属 Epic：#3 - 所属 MVP / 版本：#19 / MVP-1 - 阶段：已完成 ## 原始需求 - 来源：用户对话与已确认 MVP-1 技术设计、管理端原型 #17、用户端原型 #18。 - 提出时间：2026-08-21 - 脱敏摘要：按已确认 MVP-1 范围建立生产实现单元工单。 ## 文档影响 - [ ] 不影响长期文档，原因： - [ ] 更新项目档案或本地开发与验证 - [x] 更新架构与代码地图 - [ ] 更新业务规则与术语 - [ ] 更新常见修改或故障排查 - [x] 更新其他 Wiki 页面：Product-Requirements-Overview ## 交付文档影响 - [x] 无交付文档影响，原因：本工单交付内部实现，最终用户操作文档待功能集成后统一评估。 - [ ] 更新已有交付文档，受众与页面： - [ ] 新增交付文档，受众与页面： ## 变更控制 - 不增加计费扣点、支付、配额、内容审核、公开注册、MVP-2 API Key/openapi 或其他已排除范围。 - 不使用真实 Provider 额度进行调试；自动化与开发使用 mock。 - 实施开始前复核依赖工单、工作区和已确认设计；完成后保持“待验收”，由用户明确验收后关闭。 ## 依赖与并行 - 前置工单：#20、#21 - 是否允许并行：是；在路由核心和迁移完成后，可与 #22/#23 并行，不调用真实上游。 ## 目标与范围扩展 portal handler/service 以处理 image_generate、image_edit 的 multipart metadata、role_rule、每图 client_id/position/role/note、渲染 Prompt 快照，以及带 HMAC 的游标历史 API。不实现浏览器交互页面，不修改登录模型、点数边界或开放注册。 ## 已确认方案 image_generate 不接受图片；image_edit 至少一张且恰好一个 primary；metadata 与文件一一对应，position 从 0 连续唯一，role 固定 primary/reference，note 最多 500，role_rule 做 UTF-8/大小校验。Prompt 覆盖顺序固定为模板默认 → 非空用户 rule → 按 position 图片 role/note，最终 endered_prompt 一次性落库。历史使用 user_id 作用域 HMAC base64url cursor，不得退回 offset。 ## 验收标准 - [x] 提交校验和错误码覆盖 metadata/文件对应、能力、连续顺序、唯一 primary、长度与 MIME 边界。 - [x] rendered_prompt、路由/模板快照与输入角色备注在同步提交中落库，不调用上游。 - [x] 游标稳定、篡改/过期 400、跨用户隔离、limit 上限和 has_more/next_cursor 有测试。 - [x] 既有认证、生成状态机、幂等与点数只读边界未回归。 ## 验证 - 运行 portal handler/service、MySQL 集成及跨用户授权测试。 - 使用 mock/本地测试文件，不带入真实用户图片或生成结果。 ## 实施结果与证据（2026-08-22） - 结果：实现已于 2026-08-23 通过用户验收；父工单 #19 与 Epic #3 已同步勾选 #25。 - 用户验收：2026-08-23，用户明确确认 #25 验收通过。 - 实现提交：`c3e8f1f`；验收文档提交：`024a949`，均已推送至 `main`。 - 实现：活动路由/模板快照、image_generate/image_edit metadata、`files[<client_id>]` 一一对应、Prompt 覆盖与输入 role/note、用户作用域 HMAC 游标历史；同步链路不调用上游。 - 幂等：重放先返回原 generation，路由停用后仍不重复保存文件；并发首提继续由队列事务和唯一键收敛。 - 自动验证：Go build/vet/全仓测试、portal service/handler race、稳定错误码测试全部通过。 - MySQL：使用 `admin/config/settings.yml` 的本机 MySQL 8.4.8 连接创建隔离库 `chorus_test`，只通过版本化 up migrations 初始化；handler 集成连续运行和 race 运行通过。未修改 `chorus` 业务库。 - 核心 Wiki：Architecture revision `abef747ecc01c1538c376d9c35a299d3bc4fb3c5`；Product Requirements revision `789e2356d62592d8bd6e6d094036b9eaa99c3110`；镜像已同步。 - 任务归档：`Task-25-MVP-1-portal-提交契约与游标历史`，revision `e4391526ddfbd5327b37f5cd3efde6dc765cf73e`；未导出 `docs/task/`。 - 未覆盖：#26 的浏览器页面和无限滚动交互不在本工单范围；未调用真实 Provider，未使用真实用户数据或图片。

ila referenced this issue

2026-08-21 16:08:04 +08:00

mvp: MVP-1 多上游可用性与运营管理 #19

ila referenced this issue

2026-08-21 16:08:06 +08:00

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

ila referenced this issue from a commit

2026-08-22 12:08:37 +08:00

feat: 实现 portal 提交契约与游标历史 (#25)

ila referenced this issue from a commit

2026-08-23 20:55:30 +08:00

docs: 记录 portal 提交契约验收 (#25)