# 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`）序列化到前端时必须转为**字符串**。

## 4. 前端实现

- [MUST] 表格使用项目封装的 **`fms-table`** 组件，不从零实现表格。
- [MUST] 表单输入控件**不添加 `placeholder`**，用 `label` 或说明文字表达意图。
- [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] 跨页面复用的样式抽取到 `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` 实现。