45 lines
3.1 KiB
Markdown
45 lines
3.1 KiB
Markdown
# 聆界短信平台仓库开发约束
|
||
|
||
本文件适用于整个仓库。进入子目录工作时，如果存在更具体的 `AGENTS.md`，还应同时遵守子目录规范。
|
||
|
||
## 开始工作前
|
||
|
||
- 先检查当前分支、最近提交、远端差异以及 staged、unstaged、untracked 文件。
|
||
- 保留其他会话和用户已有修改；禁止未经授权执行 reset、清理、覆盖、切分支、推送或部署。
|
||
- 功能事实必须以当前代码、真实 API、PostgreSQL、Redis、MinIO、Gateway 和目标环境为准，交接记录只作为线索。
|
||
- 不得发送、补发、重投或重新入队短信；不得擅自修改余额、通道或客户配置。
|
||
|
||
## CSS 任务强制阅读
|
||
|
||
凡新增、修改、迁移或审查 CSS，必须先完整阅读：
|
||
|
||
1. `docs/css-development-guidelines.md`；
|
||
2. 涉及存量拆分时，再阅读 `docs/global-css-modularization-plan-20260904.md`。
|
||
|
||
## CSS 所有权
|
||
|
||
- 设计变量归 `src/styles/tokens.css`。
|
||
- 浏览器重置和标签基础规则归 `src/styles/reset.css`。
|
||
- AppShell、侧栏、顶栏、导航和页面骨架归 `src/styles/shell.css`。
|
||
- 跨业务复用且语义一致的公共组件样式归 `src/styles/components/`；迁移完成前的既有公共规则可继续位于明确登记的共享样式文件。
|
||
- 同一业务域多个页面共享的样式归业务域目录，并由业务域根类名限定。
|
||
- 只服务一个页面、弹窗或局部组件的样式必须放在其 TSX 同目录或对应业务目录，由所有者直接 import。
|
||
- `src/styles/global.css` 是存量兼容文件：只允许迁出、删除和保持视觉等价所必需的修正，不得新增页面或业务选择器。例外必须在变更说明中写明原因、影响范围和清理条件。
|
||
|
||
## CSS 禁止事项
|
||
|
||
- 禁止把新页面、新弹窗或新业务组件的选择器写入 `global.css`。
|
||
- 禁止使用无业务根节点限定的标签选择器或短通用类名影响其他页面。
|
||
- 禁止通过新增 `!important`、提高 specificity 或依赖偶然加载顺序掩盖归属和级联问题；第三方不可控样式等例外必须记录原因、影响范围和移除条件。
|
||
- 禁止把公共组件样式建立在业务页面样式之上。
|
||
- 禁止对 `global.css` 执行整文件格式化，或在迁移提交中夹带视觉改版和无关重排。
|
||
- 禁止仅凭类名前缀批量移动选择器；必须同时核对 TSX 引用、其他 CSS 定义、媒体查询和真实 DOM。
|
||
|
||
## CSS 变更验收
|
||
|
||
- 提交前检查 staged diff，确保只包含本轮目标文件或精确 hunk。
|
||
- 运行与范围匹配的定向测试、前端全量测试、TypeScript、生产构建、仓库当前提供的格式和样式门禁以及 `git diff --check`；自动门禁尚未覆盖的项目按日常规范人工检查并记录。
|
||
- 页面级变更至少检查 1600×1000、1366×768 和 390×844；覆盖首次进入、刷新、跨路由切换及相关交互状态。
|
||
- 使用真实 API 和测试环境完成最终功能验收；构建成功、组件测试或隔离截图不能代替真实页面验收。
|
||
- 纯 CSS 拆分不得改变计算样式。发现差异时先恢复原级联关系，不得顺手调整设计。
|