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

feat: 按确认原型实现 portal 用户界面 #12

New Issue
Closed
opened 2026-08-20 18:01:04 +08:00 by ila · 0 comments
ila commented 2026-08-20 18:01:04 +08:00
Owner
Copy Link
Copy Source

基本信息

  • 类型：需求
  • 所属 Epic：#3
  • 所属 MVP / 版本：#4（MVP-0）
  • 阶段：已完成

依赖与并行

  • 前置工单：#2（已完成）、#11
  • 是否允许与前置工单并行：是；可与 Provider/worker 工单并行，但最终 E2E 需要完整 worker
  • 原因：依赖项定义本工单所需的可执行环境、共享模型、接口或已确认设计；未满足时保持待实施，不标记阻塞。

子项目影响

  • 仅影响的子项目 / 交付单元：portal templates/static
  • 是否跨子项目：否
  • 是否修改共享接口或契约：否；消费已确认的 portal 接口和状态契约
  • 各子项目需要执行的验证：见“验证方式”和验收标准。

原始需求

  • 来源：用户对话；Product-Requirements-Overview、Architecture-and-Code-Map、Business-Rules-and-Glossary
  • 提出时间：2026-08-20
  • 关键原话或脱敏摘要：用户要求“为 MVP-0 的生产实现拆分单元工单”；本工单负责 按已确认 v1 原型实现 portal 服务端渲染、HTMX 状态和响应式界面。

要解决什么

HTML 原型已经验收，但生产 portal 尚无模板、样式和 HTMX 行为。本工单把 v1 的结构和状态落到 html/template + HTMX + Alpine + Tailwind，并连接已完成的认证/提交/查询接口。

做什么 / 不做什么

做

  • 实现登录页、应用外壳、历史列表、结果区、文本/图片输入和上传列表。
  • 实现 pending/running 轮询、终态停止、文本复制、图片查看/下载、失败重试入口。
  • 实现上传错误焦点、轮询网络错误保留内容、认证过期停止轮询并登录后返回上下文。
  • 桌面历史+主工作区双栏、平板收窄、手机当前结果/输入/历史单列。
  • 使用本地固定的 HTMX/Alpine/Tailwind 产物或可复现构建，不依赖运行时 CDN。

不做

  • 不保留原型“状态预览”控制，不伪造历史或结果。
  • 不实现公开注册、点数/API Key 导航、role/note/拖拽、无限滚动或移动抽屉。
  • 不改业务状态机、权限和 API 契约；必要变化先更新前置工单/原型。
  • 不改 admin/admin-ui。

已确认方案

  • html/template 是首屏和片段事实来源；HTMX 只替换明确片段，Alpine 仅用于局部交互。
  • 所有输入有持久 label，错误不只靠颜色，图标有可访问名称，触控目标至少 44px。
  • 路由/片段替换管理焦点，状态使用合适 aria-live，toast 不抢焦点，动效尊重 reduced motion。

预计修改文件：

  • portal/web/templates/
  • portal/web/static/
  • Tailwind standalone 输入/产物和可重复命令
  • 浏览器 E2E 测试

需求变化记录

无。实现中若范围、接口、数据、依赖、验收或风险发生变化，必须先更新本工单；改变已确认结果时重新等待用户确认。

设计与原型门禁

  • 修改类型：新页面生产实现，复用已确认原型
  • 所需设计证据：prototypes/2/v1/index.html
  • 版本/状态：v1，用户于 2026-08-20 确认；工单 #2 已完成
  • 覆盖范围：登录、文本/图片输入、历史、pending/running/终态、上传错误、轮询错误、认证过期、响应式和无障碍
  • 页面结构、流程、状态、权限或异常处理若需要改变，先创建 prototypes/<新工单>/v2 或等效新版本并重新确认，不得覆盖 v1 后直接实现

文档影响

  • 不影响长期文档
  • 按实际变化更新 Project-Profile、Architecture-and-Code-Map、Local-Development-and-Verification、Deployment-and-Operations 或 Business-Rules-and-Glossary
  • Wiki 先改、在线回读后再同步 docs/，不得直接维护镜像

交付文档影响

  • 更新已有交付界面实现，目标受众：终端种子用户
  • 需要用户/目标岗位验证；依据已确认 v1 做实现后人工验收
  • 新增独立交付文档

验收标准

  • 登录、空状态、文本/图片输入、上传错误、pending、running、图片/文本成功、失败、轮询错误、认证过期和历史到底均连接真实 handler 状态。
  • 终态停止轮询；网络错误保留当前内容；认证过期停止轮询并可返回原上下文。
  • 第一张图片为主图、其余参考图，无 MVP-1 控件和未实现导航。
  • 375、768、1024、1440px 无主区域横向滚动、遮挡或文字溢出。
  • 键盘、44px 目标、label、焦点、对比度、aria-live、reduced motion 和登录错误流程通过。
  • 无运行时 CDN，静态资源可复现且生产页面无状态预览/模拟数据。

验证方式

  • go test ./portal/...
  • Playwright 浏览器 E2E：375/768/1024/1440
  • 键盘遍历、焦点、aria-live、终态停止与认证过期检查
  • 静态资源离线/无 CDN 检查
  • 与 prototypes/2/v1/index.html 的状态矩阵逐项核对

未执行或因环境不足无法执行的验证必须如实回写，不得把预期结果记为通过。

风险和回退

  • 风险：实现偏离已确认原型或把 MVP-1 控件提前加入；逐项对照 #2，变化先重新设计确认。
  • 风险：HTMX 片段替换丢失焦点/轮询重复；用浏览器 E2E 覆盖真实路由。
  • 回退：回退本工单模板/静态提交；保留已确认 v1，不原位修改它。

实施结果

  • 初始生产实现：dad14b1。
  • 异常状态和测试闭环：d7233d4。
  • 核心 Wiki 镜像：9521fbb。
  • E2E 固定幂等任务：3d1c4df。
  • 以上提交已推送到 main。
  • 实施中发现并修复真实断网触发 HTMX sendError 时没有展示恢复提示的问题；没有改变已确认页面结构、流程、权限或验收结果，无需更新原型版本。
  • 前端锁文件安装与构建通过；四视口 Playwright 连续两轮均为 4/4 通过，截图已检查。
  • go build ./...、go vet ./...、串行全仓库测试及 queue/portal race 测试通过。
  • Harness 严格检查、42 项 Harness 单元测试、Wiki 镜像检查和 git diff --check 通过。
  • Wiki revisions：Architecture 08b7352c995a、Local Development 357def01026f、Deployment 23cabbc25081、Project Profile 9e3b50db59ed、Product Requirements f7337354be2c。
  • 任务归档：Task-12-按确认原型实现-portal-用户界面@12e6b7d579fb。
  • 未验证：未调用真实上游或生产环境；完整 worker 浏览器闭环属于 #13。
  • 状态：待用户验收，工单保持打开。

验收结论

  • 用户于 2026-08-21 明确确认 #12 验收通过。
  • 验收文档提交：9c31b9a，已推送到 main。
  • Product Requirements Wiki revision：267432ac79eb。
  • 任务归档 revision：6bcc4f8ec8c8。
## 基本信息 - 类型：需求 - 所属 Epic：#3 - 所属 MVP / 版本：#4（MVP-0） - 阶段：已完成 ## 依赖与并行 - 前置工单：#2（已完成）、#11 - 是否允许与前置工单并行：是；可与 Provider/worker 工单并行，但最终 E2E 需要完整 worker - 原因：依赖项定义本工单所需的可执行环境、共享模型、接口或已确认设计；未满足时保持待实施，不标记阻塞。 ## 子项目影响 - 仅影响的子项目 / 交付单元：portal templates/static - 是否跨子项目：否 - 是否修改共享接口或契约：否；消费已确认的 portal 接口和状态契约 - 各子项目需要执行的验证：见“验证方式”和验收标准。 ## 原始需求 - 来源：用户对话；Product-Requirements-Overview、Architecture-and-Code-Map、Business-Rules-and-Glossary - 提出时间：2026-08-20 - 关键原话或脱敏摘要：用户要求“为 MVP-0 的生产实现拆分单元工单”；本工单负责 按已确认 v1 原型实现 portal 服务端渲染、HTMX 状态和响应式界面。 ## 要解决什么 HTML 原型已经验收，但生产 portal 尚无模板、样式和 HTMX 行为。本工单把 v1 的结构和状态落到 html/template + HTMX + Alpine + Tailwind，并连接已完成的认证/提交/查询接口。 ## 做什么 / 不做什么 ### 做 - 实现登录页、应用外壳、历史列表、结果区、文本/图片输入和上传列表。 - 实现 pending/running 轮询、终态停止、文本复制、图片查看/下载、失败重试入口。 - 实现上传错误焦点、轮询网络错误保留内容、认证过期停止轮询并登录后返回上下文。 - 桌面历史+主工作区双栏、平板收窄、手机当前结果/输入/历史单列。 - 使用本地固定的 HTMX/Alpine/Tailwind 产物或可复现构建，不依赖运行时 CDN。 ### 不做 - 不保留原型“状态预览”控制，不伪造历史或结果。 - 不实现公开注册、点数/API Key 导航、role/note/拖拽、无限滚动或移动抽屉。 - 不改业务状态机、权限和 API 契约；必要变化先更新前置工单/原型。 - 不改 admin/admin-ui。 ## 已确认方案 - html/template 是首屏和片段事实来源；HTMX 只替换明确片段，Alpine 仅用于局部交互。 - 所有输入有持久 label，错误不只靠颜色，图标有可访问名称，触控目标至少 44px。 - 路由/片段替换管理焦点，状态使用合适 `aria-live`，toast 不抢焦点，动效尊重 reduced motion。 预计修改文件： - `portal/web/templates/` - `portal/web/static/` - Tailwind standalone 输入/产物和可重复命令 - 浏览器 E2E 测试 ## 需求变化记录 无。实现中若范围、接口、数据、依赖、验收或风险发生变化，必须先更新本工单；改变已确认结果时重新等待用户确认。 ## 设计与原型门禁 - 修改类型：新页面生产实现，复用已确认原型 - 所需设计证据：`prototypes/2/v1/index.html` - 版本/状态：v1，用户于 2026-08-20 确认；工单 #2 已完成 - 覆盖范围：登录、文本/图片输入、历史、pending/running/终态、上传错误、轮询错误、认证过期、响应式和无障碍 - 页面结构、流程、状态、权限或异常处理若需要改变，先创建 `prototypes/<新工单>/v2` 或等效新版本并重新确认，不得覆盖 v1 后直接实现 ## 文档影响 - [ ] 不影响长期文档 - [x] 按实际变化更新 Project-Profile、Architecture-and-Code-Map、Local-Development-and-Verification、Deployment-and-Operations 或 Business-Rules-and-Glossary - Wiki 先改、在线回读后再同步 `docs/`，不得直接维护镜像 ## 交付文档影响 - [x] 更新已有交付界面实现，目标受众：终端种子用户 - [x] 需要用户/目标岗位验证；依据已确认 v1 做实现后人工验收 - [ ] 新增独立交付文档 ## 验收标准 - [x] 登录、空状态、文本/图片输入、上传错误、pending、running、图片/文本成功、失败、轮询错误、认证过期和历史到底均连接真实 handler 状态。 - [x] 终态停止轮询；网络错误保留当前内容；认证过期停止轮询并可返回原上下文。 - [x] 第一张图片为主图、其余参考图，无 MVP-1 控件和未实现导航。 - [x] 375、768、1024、1440px 无主区域横向滚动、遮挡或文字溢出。 - [x] 键盘、44px 目标、label、焦点、对比度、aria-live、reduced motion 和登录错误流程通过。 - [x] 无运行时 CDN，静态资源可复现且生产页面无状态预览/模拟数据。 ## 验证方式 - `go test ./portal/...` - Playwright 浏览器 E2E：375/768/1024/1440 - 键盘遍历、焦点、aria-live、终态停止与认证过期检查 - 静态资源离线/无 CDN 检查 - 与 `prototypes/2/v1/index.html` 的状态矩阵逐项核对 未执行或因环境不足无法执行的验证必须如实回写，不得把预期结果记为通过。 ## 风险和回退 - 风险：实现偏离已确认原型或把 MVP-1 控件提前加入；逐项对照 #2，变化先重新设计确认。 - 风险：HTMX 片段替换丢失焦点/轮询重复；用浏览器 E2E 覆盖真实路由。 - 回退：回退本工单模板/静态提交；保留已确认 v1，不原位修改它。 ## 实施结果 - 初始生产实现：`dad14b1`。 - 异常状态和测试闭环：`d7233d4`。 - 核心 Wiki 镜像：`9521fbb`。 - E2E 固定幂等任务：`3d1c4df`。 - 以上提交已推送到 `main`。 - 实施中发现并修复真实断网触发 HTMX `sendError` 时没有展示恢复提示的问题；没有改变已确认页面结构、流程、权限或验收结果，无需更新原型版本。 - 前端锁文件安装与构建通过；四视口 Playwright 连续两轮均为 4/4 通过，截图已检查。 - `go build ./...`、`go vet ./...`、串行全仓库测试及 queue/portal race 测试通过。 - Harness 严格检查、42 项 Harness 单元测试、Wiki 镜像检查和 `git diff --check` 通过。 - Wiki revisions：Architecture `08b7352c995a`、Local Development `357def01026f`、Deployment `23cabbc25081`、Project Profile `9e3b50db59ed`、Product Requirements `f7337354be2c`。 - 任务归档：`Task-12-按确认原型实现-portal-用户界面@12e6b7d579fb`。 - 未验证：未调用真实上游或生产环境；完整 worker 浏览器闭环属于 #13。 - 状态：待用户验收，工单保持打开。 ## 验收结论 - 用户于 2026-08-21 明确确认 #12 验收通过。 - 验收文档提交：`9c31b9a`，已推送到 `main`。 - Product Requirements Wiki revision：`267432ac79eb`。 - 任务归档 revision：`6bcc4f8ec8c8`。
ila closed this issue 2026-08-21 11:51:49 +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#12