# M9 / issue-43 开发日志：admin 后台信息架构与仪表盘壳整理

- Issue：#77
- 里程碑：M9 体验基线与主题边界：从可用到可继续设计
- 分支：`fys-dev/feat-m9-issue-43-admin-dashboard-shell`
- 日期：2026-03-26

## 背景

`issue-42` 完成后，后台已经具备统一主题基线，但首页仍然更像联调壳：

- 角色信息、草稿编辑、发布动作、导出入口只是顺序堆叠
- 页面虽然能跑，但“信息区 / 工作区 / 动作区 / 状态区”的边界不够清楚
- 后续如果直接进入更多后台能力或视觉升级，页面结构会越来越难解释

因此这一轮的目标不是扩功能，而是先把后台首页整理成一张更像“控制台入口”的页面。

## 本次目标

- 重组后台首页信息架构
- 收拢当前保存 / 发布 / AI / 导出入口的页面层次
- 让 `admin / viewer` 差异在页面级更容易感知
- 保持当前任务只整理后台壳，不新增业务接口

## 非目标

- 不引入第三方完整 admin 模板
- 不扩展复杂 CMS 或多页面后台
- 不修改现有草稿、发布、AI、导出接口语义
- 不顺手推进公开页视觉升级

## TDD / 测试设计

这次先补“后台壳是否真的形成清晰页面结构”的测试，再做布局重排。

### 1. 壳层结构测试

新增：

- `apps/admin/components/admin-dashboard-shell.spec.tsx`

验证：

- 未登录时仍回到最小受保护壳
- `admin` 登录后能看到清晰的控制台结构和核心区块
- `viewer` 登录后能在页面级看到只读体验提示

这里刻意把子面板 mock 掉，目的是只测“后台壳的组织方式”，而不是重复覆盖草稿编辑或动作面板自身逻辑。

### 2. 现有后台子面板回归

执行：

- `pnpm --filter @my-resume/admin test`

确保：

- 草稿编辑面板
- 角色动作面板
- 导出入口
- 主题切换

在新壳结构下仍保持原有行为。

### 3. 工程级验证

执行：

- `pnpm --filter @my-resume/admin typecheck`
- `pnpm --filter @my-resume/admin build`
- admin / viewer 实际登录后台页进行人工验证

用来确认后台壳整理没有破坏 Next.js 页面构建与类型边界。

## 实际改动

### 1. 把后台首页重组为“控制台首页 + 工作区 + 侧栏”

更新：

- `apps/admin/components/admin-dashboard-shell.tsx`

新的结构分成三层：

- 顶部 `dashboard-hero`
- 左侧内容工作区
- 右侧会话 / 动作 / 流程 / 导出侧栏

这样做之后，后台首页不再只是“把已有组件往下堆”，而是明确区分：

- 这页先交代什么
- 用户当前处于什么角色和边界
- 哪些区域负责内容维护
- 哪些区域负责敏感动作和发布流解释

### 2. 把页面级角色体验前置

在英雄区和会话区里，新增了更清晰的页面级信息：

- 当前账号
- 当前角色
- 当前阶段的业务边界
- `viewer / admin` 的页面级说明

这样即使不进入动作面板内部，也能先看明白“我现在能做什么、不能做什么”。

这对教学型后台很重要，因为它降低了读者理解整页结构的成本。

### 3. 新增工作区概览与流程提示

在当前后台壳里，最容易丢失的是“这一页的工作节奏”。所以本次补了两块解释型区域：

- 工作区概览：说明当前先维护什么、为什么草稿和公开态分离
- 流程提示：用三步把编辑、发布、体验 / 导出串起来

这不是业务逻辑扩展，而是把已经存在的链路变得更可解释。

### 4. 样式从单卡片堆叠改成更稳定的 dashboard 布局

更新：

- `apps/admin/app/globals.css`

新增了后台壳专用布局类，例如：

- `dashboard-shell`
- `dashboard-hero`
- `dashboard-overview-grid`
- `dashboard-main-grid`
- `workflow-list`

目标不是做完整视觉系统，而是让后台首页拥有更稳定的信息架构和展示节奏。

### 5. 收拢动作区命名

更新：

- `apps/admin/components/role-action-panel.tsx`

把面板标题从“viewer / admin 能力边界”收成“动作中心”，让它在整页中的职责更清晰：

- 页面级边界说明放到后台壳
- 敏感动作本身放到动作中心

## Review 记录

### 是否符合当前 Issue 与里程碑目标

符合。

本次只做后台首页的信息架构整理，没有越界去做：

- 新接口
- 新业务模块
- 完整 admin 模板
- 公开页改版

### 是否存在可抽离的组件、公共函数、skills 或其他复用能力

当前先不继续抽新共享组件，原因是：

- `issue-45` 会专门处理 `packages/ui` 的最小共享展示组件沉淀
- 这轮的重点是先把后台壳结构理顺，而不是提前把 admin 专用结构共享化

不过本轮已经沉淀出几类后续可复用的页面组织模式：

- 顶部 hero + 说明 badge
- 左右栏 dashboard 布局
- 解释型流程列表

后续如果 `web / admin` 都出现类似结构，再由 `issue-45` 统一抽离会更合适。

### 本次最重要的边界判断

本次没有为了“让后台更像后台”去引入现成 admin 模板，而是继续沿用当前项目已有样式语言，做一版教学友好的信息架构整理。

这个边界很关键。因为如果现在直接上重模板，会把当前真正需要讲清楚的：

- 草稿 / 发布
- 角色边界
- 单后端原则
- 教学型后台节奏

全部埋掉。

## 自测结果

已执行：

- `pnpm --filter @my-resume/admin test`
- `pnpm --filter @my-resume/admin typecheck`
- `pnpm --filter @my-resume/admin build`
- Playwright 实际验证 `admin / viewer` 登录后台页

结果：全部通过。

人工验证结果：

- `admin` 登录后进入 `/dashboard`，页面实际出现：
  - `后台控制台`
  - `内容工作区`
  - `会话与边界`
  - `动作中心`
  - `流程提示`
  - `后台下载入口`
- `viewer` 登录后，页面级提示与动作面板只读提示都成立：
  - `viewer 当前只能体验缓存结果与只读链路，不能触发真实敏感操作。`
  - `当前账号为 viewer，只能查看，不能修改或触发真实操作。`

## 遇到的问题

### 1. `AdminDashboardShell` 之前没有壳层测试

问题：

如果只靠已有子面板测试，很容易把页面结构改散了还不自知。

处理：

- 新增 `admin-dashboard-shell.spec.tsx`
- 用 mock 子面板的方式只测壳层结构和角色级表达

### 2. `Vitest` 的 mock hoist 限制

问题：

在 `admin-dashboard-shell.spec.tsx` 中，直接使用顶层 `vi.fn()` 变量被 `vi.mock()` 工厂引用，会触发 hoist 问题。

处理：

- 改用 `vi.hoisted(...)` 创建 mock 引用

这样既保留了清晰的 mock 结构，也避免测试初始化时机错误。

## 可沉淀为教程/博客的点

- 为什么“页面能跑”不等于“后台首页结构已经成立”
- 教学型后台为什么更适合先做信息架构，而不是先套完整 admin 模板
- 壳层测试为什么要 mock 掉子面板，只测页面组织本身

## 后续待办

- 继续推进 `M9 / issue-44`：web 公开简历页视觉基线升级
- 继续推进 `M9 / issue-45`：最小共享展示组件沉淀
- 后续展示层任务可以继续补强“展示结果是否真正兑现”的验证证据，而不只停留在构建通过
