# cfc-web 后台页面美化治理方案 V1（2026-10-20）

> **规范依据**：enterprise-ui-optimizer / `references/design-tokens.md`
> **现状基线**：`cfc-web/src/styles/admin-tokens.css`（Ant Design 5 令牌体系已立）＋ 4 个全局组件已注册（`main.js` 97/98/100 行）
> **核心判断**：**规范已立、接入不足**。本方案不做"重新设计"，做"收敛接入"——把 164 个页面接入既有令牌与组件，零视觉回归风险优先。
> **风格对标**：Ant Design 5 / 华为云控制台 / 银行信贷系统 / 国资企业后台。克制、干净、专业、信息优先。

---

## 1. 页面现存问题

### 1.1 审计快照（2026-10-20，cfc-web/src/views，共 164 个页面）

| 债务项 | 数量 | 说明 |
|---|---|---|
| 旧 Element 调色板残留 | **280 处** | `#409eff`/`#f56c6c`/`#e6a23c`/`#67c23a` 与新令牌 `#1677FF`/`#FF4D4F`/`#FAAD14`/`#52C41A` 并存，**同屏出现双蓝双红** |
| Tailwind 风色板残留 | **169 处** | `#64748B`/`#1E293B`/`#10B981`/`#3B82F6`/`#F59E0B`/`#EF4444`/`#94A3B8`，色温、明度体系完全跑偏 |
| 内联 `style="..."` 属性 | **1014 处** | 主题化被阻断，换肤/暗色/令牌调整无法穿透 |
| 裸 `el-tag`（未走 StatusTag） | **246 / 293 处** | 同一状态在不同页颜色/文案不一致 |
| `el-divider content-position="left"` 分区标题 | **25 处** | 未用 `SectionTitle`，缩进字号不统一 |
| KPI 卡未用 `StatCard` 的页面 | ≈60+ 页 | 仍有手写 `stat-card`/`td-stat-card` 等私有实现 |

**债务 top 文件**（硬编码色值计数）：

| 文件 | 处数 | 文件 | 处数 |
|---|---|---|---|
| `views/Dashboard.vue` | 74 | `views/TeacherDashboard.vue` | 33 |
| `views/teacher/TeacherMessages.vue` | 58 | `views/admin/Dashboard.vue` | 31 |
| `views/Login.vue` | 48 | `views/Layout.vue` | 26 |
| `views/teacher/TeacherFamilies.vue` | 39 | `views/admin/ReportTemplateManage.vue` | 24 |
| `views/teacher/TeacherTeam.vue` | 38 | `views/teacher/TeacherOrders.vue` | 22 |
| `views/admin/ProductEdit.vue` | 36 | `views/admin/ProductManage.vue` | 21 |

**组件接入率**：`StatCard` 22 处 / `StatusTag` 47 处 / `PageHeader` 41 处 / `SectionTitle` 3 处 / `adm-table-wrap` 144 页（此项已达标）。

### 1.2 分区问题（按区域）

- **全局主题层**：449 处跑偏色值直接写在页面与内联样式里，令牌体系被"架空"；`#409eff` 旧蓝与令牌 `--adm-primary(#1677FF)` 混用，界面出现"两种蓝"。
- **顶部标题区**：约 123 页未用 `PageHeader`，标题字号（16/18/20/22 均有）、主操作按钮位置、副标题有无全凭页面习惯，首屏气质不统一。
- **筛选区**：部分页面筛选器包在 `el-card` 里（双重边框视觉噪音），部分裸排；"查询/重置"位置左右摇摆；高级筛选无折叠，一行溢出到第二行时对齐混乱。
- **KPI 卡片区**：手写统计卡样式各异（圆角、数值字号 20/24/28、是否千分位、null 显示空还是 `-`），`StatCard` 有 `COLOR_MAP` 自动映射旧色名，迁移成本极低但只铺了 5 页。
- **表格区**：表头底色不统一（白/浅灰/品牌蓝都有）；金额列左对齐未用等宽数字；操作列未固定右侧；空数据区无占位文案；`StatusTag` 未接入导致状态色五花八门。
- **详情/表单区**：分区标题 25 处仍用 `el-divider`；详情标签列宽不一；金额无千分位；手机号/身份证未脱敏；表单页底部操作区有的贴底有的跟随内容流。
- **弹窗**：依赖全局 `admin-tokens.css` 已接管 `el-dialog`/`el-message-box`（合格），但弹窗内表单的分区、按钮层级仍按页面习惯写。
- **登录页 `Login.vue`**（48 处硬编码）：品牌门面页，Tailwind 风渐变与卡片投影偏重，与企业级调性不符。

---

## 2. 整体优化思路

**策略：「先收敛、后铺开、再结构、终业务」四阶段，每批独立可提交、可回归。**

1. **收敛（A 批，零视觉风险）**：把 449 处跑偏色值按等值/语义映射替换为 `adm-*` 令牌。色彩口径统一后，后续所有批量改造才有意义——否则改一处样式冒出一处新色。
2. **铺开（B 批，低风险）**：4 个全局组件向剩余页面铺开（StatusTag / SectionTitle / StatCard / PageHeader）。组件已全局注册、无需 import，迁移是"机械替换 + 删除死样式"。
3. **结构（C+D 批，中风险）**：内联样式清理（1014 处，按页切片）＋ 筛选区/表格/空态/详情分区按令牌标准化。
4. **业务（E 批）**：金融/台账业务适配——金额千分位、敏感信息脱敏、关键写操作留痕与确认弹窗。

**为什么这样排序**：色彩令牌是全系统的"分母"，分母不统一时任何视觉优化都会互相打架；组件铺开依赖令牌就位；结构改造依赖组件就位；业务适配是最后一道专业度打磨。每批结束都跑一次等价回归（编译比对）＋ grep 归零验收，保证"看得见的好看"不引入"看不见的回归"。

---

## 3. 分区详细优化方案

### 3.1 全局主题层（A 批主战场）

**优化前**：页面里散写 `color: #409eff`、`style="color:#F59E0B"`，与令牌双轨运行。
**优化后**：全站只允许引用 `var(--adm-*)`；页面级禁止出现裸 hex（令牌定义文件除外）。

替换映射表（等值或最近语义）：

| 跑偏值 | 替换为 | 性质 |
|---|---|---|
| `#409eff` / `#409EFF` | `var(--adm-primary)` | 等值 |
| `#f56c6c` / `#EF4444` | `var(--adm-error)` | 等值 |
| `#e6a23c` / `#F59E0B` | `var(--adm-warning)` | 等值 |
| `#67c23a` / `#10B981` | `var(--adm-success)` | 等值 |
| `#909399` / `#999` / `#64748B` / `#94A3B8` | `var(--adm-text-45)` | 语义 |
| `#303133` / `#1E293B` | `var(--adm-text-88)` | 语义 |
| `#3B82F6` | `var(--adm-primary)` | 语义 |
| `#fff` / `#FFF`（背景用途） | `var(--adm-bg-container)` | 语义 |

落地方式：写一次性替换脚本（带断言、逐文件计数核对），按目录切片提交；每片跑 `vue-cli-service build --dest dist_verify` 验证编译，视觉走等价回归比对。

### 3.2 顶部标题区（B 批）

**优化前**：各页手写 `<h2 class="page-title">` / `<div class="header">`，标题 16–22px 不等，主操作按钮位置随机。
**优化后**：统一 `PageHeader`（已存在，41 页在用）：

```vue
<PageHeader title="订单与佣金" subtitle="共 128 笔">
  <el-button type="primary" icon="el-icon-download" @click="exportExcel">导出</el-button>
</PageHeader>
```

令牌：主标题 20px/600（`text-title`），副标题 12px 次文，右侧唯一主操作。剩余 ≈123 页按"列表页/表单页"两模板批量替换。

### 3.3 筛选区

**优化前**：筛选器包卡片、双边框；查询/重置位置不一。
**优化后**：去卡片化，底部 1px 分割线分区（令牌已有 `.filter-bar` 规则），常用筛选项前置 ≤4 个一行，高级筛选折叠，"查询/重置"居右：

```vue
<div class="filter-bar">
  <el-input v-model="query.keyword" placeholder="订单号 / 家庭名称" clearable style="width:220px" />
  <el-select v-model="query.status" placeholder="状态" clearable>
    <el-option v-for="o in STATUS_OPTIONS" :key="o.value" :label="o.label" :value="o.value" />
  </el-select>
  <div class="filter-bar__actions" style="margin-left:auto;display:flex;gap:8px">
    <el-button type="primary" @click="load">查询</el-button>
    <el-button @click="reset">重置</el-button>
  </div>
</div>
```

### 3.4 KPI 卡片区

**优化前**：手写 `stat-card` / `td-stat-card` / `accent-*` 私有样式，数值字号与 null 表现不一。
**优化后**：统一 `StatCard`（`COLOR_MAP` 已自动映射旧色名，迁移时 `color="blue"` 之类可原样保留）：

```vue
<div class="kpi-row" style="display:grid;grid-template-columns:repeat(4,1fr);gap:16px">
  <StatCard label="总结算金额" :value="stats.total" prefix="¥" suffix="元" color="primary" icon="el-icon-money" />
  <StatCard label="待结算" :value="stats.pending || 0" color="warning" icon="el-icon-time" />
</div>
```

### 3.5 表格区

**优化前**：表头底色三种、金额左对齐、状态裸 `el-tag`、空态空白。
**优化后**（令牌 §7 已定义，页面只需接入）：

```vue
<div class="adm-table-wrap">
  <el-table :data="list" v-loading="loading">
    <el-table-column prop="orderNo" label="订单号" min-width="160" fixed="left" />
    <el-table-column label="金额" width="120" align="right">
      <template slot-scope="{ row }"><span class="adm-num">¥{{ formatAmount(row.amount) }}</span></template>
    </el-table-column>
    <el-table-column label="状态" width="100">
      <template slot-scope="{ row }"><StatusTag :value="row.status" :options="ORDER_STATUS_OPTIONS" /></template>
    </el-table-column>
    <el-table-column label="操作" width="150" fixed="right">
      <template slot-scope="{ row }">
        <el-button type="text" @click="view(row)">查看</el-button>
        <el-button type="text" style="color:var(--adm-error)" @click="reject(row)">驳回</el-button>
      </template>
    </el-table-column>
  </el-table>
</div>
```

要点：金额列 `align="right"` + `.adm-num` 等宽数字；状态走 `StatusTag` 映射式；操作列固定右、行内弱操作用文本按钮；空态由 `el-table__empty-text` 令牌接管。

### 3.6 详情/表单区

**优化前**：25 处 `el-divider` 分区；详情标签列宽不一。
**优化后**：`SectionTitle` + `detail-section`（令牌已有）：

```vue
<div class="detail-section">
  <SectionTitle title="家庭信息" desc="下单时所选家庭" />
  <div class="detail-row">…</div>
</div>
```

表单页：底部操作区统一 `edit-form-footer`（顶部分割线 + 右对齐，确认按钮唯一主按钮）。

### 3.7 登录页（品牌门面）

**优化前**：Tailwind 风渐变 + 重投影 + 48 处硬编码。
**优化后**：左侧品牌区（主色 `#001529` 深底 + 白字品牌名 + 一句功能向副标），右侧白底表单卡（8px 圆角 + 1px 描边 + 轻阴影）；去掉一切渐变与装饰插画；输入框/按钮走全局令牌。

---

## 4. 标准化设计规范落地（可复用）

**铁律：不新建令牌，先接入。** `admin-tokens.css` 已是单一事实源，与 `design-tokens.md` 逐条对齐；本方案的规范落地 = 把页面接进来，而非再造一套。

**页面准入 checklist**（每个页面改造完逐项打钩）：

- [ ] 无裸 hex 色值（`grep -rniE '#[0-9a-f]{3,6}'` 页面文件 = 0，令牌文件除外）
- [ ] 无内联 `style=`（C 批归零；过渡期允许布局类内联，禁色彩/字号类）
- [ ] 列表页根容器 `admin-page` 或 `page-container`，表格外包 `adm-table-wrap`
- [ ] 标题区用 `PageHeader`；主操作按钮每页 ≤1
- [ ] KPI 用 `StatCard`；状态用 `StatusTag`；分区用 `SectionTitle`
- [ ] 金额列右对齐 + `.adm-num`；分页右下 + "共 N 条"
- [ ] 空态有占位文案；超长文本省略 + tooltip
- [ ] 间距取自 `--spacing-*`（8px 基准），禁止 5/7/10/14/18

**组件标准速查**：

| 组件 | 用途 | 关键 props |
|---|---|---|
| `PageHeader` | 页面标题区 | `title / subtitle` + 默认插槽（右侧操作） |
| `StatCard` | KPI 概览卡 | `label / value / icon / color / prefix / suffix / thousand` |
| `StatusTag` | 状态标签 | 映射式 `:value + :options`（推荐）/ 简单式 `:type + :text` |
| `SectionTitle` | 卡片内分区 | `title / desc / plain` + 插槽（右侧操作） |

**回归验收**：每批跑 `./node_modules/.bin/vue-cli-service build --dest dist_verify` 至 `DONE Build complete`；A 批另跑等价回归逐页编译比对（零观感变化）；提交信息带批次标记（如 `style(admin): A-1 色彩令牌收敛-仪表盘`）。

---

## 5. 本次设计能力提升点

1. **"分母优先"思维**：一套 UI 体系崩坏，很少是某个页面设计得差，而是"色彩/间距这些分母"没统一，导致每个页面各自为政。先收分母（令牌），再谈分子（单页美化），投入产出比完全相反——这是本次 449 处跑偏色给的最大教训。
2. **组件即规范**：`StatusTag` 把"状态→颜色/文案"的映射从 293 处内联判断收敛到一处 options 表，本质是把"设计规范"编译成"代码约束"。规范只有变成组件 props，才不会被页面作者无意绕过。
3. **可回归的美化才是真美化**：每批都带"编译通过 + grep 归零 + 等价回归"三道闸门，让"好看"成为可验证的属性，而不是审美玄学——这也是本仓两条工作线（cfc-web / cfc-frontend）能并行推进不互相踩踏的原因。

---

## 附：批次实施路线图（A→E，每批独立可提交）

| 批次 | 内容 | 规模 | 风险 | 验收 |
|---|---|---|---|---|
| **A** | 色彩令牌收敛（旧 Element 280 + Tailwind 169） | 449 处 / 约 90 文件 | 低（等值/语义映射） | grep 归零 + 构建通过 + 等价回归 |
| **B** | 组件铺开：246 裸 `el-tag`→`StatusTag`、25 `el-divider`→`SectionTitle`、剩余 KPI 卡→`StatCard`、≈123 页→`PageHeader` | 约 120 文件 | 低（机械替换+删死样式） | 组件计数对齐 + 构建通过 |
| **C** | 内联 `style` 清理 | 1014 处 | 中（按页切片，逐页目检） | 归零率 ≥90% + 构建通过 |
| **D** | 结构标准化：筛选区去卡片化、表格标准、空态、详情分区、登录页 | 约 60 页 | 中 | 页面 checklist 全勾 |
| **E** | 业务适配：金额千分位、手机号/身份证脱敏、关键写操作确认弹窗与留痕入口 | 按业务页 | 中 | 业务走查 + 联调清单 |

**切片顺序建议**（按债务从高到低、公共页优先）：`Dashboard` → `admin/Dashboard` → `teacher/*`（Messages/Families/Team）→ `admin/Product*` → `admin/ReportTemplateManage` → 其余按 A→E 批次滚动推进。

> 本方案与 `cfc-frontend/docs/beautification-plan-v2.md`（小程序侧 D 系列美化）方法论同源：审计定量 → 分批推进 → 每批可提交可回归。两侧互不干扰，可并行。