@agile-team/wl-skills-kit 1.2.0 → 2.1.0

package/files/.github/skills/sync/dict-sync/SKILL.draft.md

@@ -0,0 +1,100 @@
+---
+name: dict-sync
+description: "[PLANNED — DRAFT, not yet active] 字典同步 Skill 设计草稿。机制类同 menu-sync：基于 reports/SYS_DICT_INFO.md 基线 ↔ 线上字典对比，自动补齐。"
+status: planned
+---
+
+# Skill: 字典同步（dict-sync）— 草稿
+
+> ⚠️ **本文件为设计草稿（SKILL.draft.md），未启用，不参与 AI 调度。**
+> 待相关后端接口稳定后，转正为 `SKILL.md`。
+
+---
+
+## 1. 设计目标
+
+页面 `data.ts` 中常使用 `logicType: BusLogicDataType.dict` 引用数据字典（如 `customer_state`、`mmwr_apply_status`）。新增页面/字段时，需要：
+
+1. 在系统字典表中**添加新字典码**（dictCode + 描述）
+2. 在字典表中**添加各项条目**（value + label + sortNo）
+3. 团队基线中保存当前线上字典（review/diff 用）
+
+`dict-sync` 自动化以上 3 步。
+
+---
+
+## 2. 数据流
+
+```
+本地基线                                后端接口                            Skill 触发
+─────────────────────────────────────  ─────────────────────────────────  ────────────────
+reports/SYS_DICT_INFO.md  ──fetch───→  GET  /sys/dict/listAll
+                          ←──compare───  POST /sys/dict/save
+                          ──upload───→  POST /sys/dictItem/batchSave    ─→  "同步字典"
+```
+
+---
+
+## 3. 三种工作模式
+
+| 模式              | 触发                  | 动作                                      |
+| ----------------- | --------------------- | ----------------------------------------- |
+| `pull`（刷基线）  | "刷新字典基线"        | 从线上拉全量字典 → 写入 SYS_DICT_INFO.md  |
+| `push`（推新增）  | "同步字典 / 创建字典" | 对比 data.ts 引用的字典 vs 基线，补齐线上 |
+| `audit`（仅检查） | "字典审计"            | 输出报告，不调接口                        |
+
+---
+
+## 4. 配置文件
+
+`.github/skills/sync/dict-sync/env/env.local.json`（不入 git）：
+
+```json
+{
+  "gatewayPath": "https://uat-api.example.com",
+  "token": "Bearer xxx",
+  "tenantId": "10001",
+  "_inherit": "复用 skills/sync/menu-sync/env/env.local.json 的 token、gatewayPath 等基础配置"
+}
+```
+
+> 实现时支持 `_inherit`：本目录无 env.local.json 时回落到 menu-sync 的同名文件。
+
+---
+
+## 5. 冲突处理策略
+
+| 场景                             | 策略                                         |
+| -------------------------------- | -------------------------------------------- |
+| 本地新增字典，线上不存在         | 调用 /sys/dict/save 创建                     |
+| 本地有的字典项，线上字典已禁用   | 询问：跳过 / 重新启用 / 视为新建             |
+| 本地与线上 value 相同 label 不同 | 询问：以本地为准 / 以线上为准 / 跳过         |
+| 线上有的字典/项，本地没有        | 仅记录日志，**不主动删除**（防误删生产数据） |
+
+---
+
+## 6. 与其他 Skill 联动
+
+- **page-codegen**：生成页面时如发现 data.ts 用到未在基线中的字典码，自动在生成报告中提示"运行 dict-sync 补齐"
+- **convention-audit**：审计 standards/data-ts.md 时，对比基线检测"字典码未定义"
+- **prototype-scan**：扫描原型阶段如识别出状态/枚举字段，提出字典码建议
+
+---
+
+## 7. 转正前的开发任务
+
+- [ ] 确认后端字典批量保存接口（save / batchSave / 字段名 / 响应外壳是否 `{code:2000,data}`）
+- [ ] 设计 SYS_DICT_INFO.md 自动序列化/反序列化（防 markdown 渲染破坏数据）
+- [ ] 实现 `_inherit` 配置回落机制
+- [ ] 决定字典审计严格度（必须有 enabled / sortNo / remark 等字段）
+- [ ] 提供 `dict-collect` Skill 或集成到 prototype-scan：从代码自动汇总字典依赖
+- [ ] 处理多语言字典（i18n label）
+- [ ] PROD 环境保护机制（推送前必须二次确认）
+
+---
+
+## 8. 风险与边界
+
+- **不删除**：永远不主动删除线上字典/字典项
+- **租户隔离**：env.local.json 的 tenantId 严格隔离
+- **审计日志**：每次 push 输出 `reports/DICT_SYNC_<YYYYMMDD>.md`，含调用接口列表 + 入参 + 响应 + 回滚 SQL

package/files/.github/skills/{menu-sync → sync/menu-sync}/SKILL.md

@@ -1,258 +1,258 @@
----
-name: menu-sync
-description: "Use when: creating system menus for newly generated pages, batch registering menus, or syncing pages.ts entries to the backend menu table. Triggers on: 创建菜单, 注册菜单, 同步菜单, 补菜单, menu sync, create menu, register menu."
----
-
-# Skill: 菜单同步（menu-sync）
-
-将 pages.ts 中注册的页面同步到后端菜单表，使系统能够路由到新页面。
-
-> **背景**：本项目是 Module Federation 子应用，页面在 `pages.ts` 注册后，
-> 还需要在后端菜单表中创建对应记录，系统才能路由到该页面。
-> 设计文档：`.github/docs/menu-sync-design.md`
-
----
-
-## 配置与使用方式（一次配置，无需反复填写）
-
-### 数据来源分工
-
-| 数据                                             | 来源               | 说明                                    |
-| ------------------------------------------------ | ------------------ | --------------------------------------- |
-| 菜单名称、路径、组件、权限、隐藏、排序、应用编码 | `SYS_MENU_INFO.md` | 原型/详设阶段自动生成，AI 直接读取      |
-| `parentMenuNameCode`                             | API 自动查询       | AI 调 children 接口获取，无需手填       |
-| **gatewayPath、parentMenuId、sysAppNo、token**    | `env.local.json`   | 每套环境不同，唯一需要手动维护的 4 个值 |
-
-### 配置文件（只需填 4 个字段）
-
-`.github/skills/menu-sync/env/env.local.json`（已加入 `.gitignore`，本地维护，不提交）
-
-```json
-{
-  "gatewayPath": "http://网关地址:端口",
-  "parentMenuId": "父级菜单ID",
-  "sysAppNo": "应用编码（从已有菜单的sysAppNo字段获取，非明文）",
-  "token": "Bearer Token（不含bearer前缀）"
-}
-```
-
-> 字段说明及获取方式见 `env/guide.md`
-
-### 使用步骤
-
-1. **首次**：按 `env/guide.md` 填写 `env.local.json` 的 4 个字段
-2. **之后**：直接对 AI 说「帮我创建菜单」/「同步菜单」/「补菜单」
-3. AI 自动执行：读 `SYS_MENU_INFO.md` → 读 `env.local.json` → 查父级已有子节点 → 逐条对比去重 → 调 `/system/menu/save` → 输出 created/skipped 结果表
-4. **全程无需手动执行任何命令**
-
----
-
-## 方案演进路线
-
-| 阶段        | 方案                              | 状态          | 说明                                                 |
-| ----------- | --------------------------------- | ------------- | ---------------------------------------------------- |
-| **Phase 1** | AI 调用现有 API 逐条创建          | ✅ 当前可用   | 利用 `/system/menu/save` 接口，AI 充当自动化脚本     |
-| **Phase 2** | 前端推送脚本 `pnpm run menu:push` | ⏳ 待后端接口 | 需后端提供 `POST /system/menu/batchPush` upsert 接口 |
-
----
-
-## Phase 1：AI 调用 API 创建菜单（当前方案）
-
-> 此方案参考平台伙伴的 jh4j-cloud skill，适配 cx-ui-produce 项目。
-> 本质是 **menu-sync-design.md 的方案 C（只增不删）**，由 AI 自动执行。
-
-### 前置条件
-
-1. 用户提供后端系统管理地址（如 `http://localhost:9000` 或实际网关地址）
-2. 用户提供有效的 Bearer Token（从浏览器开发者工具 Network 面板复制）
-3. 用户提供父级菜单 ID（`menuId`），可通过查询接口获取
-
-### 输入
-
-用户提供以下信息（或 AI 从 pages.ts 自动提取）：
-
-- **父级菜单 ID**：`menuId`（后端菜单树中的上级目录 ID）
-- **应用编码**：`sysAppNo`（如 `produce`、`sale`、`system`）
-- **菜单数据**：可以是 pages.ts 中的条目，或用户手动指定
-
-菜单类型：
-
-| type | 含义         | 必填字段                                      |
-| ---- | ------------ | --------------------------------------------- |
-| `M`  | 目录         | `menuName`, `path`                            |
-| `C`  | 菜单（页面） | `menuName`, `path`, `permission`, `component` |
-| `A`  | 动作按钮     | `menuName`, `path`                            |
-
-### 执行流程
-
-#### Step 1: 查询父级下已有菜单（防重复）
-
-```
-GET {gatewayPath}/system/menu/children?current=1&size=100&menuId={parentMenuId}
-Headers:
-  authorization: bearer {token}
-  Sysappno: {sysAppNo}
-```
-
-#### Step 2: 逐条创建菜单
-
-对于每条待创建的菜单，先检查是否与已有菜单重名（`menuName` 或 `path` 相同），重复则跳过。
-
-> **响应码说明**：后端成功响应为 `code: 2000`（非标准 HTTP 200），判断成功应检查 `response.body.code === 2000` 或 `message` 包含"成功"。
-
-```
-POST {gatewayPath}/system/menu/save
-Headers:
-  authorization: bearer {token}
-  Sysappno: {sysAppNo}
-  Content-Type: application/json
-
-Body:
-{
-  "useCache": 1,
-  "icon": "list",
-  "common": 2,
-  "hidden": false,
-  "type": "C",
-  "parentId": "{parentMenuId}",
-  "sysAppNo": "{sysAppNo}",
-  "orderNum": {nextOrder},
-  "menuName": "客户档案",
-  "menuNameCode": "{parentMenuNameCode}:{pinyinName}",
-  "path": "mmwrCustomerArchive",
-  "permission": "mmwrCustomerArchive",
-  "component": "produce/production-mmwr/aiflow/mmwr-customer-archive/index.vue"
-}
-```
-
-#### Step 3: 记录结果
-
-创建完成后输出结果表格：
-
-| 菜单名   | path                | type | 状态                | id     |
-| -------- | ------------------- | ---- | ------------------- | ------ |
-| 客户档案 | mmwrCustomerArchive | C    | ✅ created          | 123456 |
-| 客户详情 | mmwrCustomerDetail  | C    | ⏭️ skipped (已存在) | -      |
-
-### 字段生成规则
-
-| 字段           | 规则                                                                                         |
-| -------------- | -------------------------------------------------------------------------------------------- |
-| `menuName`     | 取 pages.ts 的 `label`                                                                       |
-| `path`         | 页面目录名转 camelCase（如 `mmwr-customer-archive` → `mmwrCustomerArchive`）                 |
-| `component`    | 取 pages.ts 的 `name`（如 `produce/production-mmwr/aiflow/mmwr-customer-archive/index.vue`） |
-| `permission`   | `{域}:{path}:list`（如 `produce:mmwrCustomerArchive:list`）                                  |
-| `menuNameCode` | `{父级menuNameCode}:{菜单名拼音}`（小写连续拼接）                                            |
-| `hidden`       | 表单页/详情页等隐藏路由设为 `true`，菜单可见页面设为 `false`                                 |
-| `orderNum`     | 从父级已有菜单最大 orderNum + 1 开始递增                                                     |
-| `icon`         | 目录级 `"list"`，菜单级 `"list"`                                                             |
-
-### pages.ts → 菜单数据映射示例
-
-以 `aiflow` 子模块为例：
-
-```
-pages.ts 条目:
-  ["mmwr-customer-archive", "客户档案"]
-
-→ 菜单数据:
-  {
-    type: "C",
-    menuName: "客户档案",
-    path: "mmwrCustomerArchive",
-    component: "produce/production-mmwr/aiflow/mmwr-customer-archive/index.vue",
-    permission: "produce:mmwrCustomerArchive:list",
-    hidden: false
-  }
-
-隐藏页面示例:
-  ["mmwr-customer-apply-add-form", "客户申请新增表单"]
-
-→ 菜单数据:
-  {
-    type: "C",
-    menuName: "客户申请新增表单",
-    path: "mmwrCustomerApplyAddForm",
-    component: "produce/production-mmwr/aiflow/mmwr-customer-apply-add-form/index.vue",
-    permission: "produce:mmwrCustomerApplyAddForm:list",
-    hidden: true    // ← 表单页隐藏
-  }
-```
-
-### 隐藏页面判断规则
-
-以下页面类型应设置 `hidden: true`：
-
-- 目录名含 `-form`（独立路由表单页）
-- 目录名含 `-detail`（详情页）
-- 目录名含 `-history`（历史查询页）
-- SYS_MENU_INFO.md 中标注为"隐藏菜单"的页面
-
-### 跳过规则
-
-- 当前父级下已有同名 `menuName` → 跳过
-- 当前父级下已有相同 `path` → 跳过
-- 跳过时不做更新、不做覆盖，只记录"已跳过"
-
-### 树形菜单处理
-
-如果需要先创建目录再创建子菜单：
-
-1. 先以 `type: "M"` 创建目录
-2. 保存成功后取返回的 `data.id`
-3. 以新 `id` 作为 `parentId` 继续创建子菜单
-
----
-
-## Phase 2：推送脚本方案（待后端接口就绪后启用）
-
-> 对应 menu-sync-design.md 的 **方案 D（推送覆盖）**，是最终目标方案。
-
-### 与 Phase 1 的差异
-
-| 维度     | Phase 1 (AI 调 API) | Phase 2 (推送脚本)           |
-| -------- | ------------------- | ---------------------------- |
-| 执行者   | AI                  | `pnpm run menu:push` 脚本    |
-| 更新能力 | 只增不删（方案 C）  | upsert 覆盖（方案 D）        |
-| 改名支持 | ❌ 会产生重复       | ✅ 按 componentPath 匹配更新 |
-| 权限影响 | 无                  | 无（只写结构字段）           |
-| 依赖     | Token + 网关地址    | 后端 `batchPush` 接口        |
-
-### 所需后端接口
-
-```
-POST /system/menu/batchPush
-```
-
-- 按 `componentPath` 做 upsert（存在则更新结构字段，不存在则新增）
-- **不删除**后端多余的菜单
-- **不碰**权限/角色绑定字段
-- 详见 `.github/docs/menu-sync-design.md`
-
-### pages.ts 扩展
-
-在 `SharedPageItem` 中增加 `menuMeta` 字段：
-
-```typescript
-export interface SharedPageItem {
-  name: string;
-  label: string;
-  menuMeta?: {
-    parentName: string;
-    menuPath: string;
-    sortOrder: number;
-    appCode: string;
-    hidden?: boolean;
-    icon?: string;
-  };
-}
-```
-
-### 切换步骤
-
-1. 后端提供 `batchPush` 接口
-2. 在 pages.ts 的页面条目中补充 `menuMeta`
-3. 创建 `scripts/menu-push.ts`（vite-node 执行）
-4. 注册 `pnpm run menu:push` 命令
-5. page-codegen Skill 生成页面时自动填充 `menuMeta`
-6. 废弃 Phase 1 的 AI 手动调 API 流程
+---
+name: menu-sync
+description: "Use when: creating system menus for newly generated pages, batch registering menus, or syncing pages.ts entries to the backend menu table. Triggers on: 创建菜单, 注册菜单, 同步菜单, 补菜单, menu sync, create menu, register menu."
+---
+
+# Skill: 菜单同步（menu-sync）
+
+将 pages.ts 中注册的页面同步到后端菜单表，使系统能够路由到新页面。
+
+> **背景**：本项目是 Module Federation 子应用，页面在 `pages.ts` 注册后，
+> 还需要在后端菜单表中创建对应记录，系统才能路由到该页面。
+> 设计文档：`.github/guides/architecture.md`
+
+---
+
+## 配置与使用方式（一次配置，无需反复填写）
+
+### 数据来源分工
+
+| 数据                                             | 来源                       | 说明                                    |
+| ------------------------------------------------ | -------------------------- | --------------------------------------- |
+| 菜单名称、路径、组件、权限、隐藏、排序、应用编码 | `reports/SYS_MENU_INFO.md` | 由 page-codegen 追加写入，AI 直接读取   |
+| `parentMenuNameCode`                             | API 自动查询               | AI 调 children 接口获取，无需手填       |
+| **gatewayPath、parentMenuId、sysAppNo、token**   | `env.local.json`           | 每套环境不同，唯一需要手动维护的 4 个值 |
+
+### 配置文件（只需填 4 个字段）
+
+`.github/skills/sync/menu-sync/env/env.local.json`（已加入 `.gitignore`，本地维护，不提交）
+
+```json
+{
+  "gatewayPath": "http://网关地址:端口",
+  "parentMenuId": "父级菜单ID",
+  "sysAppNo": "应用编码（从已有菜单的sysAppNo字段获取，非明文）",
+  "token": "Bearer Token（不含bearer前缀）"
+}
+```
+
+> 字段说明及获取方式见 `env/guide.md`
+
+### 使用步骤
+
+1. **首次**：按 `env/guide.md` 填写 `env.local.json` 的 4 个字段
+2. **之后**：直接对 AI 说「帮我创建菜单」/「同步菜单」/「补菜单」
+3. AI 自动执行：读 `reports/SYS_MENU_INFO.md` → 读 `env.local.json` → 查父级已有子节点 → 逐条对比去重 → 调 `/system/menu/save` → 输出 created/skipped 结果表
+4. **全程无需手动执行任何命令**
+
+---
+
+## 方案演进路线
+
+| 阶段        | 方案                              | 状态          | 说明                                                 |
+| ----------- | --------------------------------- | ------------- | ---------------------------------------------------- |
+| **Phase 1** | AI 调用现有 API 逐条创建          | ✅ 当前可用   | 利用 `/system/menu/save` 接口，AI 充当自动化脚本     |
+| **Phase 2** | 前端推送脚本 `pnpm run menu:push` | ⏳ 待后端接口 | 需后端提供 `POST /system/menu/batchPush` upsert 接口 |
+
+---
+
+## Phase 1：AI 调用 API 创建菜单（当前方案）
+
+> 此方案参考平台伙伴的 jh4j-cloud skill，适配 cx-ui-produce 项目。
+> 本质是 **menu-sync-design.md 的方案 C（只增不删）**，由 AI 自动执行。
+
+### 前置条件
+
+1. 用户提供后端系统管理地址（如 `http://localhost:9000` 或实际网关地址）
+2. 用户提供有效的 Bearer Token（从浏览器开发者工具 Network 面板复制）
+3. 用户提供父级菜单 ID（`menuId`），可通过查询接口获取
+
+### 输入
+
+用户提供以下信息（或 AI 从 pages.ts 自动提取）：
+
+- **父级菜单 ID**：`menuId`（后端菜单树中的上级目录 ID）
+- **应用编码**：`sysAppNo`（如 `produce`、`sale`、`system`）
+- **菜单数据**：可以是 pages.ts 中的条目，或用户手动指定
+
+菜单类型：
+
+| type | 含义         | 必填字段                                      |
+| ---- | ------------ | --------------------------------------------- |
+| `M`  | 目录         | `menuName`, `path`                            |
+| `C`  | 菜单（页面） | `menuName`, `path`, `permission`, `component` |
+| `A`  | 动作按钮     | `menuName`, `path`                            |
+
+### 执行流程
+
+#### Step 1: 查询父级下已有菜单（防重复）
+
+```
+GET {gatewayPath}/system/menu/children?current=1&size=100&menuId={parentMenuId}
+Headers:
+  authorization: bearer {token}
+  Sysappno: {sysAppNo}
+```
+
+#### Step 2: 逐条创建菜单
+
+对于每条待创建的菜单，先检查是否与已有菜单重名（`menuName` 或 `path` 相同），重复则跳过。
+
+> **响应码说明**：后端成功响应为 `code: 2000`（非标准 HTTP 200），判断成功应检查 `response.body.code === 2000` 或 `message` 包含"成功"。
+
+```
+POST {gatewayPath}/system/menu/save
+Headers:
+  authorization: bearer {token}
+  Sysappno: {sysAppNo}
+  Content-Type: application/json
+
+Body:
+{
+  "useCache": 1,
+  "icon": "list",
+  "common": 2,
+  "hidden": false,
+  "type": "C",
+  "parentId": "{parentMenuId}",
+  "sysAppNo": "{sysAppNo}",
+  "orderNum": {nextOrder},
+  "menuName": "客户档案",
+  "menuNameCode": "{parentMenuNameCode}:{pinyinName}",
+  "path": "mmwrCustomerArchive",
+  "permission": "mmwrCustomerArchive",
+  "component": "produce/production-mmwr/aiflow/mmwr-customer-archive/index.vue"
+}
+```
+
+#### Step 3: 记录结果
+
+创建完成后输出结果表格：
+
+| 菜单名   | path                | type | 状态                | id     |
+| -------- | ------------------- | ---- | ------------------- | ------ |
+| 客户档案 | mmwrCustomerArchive | C    | ✅ created          | 123456 |
+| 客户详情 | mmwrCustomerDetail  | C    | ⏭️ skipped (已存在) | -      |
+
+### 字段生成规则
+
+| 字段           | 规则                                                                                         |
+| -------------- | -------------------------------------------------------------------------------------------- |
+| `menuName`     | 取 pages.ts 的 `label`                                                                       |
+| `path`         | 页面目录名转 camelCase（如 `mmwr-customer-archive` → `mmwrCustomerArchive`）                 |
+| `component`    | 取 pages.ts 的 `name`（如 `produce/production-mmwr/aiflow/mmwr-customer-archive/index.vue`） |
+| `permission`   | `{域}:{path}:list`（如 `produce:mmwrCustomerArchive:list`）                                  |
+| `menuNameCode` | `{父级menuNameCode}:{菜单名拼音}`（小写连续拼接）                                            |
+| `hidden`       | 表单页/详情页等隐藏路由设为 `true`，菜单可见页面设为 `false`                                 |
+| `orderNum`     | 从父级已有菜单最大 orderNum + 1 开始递增                                                     |
+| `icon`         | 目录级 `"list"`，菜单级 `"list"`                                                             |
+
+### pages.ts → 菜单数据映射示例
+
+以 `aiflow` 子模块为例：
+
+```
+pages.ts 条目:
+  ["mmwr-customer-archive", "客户档案"]
+
+→ 菜单数据:
+  {
+    type: "C",
+    menuName: "客户档案",
+    path: "mmwrCustomerArchive",
+    component: "produce/production-mmwr/aiflow/mmwr-customer-archive/index.vue",
+    permission: "produce:mmwrCustomerArchive:list",
+    hidden: false
+  }
+
+隐藏页面示例:
+  ["mmwr-customer-apply-add-form", "客户申请新增表单"]
+
+→ 菜单数据:
+  {
+    type: "C",
+    menuName: "客户申请新增表单",
+    path: "mmwrCustomerApplyAddForm",
+    component: "produce/production-mmwr/aiflow/mmwr-customer-apply-add-form/index.vue",
+    permission: "produce:mmwrCustomerApplyAddForm:list",
+    hidden: true    // ← 表单页隐藏
+  }
+```
+
+### 隐藏页面判断规则
+
+以下页面类型应设置 `hidden: true`：
+
+- 目录名含 `-form`（独立路由表单页）
+- 目录名含 `-detail`（详情页）
+- 目录名含 `-history`（历史查询页）
+- reports/SYS_MENU_INFO.md 中标注为"隐藏菜单"的页面
+
+### 跳过规则
+
+- 当前父级下已有同名 `menuName` → 跳过
+- 当前父级下已有相同 `path` → 跳过
+- 跳过时不做更新、不做覆盖，只记录"已跳过"
+
+### 树形菜单处理
+
+如果需要先创建目录再创建子菜单：
+
+1. 先以 `type: "M"` 创建目录
+2. 保存成功后取返回的 `data.id`
+3. 以新 `id` 作为 `parentId` 继续创建子菜单
+
+---
+
+## Phase 2：推送脚本方案（待后端接口就绪后启用）
+
+> 对应 menu-sync-design.md 的 **方案 D（推送覆盖）**，是最终目标方案。
+
+### 与 Phase 1 的差异
+
+| 维度     | Phase 1 (AI 调 API) | Phase 2 (推送脚本)           |
+| -------- | ------------------- | ---------------------------- |
+| 执行者   | AI                  | `pnpm run menu:push` 脚本    |
+| 更新能力 | 只增不删（方案 C）  | upsert 覆盖（方案 D）        |
+| 改名支持 | ❌ 会产生重复       | ✅ 按 componentPath 匹配更新 |
+| 权限影响 | 无                  | 无（只写结构字段）           |
+| 依赖     | Token + 网关地址    | 后端 `batchPush` 接口        |
+
+### 所需后端接口
+
+```
+POST /system/menu/batchPush
+```
+
+- 按 `componentPath` 做 upsert（存在则更新结构字段，不存在则新增）
+- **不删除**后端多余的菜单
+- **不碰**权限/角色绑定字段
+- 详见 `.github/guides/architecture.md`
+
+### pages.ts 扩展
+
+在 `SharedPageItem` 中增加 `menuMeta` 字段：
+
+```typescript
+export interface SharedPageItem {
+  name: string;
+  label: string;
+  menuMeta?: {
+    parentName: string;
+    menuPath: string;
+    sortOrder: number;
+    appCode: string;
+    hidden?: boolean;
+    icon?: string;
+  };
+}
+```
+
+### 切换步骤
+
+1. 后端提供 `batchPush` 接口
+2. 在 pages.ts 的页面条目中补充 `menuMeta`
+3. 创建 `scripts/menu-push.ts`（vite-node 执行）
+4. 注册 `pnpm run menu:push` 命令
+5. page-codegen Skill 生成页面时自动填充 `menuMeta`
+6. 废弃 Phase 1 的 AI 手动调 API 流程