一次闭环编写 Vue 页面与组件

把首次交付视为一次闭环：编辑前把目录、项目惯例、数据来源、编译边界和视觉约束变成有证据的实现契约；编辑后用对应检查证明契约成立。首次交付主动覆盖可由现有证据预见的结构、表单、语法和样式约束。

与其他 Skill 的边界

• 从 $organizing-frontend-components 进入时，直接复用其目标所有者、组件树和 TS/JS 后缀判断；本 Skill 继续完成 Vue 实现质量门禁。
• 单独调用且任务会新增、拆分或移动页面/组件时，先使用 $organizing-frontend-components 确定统一 index.vue 与递归 components/ 树，再继续本流程。
• 涉及真实后端对接时使用 $integrating-frontend-apis 完成契约门禁。契约未通过时保持显式 Mock 边界；URL、方法、参数和响应字段只取自可定位的契约证据。
• 新增或实质修改函数、类型、字段、共享变量或复杂流程时，在格式化前使用 $documenting-code 生成或同步注释；该阶段只处理注释，不重构代码或猜测接口与字段语义。

1. 建立证据账本

在第一次编辑前读取仓库指令，并检查目标组件、直接所有者、用户指定的参考组件、相邻实现、package.json、锁文件和构建配置。记录：

• Vue 主版本、SFC 编译器、UI 库及版本；
• JavaScript/TypeScript、Options/Composition API、表单模型采用 class、factory 还是 composable；
• 用户原型与参考页面分别约束哪些内容；
• 数据字段、API 契约和 Mock 的证据状态；
• 可能影响目标布局的全局样式、包装组件和主题变量。

参考组件的证明范围限于它实际展示的结构和项目惯例；新功能的接口、字段和业务规则分别寻找自身证据。按当前任务读取对应参考：

• 表单或数据模型：表单与模型门禁
• class 表单实例、实例方法与 Vue 2 响应性：class-模型门禁
• 数据 class、默认值或清空语义：缺省值门禁
• Element UI、Element Plus 或其他第三方组件库：第三方组件库门禁
• 模板插值、属性计算或 class/style 过长：模板紧凑性门禁
• SFC 局部样式、弹层和第三方组件覆盖：scoped-样式门禁
• Vue 2 或运算符兼容：模板与脚本运算符门禁
• API 不完整或需要 Mock：API 证据状态
• 原型、截图或指定参考页：视觉契约

完成标准：每个会影响文件结构、表单抽象、数据来源、模板语法或视觉布局的决定，都能指向用户输入或仓库文件；未知项已经明确标为 Mock、待确认或本次范围外。

2. 冻结实现契约

在动手前一次性列出本次需要交付的组件树、卫星文件、字段映射、交互状态和视觉约束。按以下所有权确定代码位置：

• index.vue 只承担模板、视图状态与交互编排。
• 表单默认值、规则、重置以及提交/回填映射进入同级 form.<ts|js>；独立于表单的领域或视图模型进入 model.<ts|js>。
• 请求适配进入 api.<ts|js>；契约缺失时改用同级 mock.<ts|js>，并保持与未来真实适配器相同的调用边界。
• class、factory、composable 和文件命名跟随最近的同类参考；参考采用 class 时继续使用 class。

发生组件拆分时，按 $organizing-frontend-components 的职责所有权规则，为每个子组件列出专属的 data/ref/reactive 状态、computed、watch、处理函数和请求响应数据，并连同初始化、重置及清理迁入对应的 index.vue 或同级卫星文件。父级保留共享数据、受控值和整体编排，通过 props/事件保持单一事实来源；仅展示父级数据的子组件继续通过 props 消费。Vue 具体检查见 组件拆分与状态归属门禁。

采用 class 作为表单或数据模型时，组件状态直接保存 new Model() 实例，不得为了所谓“Vue 响应性”使用 { ...new Model() }、JSON 克隆或 Object.assign({}, instance) 将其降级为普通对象。所有响应式字段必须在构造函数返回前完成初始化；Vue 2 运行期间不得直接新增未声明字段。

默认值、重置、回填以及 UI 模型到 API 请求参数的转换由模型实例拥有；转换方法使用依赖当前实例状态的非静态方法，例如 form.toPayload(contextId)。实际网络请求仍留在 api.<ts|js>，不得放进模型。这样组件可以直接调用当前表单实例，不需要在提交前重新 new Model(form) 恢复原型方法。

表单字段以模型为单一事实来源。每个字段都要同时核对默认值、组件库实际使用的双向绑定协议、字段关联键、校验规则、编辑回填、重置和提交映射；范围控件在表单中保持一个范围值，只在 I/O 边界拆装开始与结束字段。

内部数据以 void 0 统一表达“未提供”。null、裸 undefined 和空字符串只在用户输入、第三方组件或 API 契约明确赋予它们语义时保留；数组、对象、布尔值和数字继续使用与字段含义一致的 []、{}、false、0。在 I/O 边界按已确认契约决定省略字段，或转换为契约要求的 null/空字符串。

使用第三方组件库时，以项目锁定版本、现有封装和最近同类用法确定 props、events、slots、表单校验及弹层行为。Element UI 的 prop/rules、Element Plus 的参数化 v-model 或其他库的 name/modelValue 都只是各自契约，按当前项目的实际 API 实现。

视觉原型是目标布局契约，参考页面是项目风格证据。先固定字段顺序、分组、标签、必填标识、控件种类、尺寸、宽高和对齐，再处理装饰样式；先确认全局样式的实际影响，再添加局部覆盖。

完成标准：预定文件足以承载全部职责；每个字段都有明确的初始值和缺省值语义；每个表单字段和交互状态都有完整数据流；第三方组件的 props、events、slots 与主题行为均有版本证据；视觉清单无未决项；数据来源只处于“已证实 API”或“明确 Mock”状态。

3. 按编译通道实现

按冻结契约一次完成全部文件和状态，让模型职责从首次编辑起就处于最终所有者。保持 Vue 模板与 <script> 为两个独立编译通道：

• 模板表达式只使用目标 SFC 编译器已经证明支持的语法。Vue 2 或旧模板编译器下，模板中的 ?? 视为不兼容；把空值处理移入 computed/method，或使用已验证的显式判断。
• <script> 语法由项目的 Babel/TypeScript 链决定。项目支持时优先使用 ?.；脚本可选链的去留只由脚本构建证据决定。
• 复杂格式化、空值回退和业务分支移出模板，模板保留声明式绑定。

模板保持一行一意：每个 {{ ... }} 插值写在一个物理行内；插值或属性值中的计算超过项目 printWidth/max-len、被 formatter 拆行，或包含多步逻辑时，将无参数的响应式派生值提取为 computed，将需要行项目或其他参数的转换提取为 method。模板只保留短调用或属性访问。

静态 class 或 style 在单行中过长时，把对应展示声明收敛为语义化 CSS 类，写入当前 SFC 的 <style scoped> 域并在模板中引用；预处理器和第三方样式穿透语法跟随当前项目，scoped 始终为必需项。动态样式保留最短必要绑定，稳定部分仍归入 CSS 类。

Vue SFC 中的组件局部样式必须写在带 scoped 的 <style> 中；不得新增无 scoped 的样式块，也不得为单个页面或组件修改全局样式文件。可以复用既有全局主题、变量和组件库样式，但本组件的差异化覆盖必须由语义化根类约束在自身作用域内。

Dialog、Drawer、Popover、Select 下拉层等会挂载到 body 的节点，仍不得通过全局样式绕过作用域。优先使用组件库提供的 custom-class、popper-class、挂载目标或关闭 append-to-body 等能力，并在 scoped 块内使用当前 SFC 编译器已经证明支持的深度选择器。若现有挂载方式无法在 scoped 条件下可靠命中，应调整挂载或组件结构；不要静默改成全局覆盖。必须检查编译后的选择器和实际 DOM，确认没有残留字面量 ::v-deep、错误的 data-v 条件或未命中的规则。

对上传、日期范围、分页、选择、增删改和弹窗开关同时实现初始、成功、空值、取消/重置与编辑回填路径。Mock 应模拟异步边界和业务状态，并以明确命名和说明保持其未接后端的身份。

完成标准：实现契约中的每个文件、字段、状态和视觉约束均已落地；每个接口事实都有证据或明确 Mock 状态；class 模型保持实例身份和实例方法；每个 SFC 局部样式块均带 scoped，且没有为局部需求污染全局样式。

4. 运行契约级验证

验证范围覆盖所有新增或修改的 SFC 与卫星文件，而不是只检查报错文件：

1. 使用 $documenting-code 检查本轮新增或实质修改的函数、类型、字段、共享变量及相关契约注释，再对全部生成或修改的文件运行项目原生 formatter 和格式化检查；使用写入模式修复时，随后以检查模式确认零差异。缺少专用检查命令时，重新运行 formatter 并确认它不再产生变更。
2. 用项目实际 SFC 编译器编译每个受影响模板；对旧编译器额外确认模板中没有不支持的运算符。
3. 检查每个模板插值均位于一行，长计算已进入 computed/method，过长静态 class/style 已收敛到 <style scoped> 中的 CSS 类；确认不存在无 scoped 的 SFC 样式块和为局部组件产生的全局样式改动。
4. 运行项目原生的 lint、typecheck、相关测试与可行的构建；区分代码失败和既有环境失败。
5. 逐字段核对新增、编辑回填、校验、重置、提交/Mock 映射；采用 class 时确认 data() 直接保存实例、字段在构造阶段完整声明、请求映射由非静态实例方法完成；逐状态核对加载、空态、错误与操作反馈。
6. 有原型或截图时启动页面做视觉比对，检查既有全局主题作用后的实际结果；弹层额外核对实际 DOM 与编译选择器。仅通过 ESLint、Stylelint 或构建不等于视觉完成。
7. 搜索请求模块、URL 和调用点，证明每个网络契约都有来源；未确认接口只能指向明确的 Mock。
8. 复查 $organizing-frontend-components 给出的目录、后缀和职责所有权不变量；发生拆分时，逐项检查父级残留的状态、computed、watch、函数与请求响应数据，以及子组件 props/事件，确认子组件专属逻辑和生命周期处理已归位，保留的共享或受控状态有明确依据，且没有重复事实来源。

完整检查矩阵见 验证矩阵。

完成标准：格式化及其检查已经执行，所有适用门禁均通过；未运行项有具体原因；最终说明列出采用的仓库证据、Mock/真实 API 状态和验证结果。当前范围内可修复的失败全部修复并重新验证后才交付。