workspace/code/fms/开发规范.md

FMS 开发规范

规则等级：[MUST] = 必须遵守，违反即错误 [SHOULD] = 应当遵守，例外需说明 [NEVER] = 禁止

---

1. 代码风格 [MUST — 最高优先级]

• [MUST] 写法统一：同类场景（API 调用、错误处理、状态管理）使用一致的写法，新增代码模仿现有同类代码的风格，不自创写法。
• [MUST] 不滥用语法糖：能用 if/else 就不用三元/?.短路；能用 for 循环就不用 reduce/flatMap/解构嵌套。判断标准：不熟悉此代码的人能否一眼看懂？
• [MUST] 禁止无用嵌套：减少不必要的中变量、回调套回调、过度抽象。
• [MUST] 可读性 >= 简洁性：写得短但看不懂 → 不合格；写得稍长但一目了然 → 合格。

2. 构建与测试

• [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）序列化到前端时必须转为字符串。
• [MUST] 通用查询默认不传 search_columns / searchColumns；除非明确需要限制返回字段且已确认字段存在，否则采用接口默认返回。
• [MUST] config/dbconfigs 中的旧库仅用于参考表结构、历史数据和差异排查；除非用户明确指定，不修改旧库结构或数据。

4. 前端实现

• [MUST] 表格使用项目封装的 fms-table 组件，不从零实现表格。
• [MUST] 表单输入控件不添加 placeholder，label 只写字段名称，不追加“留空则...”这类操作提示信息。
• [MUST] 使用 FmsTree 时不设置 root-title，根节点标题由组件内部统一维护。
• [MUST] 优先复用项目现有组件和 Antdv Next 组件能力，不重复造轮子。
• [SHOULD] 页面中出现 ≥2 处相同/相近功能时，提取为可复用组件、composable 或 service 方法。
• [SHOULD] 抽取复用以确有收益为前提，不为简单逻辑增加无意义的封装。
• [MUST] 不添加 @media 响应式断点，按桌面端实现。
• [MUST] 新增 CSS 加 scoped，不影响其他页面。

5. CSS 规范

• [MUST] 样式写在 <style scoped lang="scss"> 中。
• [MUST] 优先用 Antdv Next 组件属性/设计 token 解决问题，能不写样式就不写。
• [MUST] 组件默认样式优先：Antdv Next 和项目公共组件已有默认样式时，直接使用默认效果，不重复覆盖颜色、图标、间距、边框、悬停状态等样式。只有用户明确要求，或默认样式确实无法满足功能需求时才允许覆盖；实施前需说明原因，并将范围控制在最小。
• [NEVER] 以“更明显”“更统一”“更美观”等主观判断为由，擅自覆盖组件默认样式或添加非需求所需的装饰样式。
• [MUST] 跨页面复用的样式抽取到 src/styles/main.scss 或共享 composable 中。
• [MUST] 不兼容移动端，不写 @media 断点。

6. 性能 [MUST — 高于其他所有规则]

性能是本项目最高约束，优先级高于代码便利性和组件一致性。

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 实现。