20 KiB
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Product-Requirements-Overview wiki_url: https://git.ilapage.cn/OPC/chorus/wiki/Product-Requirements-Overview.- wiki_revision: d9a3bfa00c4ba24a5239e68e8fa28cc78641230e synchronized_at: 2026-08-21T09:03:56Z
产品需求总览
本页用途
本页是产品需求的统一导航入口，帮助项目负责人、Agent 和初级维护者快速回答：项目有哪些长期需求、当前状态是什么、详细规则和实施证据在哪里。
本页只保存稳定摘要、状态和链接，不复制完整工单、主题文档或聊天内容。需求详情仍在对应事实来源维护，避免形成两份不一致的正式需求。
事实来源边界
| 信息 | 唯一事实来源 | 本页怎样记录 |
|---|---|---|
| 项目目标、用户、范围和技术基线 | Project-Profile | 链接和一句话摘要 |
| 长期功能需求、业务规则和系统边界 | 对应 Wiki 主题页 | 需求领域和详情链接 |
| 单次实现范围、变化和验收标准 | Gitea 单元任务工单 | 工单编号和当前状态 |
| 已完成方案、测试和遗留问题 | Wiki 任务归档 | 验收入口 |
| 与版本绑定的原型、设计图或交互稿 | Git 中的 design/ 或 prototypes/ |
路径、版本和确认状态 |
| 外部原型 | 原型平台 | 链接、版本或确认日期；重要版本保留可追溯快照 |
不保存完整聊天记录、Agent 内部推理、密码、令牌、个人数据或生产数据。
当前需求索引
工单 #1 已完成长期技术基线整理和验收。项目由 Epic #3 统一跟踪；MVP-0 #4 已于 2026-08-21 验收完成。MVP-1 #19 的设计门禁已完成：技术设计 #16 已于 2026-08-21 验收通过；管理端原型 #17 的 prototypes/17/v1/index.html 已于 2026-08-21 通过用户验收，用户端原型 #18 的 prototypes/18/v1/index.html 已于 2026-08-21 通过用户验收。生产实现与集成验收单元工单已建立：#20～#28。#20 已于 2026-08-21 验收完成；#21～#28 待实施并按依赖顺序推进，其中 #28 负责以仓库外环境变量安全初始化管理员账号。当前已交付边界仍是 mock 验证的唯一 ProviderModel chat/images_edits 闭环。
| 需求领域 | 用户与场景 | 需求状态 | MVP | 详细说明 | 实施工单 | 设计证据 |
|---|---|---|---|---|---|---|
| 核心生成域与单上游 | 用户提交提示词/原图得到结果 | 已交付（#6～#10、#13、#15 已验收） | MVP-0 #4 | 架构、业务规则 | #6 迁移、#7 core、#8 platform、#9 queue、#10 worker | 架构/数据/状态设计已确认 |
| 用户端生成页 | 种子用户登录并完成一次异步生成 | 已交付（#11～#13 已验收） | MVP-0 #4 | 本页“用户端布局与状态” | #11 portal 后端、#12 用户界面 | 原型设计 #2；prototypes/2/v1/index.html，2026-08-20 用户已确认 |
| 默认 prompt template | 系统以数据配置而非硬编码合成提示词 | 已交付（#7/#13 已验收） | MVP-0 #4 | 业务规则 | #7 | 2026-08-20 已确认中性模板与 {{.UserPrompt}} |
| 多 Provider 路由与故障转移 | 单上游故障时继续服务 | 已确认（#16 已验收，待实现） | MVP-1 #19 | 架构、业务规则 | #16 技术设计 | #16 架构/API/数据/状态设计于 2026-08-21 已确认 |
| 管理端配置与记录 | 运营配置模型、路由池并排障 | 原型已确认（#17） | MVP-1 #19 | 本页“管理端页面” | #17 管理端原型 | prototypes/17/v1/index.html，v1，2026-08-21 用户已确认 |
| 图片角色编辑 | 用户编辑 role_rule、角色、备注与顺序 | 原型已确认（#18） | MVP-1 #19 | 业务规则“提示词与上传” | #18 用户端原型 | prototypes/18/v1/index.html，v1，2026-08-21 用户已确认 |
| 点数只读与发放 | 用户看余额、管理员发放留痕 | 已确认 | MVP-2 | 业务规则“点数与范围” | 待建 | 原型待确认 |
| API Key 与程序调用 | 外部程序提交与查询任务 | 已确认 | MVP-2 | 本页“程序化调用” | 待建 | API/权限设计 |
| 限流、保留期、公开注册 | 治理滥用和磁盘；决定是否开放用户获取 | 待确认（阈值/流程） | MVP-2 或后续 | 业务规则“需要补充什么” | 待建 | 安全/运维/认证设计 |
MVP 分期
原则：先完成可观测、可恢复、安全的单上游闭环，再增加可用性与运营能力，最后开放治理能力。前一期的验收门禁未通过，不进入下一期。
MVP-0：最小闭环
范围：
- 可逆迁移：
users、providers、provider_models、prompt_templates、generations、generation_inputs、generation_outputs，含明确索引、外键和唯一约束。 - core 仅使用 GORM/标准库；platform 提供安全 HTTP、本地存储、缩略图和 AES-GCM 实现。
chat与images_edits；唯一启用 ProviderModel，不做多家故障转移。- SKIP LOCKED、lease owner/token/until、过期 running 原子重领、最终 CAS、attempt/error 落库。
prompt_templates提供已确认的默认配置；第一张图片自动 primary，其余 reference。- portal 只提供受控种子用户登录、桌面双栏与移动单列、异步提交、HTMX 轮询和鉴权结果访问。
- worker 在 portal 内运行并优雅退出；配置使用可重复种子命令，自动测试连接 mock 上游。
MVP-0 非目标：
- 公开注册、找回密码和邮件验证；
- 图片角色/备注编辑与拖拽排序；
- 点数和 API Key 导航/功能；
- 多 Provider、熔断、故障转移、
images、gemini； - admin/admin-ui、无限滚动、移动抽屉、限流、清理任务。
验收：
- 文本和图片各成功一次；pending/running/终态界面正确且终态停止轮询。
rendered_prompt、attempts、latency 或失败 error 字段完整。- 相同用户幂等重放不创建第二条任务；不同用户不可读取对方任务或文件。
- 过期 running 被新 token 原子重领，旧 worker 最终写入影响 0 行且不覆盖结果。
- 400/401/策略拒绝立即失败；429/5xx/超时/连接错误分类正确（MVP-0 不换家）。
- 私网、IPv6、redirect、代理和恶意结果 URL 被 SSRF 策略覆盖。
- API Key 密文含 key_id，日志/响应无明文；浏览器写请求有 CSRF，会话安全。
- 图片输出通过鉴权访问且有缩略图；文件原子落位。
- 375/768/1024/1440 无主区域横向滚动，所有主要操作可用键盘和 44px 触控目标完成。
- 迁移在空 MySQL 8 完成 up/down/up；Go 构建、vet、测试和浏览器 E2E 通过。
MVP-1：可用性与运营
汇总工单为 #19，设计门禁已完成，生产实现单元工单已建立并等待实施：
- #16 路由、Provider、迁移、API、状态和测试设计（2026-08-21 验收通过）；
- #17 固定 go-admin/go-admin-ui 的 CRUD 与三个定制页原型（
prototypes/17/v1/index.html，2026-08-21 用户验收通过）； - #18 文生图、图片 role_rule/role/note/排序与历史无限滚动原型（
prototypes/18/v1/index.html，2026-08-21 用户验收通过）。
稳定范围仍包括加权路由、gobreaker、最多 N 家故障转移、images/gemini、受审计有冷却的单次真实连通性测试和完整 retryable 测试。技术设计与两个原型均已确认；生产工单已按数据库、路由/worker、协议、安全管理端、portal 和集成验收拆分；新增 #28 以仓库外环境变量和显式 bootstrap 命令安全初始化管理员账号。执行须遵守各自依赖。
MVP-2：治理与开放
- API Key/openapi、点数只读与发放账本；
- 用户和 Provider 维度限流、配置审计；
- 经确认的保留期与清理任务；
- 移动端历史抽屉；
- 公开注册只有在注册、验证、找回、反滥用和赠送策略单独确认后才进入范围，不能默认随 MVP-2 开放。
已锁定决策
- Go 重写，只迁移设计，不复用 cmhub Django 代码。
- 管理端来源固定为：
- go-admin
f06540883b41d03782bb6b2c4150f298f328c6b6 - go-admin-ui
67d393d713877572fab0b897296a4c1d525fc81d - go-admin-doc
424855aacf6905f3fde860c3331385cb25529a0d
- go-admin
- go-admin-ui 实际是 Vue 3.5.41 + Element Plus 2.14.4 + Vue CLI 5.0.9，不按 Vue 2/Vite 设计。
- 生产表结构、
sys_*和菜单/API 种子全部经可逆 migrations；AutoMigrate 仅可在隔离可丢弃库作研究参考。 - 管理端代码生成采用“SQL → 隔离库 → 导表 → 预览/生成 → 人工审查 → 配置转可逆 SQL”；生产无 dev-tools。
- 用户端采用 html/template + HTMX + Alpine + Tailwind；不做 SPA。
- core 只依赖 GORM/标准库，gobreaker/imaging 在 platform。
- 不引入 Redis/MQ，使用 MySQL 8 SKIP LOCKED + token/CAS。
- 点数只读，不参与生成；管理员和终端用户分表。
- 生成同步提交不调用上游，所有上游调用只在 worker。
api_type和协议能力归 ProviderModel，不归 Provider。
用户端布局与状态
桌面（>=1024px）采用历史列表 + 主工作区双栏；平板可收窄历史区；MVP-0 手机使用单列顺序布局，不依赖尚未实现的抽屉。首屏必须能看到当前结果/状态和输入动作，固定元素不能遮住滚动内容。
MVP-0 导航只显示已实现的生成入口、必要账户操作和退出；点数/API Key 不显示空入口。图片区只显示上传顺序，第一张自动主体，其余参考，不展示不可用的角色/拖拽控件。
| 状态 | 必须呈现 |
|---|---|
| 首次/空历史 | 可直接开始的输入区和简洁空状态，不伪造示例结果 |
| 上传校验失败 | 对应文件、明确原因、修正方式；焦点到首个错误 |
| pending | “排队中”，可区分尚未执行 |
| running | “生成中”，轮询更新但布局不跳动 |
| succeeded image | 缩略图、查看/下载；原图访问经鉴权 |
| succeeded text | 可读文本和复制动作，复制结果有反馈 |
| failed | 脱敏错误、是否可重试的明确操作 |
| 轮询网络错误 | 保留当前内容，提示重试，不把任务误标 failed |
| 认证过期 | 停止轮询，引导重新登录，登录后返回原上下文 |
| 历史到底 | 明确结束，不持续显示 loading |
交互验收：
- 375、768、1024px 和桌面宽屏均无不合理横向滚动、遮挡和文字溢出；
- 交互目标至少 44×44px，输入有持久 label，错误不只靠颜色；正文对比度至少 4.5:1，非文本控件/焦点边界至少 3:1；
- 图标按钮使用既有 Lucide/Element Plus 图标并有可访问名称；
- 所有功能可键盘操作；MVP-1 拖拽提供上移/下移等价操作；
- 路由/片段替换后管理焦点，状态更新使用合适的
aria-live，toast 不抢焦点； - 动效尊重
prefers-reduced-motion，loading 不造成布局位移； - 页面实现前必须完成版本化 HTML 原型并由用户确认状态、响应式、权限和异常覆盖。
管理端页面
代码生成基于固定 go-admin-ui 的既有表导入：
- CRUD：providers、provider_models、prompt_templates、users；point_accounts/api_keys 到对应 MVP 再生成。
- 定制页：路由池编排、Provider 健康、生成记录详情。
- 标准 CRUD 可用一个明确复用固定 go-admin 视觉/交互的代表性原型覆盖同类页面；定制页分别覆盖加载、空、错误、权限和边界状态。
- 生成记录默认不展示 API Key、完整敏感错误或不必要的真实用户输入。
- 定制页数量明显超过三个时重新评估维护成本，但不以先前错误的前端版本判断作为依据。
Provider 连通性测试是明确的运营动作：保存配置后由授权管理员点击，发出一次最小低成本请求，显示脱敏结果，记录审计并限制冷却；它不是保存时自动触发，也不用于 CI。
程序化调用
MVP-2 的 API Key 存哈希、身份仍属于 users。提交、查询、幂等、错误码、限流和跨用户授权在独立 API 设计工单确认；浏览器 Cookie/CSRF 与 API Key 认证链不得混用。
明确不做
计费扣点、充值与支付回调、汇率、软件授权与设备绑定、内容审核、cmshopee 专用端点、每日生成配额。
风险与待定
- 上传数量/大小/MIME/像素、超时/lease/worker、限流的生产值；
- 首个真实 Provider/模型和连通性测试最小请求；
- 生成物保留期、备份、磁盘告警、RPO/RTO；
- 未来公开注册及账号验证/找回/反滥用流程；
- 固定 go-admin 版本后续升级策略；升级必须重新审查生成器权限和技术栈，不能静默漂移。
登记规则
每一行代表一项长期需求或稳定需求领域，不代表一个普通 Bug。至少填写：
- 清楚、稳定的需求名称；
- 谁在什么场景下需要它；
- 当前状态和所属版本、MVP 或发布范围；
- 唯一的详细 Wiki 页面；
- 当前或主要实施工单；
- 原型状态或明确写“无”；
- 已交付时的任务归档或验收入口。
需求正文、接口细节、业务规则和验收标准只在各自事实来源修改。本页使用一至两句话摘要并链接过去，不复制大段内容。
原型与设计资产
原型门禁
先选择最低成本、足以确认需求的设计证据：
| 修改类型 | 是否建单 | 原型或替代证据 |
|---|---|---|
| 纯界面显示文案，且不改变语义、流程、权限、状态、接口、高风险文字、国际化键、程序标识符、布局或可访问性 | 否 | 无原型，只做最小界面检查 |
| 现有界面的小范围样式或布局调整 | 是 | 标注截图、低保真图或明确复用的现有规范 |
| 新组件但沿用现有设计体系 | 是 | 组件状态和边界说明，按需提供低保真图 |
| 新页面、独立用户功能、重大交互或导航变化 | 是 | Quant-UX 或其他工具制作并经用户确认的可审阅原型 |
| 后端、接口、数据或定时任务 | 是 | 架构、API、数据、状态或流程设计，不强制 UI 原型 |
| 恢复既有确认行为的 Bug | 是 | 原设计、截图、复现步骤或已有验收证据 |
“文字豁免”只指用户看到的显示文案，不包括代码组件名、类名、变量、API 字段、数据库字段或国际化键。任何条件不明确时都要建单。
新增页面、独立用户功能、重大交互或导航变化的顺序固定为：确认文字需求 → 制作可审阅原型 → 用户确认原型和覆盖范围 → 建立或放行实现工单 → 编写生产代码。原型发生影响页面结构、主要流程、状态、权限、异常处理或验收结果的变化时，必须重新确认。
本地 HTML 审核快照
需要完整原型门禁的新页面、独立用户功能、重大交互或导航变化，在用户审核前把 Quant-UX 或等效设计源的待审核版本生成到 prototypes/<工单号>/<版本>/index.html。版本目录内的资源使用相对路径，快照应在本地可浏览；如果必须启动静态服务，在工单记录最小启动命令。可编辑设计源仍以原设计工具为准，Git HTML 是不可覆盖的版本化审核证据，Wiki 和工单负责索引。
已确认快照不得原位覆盖。页面结构、流程、状态、权限、异常处理或验收结果变化时创建新版本目录、重新导出并重新确认。审核前检查页面、交互和资源完整性，并删除凭据、账号、个人信息和生产数据。纯显示文案、小范围 UI、非 UI 需求和恢复既有行为的 Bug 不强制生成 HTML。
设计工具无法生成可用 HTML 时，工单记录限制并停止审核，等待用户确认等效的本地可浏览方案；不能把难以访问的线上链接直接当作已确认原型。
原型确认记录
原型或替代设计证据至少记录链接/路径、版本/revision或确认日期、状态、确认人、确认时间和覆盖范围。外部原型需要保留可追溯版本；重要已确认版本按需保存快照。没有 UI 原型时，记录采用的技术设计或无需原型的原因。
- 与代码版本绑定的图片、HTML 交互稿和设计源文件放入 Git 的
design/或prototypes/，不要手工放入 Wiki 镜像目录docs/。 - #17 管理端运营原型：
prototypes/17/v1/index.html，v1，2026-08-21，状态“已确认”；由用户于 2026-08-21 验收通过，覆盖四类标准 CRUD、路由池编排、Provider 健康/主动探测、生成记录详情，以及加载、空、错误、无权限和边界状态。 - #18 用户端增强原型：
prototypes/18/v1/index.html，v1，2026-08-21，状态“已确认”；由用户于 2026-08-21 验收通过，覆盖文生图、图片编辑、role_rule 覆盖、每图 role/note/order、键盘排序与历史增量加载/失败恢复/到底状态。 - 外部 Figma 等原型记录可访问链接、版本或确认日期、负责人和适用需求；重要的已确认版本保留可追溯快照。
- 原型必须标记“草稿、已确认、已废弃”之一。草稿不能作为正式实现依据；已废弃原型保留状态和替代入口，不让 Agent 误用。
- 原型只表达界面和交互意图，不能代替文字业务规则、安全边界、异常处理和验收标准。
- 没有原型时写“无”和原因，不创建空图片、空目录或占位原型。
- 原型包含账号、个人信息或生产数据时必须先脱敏；凭据不得进入原型或截图。
状态规则
需求状态使用：待确认、已确认、开发中、待验收、已交付、已停止。
- 方案未确认时为“待确认”；用户确认后才能进入“已确认”。
- 开始执行单元任务后为“开发中”；实现完成并等待用户确认时为“待验收”。
- 用户明确验收后改为“已交付”。
- 需求取消或被替代时改为“已停止”，并链接原因和替代需求，不删除历史记录。
- 一个需求领域包含多个任务时，以尚未完成的关键任务决定状态，并在状态中简短说明。
更新时机
以下情况必须更新本页：
- 用户确认新的长期产品需求或新需求领域；
- 需求进入开发、待验收、已交付或已停止；
- 需求的正式 Wiki、主要工单、原型或验收入口变化；
- 原型从草稿变为已确认或已废弃；
- MVP、版本范围或用户场景发生变化。
普通内部重构、小缺陷和不改变长期能力的任务只保留在工单，不必进入本页。
最小验收清单
- 新成员能从本页找到每项长期需求的详细说明。
- 状态与相关 Gitea 工单一致。
- 每项已交付需求具有验收入口。
- 原型具有路径或链接、版本和确认状态，或者明确写“无”。
- 本页没有复制完整工单或主题文档。
- 草稿原型没有被描述为正式需求。
- 不包含凭据、个人数据或生产数据。