102 lines
5.9 KiB
Markdown
102 lines
5.9 KiB
Markdown
# 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` 实现。
|