hwm09110 Vue 项目页面开发规范
开始写代码前先读项目。优先复用项目里已经存在的能力，再决定是否新增组件。页面实现必须贴合当前仓库的既有规范，而不是引入另一套新的开发风格。
除非用户明确要求使用其他语言，否则默认使用中文响应。
工作流程
1. 先建立项目上下文
至少读取下面这些内容，确认项目的实际开发方式：
package.json- Vite、Vue CLI、Nuxt 或其他构建配置
src/router/**或等价的路由注册位置src/views/**、src/pages/**、src/components/**- 共享布局、表格、表单、弹窗、查询区、卡片、详情区相关组件
src/api/**、src/services/**、src/stores/**、src/composables/**- lint、prettier、stylelint、TypeScript、提交规范等配置
- 全局样式、主题变量、设计 token、工具类约定
优先确认这些关键信息：
- 项目使用的是 Vue 2 还是 Vue 3
- 项目以 Options API、Composition API 还是混合风格为主
- 项目使用的是 Element Plus、Ant Design Vue、Naive UI、Vant，还是内部组件库
- 页面常见结构模式，例如
查询 + 表格 + 分页、Tabs + 详情、抽屉 + 表单、弹窗 + 表单 - 接口请求、权限、枚举、字典等通用逻辑的处理方式
如果仓库里已经给出了答案，就优先遵循仓库做法，而不是套用通用最佳实践。
2. 从真实代码中归纳项目规范
不要凭经验猜“Vue 项目一般怎么写”。至少参考一个相似页面和一个相似可复用组件，再归纳规范。
重点检查并遵循：
- 文件与目录命名方式
- SFC 代码块顺序，例如
template、script、style - 是否以
script setup为主 - props、emits、refs、接口返回、表格行数据的 TypeScript 写法
- 事件命名、属性命名、
v-model约定 - 样式方案是 scoped SCSS、CSS Modules、工具类还是 design tokens
- 状态放在局部、composables、Pinia 还是 Vuex
- 接口调用是在页面内直接发起，还是走共享 service 层
如果任务较大或场景不明确，在正式改代码前先简要总结识别到的项目规范。
3. 按严格优先级复用现有组件
选择组件时按下面顺序优先：
- 同业务语义的已有页面级区块
- 同业务域下已有业务组件
- 项目中已被多处使用的通用共享组件
- 仓库中已成标准的第三方 UI 基础组件
- 只有在复用明显不够时，才新建自定义组件
在创建新组件前，优先搜索：
- 相似表单
- 相似表格和列渲染
- 相似查询筛选区
- 相似卡片、列表、详情模块
- 相似弹窗、抽屉、上传、选择器、树选择器
如果已有组件不完全匹配，优先考虑按现有风格扩展它，而不是重造一个平行版本。
4. 判断是否需要抽离组件
满足以下任一情况时，优先考虑把页面区块抽成组件：
- 该区块有清晰的业务语义，且名称明确
- 同类区块已经或即将在两个及以上页面复用
- 该区块本身包含较复杂的交互、校验或局部状态
- 抽离后能显著降低页面文件复杂度，提高可读性
- 该区块需要稳定的对外接口，例如 props、emits、slots
出现以下情况时，优先保留在页面内：
- 逻辑高度耦合当前页面，基本不会复用
- 抽离之后只是搬运模板，没有形成清晰抽象
- 代码本身较短，留在页面里更直观
- 项目中同类结构通常就是直接写在页面中
抽组件时要保持抽象克制，不要为了“以后可能复用”而提前做成泛化组件。
5. 新代码必须说项目里的“语言”
新增页面或组件时，必须贴合仓库主流实现方式：
- 使用项目中占主流的 API 风格
- 遵循已有 props、emits、slots、expose 的设计方式
- 保持和周边文件一致的命名方式
- 遵循既有路径别名与 barrel 导出规则
- 遵循既有表单 schema、表格 schema、弹窗调用方式
- 保持一致的空态、加载态、权限控制、错误处理方式
如果必须新增组件：
- 放到符合当前项目习惯的目录中
- 名称优先体现业务语义，而不是纯视觉语义
- 对外 API 尽量小而明确
- 只在当前证据足够时才做成可复用组件
6. 实施过程中的输出要求
在执行任务时，必须明确说明：
- 复用了哪些现有文件或组件
- 识别到了哪些项目规范
- 是否新建了组件
- 为什么必须新建组件，或者为什么更适合保留在页面里
如果关键项目上下文还不够，先继续读代码，不要猜。
在进行较大规模实现前，先输出一份中文“开发前检查”。必须按下面结构填写真实内容，不能保留占位符：
## 开发前检查
### 1. 已识别的项目规范
- 技术栈：
- 页面组织方式：
- 状态管理方式：
- 样式方案：
- 接口调用方式：
- 组件书写习惯：
### 2. 可复用组件与代码
- 复用组件/模块 1：`路径`
复用原因：
- 复用组件/模块 2：`路径`
复用原因：
### 3. 本次页面实现方案
- 页面拆分思路：
- 准备直接复用的部分：
- 需要新增的部分：
### 4. 是否需要封装新组件
- 结论：需要 / 不需要
- 判断依据 1：
- 判断依据 2：
- 如果封装：组件名称、放置目录、对外 props/emits
- 如果不封装：为什么保留在页面内更合适
如果任务很小，可以写得简洁，但不能省略这四部分。
在通用检查单之后，再补一份“页面类型专项分析”：
- 以查询、表格、批量操作、分页、Tabs、行操作为主的页面，使用“列表页模板”
- 以新增、编辑、提交、校验、分步表单、抽屉表单、弹窗表单为主的页面，使用“表单页模板”
- 以记录展示、资料页、分组区块、时间线、卡片区、只读信息展示为主的页面，使用“详情页模板”
- 如果页面混合多种模式，选择主模式，并简要说明次要模式
只要是实质性的页面开发任务，就不要省略页面类型专项分析。
实现完成后，再按下面结构输出中文总结：
## 实现结果
- 已复用组件：
- 新增组件：
- 未封装组件的部分：
- 主要遵循的项目规范：
- 如有取舍，说明原因：
如果没有新建组件，要明确写出来。
决策原则
- 优先保证一致性，而不是追求技巧性。
- 优先遵循本项目先例，而不是外部习惯。
- 优先做小步、可组合的修改，而不是大拆大改。
- 优先扩展已有组件，而不是新建平行体系。
- 组件命名优先体现业务语义，而不是
InfoBox、ListItemWrapper这类视觉语义。 - 只有在代码库里有现实依据时，才判断值得抽成复用组件，不为想象中的未来复用提前设计。
- 当你声称识别了某项规范或某个复用依据时，尽量给出具体文件路径作为证据。
禁止事项
- 不要在没看现有页面前就生成一套全新页面架构
- 不要在一次改动里混用多种代码风格
- 不要引入一套新的组件命名体系
- 不要创建项目里本来不存在的“基础组件体系”
- 不要过度抽象只属于当前页面的逻辑
- 不要忽视已有的查询区、表格、表单、弹窗、布局组件
- 不要静默替换项目既有的接口、状态管理、样式方案
参考文件
按需读取这些参考文件：
references/project-scan-checklist.md：编码前的项目扫描清单references/component-extraction-rules.md：判断是否需要抽组件的规则references/chinese-output-template.md：开发前检查和实现后总结模板references/page-analysis-templates.md：列表页、表单页、详情页的固定分析模板