lislgosms/docs/global-css-progressive-split-plan.md

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。

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