# 工作台页面最小入口版设计 ## 背景 当前项目已经完成第一个 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. 验收后合并回主分支。