# Web 管理端 Fresh Mint 改造记录与后续路线图

> **目的**：集中记录已落地的改造、涉及文件与设计依据，便于后续按同一标准继续改 `web-admin`，并与 `docs/web-admin-ui-spec-fresh-mint.md`、`test/fresh-mint-green.html` 对齐。

---

## 1. 设计权威（后续改样式前先读）

| 来源 | 路径 | 说明 |
|------|------|------|
| 视觉规范（详细 Token / 组件） | `docs/web-admin-ui-spec-fresh-mint.md` | 正文 + 附录 |
| 对照 HTML | `test/fresh-mint-green.html` | 冲突以 HTML 为准 |
| 项目规则摘要 | `.cursorrules` →「Web端 - Fresh Mint」与硬提醒章节 | 章节号指向规范文档 |

---

## 2. 已完成的改造（按主题）

### 2.1 设计令牌与全局变量

- 新增 **`web-admin/src/assets/styles/core/fresh-mint-tokens.scss`**，在 **`web-admin/src/assets/styles/index.scss`** 最前 `@use`，提供 `--mint-primary`、`--mint-border`、`--mint-content-padding` 等。
- 调整 **`web-admin/src/assets/styles/core/tailwind.css`**（浅色 `:root`）：页面底 `#fefefe`、边框 `#d9e8e2`、hover/active 与 demo 对齐。
- **`web-admin/src/assets/styles/core/reset.scss`**：全局 `Inter` 字体栈、14px / line-height 1.5、正文色。

### 2.2 入口与 HTML

- **`web-admin/index.html`**：引入 **Inter**（Google Fonts）、首屏背景 **`#fefefe`**；脚本 **移除 `dark` class** 并写入 **`localStorage['sys-theme'] = 'light'`**。

### 2.3 主题策略：仅浅色

- **`web-admin/src/config/setting.ts`**：默认 `systemThemeType`、`systemThemeMode` 均为 **`LIGHT`**。
- **`web-admin/src/config/index.ts`**：**`settingThemeList` 仅保留 Light 一项**（设置面板不再提供暗色/跟随系统）。
- **`web-admin/src/hooks/core/useTheme.ts`**：重写为 **始终应用浅色**；`switchThemeStyles` 忽略入参；`initializeTheme` 用 **`setGlopTheme(LIGHT, LIGHT)`** 纠正旧持久化，并固定主色、侧栏宽等。
- **`web-admin/src/components/core/layouts/art-settings-panel/composables/useSettingsPanel.ts`**：`initSystemTheme` 固定浅色；**取消 `prefers-color-scheme` 监听**。

### 2.4 布局与壳子

- **`web-admin/src/views/index/style.scss`**：主内容区 **全宽**、**24px** 外边距；`.page-content` 白底、**边框 + 10px 圆角 + 轻阴影**（对齐 demo 卡片）。
- **`web-admin/src/config/setting.ts`**：默认 **`menuOpenWidth: 220`**；`initializeTheme` 中仍会 **将侧栏宽度纠为 220px**（覆盖旧本地持久化）。
- **`web-admin/src/components/core/layouts/art-header-bar/index.vue`**：顶栏高度 **56px（h-14）**、白底 + **底部分割线**。
- **`web-admin/src/components/core/layouts/art-work-tab/index.vue`**：Tab 条 **底边分割**；激活态 **`box-shadow: 0 -2px 0 #10b981 inset`**（对齐 demo Tab）。
- **`web-admin/src/components/core/layouts/art-menus/art-sidebar-menu/theme.scss`**：菜单 hover 背景 **`#fafafa`**。

### 2.5 Element Plus 全局与业务块

- **`web-admin/src/assets/styles/core/el-ui.scss`**：圆角 **8px / 弹窗 10px**；**`.page-container` 内边距 24px**；浅色下 **全局 input/select 描边与主按钮绿**；与 **`.page-container` / `.console-container`** 下表格、弹窗、搜索条等已有「对齐配送调度」段落保持一致或已合并。

### 2.6 登录页与控制台

- **`web-admin/src/views/auth/login/index.vue`**：页面底 **`#fefefe`**；左侧渐变 **薄荷绿系**；文案色与主按钮渐变对齐 Fresh Mint。
- **`web-admin/src/views/dashboard/console/index.vue`**：`.console-container` 使用 **`--mint-content-padding`**、**`#fefefe`** 背景与文字色变量。

### 2.7 构建命令

- **`web-admin/package.json`**：增加 **`build:vite`**（仅 `vite build`，在 `vue-tsc` 未全部修复时便于验证样式与打包）。

---

## 3. 涉及的主要文件清单（便于 Code Review / 继续改）

| 类别 | 文件 |
|------|------|
| 令牌 / 全局样式 | `fresh-mint-tokens.scss`、`index.scss`、`tailwind.css`、`reset.scss`、`el-ui.scss` |
| 布局 | `views/index/style.scss`、`art-header-bar/index.vue`、`art-work-tab/index.vue`、`art-sidebar-menu/theme.scss` |
| 主题逻辑 | `config/setting.ts`、`config/index.ts`、`hooks/core/useTheme.ts`、`useSettingsPanel.ts` |
| 入口 | `index.html` |
| 页面示例 | `views/auth/login/index.vue`、`views/dashboard/console/index.vue` |
| 工程 | `package.json`（`build:vite`） |

---

## 4. 后续改造思路与建议步骤（统一按规范推进）

以下与此前「8 步主线」一致，并按当前仓库状态做了**增量说明**。

### 阶段 A：列表页模板统一（高优先级）

1. **确认业务页根容器**：列表类页面是否统一使用 **`page-container`**（或等价 class），以便继承 `el-ui.scss` 中 **search-bar / toolbar / el-table / pagination** 的现成规则。
2. **筛选区**：表单项 label **11px 灰色**、栅格间距；与规范 **§5** 对照，不足则在页面或公共组件层补 class。
3. **表格**：表头 `#f8fafc`、斑马纹、hover、金额列强调；需要时 **固定右侧操作列**（Element 表格 `fixed="right"` + 全局样式已部分覆盖）。
4. **分页**：与 demo **§7.8** 对齐（当前多为 `el-pagination`，以全局覆盖 + 页面结构为主）。

### 阶段 B：弹窗与表单

1. **`el-dialog` / `el-drawer`**：标题区、body、footer **灰底条 + 右对齐按钮** 已在 `el-ui.scss` 多处落地，新建弹窗尽量复用 **同一 DOM 结构/class**（如 `dialog-footer`、`form-section`）。
2. **详情弹窗**：大弹窗内 **Hero / KV / 分节** 按规范 **§9** 逐步组件化（可先挑 1～2 个业务页试点）。

### 阶段 C：进阶组件

1. **树形 / 子表、迷你表、上传区**：规范 **§8、§10**；业务出现再套，避免过早抽象。
2. **Tab 刷新遮罩、按钮 Loading**：规范附录与 **§6**；按需与产品确认是否实现。

### 阶段 D：授权子系统（注册 / 忘记密码）

1. 当前 **注册 / 忘记密码** 使用 **`LoginLeftView` + `AuthTopBar`**，左侧装饰色多依赖 **`--el-color-primary-*`**，主色已为薄荷绿，整体会偏绿。
2. 若需与 **独立登录页** 完全一致（整页底 `#fefefe`、同一套左右比例），可单独排期改 **`LoginLeftView`** 或拆一套「简化授权布局」。

### 阶段 E：工程与类型

1. **`pnpm run build`**：含 **`vue-tsc`**，当前仓库可能存在 **历史 TS 报错**；样式与打包验证可先用 **`pnpm run build:vite`**（见 `package.json`）。
2. 类型问题建议 **按模块分批修复**，与 UI 改造可并行，避免混在同一 PR 难以 review。

### 阶段 F：文档与规范同步

1. 每完成一大块 UI 改造，**回写** `docs/web-admin-ui-spec-fresh-mint.md` 中「实现差异说明」（若有）或仅在本文件 **§2** 追加一条记录即可。
2. **`.cursorrules`** 中「硬提醒」章节号若随规范文档结构调整，需同步更新。

---

## 5. 验收建议（每阶段可重复）

- 与 **`test/fresh-mint-green.html`** 并排对照：**侧栏、顶栏、内容区 padding、Tab、主按钮、表格头/行、分页、弹窗底栏**。
- 浏览器 **仅浅色**：`document.documentElement` **无 `dark` class**，刷新后 **`sys-theme` 为 `light`**。
- 控制台无 **与本次样式相关的** 报错；打包执行 **`pnpm run build:vite`** 通过。

---

## 6. 修订记录

| 日期 | 说明 |
|------|------|
| 2026-04-16 | 初版：记录已落地的 Fresh Mint + 仅浅色改造及后续路线图 |

后续若有大块改造，请在本表追加一行并简要列出关联 PR 或提交说明。