# 美化治理修改计划（2026-10-20）

> 基于 `docs/beautification-audit-2026-10-20.md`，按 A→F 六批推进，每批独立可提交。

---

## 先决：补令令牌（A 批前必做）

以下 3 个令牌审计报告中已确认缺失或需核对，先补到 `uni.scss` 再进 A 批。

| 新令牌名 | 目标值 | 用途 | 位置 |
|---|---|---|---|
| `$status-disabled` | `#CCC` / `#DDDDDD`（待定，取 `#E0E0E0` 或 `#CCCCCC`） | 灰阶替换占位 | `uni.scss` §13 后 |
| `$facade-hairline-3` | `#EEE` | 对应灰阶硬编码 | `uni.scss` §15 后 |
| `$status-danger-strong-2` | `#C62828` | 已在 §15 末尾定义，但需核对 `status-danger-strong` vs `strong-2` 关系 | 已存在，仅核对 |

> **注意**：`$status-danger-strong-2: #C62828` 已在 uni.scss L622 定义，可直接使用；`$facade-hairline-2: #EEE` 已在 L625 定义，`#EEE` 灰可直接映射；`$facade-hairline-3` 暂无，按需新建为 `#DDDDDD` 或映射已有 `#DDD` 近值。**建议先不新建**，直接用 `$facade-hairline-2: #EEE` 覆盖，`#CCC` 用 `$facade-hairline: #E0E0E0`（L624）。

---

## A 批 · 中性灰阶 + 品牌/状态色令牌化

### 目标
将约 **4,000 处**硬编码灰阶/品牌色替换为等值 SCSS 令牌，零视觉风险。

### 替换对照表

| 硬编码值 | 令牌 | 处数 | 涉及文件（估算） |
|---|---|---|---|
| `#FFF` / `#FFFFFF` | `$app-surface` | 1,203 | 302 |
| `#333` | `$facade-text-strong` | 655 | 202 |
| `#666` | `$facade-text-body` | 273 | 147 |
| `#999` | `$facade-text-muted` | 582 | 186 |
| `#F5F5F5` | `$facade-fill-2` | 212 | 101 |
| `#F0F0F0` | `$facade-fill` | 152 | 96 |
| `#FAFAFA` | `$facade-fill-ghost` | ~60 | 22+ |
| `#F9FAFB` | `$facade-fill-gray-50` | ~60 | 22+ |
| `#CCC` | `$facade-hairline` (`#E0E0E0`) ⚠️ | 95 | 69 |
| `#DDD` | `$facade-hairline-2` (`#EEE`) ⚠️ | 74 | 41 |
| `#EEE` | `$facade-hairline-2` (`#EEE`) ✅ | 71 | 42 |
| `#F97316` | `$brand-primary` | 689 | 166 |
| `#FF8C42` | `$dim-body` | 133 | 37 |
| `#FFF7ED` | `$uni-primary-pale` | 123 | 77 |
| `#FB923C` | `$brand-primary-light` | 92 | 58 |
| `#10B981` | `$status-success` | 108 | 51 |
| `#EF4444` | `$status-danger` | 69 | 43 |
| `#6366F1` | `$dim-wisdom` | 72 | 25 |
| `#C62828` | `$status-danger-strong-2` | 63 | 15 |

### 实施策略

#### 灰阶（#FFF ~ #EEE 共 ~3,100 处）

按分包切片，每片一提交：

1. **切片顺序**（文件数少的先）：
   - 主包 5 个 TabBar 页（index/body/wisdom/mind/wealth）
   - `pages/login`
   - `pages/profile` / `pages/profile-extra`
   - `pages/guide`（11 文件）
   - `pages/tasks`（4 文件）
   - `pages/rewards`（2 文件）
   - `pages/wishes`（3 文件）
   - `pages/games`（5 文件）
   - `pages/assessment`（5 文件）
   - `pages/growth`（6 文件）
   - `pages/activity`（3 文件）
   - `pages/promotion`（6 文件）
   - `pages/membership`（3 文件）
   - `pages/shop`（15 文件，较大，单开）
   - `pages/teacher`（7 文件）
   - `pages/parent`（3 文件）
   - `pages/child`（2 文件）
   - `pages/dan-assessment`、`pages/share`
   - `pages/mind-detail`、`pages/body-detail`、`pages/wisdom-detail`、`pages/action-detail`
   - `pages/tianpan`（7 文件，单独 B 批处理）
   - `pages/article-center`、`pages/health`（18 文件，较大，单开）
   - `components/`（公共组件，单独切片）

2. **灰阶替换脚本**：用 `scripts/audit-beautify-debt.js` 生成 CSV，提取各值分布，写替换脚本。

#### 品牌/状态色（~1,300 处）

同上分包切片，注意：
- `#F97316 → $brand-primary` 是最优先项（166 文件，689 处），一次全切完
- `#FFF7ED → $uni-primary-pale`（77 文件）紧随其后

### 验证方法

- 每个文件替换后用 `node --check` 验证语法（若脚本能提取 script 块）
- 用 `scripts/tmp_c2_verify.js` before+预期替换==after 逐字节验证（如有工具）
- 审计前后跑 `scripts/audit-beautify-debt.js` 看硬编码色总数下降曲线

---

## B 批 · tianpan 家族 px→rpx（7 文件）

### 目标
将 387 处 CSS px 按 `px × 2 = rpx`（375px 基准）转换，7 处 canvas 字号保留。

### 涉及文件（CSS px 由高到低）

| 文件 | CSS px 处数 |
|---|---|
| `pages/tianpan/index.vue` | 85 |
| `pages/tianpan/relation-detail.vue` | 71 |
| `pages/tianpan/member-detail.vue` | 69 |
| `pages/tianpan/traditional.vue` | 60 |
| `pages/tianpan/daily-fortune.vue` | 38 |
| `pages/tianpan/annual-energy.vue` | 36 |
| `pages/tianpan/related-items.vue` | 28 |
| **其余 24 文件** | ~73 |

### 实施步骤

1. 对每个文件，在 `<style>` 块内做正则替换：`(\d+)px` → `$1 * 2rpx`（或用 `(val * 2)rpx` 格式）
2. **保留项**：canvas 绘图的字号（如 `ctx.font = '14px'`）和 canvas 尺寸（`width="375"` 等属性）不转换
3. 用 `dart-sass` 编译验证语法无误
4. `node --check` 验证 JS 语法
5. **真机抽查**：`tianpan/index` 和 `relation-detail` 两页，重点检查绝对定位元素位置是否偏移

### 注意事项

- 转换后个别 375px 固定宽度元素可能在大屏上显得过宽，需确认是否有意为之（375px 基准设计，乘以 2 后在大屏上 = 750rpx ≈ 全屏，符合预期）
- 每文件一提交

---

## C 批 · JS 色板收编（86 文件 969 处）

### 目标
新建 `utils/brand-colors.js` 作为 JS 侧单一色板事实源，替换 86 个文件中硬编码的 hex 字符串。

### 色板结构

```js
// utils/brand-colors.js
export const BrandColors = {
  // 品牌橙族
  primary: '#F97316',
  primaryLight: '#FB923C',
  primaryPale: '#FFF7ED',
  primaryDark: '#EA580C',
  // 五维色
  body: '#FF8C42',
  mind: '#FF6B9D',
  wisdom: '#6366F1',
  action: '#10B981',
  wealth: '#F59E0B',
  // 状态色
  success: '#10B981',
  warning: '#FBBF24',
  danger: '#EF4444',
  // 中性灰
  white: '#FFFFFF',
  textStrong: '#333333',
  textBody: '#666666',
  textMuted: '#999999',
  fill: '#F5F5F5',
  fillGhost: '#FAFAFA',
}

// 导出别名（避免 import 路径散乱）
export const DimColors = BrandColors
export const StatusColors = { success: BrandColors.success, warning: BrandColors.warning, danger: BrandColors.danger }
```

### 优先替换文件（TOP 10）

1. `components/ContentSharePoster.vue`（67 处）
2. `pages/mind/emotion-checkin.vue`（36 处）
3. `components/PearlDiagram.vue`（34 处）
4. `pages/wisdom/energy/index.vue`（34 处）
5. `pages/article-center/ArticleBookshelf.vue`（30 处）
6. `pages/index/home-pages/parent-index.vue`（30 处）
7. `components/FamilyTianpanCard.vue`（29 处）
8. `components/SharePoster.vue`（29 处）
9. `components/PageBanner.vue`（26 处）
10. `pages/tianpan/index.vue`（24 处）

### 实施步骤

1. 建 `utils/brand-colors.js`，按色板簇分批替换（每次一个族）
2. 每个文件替换后 `node --check` 验证 JS 语法
3. **canvas 渲染抽查**：ContentSharePoster、PearlDiagram 两页手动预览
4. 每族一提交（品牌橙→五维色→状态色→中性灰）

---

## D 批 · P0 重债页重制（12 页）

### 建议顺序（业务影响 × 债务）

| 优先级 | 页面 | 路径 | 债务 | 说明 |
|---|---|---|---|---|
| 1 | health-report-detail | `pages/health/report-detail.vue` | 432 | 对外门面，报告核心页 |
| 2 | health-report-confirm | `pages/health/report-confirm.vue` | 420 | 报告确认流程 |
| 3 | health-gut-flora | `pages/health/gut-flora-detail.vue` | 417 | 报告详情子链 |
| 4 | health-plan-summary | `pages/health/health-plan-summary.vue` | 351 | 健康计划总览 |
| 5 | shop-checkout | `pages/shop/checkout/checkout.vue` | 330 | 交易转化关键路径 |
| 6 | parent-index | `pages/index/home-pages/parent-index.vue` | 321 | 家长端首页（流量最大） |
| 7 | health-challenge | `pages/health/challenge-manage.vue` | 321 | 挑战管理 |
| 8 | family-members | `pages/profile-extra/family-members.vue` | 291 | 家庭关系核心页 |
| 9 | activity-detail | `pages/activity/activity-detail.vue` | 282 | 活动详情 |
| 10 | product-detail | `pages/discover-detail/product-detail.vue` | 252 | 商品详情页 |
| 11 | sleep-checkin | `pages/growth/sleep-checkin.vue` | 246 | 成长记录打卡 |
| 12 | membership-upgrade | `pages/membership/upgrade.vue` | 246 | 会员升级 |

### 实施方法

1. **取证**：用 `scripts/audit-beautify-debt.js` 跑单页审计，定位硬编码色和结构性问题
2. **Token 化**：先确认所需令牌是否已在 `uni.scss`，缺失则先补（归入 A 批）
3. **重构**：按"一页一提交"原则，每页 1-2 轮迭代
4. **验证**：HBuilderX 真机打包后视觉对比（Agent 侧不做 build）

---

## E 批 · 图片治理（122 个 `<image>`）

### 待办清单

1. **长列表补 `lazy-load`**：
   - `pages/discover/`（discover 列表）
   - `pages/article-center/`（文章列表）
   - `pages/shop/`（商品列表，15 文件）
   - `pages/profile-extra/`（成员列表）

2. **头像/封面图加 `mode`**：
   - 头像类：`mode="aspectFill"`（裁切适应正方形容器）
   - 封面/商品图：`mode="aspectFit"`（保比例适应容器）

3. **静态资源检查**：`static/` 下 33 张 png 是否可压缩（体积分析，本轮未做）

---

## F 批 · 重复模式组件化（消灭重复，非颜色）

### 待抽取组件

| 模式 | 重复位置 | 建议组件名 |
|---|---|---|
| `tag-btn` / `tag-active` 选择标签 | diet-checkin、exercise-checkin | `TagChip` |
| `role-card` / 选择卡（透明边+选中变橙） | user-edit、service-role-apply | `SelectableCard` |
| `step-dot` / 步骤圆点 | health-plan-summary、self-quiz | `StepDots` |
| `submit-btn` 渐变主按钮 | 3 个 checkin 页 | 复用 `PlayfulButton` primary |

### 实施注意

- 此批非紧急，可在 A/B/C 完成后并行或延后
- 组件抽取前先确认当前重复模式的视觉一致性（是否已对齐）

---

## 快赢清单（本周可完成，合计 <250 处）

| 任务 | 预估工作量 | 风险 |
|---|---|---|
| `#FFF → $app-surface` 全量（999 处） | 2-3 提交切片 | 零（等值） |
| `profile-main/profile.vue` 局部 `$c-*` 色板 hoist（73 处） | 1 提交 | 低 |
| FamilyEnergyBar 等 6 处内联 style 收敛为 class | 1 提交 | 低 |
| 补 `$facade-hairline-3` 令牌（如需） | 1 行 SCSS | 零 |

---

## 验证门禁（每批必须通过）

1. `node --check` 语法检查（对修改过的 .vue / .js 文件）
2. `scripts/audit-beautify-debt.js` 跑前后对比，硬编码色总数应单调下降
3. 三大硬指标保持：旧蓝 = 0 / transition:all = 0 / getSystemInfoSync = 0
4. D 批和 B 批需 HBuilderX 真机打包做视觉验收（Agent 侧禁跑 build）

---

## 边界与勿动项

- ~~深面板 chrome：`wuxing-sandbox` / `energy-detail` / `gate-guide-bar` 的 `#8FC5E8` + rgba(143,197,232,x)~~
- ~~material 蓝徽章 `#42A5F5`、五行水行 `#42A5F5` 语义色~~
- ~~canvas 字号与 canvas px 尺寸~~
- ~~JS/模板色值禁止写 SCSS 变量（编译期不可达）~~
- ~~quiz 深底 `#24243E`（logic-test / psych-assessment 暗色测评场景）~~