---
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`