20260728173026

code/fms/开发规范.md

@@ -1,64 +1,96 @@
 # FMS 开发规范
 
-## 一、构建与测试
+> 规则等级：[MUST] = 必须遵守，违反即错误 [SHOULD] = 应当遵守，例外需说明 [NEVER] = 禁止
 
-- **不要过多封装**
-- 完成功能后不主动执行构建。
-- 允许执行测试以验证改动（如后端 `./mvnw test`、前端 `pnpm fmt:check` 及页面功能验证）。
-- 只有用户明确要求时，才执行构建或启动服务。
-- 交付时说明本次是否执行了测试及测试结果，并说明未执行构建。
+---
 
-## 二、后端接口
+## 1. 代码风格 [MUST — 最高优先级]
 
-- 优先使用现有通用接口完成查询、分页、保存和取号：
-  - `/data/loaddata`
-  - `/data/page`
-  - `/data/saveobjt`
-  - `/data/nextid`
-- 不随意修改通用接口的地址、参数、返回结构和处理逻辑。
-- 不随意新增业务专用接口。
-- 不新增 services 这类接口或者文件。
-- 如果现有通用接口确实无法完成需求，必须先说明原因、拟新增或修改的内容及影响范围，并取得用户确认后再实施。
+- [MUST] **写法统一**：同类场景（API 调用、错误处理、状态管理）使用一致的写法，新增代码模仿现有同类代码的风格，不自创写法。
+- [MUST] **不滥用语法糖**：能用 `if/else` 就不用三元/`?.短路`；能用 `for` 循环就不用 `reduce`/`flatMap`/解构嵌套。判断标准：不熟悉此代码的人能否一眼看懂？
+- [MUST] **禁止无用嵌套**：减少不必要的中变量、回调套回调、过度抽象。
+- [MUST] **可读性 >= 简洁性**：写得短但看不懂 → 不合格；写得稍长但一目了然 → 合格。
 
-## 三、前端实现
+## 2. 构建与测试
 
-- 优先使用项目现有组件和 Antdv Next 组件，不重复实现组件已有的功能。
-- 页面存在相同或相近功能时，优先抽取为可复用组件、组合函数或服务方法。
-- 抽取复用应以确实减少重复和降低维护成本为前提，不为简单逻辑增加无必要的封装。
-- 优先复用现有布局、样式变量和组件能力，以尽量少的 CSS 完成功能。
-- 不使用 CSS 重复实现组件已有的尺寸、状态、交互和响应式能力。
-- 新增 CSS 应限制在当前组件作用域内，避免影响其他页面。
-- 不需要兼容移动端，按桌面端实现即可。
-- 表格尽量使用 `fms-table` 组件（项目封装的表格组件），不重复从零实现表格能力。
-- 表单输入控件不需要添加 placeholder（占位提示文字），用字段 label 或说明文字表达意图即可。
+- [NEVER] 完成功能后**不主动执行构建或启动服务**。
+- [SHOULD] 可运行测试验证改动：后端 `./mvnw test`，前端 `pnpm fmt:check`。
+- [MUST] 只有用户明确要求时，才执行构建或启动服务。
+- [MUST] 交付时说明：是否执行了测试 + 测试结果 + 未执行构建。
 
-## 四、变更范围
+## 3. 后端接口
 
-- 修改应围绕当前需求，避免无关重构和格式化其他文件。
-- 保留已有功能和用户尚未提交的改动。
-- 涉及通用接口、公共组件或全局样式的变更，实施前必须先确认影响范围。
+- [MUST] **只用通用接口**完成所有数据操作：
+  - 查询：`POST /data/loaddata`
+  - 分页：`POST /data/page`
+  - 保存：`POST /data/saveobjt`
+  - 取号：`GET /data/nextid`
+- [NEVER] 新增业务专用接口、新增 Service 类/文件。
+- [NEVER] 修改通用接口的 URL、参数、返回值结构或处理逻辑。
+- [MUST] 如通用接口确实无法满足需求：先说明原因 + 拟修改内容 + 影响范围，取得用户确认后再实施。
+- [MUST] `bigint` 类型（如 `b_id`）序列化到前端时必须转为**字符串**。
 
-## 五、CSS 规范
+## 4. 前端实现
 
-1. **尽量使用 SCSS**：组件样式统一写在 `<style scoped lang="scss">` 中，利用嵌套、变量、mixin 减少重复；全局/公用样式放在 `src/styles/main.scss`（或在此引入的 partial）中，集中管理主题变量（如 `--fms-*`）。
-2. **以最少的 CSS 完成任务**：优先复用 Antdv Next 组件能力、设计变量和已有工具类，能用组件属性或已有 token 解决的就不写样式，不重复实现已有的尺寸/状态/交互。
-3. **公用样式集中管理**：跨页面或同功能重复出现的样式抽到 `src/styles/main.scss`、共用组件或组合（composable）中，做到「改一处、处处变」；组件内只保留该组件独有、无法共享的样式，并保持 `scoped`。
-4. **不兼容移动端**：按桌面端实现，不写 `@media` 响应式断点；如确有需要，须先与需求方确认。
+- [MUST] 表格使用项目封装的 **`fms-table`** 组件，不从零实现表格。
+- [MUST] 表单输入控件**不添加 `placeholder`**，用 `label` 或说明文字表达意图。
+- [MUST] 优先复用项目现有组件和 Antdv Next 组件能力，不重复造轮子。
+- [SHOULD] 页面中出现 ≥2 处相同/相近功能时，提取为可复用组件、composable 或 service 方法。
+- [SHOULD] 抽取复用以确有收益为前提，不为简单逻辑增加无意义的封装。
+- [MUST] 不添加 `@media` 响应式断点，按桌面端实现。
+- [MUST] 新增 CSS 加 `scoped`，不影响其他页面。
 
-## 六、性能优先（重要、重要、重要）
+## 5. CSS 规范
 
-- **性能是本项目的一等约束，贯穿全部层面**，优先于代码便利与组件/外观一致性。适用于前端、后端、数据库及一切场景，任何改动都不得引入可感知的性能退化（卡顿、慢查询、高延迟、资源浪费等）。
-- **前端**：表格单元格、列表项、滚动区域默认使用原生 DOM（`h("button")` / `<input>` / 原生元素）或轻量自绘元素，**避免每行/每项常驻重型组件实例**（如 antdv 的 `Dropdown`、`Select`、`Input`、`Modal` 等）。
-  - 重型组件（如 `Dropdown` 菜单）必须「按需挂载」：列表态只渲染轻量触发器（原生按钮 + 图标），仅在用户真正交互（点击/悬停）时才为「当前那一行/项」临时挂载真正的组件，交互结束（菜单关闭/失焦）即卸载，保证**任意时刻最多只有 1 个该类组件实例存在**。
-  - 虚拟滚动（如 `fms-table` / stk-table）场景下，组件实例的 mount/unmount 会随滚动反复发生；常驻重型组件会显著拖慢帧率（实测每行一个 `Dropdown` 可让滚动从约 55fps 跌到 40–50fps）。务必用轻量元素 + 按需挂载规避。
-  - 含列表/表格滚动的页面，交付或评审前应关注 FPS，必要时用轻量替代或按需挂载优化。
-- **后端**：优先复用现有通用接口完成查询/分页/保存/取号，不随意新增业务接口或重复封装；查询与保存应合理批量（如用 `/data/saveobjt` 的单事务批量 upsert 而非逐条请求）；避免 N+1 查询、在循环内做远程调用或重复 IO；大数据量必须分页，不一次拉全表。
-- **数据库（SQL Server）**：编写 SQL 时优先走索引（避免对索引列做函数包裹、隐式类型转换、`SELECT *`、不必要的 `ORDER BY`/`DISTINCT`）；分页、聚合、联表需评估执行计划与数据量；大表慎用全表扫描与锁表操作；连接池（Druid 多组织路由）配置与慢查询需关注，避免连接泄漏与长事务。
-- 性能问题应在设计/编码阶段前置考量，而非事后优化；涉及慢查询、重接口、大列表等高风险改动，实施前应说明性能影响与规避方式。
+- [MUST] 样式写在 `<style scoped lang="scss">` 中。
+- [MUST] 优先用 Antdv Next 组件属性/设计 token 解决问题，能不写样式就不写。
+- [MUST] 跨页面复用的样式抽取到 `src/styles/main.scss` 或共享 composable 中。
+- [MUST] 不兼容移动端，不写 `@media` 断点。
 
-## 七、表格「更多操作」按钮
+## 6. 性能 [MUST — 高于其他所有规则]
 
-- 表格/列表中若需要「更多操作」（⋯）按钮并弹出菜单，**必须采用按需挂载模式**（禁止为每一行常驻一个 `Dropdown` 组件实例，否则会导致滚动卡顿）：
-  - **列表态**：单元格只渲染一个轻量原生 `⋯` 图标按钮（无边框、透明背景、hover 显底色），点击后才为当前行挂载真正的 `Dropdown`（`menu` 属性驱动 `items`，`open` 受控，`onOpenChange` 关闭即卸载）。
-  - **任意时刻最多 1 个 `Dropdown` 实例**；菜单项统一使用「图标 + 文字」形式（如 `h(icon, { size: 14 })` 加文本）。
-- **参考实现**：`src/views/module-management/components/ModulePowersPanel.vue` 中的 `MoreActions` 组件——原生 `⋯` 触发器 + 仅在 `open` 时挂载 `antdv-next` 的 `Dropdown`，菜单含「编辑 / 复制 / 设置多语言」三项，每项带图标与文字。新增类似按钮时直接参照此模式。
+> 性能是本项目最高约束，优先级高于代码便利性和组件一致性。
+
+### 6.1 前端性能
+
+- [MUST] 表格/列表/滚动区域的**每一行/项只渲染轻量原生元素**（`h("button")`、`<input>`、原生 DOM）。禁止每行常驻重型组件实例。
+- [MUST] 重型组件（`Dropdown`、`Select`、`Input`、`Modal` 等）采用**按需挂载**模式：
+  1. 默认只渲染轻量原生触发器（如按钮+图标）
+  2. 用户交互时（点击/悬停）才为**当前行**挂载真实组件
+  3. 交互结束（菜单关闭/失焦）立即卸载
+  4. 任意时刻最多 1 个该类组件实例存在
+- [MUST] 交付/评审前确认表格滚动无卡顿。重型组件常驻会导致 FPS 从 ~55 降到 ~40-50。
+
+### 6.2 后端性能
+
+- [MUST] 批量操作：一次 `/data/saveobjt` 批量 upsert，不逐条请求。
+- [MUST] 禁止 N+1 查询、在循环内远程调用或重复 IO。
+- [MUST] 大数据量必须分页，不一次性拉全表。
+
+### 6.3 数据库性能
+
+- [MUST] 禁止对索引列做函数包裹和隐式类型转换。
+- [MUST] 禁止 `SELECT *`，明确列出需要的列。
+- [SHOULD] 减少不必要的 `ORDER BY` / `DISTINCT`。
+- [MUST] 大表禁止全表扫描和锁表操作。
+- [MUST] 避免连接泄漏和长事务。
+
+### 6.4 通用原则
+
+- [MUST] 性能问题在设计/编码阶段前置考量，不做事后优化。
+- [MUST] 慢查询、重接口、大列表等高风险改动，实施前说明性能影响和规避方式。
+
+## 7. 变更范围
+
+- [MUST] 修改仅围绕当前需求，不进行无关重构、代码风格调整或格式化其他文件。
+- [MUST] 保留已有功能和用户未提交的改动，不做破坏性变更。
+- [MUST] 涉及通用接口、公共组件、全局样式的变更，实施前必须确认影响范围。
+
+## 8. 表格「更多操作」按钮 [MUST]
+
+- [MUST] 采用**按需挂载**模式，禁止每行常驻 `Dropdown` 实例：
+  - 列表态只渲染原生 `⋯` 按钮（透明背景、无边框、hover 显底色）
+  - 点击后为当前行挂载 `Dropdown`（`menu` 驱动 `items`，`open` 受控，`onOpenChange` 关闭时卸载）
+  - 任意时刻最多 1 个 `Dropdown` 实例
+  - 菜单项格式：图标 + 文字
+- [MUST] 参照 `src/views/module-management/components/ModulePowersPanel.vue` 中的 `MoreActions` 实现。