20260916231505

code/fms/开发规范.md

@@ -200,6 +200,24 @@ async function handleSave() {
 
 3. **不为了抽象而抽象** — 如果缓存逻辑只在一个组件中使用，直接放在该组件；只有页签和布局都需要同一缓存名称规则时，才抽成布局目录公共函数。
 
+### 样式与 CSS 组织
+
+1. **全局样式只放语义组合类，不放原子工具类** — 全局样式层（`src/styles/common.scss`）只收跨页面复用的语义骨架，例如 `.fms-page`（页面根）、`.fms-page__body`（左右分栏容器）、`.fms-page__main`（右栏主区）。不在全局定义 `.fms-fill`、`.fms-clip`、`.fms-column` 这类单一职责的原子类：它们把组合责任推给调用方，模板里必然出现 `fms-fill fms-clip`、`fms-fill fms-clip fms-column` 这样的拼串，而且漏拼一个不会报错，只会坏掉一个页面。每种组合形态必须由一个显式命名的类承担。
+
+2. **全局类必须有第二个真实调用点** — 进入全局样式层的类至少要有两个真实调用点；只有一个调用点的样式留在使用页面的 scoped 块中，没有调用点的必须删除。
+
+3. **命名表达"这是什么"，不表达"它长什么样"** — 优先使用页面结构、面板、部件名（`fms-page`、`fms-tree-panel`、`fms-toolbar`），不使用视觉结果名（`fms-fill`、`fms-clip`、`fms-flex`）。一个类要靠注释解释"它刻意不含 `overflow: hidden`"才能被理解，说明抽象没找准，应重新设计。
+
+4. **模板里连续出现三个以上 `fms-*` 就是缺语义类** — 页面模板中的 `fms-*` 通常不超过两个（页面根一个、右栏一个）。出现三个及以上连续拼串时，先在全局补出对应的语义组合类，再改调用方。
+
+5. **样式跟着组件走，不跟着页面走** — 组件自身的布局样式写在组件 `<style scoped>` 内，不进全局。一段结构相同的标记在多个页面重复出现时，先抽组件（标记与样式一并收进组件），再删除全局里对应的类；只有真正的跨页面页面骨架才留在全局。像"搜索框 + 动作区 + 可滚动区 + 树"这类左树面板结构，属于面板组件的职责，不拆散到各页面模板和全局样式里。
+
+6. **不靠选择器权重压组件库** — 需要提升选择器权重才能覆盖组件库内部样式时（例如用 `.fms-tree-panel__actions .fms-tool-btn` 去压 `.button-ghost` 的 `padding` / `border` / `hover`），先在组件库补一个变体（如 `Button` 的 `size="icon"`），不要在业务侧堆嵌套选择器和权重注释。
+
+7. **高度撑满走 flex 链，不写百分比高度** — 页面根依靠 `.fms-content` → `.fms-page-wrap` → 页面根的 `flex: 1` + `min-height: 0` 获得确定高度；不写 `height: 100%`、`100vh` 或 `calc(100vh - xx)` 魔数。
+
+存量页面中的原子类调用按需迁移：修改涉及到的页面时顺带改成语义类并同步更新样式定义，不为统一命名单独发起大范围重构（同「命名约定」第 8 条）。
+
 ## 多语言（i18n）约定
 
 1. **区分管理界面与业务资源** — module 目录下的模块管理、菜单管理、多语言类型等页面自身面向 IT 人员，界面文案固定使用中文，不把这些管理界面文案接入业务多语言体系；但模块名称、字段名称和 JSON 布局节点等面向客户的业务资源仍可维护 `s_i18n` 资源键和翻译。