@qilitt-mickey/vue3-temp-skill 1.1.74 → 1.1.76

package/references/data-writeback.md

@@ -1,124 +1,124 @@
----
-name: data-writeback
-description: 编辑回显用 Object.assign(formData, res.data) 避免破坏响应式
-scope: project
-tags: [回显, 回填, 回写, useFormCheck, Object.assign, 编辑数据]
----
-
-# 数据回写与编辑
-
-> 按本文件示例编写，复用项目已有回显/回填约定与选择器回写方式，勿另起一套表单赋值实现。
-
-**完整性守则**：编辑回显**必须** `Object.assign(formData, res.data)`，禁止 `formData = res.data` 破坏响应式。提交按钮默认带 `loading`。
-
-## 强制样板（编辑回显）
-
-```typescript
-async function getDetail() {
-  const { id } = getParameter.value;
-  if (!id) return;
-  const res = await getDetailApi({ id });
-  if (res.status === 200 && res.data) Object.assign(formData, res.data);
-}
-```
-
-## 表单回显
-
-### 新增/编辑页
-
-```typescript
-async function getDetail() {
-  const { id } = getParameter.value
-  if (!id) return
-  const res = await getDetailApi({ id })
-  Object.assign(formData, res.data)
-}
-```
-
-### 选择类组件回填
-
-| 组件 | 回填方式 |
-|------|---------|
-| `ReSelectQuery` | 传 `edit-data` 属性 |
-| `el-tree-select` | 传 `:cache-data` 属性 |
-| `ReCascader` | 直接传 `v-model` 数组 |
-
-### 表单重置
-
-```typescript
-function reset() {
-  formRef.value.resetFields()
-}
-```
-
-## 表格行编辑
-
-表格内编辑时维护行状态，支持备份/恢复：
-
-```typescript
-const tableData = ref([])
-
-function startEdit(row) {
-  row._edit = true
-  row._backup = { ...row }  // 备份原始数据
-}
-
-function cancelEdit(row) {
-  Object.assign(row, row._backup)  // 恢复
-  row._edit = false
-}
-
-function saveEdit(row) {
-  // 调用保存接口
-  saveRowApi(row).then(() => {
-    row._edit = false
-    delete row._backup
-  })
-}
-```
-
-## 多表单联合校验
-
-页面包含多个表单时，使用 `validateForms` 统一校验：
-
-```typescript
-import { validateForms } from '@/utils/utils'
-
-const formModulesRef = ref([])
-const formModules = [
-  { refName: 'formA' },
-  { refName: 'formB' },
-]
-
-async function handleSubmit() {
-  const valid = await validateForms(formModulesRef.value, formModules)
-  if (!valid) return
-  // 所有表单校验通过，提交数据
-}
-```
-
-## useFormCheck Hook
-
-表单校验聚合，适用于需要监听多个字段校验状态的场景：
-
-```typescript
-import { useFormCheck } from '@/hooks/useFormCheck'
-
-const { validateStatus, onValidate } = useFormCheck(['field1', 'field2'])
-
-// 在 el-form 的 @validate 事件中收集
-// validateStatus 响应式记录各字段的校验结果
-```
-
-## 关键约定
-
-1. 回显时只覆盖表单字段，不破坏响应式结构（使用 `Object.assign` 而非重新赋值）。
-2. 编辑前备份数据（`_backup`），取消时恢复。
-3. 选择类组件回填需同时维护 code 与 name 两个字段。
-4. 多表单校验使用 `validateForms`，不要手动逐个调用 `validate()`。
-5. 提交按钮必须有 `loading` 状态防重复提交。
-
-## 关联文件
-
-- `src/utils/utils.ts`
-- `src/hooks/useFormCheck.ts`
+---
+name: data-writeback
+description: 编辑回显用 Object.assign(formData, res.data) 避免破坏响应式
+scope: project
+tags: [回显, 回填, 回写, useFormCheck, Object.assign, 编辑数据]
+---
+
+# 数据回写与编辑
+
+> 按本文件示例编写，复用项目已有回显/回填约定与选择器回写方式，勿另起一套表单赋值实现。
+
+**完整性守则**：编辑回显**必须** `Object.assign(formData, res.data)`，禁止 `formData = res.data` 破坏响应式。提交按钮默认带 `loading`。
+
+## 强制样板（编辑回显）
+
+```typescript
+async function getDetail() {
+  const { id } = getParameter.value;
+  if (!id) return;
+  const res = await getDetailApi({ id });
+  if (res.status === 200 && res.data) Object.assign(formData, res.data);
+}
+```
+
+## 表单回显
+
+### 新增/编辑页
+
+```typescript
+async function getDetail() {
+  const { id } = getParameter.value
+  if (!id) return
+  const res = await getDetailApi({ id })
+  Object.assign(formData, res.data)
+}
+```
+
+### 选择类组件回填
+
+| 组件 | 回填方式 |
+|------|---------|
+| `ReSelectQuery` | 传 `edit-data` 属性 |
+| `el-tree-select` | 传 `:cache-data` 属性 |
+| `ReCascader` | 直接传 `v-model` 数组 |
+
+### 表单重置
+
+```typescript
+function reset() {
+  formRef.value.resetFields()
+}
+```
+
+## 表格行编辑
+
+表格内编辑时维护行状态，支持备份/恢复：
+
+```typescript
+const tableData = ref([])
+
+function startEdit(row) {
+  row._edit = true
+  row._backup = { ...row }  // 备份原始数据
+}
+
+function cancelEdit(row) {
+  Object.assign(row, row._backup)  // 恢复
+  row._edit = false
+}
+
+function saveEdit(row) {
+  // 调用保存接口
+  saveRowApi(row).then(() => {
+    row._edit = false
+    delete row._backup
+  })
+}
+```
+
+## 多表单联合校验
+
+页面包含多个表单时，使用 `validateForms` 统一校验：
+
+```typescript
+import { validateForms } from '@/utils/utils'
+
+const formModulesRef = ref([])
+const formModules = [
+  { refName: 'formA' },
+  { refName: 'formB' },
+]
+
+async function handleSubmit() {
+  const valid = await validateForms(formModulesRef.value, formModules)
+  if (!valid) return
+  // 所有表单校验通过，提交数据
+}
+```
+
+## useFormCheck Hook
+
+表单校验聚合，适用于需要监听多个字段校验状态的场景：
+
+```typescript
+import { useFormCheck } from '@/hooks/useFormCheck'
+
+const { validateStatus, onValidate } = useFormCheck(['field1', 'field2'])
+
+// 在 el-form 的 @validate 事件中收集
+// validateStatus 响应式记录各字段的校验结果
+```
+
+## 关键约定
+
+1. 回显时只覆盖表单字段，不破坏响应式结构（使用 `Object.assign` 而非重新赋值）。
+2. 编辑前备份数据（`_backup`），取消时恢复。
+3. 选择类组件回填需同时维护 code 与 name 两个字段。
+4. 多表单校验使用 `validateForms`，不要手动逐个调用 `validate()`。
+5. 提交按钮必须有 `loading` 状态防重复提交。
+
+## 关联文件
+
+- `src/utils/utils.ts`
+- `src/hooks/useFormCheck.ts`

package/references/design-apply.md

@@ -1,167 +1,167 @@
----
-name: design-apply
-description: 设计变更集落地执行协议。接收 project-ui-design 输出的语义 ID 变更集 JSON，经 parser 三级匹配翻译为施工坐标，按"先结构后样式"顺序落地到目标项目，并过变更集合规闸门。
-scope: project
-tags: [design-apply, changeset, semantic-id, mapping, parser, theme, layout]
----
-
-# 设计变更集落地（design-apply）
-
-## 定位
-
-本能力组是**双 Skill 链路的项目侧执行端**：统一获取上游设计技能产出的「语义 ID 变更集」JSON（`design.changeset/1.0`，协议技术栈中立），由本 Skill 负责翻译并落地到目标项目（vue3-web-temp 及派生项目）。上游设计技能为 **project-ui-design**，协议文档见其 `references/changeset-schema.md`。
-
-**变更集落点唯一化（强制）**：变更集一律落在 `<落地项目>/.design/changeset-<场景>-<页型>-<主题>.json`，与交付台账 `ledger.json` 同目录；多份并存时无法判定「本轮交付物」（`design-audit.mjs` 会告警）。**落地台账**（`ledger.json`，由审计闸自动维护）记录每轮的 `covered/applicable`、设计层行数与已落地语义 ID 集合——它既是**回退检测**的依据，也是**断点续传**的入口：跨轮「继续」时按 `applicable − 已落地点数` 取剩余工作项，禁止把「继续」当成重跑一次同样的开头。
-
-```
-设计变更集 JSON（设计技能产出，中立协议）
-        ↓ 项目侧统一获取（设计技能不感知下游）
-parser match（确定性翻译）→ 施工坐标 → AI 按坐标改代码 → 合规闸门
-```
-
-分工原则：**词典（mapping/）负责精确，parser 负责翻译，AI 负责施工**。AI 不自行猜测任何点位定位或变量映射。
-
-**方向约定**：设计技能只做产出，不知道对接方是谁；本 Skill 是变更集的统一获取与执行方。变更集来源不限（project-ui-design 或任何按协议输出的设计工具/人工）。
-
-## 变更集获取与词汇约束下发
-
-变更集输入有两条来路，处理方式相同：
-
-1. **直接输入**：用户/上游直接给出变更集 JSON 文件或内容。
-2. **设计技能产出**：用户在设计会话产出变更集后转来落地。若用户尚未产出，可先**下发词汇约束**提升命中率——把 `node parser/index.js list --verbose` 的点位清单（ID + 字段 + 形态枚举）一并提供给设计侧（`mapping_version` 恒为 `1.0.0`，设计侧无需查询版本），设计侧按约束输出（约束外意图走其 pending 通道，落地时按 L3 处理）。
-
-无论哪条来路，落地流程一律走下文「执行流程」。
-
-**阅读纪律（防上下文溢出，与流程红线同级）**：
-
-1. **词典走 parser，禁直读全文**：`mapping/` 下 JSON 是 parser 的事实源，不是给人（AI）通读的——查点位用 `parser query <id>`、查清单用 `parser list`，**禁止整文件读入 `mapping/scenes/*.json` / `mapping/basic/*.json`**（仅 validator/regression 维护场景或 parser 明确报错需要人工核对单条时，用 `Grep` 精确抽取相关条目，不整读）。
-2. **落地会话禁读设计侧规范库**：设计技能的 `page-specs/`（规范/令牌/效果图）不属于项目侧视野——项目侧消费的是**变更集 + oracle.json + 登记表**三个交付物；`oracle.mockup` 指向的效果图由 `resolveFirstExisting` 跨库解析给 parser 使用，但人（AI）**不打开、不阅读设计侧效果图与规范文件**。
-3. **效果图只读一次**：期望值优先直接消费设计侧交付的 `oracle.json`；确需现场抽取时（无产物降级路径），抽取完成后值落盘，**后续轮次禁止反复打开效果图 HTML/JPG**。
-4. **做到哪一步读哪一份**：各步骤细节在 `steps/` 子文件（见下方索引），按当前阶段加载，禁止一次全部通读。
-
-## 出厂中性 · 变更集驱动（架构红线，违反即返工）
-
-**同一份模板源码，换一份变更集 = 换一套外观。** 任何「本次设计的结论」都不许固化进源码：
-
-| | 允许 | 禁止 |
-|---|---|---|
-| 模板源码 | 只提供**能力通道**：CSS 变量的消费者挂载点、form 枚举、DOM/属性钩子、正确的层叠优先级 | 预置**设计结论**：某个具体颜色、某句问候语、某个方位的指示条、某个硬编码尺寸 |
-| 设计产出 | AI 按本协议写入**设计层文件 / 页面级 scoped 样式 / DOM 属性与配置** | 为表达某张效果图而改写出厂样式文件与出厂组件（换设计即失效，且污染模板） |
-
-**判据（一句话）**：换一张效果图只需要换变更集、不需要改源码 ⇒ 架构正确；需要改源码才能换 ⇒ 设计结论被烧进了源码，必须回退为通道。
-
-- ❌ 反例：把「菜单激活指示条 = 左侧 3px」写死进 `sidebar.scss` / `element-plus.scss`；把问候语 DOM 直接加进 `lay-navbar/index.vue`；出厂 `<component>` 上硬编码 `data-content-mode="scroll"`。
-- ✅ 正例：`admin.layout.sidebar.menu` 暴露 `forms`（pill/indicator_left/indicator_right/indicator_underline/none）+ 几何字段，方位与粗细由变更集驱动；高度模式出厂不带任何属性，由页面根节点按变更集声明。
-
-**落地三落点判据**（每个变更字段先判落点再动手）：
-
-1. **有非样式通道**（DOM 属性 / 组件配置 / `platform-config.json`）→ 必须走该通道（form=scroll/fixed → 页面根节点 `data-content-mode`；form=card → `ShowModel`）。降级写成 SCSS = 未施工。
-2. **无通道且需改 DOM**（新增节点，如问候语欢迎区）→ 结构增量施工（AI 在组件模板内按 `form` 插入，保形插入、不删原代码）。
-3. **纯视觉表达**（颜色/圆角/间距/指示条几何）→ 设计层文件（见第 3 步）。
-
-**出厂文件仅在「通道缺失」时才可改动**，且须同时满足：① 补的是能力不是结论（补变量消费者、补 form 枚举、修层叠优先级）；② 在交付说明中单列「补通道」条目写明缺失点与修复内容。
-
-**模板源码注释保持中性（防污染）**：源码注释只写「这段代码做什么」——给后续维护者看。**禁止把面向 AI 的规范写进模板源码**：语义 ID、变更条目、本协议步骤号、缺口 / 自举 / 申报 / 「设计还原禁止改写本段」这类纪律条款，一律留在技能侧（`crud-pages.md` 结构通道 / `code-quality.md` 清单 / 本节），不得写进 `lay-*.vue`、`element-plus.scss`、`sidebar.scss`、`index.scss`、`design-shell.scss` 等模板文件。判据：**技能侧改了内容不需要动模板 ⇒ 正确**；改一条纪律还要去改模板注释 ⇒ 放错层。落地时技能侧只承诺「这四类通道的能力」（`data-content-mode` / `data-fill` / `design-shell.scss` 落点 / 构图钩子），具体契约与纪律全部由技能文档承载。
-
-## 输入契约（变更集 Schema v1.0）
-
-```jsonc
-{
-  "schema": "design.changeset/1.0",       // 协议版本（parser 兼容历史值 design-changeset/v1，新输出一律用 1.0）
-  "changeset_version": "1.0.0",           // 恒填 "1.0.0"
-  "mapping_version": "1.0.0",             // 恒填 "1.0.0"：版本由双侧 SKILL.md 体系版本统一管理，词典不单独演进。parser 校验口径 = 变更集值 ∈ 词典版本集合（恒通过）；仅协议破坏性升级时双侧同步升版
-  "scene": "admin",              // 场景前缀，须与 mapping 场景域一致
-  "scheme": "default",           // 方案标识（mode=restore 时必填）：取设计侧 page-specs/styles/registry.json 的方案 id；与 scene 共同定位「方案 × 场景」的清单/登记表
-  "mode": "restore",             // 交付模式（G8 模式闸）：restore=场景还原（scheme + oracle.mockup + coverage.registry 强制必填）；design=显式声明的轻量微调；缺省 design
-  "layout_type": "vertical",    // 标准布局枚举：vertical / horizontal / mix（字段名固定 layout_type，非 layout）
-  "page_bindings": [             // 页面映射（G13 页面绑定闸）：效果图页面 → 项目页面的身份声明；缺省 = 全部映射已有页面。效果图页面默认是设计角色坐标系，不是页面增量——未显式 target:"new" 时禁止新增页面/路由/菜单
-    { "mockup": "后台管理端.html", "target": "<项目已有列表页路由名/路径>", "note": "效果图标题是设计角色坐标系 = 已有页面换肤基线，非新增业务" }
-  ],
-  "global": { "brand_primary": "钴蓝-5" },  // 可选：全局令牌通道（整套主题切换优先走此节点；值 = 语义名或临时主题 hex）
-  "changes": [
-    {
-      "id": "admin.layout.sidebar.menu",     // 语义 ID（词典 key）
-      "visible": true,                       // 可选：隐藏用 false（v-if/display，不删代码）
-      "position": "right",                   // 可选：相对方位（left/right/top/bottom）
-      "form": "card",                        // 可选：形态切换（见条目 forms 枚举）
-      "style": { "menu_bg": "钴蓝-9" },      // 可选：抽象样式字段（词典 css_vars/custom_style_map key；值 = 语义名或 hex）
-      "apply_via": "admin.layout.sidebar.menu",   //  可选：本声明引用的锚点来源条目（缺省 = 自身；值 = 语义 ID，不是选择器）
-      "layer": { "menu_text": "host" },      //  可选：落点层级（host 宿主盒 / inner 内层文本盒）；可为字符串（整条生效）或「字段 → 层级」对象
-      "structure_ops": [                     //  可选：结构施工声明（数据 / 结构驱动点位必须给，只写 CSS = 无效声明）
-        { "op": "render_branch", "node": "status_tag", "source": "row.status" }
-      ]
-    }
-  ],
-  "pending": [                     // 新增 ID 通道：parser 解析 function/parent 供 L3 施工
-    { "proposed_id": "portal.content.banner.carousel", "function": "门户首页轮播横幅", "parent": "portal.content.banner" }
-  ]
-}
-```
-
-** 三个声明维度**（补齐「由哪个通道落地 / 被压时怎么赢 / 需要改结构时落在哪」）：
-
-| 字段 | 作用 | 值域 |
-|---|---|---|
-| `apply_via` | 指认本声明使用的**锚点来源条目**（在哪条词条的 `anchors` 上落地） | 语义 ID 字符串（2~4 段小写下划线）；不是选择器 / 变量名 |
-| `layer` | 指认样式落在**宿主盒**还是**内层文本盒** | `"host"` / `"inner"`；或 `{ "<style字段>": "host"｜"inner" }` |
-| `structure_ops[]` | 需要**结构施工**时声明「改哪个语义节点 / 数据源、怎么改」 | `op` ∈ `add_node` / `remove_node` / `move_node` / `render_branch` / `bind_source`；`node` / `source` / `from` / `to` 为语义名 |
-
-硬约束：
-- 变更集**只含变更点位**——未提到的点位一律不动。
-- `style` 字段为**抽象视觉语义**（`menu_bg`、`radius`），不得出现 CSS 变量名、选择器、`!important`、技术栈词汇。值口径：官方 5 套主题用语义名（`钴蓝-5`，译表见 `mapping/basic/semantic-values.json`）；库外临时主题直接 hex + `notes` 申报派生口径。
-- `position` 用相对方位词，不用像素坐标。
-- `visible: false` 只做隐藏，**永不删除代码**。
-- `apply_via` / `layer` / `structure_ops` 与 `style` 同属**语义声明**，同样不得出现选择器、CSS 变量名、DOM 词、技术栈词：`apply_via` 必须是语义 ID（锚点名）、`layer` 只能取 `host` / `inner`、`structure_ops[].op` 只能取五枚举。
-- `pending` 数组声明的是设计侧新点位，直接归入 L3 处理（不是错误）。**注意：pending 不是施工指令**——L3 施工的内容以 `changes[]` 中同 ID 新条目声明的意图为准；设计侧只登记 pending、未在 changes[] 声明意图的点位，落地时按出厂现状处理并在缺口清单中反馈「该点位设计意图缺失」。
-- parser 校验已实现：schema 硬校验、mapping_version 缺失/不匹配拒绝、禁词与 hex 位置校验、语义 ID 命名校验、`layer` / `apply_via` / `structure_ops` 结构校验。
-
-各步骤**子文件按需加载**（做到哪一步读哪一份，禁止一次全部通读）：
-
-| 步骤 | 子文件 | 内容 | 加载时机 |
-|---|---|---|---|
-| 第 0 步 | [`step0-preflight.md`](steps/step0-preflight.md) | 第 0 步 · 版本与场景检查 · 对接匹配（适配前置）· 运行时清场 | 每次落地开工前（版本/场景/对接匹配/运行时清场三件套） |
-| 第 1 步 | [`step1-match.md`](steps/step1-match.md) | 第 1 步 · parser 确定性匹配（含词典硬闸 G8-G11/G1/G5） | match 执行与闸门判读 |
-| 第 1 步附加 | [`step1b-audit.md`](steps/step1b-audit.md) | 第 1 步附加 · 挂载点审计（audit · 静态查三类隐性缺口） | match 通过后、施工前 |
-| 第 1 步附加（之二） | [`step1c-registry.md`](steps/step1c-registry.md) | 登记表覆盖率（子项级细闸） | 变更集带 coverage.registry / --registry 时 |
-| 第 2 步 | [`step2-structure.md`](steps/step2-structure.md) | 第 2 步 · 结构先行（visible / position / form · structure_ops · layer · suppress · priority 消费） | 进入施工时（先于一切样式） |
-| 第 3 步 | [`step3-style.md`](steps/step3-style.md) | 第 3 步 · 样式落地（两层转换 + 语义值译表） | 结构完成后 |
-| 第 3 步附加 | [`step3b-shell.md`](steps/step3b-shell.md) | 第 3 步附加 · 设计层落点文件 design-shell.scss（强制 · 覆写定律 · 自举） | 写任何新 CSS 规则前 |
-| 第 3 步附加（之二） | [`step3c-priority.md`](steps/step3c-priority.md) | 覆写优先级消费（硬步骤） | 与 step3b 配套，落规则前逐条判定 |
-| 第 4 步 | [`step4-l3.md`](steps/step4-l3.md) | 第 4 步 · L3 新模块处理（分级布局） | 存在未命中点位 / 新页面生成时 |
-| 第 5 步 | [`step5-gates.md`](steps/step5-gates.md) | 第 5 步 · 合规闸门（变更集专属检查清单） | 施工完成后、验收前 |
-| 第 6 步 | [`step6-verify.md`](steps/step6-verify.md) | 第 6 步 · 渲染态验收（oracle 逐点 diff · 快照回归 · 残差豁免） | 变更集含 oracle 时强制 |
-| 维护 | [`maintenance.md`](steps/maintenance.md) | 词典维护纪律 · 出厂状态漂移排查 | 改 mapping / 排查词典假前提时 |
-| 回归 | [`regression.md`](steps/regression.md) | 端到端回归 A-V · 配套工具 | 改 parser/mapping 后必跑 |
-
-**红线摘要（全文适用，细节在各步子文件）**：出厂中性 · 变更集驱动（上文）；先结构后样式（第 2 步先于第 3 步）；缺口只分「能力缺口（当场落地）」与「意图缺口（回流设计侧）」两类；**效果图/大文件只读一次**——期望值落盘 `oracle.json` 后，后续环节一律消费落盘产物，禁止反复重读。环境无 Node 时按「环境备注」（见 maintenance.md）人工执行。
-
-## 施工标记规范（G3：@sid / @closed，design-audit E15 机检）
-
-结构性声明（`form` / `suppress` / `suppress_inner` / `structure_ops` / `text_visible:none` / `visible:false`）**必须在设计层留机读标记**——声明了不等于落地了，没有标记就没有对账凭证（悬空声明例：`collapse_trigger.form=header_inline` 声明后壳层零规则，落地端静默无效）：
-
-| 标记 | 写法 | 作用 |
-|---|---|---|
-| `@sid` | 规则上方 `/* @sid: <语义ID> */` | 「变更集 ↔ 设计层」逐条落点对账（@sid 强制） |
-| `@closed` | 收口规则上方 `/* @closed: <通道名> */` | suppress 收口兑现证据（通道名 = 词典 forms/css_vars/custom_style_map 的键） |
-
-补充证据通道：通道为 `css_vars` 键时，设计层对该 var 写关闭值（`transparent` / `none` / `0`）即视为兑现，可免 `@closed` 标记；`visible:false` 的 `display:none` 规则按 E6 口径取证。**双向对账（E15）**：设计层 `@closed` 了变更集未声明的通道 → WARN（台账失真，收口记录进不了 D13 继承链）；声明了词典不认识的 form 值 / 通道名 → ERROR（悬空声明 = 无规则可挂）；结构性声明在设计层零证据 → ERROR。
-
-## 会话结束条件（终态硬闸，违反 = 交付未完成）
-
-**落地会话不许「做一批、停下来等用户说继续」。** 「继续」只是异常中断后的恢复手段，不是交付形态——把恢复手段当成默认流程 = 把 1:1 还原降级为多次半成品。本轮做完一批点位后，**必须自动进入下一批**，直到同时满足以下三条才允许结束会话：
-
-| # | 结束条件 | 判定方式 |
-|---|---|---|
-| 1 | **施工对账清零**：变更集全部已声明点位（`changes[]` ∪ `visible:false` ∪ `pending` 兑现项）全部落地 | 对照 `.design/ledger.json` 台账与 parser match 输出逐条核销；剩余 >0 → 继续施工 |
-| 2 | **静态闸清零**：`parser audit` 与 `scripts/design-audit.mjs` 的 ERROR = 0 | 两闸任一 ERROR 即返工，不得带错收尾 |
-| 3 | **验收闭环**：变更集含 oracle 时跑第 6 步 verify（本环境无浏览器 → 渲染态抽取显式移交用户执行，并说明移交项） | verify 全绿或移交说明已给出 |
-| 4 | **终态机读凭证**：跑通 `node <技能>/scripts/apply-final-gate.mjs --project <项目根> --container-width <内容区宽>`，取得 `FINAL-GATE: PASS` | 该命令串联四闸（changeset-selfcheck → parser match → parser audit → design-audit），任何一步非零即 `FAIL`，会话**不得以完成态结尾**；PASS 凭证自动写入 `.design/ledger.json` 的 `finalGate` 字段——终态判定以凭证为准，不以会话自述为准。**mode 唯一合法值 restore**：缺 mode / 写 design / 基线命中却缺三件套，均在此拦截 |
-
-> 条件 4 是 1–3 的机器汇总，不替代前三条的人读核对；前 3 条满足而凭证 FAIL = 仍有静态闸未清零，按 FAIL 输出逐项修复。
-
-**禁止的收尾话术（出现即判定为本轮交付失败，必须继续）**：
-- 「全量覆盖是迭代项 / 随迭代补齐 / 后续迭代再补其余细项 / 不阻塞已落地代码」——**覆盖率欠账 = 交付未完成**，不是迭代计划；设计侧变更集 `coverage.note` 出现同类表述同样视为交付失败（设计侧闸 D4/D9 会先拦，话术绕过闸的在这里兜底）。
-- 「核心点位已落地，其余点位影响不大」——影响大小不由落地端裁定，范围只由变更集 `coverage` 与登记表裁定。
-- 「已落地主题色与关键视觉，还原度已达 X%」——还原度以 verify / 登记表对账为准，不得以点位抽样自评。
-
-**环境能力边界**：无浏览器只豁免「渲染态抽取与 verify」，**不豁免逐点施工**——静态可落地的 190 子项必须在会话内全部落地，施工不需要浏览器。
+---
+name: design-apply
+description: 设计变更集落地执行协议。接收 project-ui-design 输出的语义 ID 变更集 JSON，经 parser 三级匹配翻译为施工坐标，按"先结构后样式"顺序落地到目标项目，并过变更集合规闸门。
+scope: project
+tags: [design-apply, changeset, semantic-id, mapping, parser, theme, layout]
+---
+
+# 设计变更集落地（design-apply）
+
+## 定位
+
+本能力组是**双 Skill 链路的项目侧执行端**：统一获取上游设计技能产出的「语义 ID 变更集」JSON（`design.changeset/1.0`，协议技术栈中立），由本 Skill 负责翻译并落地到目标项目（vue3-web-temp 及派生项目）。上游设计技能为 **project-ui-design**，协议文档见其 `references/changeset-schema.md`。
+
+**变更集落点唯一化（强制）**：变更集一律落在 `<落地项目>/.design/changeset-<场景>-<页型>-<主题>.json`，与交付台账 `ledger.json` 同目录；多份并存时无法判定「本轮交付物」（`design-audit.mjs` 会告警）。**落地台账**（`ledger.json`，由审计闸自动维护）记录每轮的 `covered/applicable`、设计层行数与已落地语义 ID 集合——它既是**回退检测**的依据，也是**断点续传**的入口：跨轮「继续」时按 `applicable − 已落地点数` 取剩余工作项，禁止把「继续」当成重跑一次同样的开头。
+
+```
+设计变更集 JSON（设计技能产出，中立协议）
+        ↓ 项目侧统一获取（设计技能不感知下游）
+parser match（确定性翻译）→ 施工坐标 → AI 按坐标改代码 → 合规闸门
+```
+
+分工原则：**词典（mapping/）负责精确，parser 负责翻译，AI 负责施工**。AI 不自行猜测任何点位定位或变量映射。
+
+**方向约定**：设计技能只做产出，不知道对接方是谁；本 Skill 是变更集的统一获取与执行方。变更集来源不限（project-ui-design 或任何按协议输出的设计工具/人工）。
+
+## 变更集获取与词汇约束下发
+
+变更集输入有两条来路，处理方式相同：
+
+1. **直接输入**：用户/上游直接给出变更集 JSON 文件或内容。
+2. **设计技能产出**：用户在设计会话产出变更集后转来落地。若用户尚未产出，可先**下发词汇约束**提升命中率——把 `node parser/index.js list --verbose` 的点位清单（ID + 字段 + 形态枚举）一并提供给设计侧（`mapping_version` 恒为 `1.0.0`，设计侧无需查询版本），设计侧按约束输出（约束外意图走其 pending 通道，落地时按 L3 处理）。
+
+无论哪条来路，落地流程一律走下文「执行流程」。
+
+**阅读纪律（防上下文溢出，与流程红线同级）**：
+
+1. **词典走 parser，禁直读全文**：`mapping/` 下 JSON 是 parser 的事实源，不是给人（AI）通读的——查点位用 `parser query <id>`、查清单用 `parser list`，**禁止整文件读入 `mapping/scenes/*.json` / `mapping/basic/*.json`**（仅 validator/regression 维护场景或 parser 明确报错需要人工核对单条时，用 `Grep` 精确抽取相关条目，不整读）。
+2. **落地会话禁读设计侧规范库**：设计技能的 `page-specs/`（规范/令牌/效果图）不属于项目侧视野——项目侧消费的是**变更集 + oracle.json + 登记表**三个交付物；`oracle.mockup` 指向的效果图由 `resolveFirstExisting` 跨库解析给 parser 使用，但人（AI）**不打开、不阅读设计侧效果图与规范文件**。
+3. **效果图只读一次**：期望值优先直接消费设计侧交付的 `oracle.json`；确需现场抽取时（无产物降级路径），抽取完成后值落盘，**后续轮次禁止反复打开效果图 HTML/JPG**。
+4. **做到哪一步读哪一份**：各步骤细节在 `steps/` 子文件（见下方索引），按当前阶段加载，禁止一次全部通读。
+
+## 出厂中性 · 变更集驱动（架构红线，违反即返工）
+
+**同一份模板源码，换一份变更集 = 换一套外观。** 任何「本次设计的结论」都不许固化进源码：
+
+| | 允许 | 禁止 |
+|---|---|---|
+| 模板源码 | 只提供**能力通道**：CSS 变量的消费者挂载点、form 枚举、DOM/属性钩子、正确的层叠优先级 | 预置**设计结论**：某个具体颜色、某句问候语、某个方位的指示条、某个硬编码尺寸 |
+| 设计产出 | AI 按本协议写入**设计层文件 / 页面级 scoped 样式 / DOM 属性与配置** | 为表达某张效果图而改写出厂样式文件与出厂组件（换设计即失效，且污染模板） |
+
+**判据（一句话）**：换一张效果图只需要换变更集、不需要改源码 ⇒ 架构正确；需要改源码才能换 ⇒ 设计结论被烧进了源码，必须回退为通道。
+
+- ❌ 反例：把「菜单激活指示条 = 左侧 3px」写死进 `sidebar.scss` / `element-plus.scss`；把问候语 DOM 直接加进 `lay-navbar/index.vue`；出厂 `<component>` 上硬编码 `data-content-mode="scroll"`。
+- ✅ 正例：`admin.layout.sidebar.menu` 暴露 `forms`（pill/indicator_left/indicator_right/indicator_underline/none）+ 几何字段，方位与粗细由变更集驱动；高度模式出厂不带任何属性，由页面根节点按变更集声明。
+
+**落地三落点判据**（每个变更字段先判落点再动手）：
+
+1. **有非样式通道**（DOM 属性 / 组件配置 / `platform-config.json`）→ 必须走该通道（form=scroll/fixed → 页面根节点 `data-content-mode`；form=card → `ShowModel`）。降级写成 SCSS = 未施工。
+2. **无通道且需改 DOM**（新增节点，如问候语欢迎区）→ 结构增量施工（AI 在组件模板内按 `form` 插入，保形插入、不删原代码）。
+3. **纯视觉表达**（颜色/圆角/间距/指示条几何）→ 设计层文件（见第 3 步）。
+
+**出厂文件仅在「通道缺失」时才可改动**，且须同时满足：① 补的是能力不是结论（补变量消费者、补 form 枚举、修层叠优先级）；② 在交付说明中单列「补通道」条目写明缺失点与修复内容。
+
+**模板源码注释保持中性（防污染）**：源码注释只写「这段代码做什么」——给后续维护者看。**禁止把面向 AI 的规范写进模板源码**：语义 ID、变更条目、本协议步骤号、缺口 / 自举 / 申报 / 「设计还原禁止改写本段」这类纪律条款，一律留在技能侧（`crud-pages.md` 结构通道 / `code-quality.md` 清单 / 本节），不得写进 `lay-*.vue`、`element-plus.scss`、`sidebar.scss`、`index.scss`、`design-shell.scss` 等模板文件。判据：**技能侧改了内容不需要动模板 ⇒ 正确**；改一条纪律还要去改模板注释 ⇒ 放错层。落地时技能侧只承诺「这四类通道的能力」（`data-content-mode` / `data-fill` / `design-shell.scss` 落点 / 构图钩子），具体契约与纪律全部由技能文档承载。
+
+## 输入契约（变更集 Schema v1.0）
+
+```jsonc
+{
+  "schema": "design.changeset/1.0",       // 协议版本（parser 兼容历史值 design-changeset/v1，新输出一律用 1.0）
+  "changeset_version": "1.0.0",           // 恒填 "1.0.0"
+  "mapping_version": "1.0.0",             // 恒填 "1.0.0"：版本由双侧 SKILL.md 体系版本统一管理，词典不单独演进。parser 校验口径 = 变更集值 ∈ 词典版本集合（恒通过）；仅协议破坏性升级时双侧同步升版
+  "scene": "admin",              // 场景前缀，须与 mapping 场景域一致
+  "scheme": "default",           // 方案标识（mode=restore 时必填）：取设计侧 page-specs/styles/registry.json 的方案 id；与 scene 共同定位「方案 × 场景」的清单/登记表
+  "mode": "restore",             // 交付模式（G8 模式闸）：restore=场景还原（scheme + oracle.mockup + coverage.registry 强制必填）；design=显式声明的轻量微调；缺省 design
+  "layout_type": "vertical",    // 标准布局枚举：vertical / horizontal / mix（字段名固定 layout_type，非 layout）
+  "page_bindings": [             // 页面映射（G13 页面绑定闸）：效果图页面 → 项目页面的身份声明；缺省 = 全部映射已有页面。效果图页面默认是设计角色坐标系，不是页面增量——未显式 target:"new" 时禁止新增页面/路由/菜单
+    { "mockup": "后台管理端.html", "target": "<项目已有列表页路由名/路径>", "note": "效果图标题是设计角色坐标系 = 已有页面换肤基线，非新增业务" }
+  ],
+  "global": { "brand_primary": "钴蓝-5" },  // 可选：全局令牌通道（整套主题切换优先走此节点；值 = 语义名或临时主题 hex）
+  "changes": [
+    {
+      "id": "admin.layout.sidebar.menu",     // 语义 ID（词典 key）
+      "visible": true,                       // 可选：隐藏用 false（v-if/display，不删代码）
+      "position": "right",                   // 可选：相对方位（left/right/top/bottom）
+      "form": "card",                        // 可选：形态切换（见条目 forms 枚举）
+      "style": { "menu_bg": "钴蓝-9" },      // 可选：抽象样式字段（词典 css_vars/custom_style_map key；值 = 语义名或 hex）
+      "apply_via": "admin.layout.sidebar.menu",   //  可选：本声明引用的锚点来源条目（缺省 = 自身；值 = 语义 ID，不是选择器）
+      "layer": { "menu_text": "host" },      //  可选：落点层级（host 宿主盒 / inner 内层文本盒）；可为字符串（整条生效）或「字段 → 层级」对象
+      "structure_ops": [                     //  可选：结构施工声明（数据 / 结构驱动点位必须给，只写 CSS = 无效声明）
+        { "op": "render_branch", "node": "status_tag", "source": "row.status" }
+      ]
+    }
+  ],
+  "pending": [                     // 新增 ID 通道：parser 解析 function/parent 供 L3 施工
+    { "proposed_id": "portal.content.banner.carousel", "function": "门户首页轮播横幅", "parent": "portal.content.banner" }
+  ]
+}
+```
+
+** 三个声明维度**（补齐「由哪个通道落地 / 被压时怎么赢 / 需要改结构时落在哪」）：
+
+| 字段 | 作用 | 值域 |
+|---|---|---|
+| `apply_via` | 指认本声明使用的**锚点来源条目**（在哪条词条的 `anchors` 上落地） | 语义 ID 字符串（2~4 段小写下划线）；不是选择器 / 变量名 |
+| `layer` | 指认样式落在**宿主盒**还是**内层文本盒** | `"host"` / `"inner"`；或 `{ "<style字段>": "host"｜"inner" }` |
+| `structure_ops[]` | 需要**结构施工**时声明「改哪个语义节点 / 数据源、怎么改」 | `op` ∈ `add_node` / `remove_node` / `move_node` / `render_branch` / `bind_source`；`node` / `source` / `from` / `to` 为语义名 |
+
+硬约束：
+- 变更集**只含变更点位**——未提到的点位一律不动。
+- `style` 字段为**抽象视觉语义**（`menu_bg`、`radius`），不得出现 CSS 变量名、选择器、`!important`、技术栈词汇。值口径：官方 5 套主题用语义名（`钴蓝-5`，译表见 `mapping/basic/semantic-values.json`）；库外临时主题直接 hex + `notes` 申报派生口径。
+- `position` 用相对方位词，不用像素坐标。
+- `visible: false` 只做隐藏，**永不删除代码**。
+- `apply_via` / `layer` / `structure_ops` 与 `style` 同属**语义声明**，同样不得出现选择器、CSS 变量名、DOM 词、技术栈词：`apply_via` 必须是语义 ID（锚点名）、`layer` 只能取 `host` / `inner`、`structure_ops[].op` 只能取五枚举。
+- `pending` 数组声明的是设计侧新点位，直接归入 L3 处理（不是错误）。**注意：pending 不是施工指令**——L3 施工的内容以 `changes[]` 中同 ID 新条目声明的意图为准；设计侧只登记 pending、未在 changes[] 声明意图的点位，落地时按出厂现状处理并在缺口清单中反馈「该点位设计意图缺失」。
+- parser 校验已实现：schema 硬校验、mapping_version 缺失/不匹配拒绝、禁词与 hex 位置校验、语义 ID 命名校验、`layer` / `apply_via` / `structure_ops` 结构校验。
+
+各步骤**子文件按需加载**（做到哪一步读哪一份，禁止一次全部通读）：
+
+| 步骤 | 子文件 | 内容 | 加载时机 |
+|---|---|---|---|
+| 第 0 步 | [`step0-preflight.md`](steps/step0-preflight.md) | 第 0 步 · 版本与场景检查 · 对接匹配（适配前置）· 运行时清场 | 每次落地开工前（版本/场景/对接匹配/运行时清场三件套） |
+| 第 1 步 | [`step1-match.md`](steps/step1-match.md) | 第 1 步 · parser 确定性匹配（含词典硬闸 G8-G11/G1/G5） | match 执行与闸门判读 |
+| 第 1 步附加 | [`step1b-audit.md`](steps/step1b-audit.md) | 第 1 步附加 · 挂载点审计（audit · 静态查三类隐性缺口） | match 通过后、施工前 |
+| 第 1 步附加（之二） | [`step1c-registry.md`](steps/step1c-registry.md) | 登记表覆盖率（子项级细闸） | 变更集带 coverage.registry / --registry 时 |
+| 第 2 步 | [`step2-structure.md`](steps/step2-structure.md) | 第 2 步 · 结构先行（visible / position / form · structure_ops · layer · suppress · priority 消费） | 进入施工时（先于一切样式） |
+| 第 3 步 | [`step3-style.md`](steps/step3-style.md) | 第 3 步 · 样式落地（两层转换 + 语义值译表） | 结构完成后 |
+| 第 3 步附加 | [`step3b-shell.md`](steps/step3b-shell.md) | 第 3 步附加 · 设计层落点文件 design-shell.scss（强制 · 覆写定律 · 自举） | 写任何新 CSS 规则前 |
+| 第 3 步附加（之二） | [`step3c-priority.md`](steps/step3c-priority.md) | 覆写优先级消费（硬步骤） | 与 step3b 配套，落规则前逐条判定 |
+| 第 4 步 | [`step4-l3.md`](steps/step4-l3.md) | 第 4 步 · L3 新模块处理（分级布局） | 存在未命中点位 / 新页面生成时 |
+| 第 5 步 | [`step5-gates.md`](steps/step5-gates.md) | 第 5 步 · 合规闸门（变更集专属检查清单） | 施工完成后、验收前 |
+| 第 6 步 | [`step6-verify.md`](steps/step6-verify.md) | 第 6 步 · 渲染态验收（oracle 逐点 diff · 快照回归 · 残差豁免） | 变更集含 oracle 时强制 |
+| 维护 | [`maintenance.md`](steps/maintenance.md) | 词典维护纪律 · 出厂状态漂移排查 | 改 mapping / 排查词典假前提时 |
+| 回归 | [`regression.md`](steps/regression.md) | 端到端回归 A-V · 配套工具 | 改 parser/mapping 后必跑 |
+
+**红线摘要（全文适用，细节在各步子文件）**：出厂中性 · 变更集驱动（上文）；先结构后样式（第 2 步先于第 3 步）；缺口只分「能力缺口（当场落地）」与「意图缺口（回流设计侧）」两类；**效果图/大文件只读一次**——期望值落盘 `oracle.json` 后，后续环节一律消费落盘产物，禁止反复重读。环境无 Node 时按「环境备注」（见 maintenance.md）人工执行。
+
+## 施工标记规范（G3：@sid / @closed，design-audit E15 机检）
+
+结构性声明（`form` / `suppress` / `suppress_inner` / `structure_ops` / `text_visible:none` / `visible:false`）**必须在设计层留机读标记**——声明了不等于落地了，没有标记就没有对账凭证（悬空声明例：`collapse_trigger.form=header_inline` 声明后壳层零规则，落地端静默无效）：
+
+| 标记 | 写法 | 作用 |
+|---|---|---|
+| `@sid` | 规则上方 `/* @sid: <语义ID> */` | 「变更集 ↔ 设计层」逐条落点对账（@sid 强制） |
+| `@closed` | 收口规则上方 `/* @closed: <通道名> */` | suppress 收口兑现证据（通道名 = 词典 forms/css_vars/custom_style_map 的键） |
+
+补充证据通道：通道为 `css_vars` 键时，设计层对该 var 写关闭值（`transparent` / `none` / `0`）即视为兑现，可免 `@closed` 标记；`visible:false` 的 `display:none` 规则按 E6 口径取证。**双向对账（E15）**：设计层 `@closed` 了变更集未声明的通道 → WARN（台账失真，收口记录进不了 D13 继承链）；声明了词典不认识的 form 值 / 通道名 → ERROR（悬空声明 = 无规则可挂）；结构性声明在设计层零证据 → ERROR。
+
+## 会话结束条件（终态硬闸，违反 = 交付未完成）
+
+**落地会话不许「做一批、停下来等用户说继续」。** 「继续」只是异常中断后的恢复手段，不是交付形态——把恢复手段当成默认流程 = 把 1:1 还原降级为多次半成品。本轮做完一批点位后，**必须自动进入下一批**，直到同时满足以下三条才允许结束会话：
+
+| # | 结束条件 | 判定方式 |
+|---|---|---|
+| 1 | **施工对账清零**：变更集全部已声明点位（`changes[]` ∪ `visible:false` ∪ `pending` 兑现项）全部落地 | 对照 `.design/ledger.json` 台账与 parser match 输出逐条核销；剩余 >0 → 继续施工 |
+| 2 | **静态闸清零**：`parser audit` 与 `scripts/design-audit.mjs` 的 ERROR = 0 | 两闸任一 ERROR 即返工，不得带错收尾 |
+| 3 | **验收闭环**：变更集含 oracle 时跑第 6 步 verify（本环境无浏览器 → 渲染态抽取显式移交用户执行，并说明移交项） | verify 全绿或移交说明已给出 |
+| 4 | **终态机读凭证**：跑通 `node <技能>/scripts/apply-final-gate.mjs --project <项目根> --container-width <内容区宽>`，取得 `FINAL-GATE: PASS` | 该命令串联四闸（changeset-selfcheck → parser match → parser audit → design-audit），任何一步非零即 `FAIL`，会话**不得以完成态结尾**；PASS 凭证自动写入 `.design/ledger.json` 的 `finalGate` 字段——终态判定以凭证为准，不以会话自述为准。**mode 唯一合法值 restore**：缺 mode / 写 design / 基线命中却缺三件套，均在此拦截 |
+
+> 条件 4 是 1–3 的机器汇总，不替代前三条的人读核对；前 3 条满足而凭证 FAIL = 仍有静态闸未清零，按 FAIL 输出逐项修复。
+
+**禁止的收尾话术（出现即判定为本轮交付失败，必须继续）**：
+- 「全量覆盖是迭代项 / 随迭代补齐 / 后续迭代再补其余细项 / 不阻塞已落地代码」——**覆盖率欠账 = 交付未完成**，不是迭代计划；设计侧变更集 `coverage.note` 出现同类表述同样视为交付失败（设计侧闸 D4/D9 会先拦，话术绕过闸的在这里兜底）。
+- 「核心点位已落地，其余点位影响不大」——影响大小不由落地端裁定，范围只由变更集 `coverage` 与登记表裁定。
+- 「已落地主题色与关键视觉，还原度已达 X%」——还原度以 verify / 登记表对账为准，不得以点位抽样自评。
+
+**环境能力边界**：无浏览器只豁免「渲染态抽取与 verify」，**不豁免逐点施工**——静态可落地的 190 子项必须在会话内全部落地，施工不需要浏览器。