feat: add phone frequency controls and modularize codebase
This commit is contained in:
hectorzhao
@@ -0,0 +1,535 @@
|
||||
# `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。
|
||||
|
||||
在用户明确要求启动前，本计划保持“待执行”状态。
|
||||
Reference in New Issue
Block a user