| 12345678910111213141516171819202122232425262728293031323334353637 |
- ---
- description: Vue/JS 代码结构与注释规范（录入流程等业务组件）
- alwaysApply: true
- ---
- # Vue 代码结构与可维护性
- 编写或重构 Vue 组件（尤其业务页、多步骤表单）时遵循：
- ## 结构分块（script setup）
- 按顺序组织，块之间用简短分隔注释：
- 1. Props / Emits（props 加 JSDoc 说明业务含义）
- 2. 常量（Session 键、默认值等集中为对象，如 `SESSION = { ... }`）
- 3. 页面状态（ref/reactive，关键字段一行注释）
- 4. 计算属性
- 5. 工具函数（readJson、数据映射等）
- 6. 业务逻辑（按领域分子块：加载、选中态、提交等）
- 7. 事件处理 / 生命周期
- ## 注释原则
- - 只注释**非显而易见**的内容：业务约定、缓存结构差异、分支原因
- - 不写「赋值给 x」「调用接口」类废话
- - 复杂函数顶部一行说明职责
- ## 可维护性
- - 魔法字符串、Session 键名集中管理，不散落
- - 重复逻辑抽成小函数（命名表意，如 `buildSelectedPayload`、`ensureCustomGroupTop`）
- - 区分数据结构时用 helper（如 `isScopedCache`、`flattenEquipment`）
- - 改动克制：只动需求相关代码，不顺手大重构
- ## 参考示例
- `src/views/old_mini/entry_information/components/selectEquipment.vue`
|
