65 lines
6.1 KiB
Markdown
65 lines
6.1 KiB
Markdown
# FMS 开发规范
|
||
|
||
## 一、构建与测试
|
||
|
||
- **不要过多封装**
|
||
- 完成功能后不主动执行构建。
|
||
- 允许执行测试以验证改动（如后端 `./mvnw test`、前端 `pnpm fmt:check` 及页面功能验证）。
|
||
- 只有用户明确要求时，才执行构建或启动服务。
|
||
- 交付时说明本次是否执行了测试及测试结果，并说明未执行构建。
|
||
|
||
## 二、后端接口
|
||
|
||
- 优先使用现有通用接口完成查询、分页、保存和取号：
|
||
- `/data/loaddata`
|
||
- `/data/page`
|
||
- `/data/saveobjt`
|
||
- `/data/nextid`
|
||
- 不随意修改通用接口的地址、参数、返回结构和处理逻辑。
|
||
- 不随意新增业务专用接口。
|
||
- 不新增 services 这类接口或者文件。
|
||
- 如果现有通用接口确实无法完成需求，必须先说明原因、拟新增或修改的内容及影响范围，并取得用户确认后再实施。
|
||
|
||
## 三、前端实现
|
||
|
||
- 优先使用项目现有组件和 Antdv Next 组件，不重复实现组件已有的功能。
|
||
- 页面存在相同或相近功能时，优先抽取为可复用组件、组合函数或服务方法。
|
||
- 抽取复用应以确实减少重复和降低维护成本为前提，不为简单逻辑增加无必要的封装。
|
||
- 优先复用现有布局、样式变量和组件能力，以尽量少的 CSS 完成功能。
|
||
- 不使用 CSS 重复实现组件已有的尺寸、状态、交互和响应式能力。
|
||
- 新增 CSS 应限制在当前组件作用域内，避免影响其他页面。
|
||
- 不需要兼容移动端，按桌面端实现即可。
|
||
- 表格尽量使用 `fms-table` 组件（项目封装的表格组件），不重复从零实现表格能力。
|
||
- 表单输入控件不需要添加 placeholder（占位提示文字），用字段 label 或说明文字表达意图即可。
|
||
|
||
## 四、变更范围
|
||
|
||
- 修改应围绕当前需求，避免无关重构和格式化其他文件。
|
||
- 保留已有功能和用户尚未提交的改动。
|
||
- 涉及通用接口、公共组件或全局样式的变更，实施前必须先确认影响范围。
|
||
|
||
## 五、CSS 规范
|
||
|
||
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` 响应式断点；如确有需要，须先与需求方确认。
|
||
|
||
## 六、性能优先（重要、重要、重要）
|
||
|
||
- **性能是本项目的一等约束，贯穿全部层面**，优先于代码便利与组件/外观一致性。适用于前端、后端、数据库及一切场景，任何改动都不得引入可感知的性能退化（卡顿、慢查询、高延迟、资源浪费等）。
|
||
- **前端**：表格单元格、列表项、滚动区域默认使用原生 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 多组织路由）配置与慢查询需关注，避免连接泄漏与长事务。
|
||
- 性能问题应在设计/编码阶段前置考量，而非事后优化；涉及慢查询、重接口、大列表等高风险改动，实施前应说明性能影响与规避方式。
|
||
|
||
## 七、表格「更多操作」按钮
|
||
|
||
- 表格/列表中若需要「更多操作」（⋯）按钮并弹出菜单，**必须采用按需挂载模式**（禁止为每一行常驻一个 `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`，菜单含「编辑 / 复制 / 设置多语言」三项，每项带图标与文字。新增类似按钮时直接参照此模式。
|