aitori-stylist/docs/superpowers/specs/2026-06-28-dashboard-workbench-minimal-entry-design.md

工作台页面最小入口版设计

背景

当前项目已经完成第一个 case: 美发师最小闭环登录。登录成功后，用户会进入后台工作台页面 DashboardPage。但当前工作台页面仍然保留了较多“像是已完成、实际上并未进入当前开发范围”的内容，包括:

• 欢迎区右侧的“今日预约 / 待跟进”统计提示
• 4 个统计卡
• 今日顾客
• 待跟进顾客
• 最近施术记录
• 这些区块下的列表渲染、按钮跳转和相关接口请求

现阶段用户要求以自己的需求为准，将工作台页面收敛成一个“当前版本最小可用入口页”: 只保留 3 个主操作卡片作为可用入口，其余区域统一明确为“当前版本未开发”，同时删除除 UI 外的无效逻辑，避免前端表现误导用户。

用户还要求把 Git 流程纳入本 case 的执行范围。由于当前项目尚未被 Git 管理，因此需要先初始化仓库，再将登录 case 形成基线提交，然后在新的分支上开发本 case，开发完成后再合并回主分支。

目标

• 将工作台页面收敛为“最小入口版”。
• 页面只保留 3 个主操作卡片为真实可点击入口。
• 欢迎区显示当前登录用户的真实用户名，而不是固定文案。
• 将其余统计、列表、记录区块统一改为未开发态展示。
• 删除这些未开发区块背后的数据请求、状态管理和交互逻辑。
• 在代码中补充清晰注释，便于后续恢复开发。
• 将 Git 初始化、基线提交、新分支开发和合并流程纳入执行。
• 同步调整登录相关文档，记录工作台对 token 用户名字段的依赖。

非目标

• 本 case 不开发预约系统。
• 本 case 不开发顾客跟进系统。
• 本 case 不开发工作台统计接口。
• 本 case 不开发工作台列表接口。
• 本 case 不新增新的工作台专属后端接口。
• 本 case 不恢复“最近施术记录”等区块的数据渲染。
• 本 case 不引入复杂的工作台状态机或缓存策略。

设计原则

• 工作台只暴露当前真正可用的入口，不展示“看似能用”的半成品能力。
• 未开发区域要明确可感知，不做假数据充数，不伪装成已实现功能。
• 当前版本能删掉的无效逻辑就删掉，只保留对 UI 占位真正有帮助的结构。
• 前端优先复用现有页面布局和 copy，避免不必要的重写。
• 用户名展示优先复用登录 token，而不是为了工作台额外增加 /me 依赖。
• 注释必须具体说明未来要恢复哪类业务数据，不写泛泛的 TODO。
• Git 流程视为本 case 的前置工程要求，而不是独立附加事项。

当前页面现状

当前 frontend/src/pages/dashboard/DashboardPage.tsx 具有以下行为:

• 页面初始化时会并行请求:
  • getWorkbenchData()
  • getCustomerDashboardSummary()
  • getTemplateDashboardSummary()
  • getStylistMe()
• 欢迎区会根据当前时间生成问候语，并显示 stylistName
• 右上角显示“今日预约 X 件 / 待跟进 X 件”
• 页面中部显示 3 个主操作卡片
• 页面下方显示 4 个统计卡
• 页面更下方显示今日顾客、待跟进顾客、最近施术记录 3 个模块

这意味着当前页面把“入口能力”和“工作台数据聚合能力”耦合在了一起，不符合当前阶段最小可用范围。

方案选择

本 case 最终采用“最小收缩版工作台”方案:

• 保留现有页面骨架、排版层级和 3 个入口卡片。
• 删除不属于当前开发范围的数据请求和渲染逻辑。
• 将非本期能力明确收敛为未开发态 UI。

不采用以下方案:

• 完全静态重写版: 改动过大，后续恢复各区块时返工更多。
• 接口预留壳子版: 会保留当前无价值的 state 和请求代码，不符合“除了 UI 以外逻辑都去掉”的要求。

页面结构设计

1. 欢迎区

欢迎区保留以下内容:

• 时间问候语: 早上好 / 下午好 / 晚上好
• 当前登录用户名
• 工作台说明文案

用户名显示规则:

• 由当前登录 token 解析得到。
• 不再通过 getStylistMe() 额外请求。

原因:

• 当前页面不需要为了欢迎语发起额外接口请求。
• 登录 token 已经是当前登录身份的本地载体，工作台应优先复用它。

2. 欢迎区右侧统计文案

当前右上角“今日预约 0 件 / 待跟进 0 件”在本版本中隐藏:

• 页面上不显示该行文案。
• 代码中保留一条注释，明确说明欢迎区统计当前版本未开发，未来再接预约/跟进真实数据。

原因:

• 该信息目前没有真实业务来源。
• 显示 0 会给用户造成“系统已经实现，只是暂时没有数据”的错误认知。

3. 三个主操作卡片

这 3 个卡片是当前页面唯一可点击的真实入口:

1. 新建顾客 -> /customers/new
2. AI 发型模拟 -> /simulation
3. 发型模板 -> /templates

要求:

• 保留当前卡片视觉层次和按钮可点击状态。
• 不增加新的入口卡片。
• 不改变这 3 个入口的路由目标。

4. 四个统计卡

统计卡区块继续保留布局，但进入未开发态:

• 保留 4 卡并列布局。
• 不再显示真实统计数字。
• 数字位置显示占位，例如 --。
• 卡片说明文字保留，但卡片整体置灰。
• 增加“当前版本暂未开发”说明文案。

对应逻辑要求:

• 删除 customerSummary
• 删除 templateSummary
• 删除 getCustomerDashboardSummary()
• 删除 getTemplateDashboardSummary()

原因:

• 当前版本不开发这些统计能力。
• 保留数据请求只会制造维护成本和错误联想。

5. 今日顾客 / 待跟进顾客 / 最近施术记录

这 3 个大区块保留标题和板块结构，但统一改为未开发态:

• 区块标题继续显示，页面视觉结构不塌。
• 区块内容替换为统一的置灰空状态。
• 显示“当前版本暂未开发”的明确文案。
• 不再显示任何列表项。

对应逻辑要求:

• 删除 dashboardData 相关 state
• 删除 getWorkbenchData()
• 删除 appointments
• 删除 followUps
• 删除 records
• 不再渲染列表映射逻辑

未开发态交互设计

1. 未开发区块按钮

未开发区块中的按钮不再保留真实导航逻辑:

• 优先改为禁用态按钮
• 视觉上明确不可点击
• 同时通过按钮文案或邻近说明告诉用户“当前版本暂未开发”

不采用“保留点击后再 toast 提示”的方案，原因如下:

• 当前能力明确未开发，禁用态更直接
• 可以减少无意义点击与额外交互噪声
• 更符合“只有 3 个卡片可点击”的版本边界

2. 只有三张卡片可点击

工作台页面最终交互规则是:

• 只有 3 个主操作卡片可点击
• 其余区域全部不可进入新页面
• 用户不会被误导去尝试尚未实现的工作流

用户名来源设计

Token 载体

为支持欢迎区显示当前登录用户名，本 case 要求登录 token payload 承载最小必要字段:

• sub
• email
• username

这意味着本 case 会联动调整登录 token 契约。

前端解析方式

前端新增一个轻量工具用于解析当前 token 中的用户信息:

• 只负责安全地读取 payload
• 只消费当前工作台需要的字段
• 不引入 JWT 校验逻辑
• 失败时返回空值，避免页面崩溃

说明:

• 前端本地解析 token 只用于展示用户名，不用于鉴权决策。
• 实际鉴权仍然以 token 是否存在及后端校验结果为准。

注释策略

本 case 要求在以下位置保留明确注释:

• 欢迎区被隐藏的统计文案附近
• 4 个统计卡的未开发态结构附近
• 今日顾客 / 待跟进顾客 / 最近施术记录区块附近
• token 解析用户名的工具附近

注释原则:

• 不写“TODO: 后面再做”
• 要直接说明“未来应从哪个业务域或接口恢复”
• 示例表达方向:
  • 当前版本未开发预约/跟进统计，后续从 workbench 聚合接口恢复
  • 当前版本未开发顾客/记录列表，后续从工作台聚合数据恢复

需要移除的前端逻辑

本 case 完成后，DashboardPage 中应移除以下非必要逻辑:

• getWorkbenchData()
• getCustomerDashboardSummary()
• getTemplateDashboardSummary()
• getStylistMe()
• dashboardData state
• customerSummary state
• templateSummary state
• stylistName 由远程接口赋值的逻辑
• 今日顾客 / 待跟进顾客 / 最近施术记录的列表渲染逻辑

保留:

• 时间问候语逻辑
• 页面布局结构
• 3 个主入口卡片
• 解析 token 获取用户名的本地逻辑

Git 流程设计

当前项目尚未被 Git 管理，因此本 case 的执行前置流程如下:

1. 在项目根目录执行 git init
2. 将当前已完成的“登录 case”代码和文档形成基线提交
3. 以主分支作为基础，创建新的工作分支开发第二个 case
4. 第二个 case 开发完成后合并回主分支

说明:

• 因为仓库此前不存在，所以“基线提交”不是额外优化，而是本 case 正式开发所需前置条件。
• 第二个 case 需要在独立分支开发，以满足用户要求并隔离本次页面收缩改动。

文档联动更新

本 case 除新增工作台 spec 外，还需要同步更新前一个登录 case 文档中的相关说明:

• 登录 token payload 将新增 username
• 工作台欢迎区将直接消费 token 中的 username

原因:

• 否则文档会落后于实际契约
• 后续开发者或 AI 只看登录文档时，会漏掉这条联动关系

测试策略

后端

后端测试只覆盖本 case 直接依赖的登录契约变化:

• 登录成功签发 token 时包含 username
• 现有登录测试更新到新 payload 约束

本 case 不新增工作台后端接口测试。

前端

前端测试重点如下:

• 欢迎区显示从 token 解析出来的用户名
• 页面只保留 3 个真实可点击卡片
• 右上角“今日预约 / 待跟进”文案不显示
• 4 个统计卡显示为未开发态
• 3 个大区块显示为未开发态
• 未开发区块的按钮不可跳转

手工验收

手工验收至少包括:

• 登录后进入工作台
• 欢迎语里显示当前登录用户名
• 点击 3 个主入口卡片，跳转到正确页面
• 其余区域无法进入新页面
• 页面视觉结构完整，无明显塌陷或错位

验收标准

• 登录后进入工作台时，欢迎区显示当前登录用户名，而不是固定写死名称。
• 页面上只有 3 个主操作卡片可以点击。
• 右上角“今日预约 / 待跟进”统计文案不再显示。
• 4 个统计卡显示为未开发态，不再依赖真实统计请求。
• 今日顾客、待跟进顾客、最近施术记录 3 个区块显示为未开发态。
• 未开发区块中的按钮不再保留真实跳转行为。
• DashboardPage 中与这些未开发区块相关的数据请求和 state 已被移除。
• 代码中存在清晰注释，说明未来从哪个业务域恢复这些能力。
• 项目完成 Git 初始化，并形成登录 case 基线提交。
• 第二个 case 在新分支开发并最终合并回主分支。

推荐的下一步

在本设计确认后，下一步进入实现计划阶段，拆分为:

1. 初始化 Git 仓库并建立登录 case 基线提交。
2. 创建第二个 case 的开发分支。
3. 调整登录 token payload，加入 username。
4. 重构工作台页面为最小入口版。
5. 更新相关测试与登录文档。
6. 验收后合并回主分支。