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

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 流程

package/files/.github/skills/sync/menu-sync/USAGE.md

@@ -0,0 +1,104 @@
+# 使用指南：menu-sync（菜单同步）
+
+> **谁读这个文档**：团队成员（前端 + 后端联调时）
+> **AI 触发文件**：同目录 `SKILL.md`
+
+---
+
+## 这个 Skill 解决什么问题
+
+新页面写完后，需要在系统菜单中**注册一条菜单记录**才能从 UI 访问。这个 Skill：
+
+1. 拉取**线上菜单数据**到 `reports/SYS_MENU_INFO.md`（团队基线）
+2. 对比已生成页面 vs 线上菜单，**自动补齐缺失菜单项**
+3. 调用菜单注册接口（或生成 SQL 让后端执行）
+
+---
+
+## 何时使用
+
+- 新增页面后，从 UI 访问报"菜单不存在"
+- 一次性创建一批页面，需要批量注册菜单
+- 同步线上菜单基线（PROD/UAT/DEV 拉齐）
+
+---
+
+## 触发关键词
+
+`创建菜单` / `注册菜单` / `同步菜单` / `补菜单`
+
+---
+
+## 前置条件
+
+`.github/skills/sync/menu-sync/env/env.local.json`（首次使用先填写）：
+
+```json
+{
+  "gatewayPath": "https://uat-api.example.com",
+  "token": "Bearer xxx",
+  "tenantId": "10001",
+  "rootMenuId": "1234567890"
+}
+```
+
+> **`env.local.json` 不入 git**（已加 .gitignore）。每个开发者本地填自己的 token。
+
+---
+
+## 标准对话示例
+
+```
+你：把 src/views/produce/aiflow/ 下新建的 7 个页面同步到菜单
+AI：[Pre-flight]
+    步骤 1：读取线上菜单基线 reports/SYS_MENU_INFO.md（最新更新：2025-04-20）
+    步骤 2：扫描 src/views/produce/aiflow/ 共 7 个页面
+    步骤 3：对比缺失：5 项缺失，2 项已存在
+    步骤 4：将调用 /sys/menu/save 创建 5 项
+    [需你确认]：
+    - 父菜单：精整作业 → 客户管理（rootMenuId: xxx）
+    - 排序：sortNo 自动递增
+    - 权限标识：mmwr:customer:list 等
+    确认 yes/no？
+```
+
+---
+
+## 输出物
+
+1. **基线文件**：`.github/reports/SYS_MENU_INFO.md` —— 线上菜单的本地基线（团队 review 用）
+2. **同步报告**：`.github/reports/MENU_SYNC_<YYYYMMDD>.md` —— 本次新增/更新了哪些菜单
+3. **回滚 SQL**：报告里附带 DELETE SQL，用于回退
+
+---
+
+## 常见踩坑
+
+| 现象                 | 原因                         | 解法                                           |
+| -------------------- | ---------------------------- | ---------------------------------------------- |
+| 同步成功但 UI 看不到 | 用户角色没分配新菜单         | 跑 permission-sync（PLANNED）或后台手工分配    |
+| 401/403 报错         | env.local.json 的 token 过期 | 重新登录系统，从 Network 抓 Authorization 替换 |
+| 同名菜单重复创建     | 没读 SYS_MENU_INFO.md 基线   | 先跑一遍"刷新基线"再 sync                      |
+| 父菜单 ID 不对       | rootMenuId 配错              | 从浏览器开发者工具看父菜单的 dom data-id       |
+
+---
+
+## 团队协作流程
+
+1. 新人入职，让他先把 `env.local.json` 填一份（参考 env.example.json）
+2. **每周一**由 lead 跑一次"刷新基线"，确保 reports/SYS_MENU_INFO.md 最新
+3. PR 提交前自查"我加的菜单有没有提交进基线"
+4. 上线前再 sync 一次到生产环境（切换 env 文件中的 gatewayPath）
+
+---
+
+## FAQ
+
+**Q：env.local.json 泄露 token 危险吗？**
+A：危险。token 视同密码。已加 .gitignore + .npmignore。**不要 commit**。
+
+**Q：能不能直接给 SQL 让后端跑？**
+A：能。在指令里加"只生成 SQL，不调用接口"即可。
+
+**Q：和 dict-sync / permission-sync 关系？**
+A：菜单是入口，字典是值域，权限是访问控制。三者独立但配合。建议顺序：menu-sync → permission-sync → dict-sync。