# `global.css` 渐进式拆分计划

更新日期：2026-07-31
适用仓库：CMPP 平台主仓库
计划编号：R12
当前状态：仅完成方案设计，暂不执行

> 本计划必须等当前工作区代码完成周末测试、问题修复和基线确认后再启动。
> 在此之前不得为了本计划移动 CSS、调整选择器、改变样式加载顺序或顺带修改页面。

## 1. 背景

R11 已完成基础样式、AppShell、通用组件、运营端共享样式和客户端共享样式的
本地拆分，但 R11 的完成不代表所有单页面样式已经从 `src/styles/global.css`
迁出。

截至 2026-07-31 的本地工作区快照：

- `src/styles/global.css` 约 9049 行；
- 页面专属样式和跨门户兼容样式仍然混合存在；
- 当前工作区还有大量尚未提交的 R1-R11 重构及业务修改；
- 当前代码尚待周末完成集中测试；
- 本计划未实施、未提交、未推送、未部署。

以上数据只表示编写本计划时的快照。正式执行 R12 前必须重新统计，不能直接把
本文记录视为届时事实。

## 2. 目标与非目标

### 2.1 目标

1. 按页面所有权逐步迁出 `global.css` 中的单页面样式。
2. 每个步骤形成一个可独立构建、测试、发布、观察和回滚的版本。
3. 保持现有页面视觉、交互、真实 API、数据库和业务行为不变。
4. 降低继续开发新页面和新功能时对全局样式的依赖。
5. 最终让 `global.css` 中每一组保留规则都有明确的全局或兼容用途。

### 2.2 非目标

1. 不以一次性清空 `global.css` 为目标。
2. 不以减少行数作为拆分成功的唯一标准。
3. 不在纯 CSS 拆分步骤中重做页面视觉设计。
4. 不在拆分时顺带修改业务功能、接口、文案或数据结构。
5. 不为了统一命名而一次性批量修改多个页面的 className。
6. 不把跨页面规则简单复制到多个页面文件中。

## 3. 启动前置条件

必须同时满足以下条件后，才能执行 R12：

1. 当前工作区代码已经完成用户计划的周末测试。
2. 测试中发现的 Bug 已经处理，或已经明确登记为与 CSS 拆分无关的遗留问题。
3. 本地工作区的修改归属已经确认，不会误覆盖其他会话的改动。
4. 已明确 R1-R11 及当前业务修改的提交、推送和部署状态。
5. 已重新执行并记录：
   - `git status --short --branch`
   - `git diff`
   - `git fetch`
   - 本地 `HEAD`
   - `origin/main`
   - 预生产 `.deployed-commit`
6. 已保存目标页面拆分前的桌面端和移动端视觉基线。
7. 已确认目标页面可以使用真实后端数据进行验收。

如果周末测试仍有未定位的布局、弹窗、表格或响应式问题，应先修复这些问题，再启动
CSS 迁移，避免把原有 Bug 错误归因给拆分。

## 4. 核心拆分原则

### 4.1 每一步只拆一个页面或一个紧密子域

低风险页面可以在一个发布版本中安排两到三个，但实际代码移动仍要保持独立步骤。
中高风险页面每个版本只处理一个页面或一个子页面。

### 4.2 按选择器所有权拆分，不按行数硬切

迁移前必须搜索选择器的全部引用。只有确认属于目标页面的规则才能迁移。

以下情况不得直接移动：

- 同时被运营端和客户端使用；
- 同时被两个以上业务页面使用；
- 选择器名称像页面专属，但实际由公共组件渲染；
- 逗号组合选择器中包含其他页面的分支；
- 媒体查询中混合了多个页面的响应式规则。

### 4.3 完整迁移一个样式族

迁移某个页面样式时，必须同时处理：

- 默认规则；
- hover、focus、active、disabled 等状态；
- 加载、空数据、错误和完成状态；
- 桌面端及全部响应式断点；
- 页面专属动画和 `@keyframes`；
- 打印规则；
- 同一组件的弹窗、抽屉、表格和分页规则。

禁止只移动桌面样式，把移动端覆盖遗留在 `global.css`。

### 4.4 保持级联顺序

页面 CSS 的导入位置必须保证迁移前后的覆盖顺序一致。迁移步骤中原则上不同时做：

- 选择器权重调整；
- className 重命名；
- `!important` 清理；
- CSS Layers 重排；
- 公共组件视觉改版。

如果发现迁移必须改变权重，应停止纯迁移，把权重治理拆成单独版本。

### 4.5 新增页面样式不得继续进入 `global.css`

R12 启动后建立强制约束：

- 新页面必须有自己的页面 CSS；
- 已有页面的新专属样式写入该页面 CSS；
- 真正公共的样式进入对应的基础、壳层、组件、运营端或客户端共享文件；
- 暂时无法判定归属的规则必须写明使用方和保留原因。

## 5. 分阶段实施路线

### R12.0：建立拆分基线和所有权门禁

本步骤不移动生产 CSS。

工作内容：

1. 重新统计各样式文件行数和导入顺序。
2. 建立 `global.css` 选择器所有权清单。
3. 记录每个候选选择器在 React 源码中的引用。
4. 标记单页面、跨页面、跨门户、公共组件和疑似无引用规则。
5. 建立后续步骤使用的选择器归属检查脚本。
6. 保存关键页面视觉基线和构建产物中的 CSS 顺序。

完成标准：

- 能够明确识别已经迁出的选择器是否重新进入 `global.css`；
- 能够识别页面 CSS 是否缺少对应的响应式规则；
- 不改变现有页面和生产代码行为。

### 第一阶段：低风险、前缀清晰的页面

#### R12.1：客户端短信发送明细

候选样式：

- `.send-detail-*`
- 对应媒体查询分支
- 仅由发送明细页面使用的状态规则

目标文件：

`src/apps/client/send-detail/ClientSendDetailPage.css`

这是建议的第一个实际迁移步骤，原因是选择器前缀清晰、页面以只读明细为主、
交互状态少、与其他页面耦合较低。

预计迁出规模：约 120-200 行，以正式执行时重新盘点为准。

#### R12.2：客户端上行短信

候选样式：

- `.uplink-*`
- 页面表格、详情和响应式规则

目标文件：

`src/apps/client/uplink/ClientUplinkMessagesPage.css`

#### R12.3：客户端应用管理

候选样式：

- `.sms-app-*`
- 应用卡片、状态、操作区和响应式规则

目标文件：

`src/apps/client/applications/ClientApplicationsPage.css`

#### R12.4：运营看板首页

候选样式：

- `.admin-dashboard-*`
- `.admin-workload-*`
- `.admin-alert-*`

目标文件：

`src/apps/admin/home/AdminHome.css`

第一阶段完成后，应确认拆分方法、检查脚本、加载顺序和视觉验收流程可靠，再进入
更复杂的客户端页面。

### 第二阶段：客户端中高风险页面

#### R12.5：批量任务页面

候选样式：

- `.batch-filter-*`
- `.batch-table-*`
- `.batch-task-*`
- `.batch-progress`
- `.batch-actions`
- `.batch-pagination`

进度条、操作区、分页以及所有响应式分支必须作为一个完整页面样式族迁移。

#### R12.6：客户端模板页面

只迁移模板列表页面实际拥有的样式，例如：

- `.template-toolbar`
- `.template-card-grid`
- `.template-card*`
- `.template-content`
- `.template-vars`
- `.template-card-footer`

以下规则不能因为名称相似而一起迁移：

- 短信发送页使用的 `.template-trigger`；
- 短信发送页使用的 `.template-picker-*`；
- 通用组件使用的弹窗标题和表单规则。

#### R12.7：客户端短信发送页面

候选样式族：

- `.sms-send-*`
- `.send-card`
- `.receiver-*`
- `.send-form-*`
- `.add-recipient`
- `.import-panel`
- `.send-tip`
- `.send-submit-*`
- `.preview-*`
- `.phone-preview`
- 页面专属模板选择器

本页面交互状态多，涉及号码录入、批量导入、模板选择、发送预览和移动端布局，
必须单独形成一个版本。

#### R12.8：企业认证页面

候选样式：

- `.enterprise-page`
- 企业认证表单和步骤状态
- `.enterprise-result*`
- 对应的全部响应式规则

该页面存在多状态切换，迁移时必须验证未认证、审核中、通过、驳回和重新提交等状态。

### 第三阶段：运营端企业和审核页面

#### R12.9：企业列表和查询区域

只处理企业列表、筛选条件、查询区域和列表卡片，不同时拆企业详情和编辑表单。

#### R12.10：企业详情

候选样式：

- `.admin-enterprise-detail`
- `.admin-enterprise-profile`
- 企业摘要和业务页签
- 企业应用展示区域

#### R12.11：企业新增和编辑表单

处理企业表单、营业执照、联系人和账户配置等页面专属样式。

#### R12.12：企业应用新增和编辑

候选样式：

- `.admin-app-form-*`
- 应用协议配置
- 路由和连接相关表单
- 页面专属开关和提示区域

此步骤涉及复杂表单，应与企业列表和详情分开。

#### R12.13：企业审核

迁移企业审核详情和页面专属布局，保留真正跨审核页面共享的表格、筛选、分页和
状态标志。

#### R12.14：短信、签名、模板和引流审核

优先按具体审核页面逐一迁移。只有确认多个审核页面的结构和视觉完全一致后，
才能把对应规则留在或迁入运营端共享样式。

### 第四阶段：通道和报备页面

这是 R12 风险最高的一组，不得合并成一次大迁移。

#### R12.15：通道组列表

只处理通道组列表、状态、基础操作和响应式布局。

#### R12.16：通道组表单及路由配置

处理通道组编辑、通道路由、优先级和相关动态表单。不得同时修改路由业务规则。

#### R12.17：通道报备列表和详情

处理通道报备列表、签名状态、详情和操作区域。

#### R12.18：待生成报备批次

处理“待生成资料”和“已生成批次”两个 Tab 的筛选、表格、分页和详情弹窗。
拆分时必须保持现有搜索条件宽度和统一按钮规范。

#### R12.19：报备资料导入、审核和预览

处理导入结果、逐行审核、勾选批量审核、整批审核、导出预览和状态修改等样式。
本步骤如果 diff 过大，应继续拆成：

1. 导入和解析结果；
2. 审核列表和批量操作；
3. 导出与预览。

### 第五阶段：统计及其他运营页面

#### R12.20：签名通道发送质量

独立迁移筛选条件、质量卡片、表格、明细弹窗和运营商概览，不与其他统计页面合并。

#### R12.21：下游投递记录

迁移查询、记录表格、详情和响应式布局。

#### R12.22：恢复状态管理

迁移筛选、状态、错误信息、操作区和详情弹窗。

#### R12.23：网关异常及相关记录

按实际页面引用拆分异常记录、协议日志和详情样式。

#### R12.24：充值管理

迁移充值列表、充值操作、凭证和页面专属弹窗。公共回执组件样式不得重复复制。

#### R12.25：运营端上行短信

与客户端上行短信页面分别确认所有权，不能仅因业务名称相同就共用页面专属规则。

#### R12.26：系统用户、操作日志和安全配置

这些页面可能与客户端系统页面共用 `.system-*` 规则。先迁移明确的页面专属规则，
跨门户规则留到第六阶段统一治理。

#### R12.27：引流资料及其他剩余页面

对未覆盖页面重新进行引用盘点，继续遵循“一页一步”的原则，不设置一次性清仓步骤。

### 第六阶段：跨门户兼容样式治理

在所有主要单页面样式完成迁移后，再处理同时被运营端和客户端使用的历史规则，例如：

- `.system-page`
- `.system-page-toolbar`
- `.system-filter-row`
- `.system-table-card`
- `.inline-actions`
- `.system-user-form`
- 其他经引用扫描确认的跨门户兼容类名

逐项采用以下处理方式之一：

1. 确认真正公共，迁入公共组件或公共布局样式；
2. 只有布局公共，抽取新的公共布局类；
3. 名称相同但实际表现不同，分别改为页面专属类；
4. 暂时不能确认，继续保留在 `global.css` 并注明使用方和原因。

跨门户样式必须最后处理，避免一次变化同时影响多个已拆页面。

### R12.28：最终残留审计

工作内容：

1. 删除经静态扫描和运行时验证确认无引用的规则。
2. 合并确认声明和作用域均等价的重复规则。
3. 检查响应式分支、关键帧、打印样式和浏览器兼容规则。
4. 为必须保留的规则记录用途、使用方和不能下沉的原因。
5. 启用“页面专属样式不得新增到 `global.css`”的持续门禁。

最终成功标准不是 `global.css` 变成零行，而是其剩余规则全部具有明确、可验证的
全局职责。

## 6. 风险分级和建议节奏

### 6.1 风险分级

低风险：

- 客户端发送明细；
- 客户端上行短信；
- 客户端应用管理；
- 运营看板首页。

中风险：

- 批量任务；
- 客户端模板；
- 审核页面；
- 签名通道发送质量；
- 充值和系统页面。

高风险：

- 客户端短信发送；
- 企业认证；
- 企业和应用复杂表单；
- 通道组路由；
- 通道报备和资料导入；
- 下游恢复类页面。

### 6.2 发布节奏

- 低风险页面：一个发布版本最多安排 2-3 个，但分别实施和验证。
- 中风险页面：一个发布版本只处理 1 个页面。
- 高风险页面：一个发布版本只处理 1 个页面或 1 个子页面。
- 不在同一版本中同时拆高风险页面和修改该页面业务功能。
- 每个版本至少稳定观察一个发布周期，再进入下一个高风险步骤。

预计整个计划约 28 个小步骤。步骤数量允许在 R12.0 重新盘点后调整，但不得通过
合并高风险页面来人为压缩版本数量。

## 7. 每一步的固定执行流程

### 7.1 开始前

1. 检查 Git 分支、差异、未跟踪文件和其他会话修改。
2. 记录目标页面当前 CSS 导入链。
3. 搜索候选选择器的全部源码引用。
4. 保存目标页面桌面端和移动端视觉基线。
5. 明确本步骤允许移动和禁止移动的选择器清单。

### 7.2 实施中

1. 新建或使用目标页面 CSS 文件。
2. 从稳定页面入口导入页面 CSS。
3. 迁移完整样式族和所有媒体查询分支。
4. 遇到跨页面的逗号选择器时先拆开规则，再迁移目标分支。
5. 不修改 API、数据库、业务判断、文案和用户操作流程。
6. 不清理与本步骤无关的历史 CSS。

### 7.3 本地门禁

至少执行：

- 目标选择器所有权检查；
- CSS 导入顺序检查；
- 前端 TypeScript 检查；
- Vite 生产构建；
- 已建立的 R0-R11 重构门禁；
- `git diff --check`。

CSS 拆分原则上不影响后端，但在准备形成可发布版本时仍应执行项目既定的完整发布
门禁，包括 API、Prisma、Gateway 和依赖安全检查，防止把工作区中的其他修改漏测。

### 7.4 页面验收

使用真实后端和真实接口，至少检查：

- 1280px 及以上桌面端；
- 1024px；
- 768px；
- 375px 移动端；
- 正常数据；
- 空数据；
- 加载状态；
- 错误状态；
- 表格、分页、弹窗和抽屉；
- 浏览器控制台；
- 页面有无横向溢出。

不得使用 mock、静态数据或 `localStorage` 伪造验收结果。涉及生产环境时，不得发送
真实短信或修改真实通道、余额和连接状态。

### 7.5 记录和发布

1. 更新本计划的实际进度。
2. 同步更新相关测试用例和 `docs/testing-progress.md`。
3. 记录迁移前后行数、选择器数量、目标文件和验证结果。
4. 未经明确授权不提交、不推送、不部署。
5. 获得部署授权后，继续遵守项目既定备份、精确提交打包和发布后检查流程。

## 8. 必须暂停拆分的情况

出现以下任一情况，应停止当前步骤并先诊断：

1. 迁移必须改变选择器权重才能保持视觉一致。
2. 一个候选样式被多个未纳入本步骤的页面使用。
3. 页面在迁移前已经存在无法解释的视觉差异。
4. 目标页面真实后端不可用，无法完成关键状态验收。
5. diff 已经大到无法逐段人工复核。
6. 必须同时修改业务逻辑才能继续迁移。
7. 发现其他会话正在修改相同页面或相同样式区段。

暂停后应把问题拆成单独 Bug 或更小的重构步骤，不能通过扩大当前版本范围继续推进。

## 9. 预期结果

计划完成后：

- 页面专属样式由对应页面目录维护；
- 公共样式按基础、壳层、组件、运营端、客户端和跨门户职责维护；
- 新增菜单和页面不再继续膨胀 `global.css`；
- 修改一个页面时能够明确判断受影响范围；
- 每次 CSS 调整都有可执行的静态门禁和真实页面回归范围；
- `global.css` 即使仍有一定规模，也不再承担无法解释的页面样式集合职责。

## 10. 后续启动建议

周末现有代码测试完成后，按以下顺序启动：

1. 重新确认 Git、预生产版本和测试基线；
2. 执行 R12.0，不移动生产 CSS；
3. 评审 R12.0 生成的所有权清单；
4. 执行 R12.1 客户端短信发送明细页；
5. 单独完成构建、真实页面验收和发布观察；
6. 确认方法稳定后再继续 R12.2。

在用户明确要求启动前，本计划保持“待执行”状态。