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

package/files/.github/standards/08-git.md

@@ -0,0 +1,60 @@
+# 08 — Git 分支 & 提交规范
+
+> **强制度**：🔴 必遵。
+> 本项目强制使用 `@robot-admin/git-standards`（commitlint + cz-customizable + husky）。
+
+---
+
+## 分支命名
+
+```
+feat/xxx       新功能
+fix/xxx        Bug 修复
+refactor/xxx   重构
+docs/xxx       文档更新
+chore/xxx      构建/工具变更
+perf/xxx       性能优化
+test/xxx       测试相关
+```
+
+## 提交方式（强制）
+
+```bash
+git add .
+git cz   # 交互式选择 type + scope + 描述
+```
+
+❌ **禁止**：`git commit -m "xxx"` 直接提交（绕过规范校验）
+
+## 提交类型（type）枚举
+
+`feat` / `fix` / `perf` / `docs` / `style` / `refactor` / `test` / `chore` / `revert` / `build` / `deps` / `wip`
+
+## scope 强制要求
+
+提交时必须填写影响范围，格式：`type(scope): 中文描述`
+
+```
+feat(mmwr-customer): 新增客户档案页面
+fix(domestic-trade): 修复订单状态切换闪烁
+refactor(c_formModal): 重构表单回填逻辑
+```
+
+## husky 钩子未生效时
+
+1. 检查 `@robot-admin/git-standards` 是否已执行 `init`
+2. 检查 `.husky/` 目录及 `pre-commit`、`commit-msg` 钩子文件
+3. 联系 CHENY（工号 409322）
+
+## AI 生成 commit message 参考
+
+AI 在协助提交时，按以下格式输出建议：
+
+```
+feat(模块名): 中文描述
+
+- 变更点 1
+- 变更点 2
+```
+
+不主动执行 `git commit`，由开发者通过 `git cz` 交互式确认。

package/files/.github/standards/09-typescript.md

@@ -0,0 +1,71 @@
+# 09 — TypeScript 类型规范
+
+> **强制度**：🟡 建议。
+> 项目使用 `strict: false` 宽松模式起步。
+
+---
+
+## 类型定义优先级
+
+- **`interface`**：可扩展的对象类型
+- **`type`**：联合类型 / 工具类型 / 字面量类型
+
+```typescript
+// ✅ interface 用于对象
+interface User {
+  id: string;
+  name: string;
+}
+
+// ✅ type 用于联合 / 工具类型
+type Status = "pending" | "active" | "closed";
+type PartialUser = Partial<User>;
+```
+
+## any 使用约束
+
+❌ 禁止滥用 `any`。`as any` 仅允许出现在以下场景：
+
+1. 对接外部 SDK 返回值的边界处
+2. `AbstractPageQueryHook.create()` 的返回值接收（框架限制）
+3. 确实无法确定类型时，加注释 `// TODO: 待补充类型`
+
+```typescript
+// ✅ 允许（框架限制）
+return Page.create() as any
+
+// ✅ 允许（外部边界，加注释）
+const sdkResult = thirdPartySdk.call() as any // TODO(cheny): SDK 1.5 后补充类型
+
+// ❌ 禁止（懒省事）
+function handleClick(row: any) { ... }
+```
+
+## 类型导入
+
+- 业务类型统一从 `@/types/page` 桶文件引入
+- ❌ 不重复定义同名类型
+- ✅ 复杂类型在 `@/types/` 下分文件管理
+
+## 字段类型
+
+- 业务字段优先用 `string` / `number` / `boolean`
+- ❌ 不默认用 `any`
+- ⚠️ 可选字段用 `?`，可空字段用 `| null`
+
+```typescript
+interface Customer {
+  id: string;
+  name: string;
+  remark?: string; // 可选
+  closedAt: string | null; // 可空（后端明确返回 null）
+}
+```
+
+## 与 @robot-admin/git-standards 兼容
+
+| 项目状态             | 处理                                       |
+| -------------------- | ------------------------------------------ |
+| 已有 `tsconfig.json` | ✅ 直接安装 git-standards，零冲突          |
+| 无 TS 环境           | 先 `tsc --init` 初始化，再装 git-standards |
+| ESLint TS 规则       | `warn` 级别，不阻断提交，仅作质量提示      |

package/files/.github/standards/10-pinia.md

@@ -0,0 +1,57 @@
+# 10 — Pinia 状态管理规范
+
+> **强制度**：🔴 必遵。
+
+---
+
+## 何时用 Store
+
+- ✅ 跨页面共享：用户信息、权限、全局配置、主题
+- ✅ 需要持久化到 `localStorage` 的状态
+- ✅ 多个不相邻组件共享的会话级状态
+
+## 何时不用 Store（保留页面级 ref）
+
+- ❌ 当前页的查询参数、列表数据、分页、弹窗状态
+- ❌ data.ts 内部的所有状态（默认页面级，不提升到 Store）
+
+## 强制约束
+
+❌ **禁止**：在 `data.ts` 里 `import` Store
+
+> 理由：data.ts 是**页面数据契约**，应保持职责单一，不依赖全局状态。
+> 跨页面共享数据通过 props / 路由参数 / 组件层包装传入，不直接耦合 Store。
+
+## Store 文件结构
+
+```
+src/stores/
+└── {domain}/
+    └── index.ts        每个领域独立目录，避免单文件膨胀
+```
+
+## Store 命名
+
+- `useXxxStore` 标准命名
+- 若项目已统一 `s_` 前缀（如 `s_userStore`），全项目保持一致
+
+```typescript
+// src/stores/user/index.ts
+export const useUserStore = defineStore("user", () => {
+  const userInfo = ref<User | null>(null);
+  function setUser(u: User) {
+    userInfo.value = u;
+  }
+  return { userInfo, setUser };
+});
+```
+
+## 持久化
+
+如需持久化，推荐 `pinia-plugin-persistedstate`：
+
+```typescript
+defineStore('user', () => { ... }, {
+  persist: { storage: localStorage, paths: ['userInfo'] }
+})
+```

package/files/.github/standards/11-form-validation.md

@@ -0,0 +1,81 @@
+# 11 — 表单与校验规范
+
+> **强制度**：🔴 必遵。
+
+---
+
+## c_formModal / c_formSections 场景
+
+平台已封装组件，**内置完整生命周期**：
+
+```
+open → 数据回填 → validate → submit → close / resetFields
+```
+
+✅ AI 直接按组件文档使用即可，**不需要重复写 validate / resetFields 逻辑**。
+
+参考：`src/components/local/c_formModal/README.md`
+
+---
+
+## FORM_ROUTE 独立路由表单页（c_formModal 不适用时）
+
+无 c_formModal 托管的复杂表单（多 Tab、多子表、向导式），**必须遵守**：
+
+### 1. 提交前调用 validate
+
+```typescript
+async function handleSubmit() {
+  const valid = await formRef.value?.validate();
+  if (!valid) return;
+  await postAction(API_CONFIG.save, formData.value);
+}
+```
+
+### 2. 取消/离开调用 resetFields
+
+```typescript
+function handleCancel() {
+  formRef.value?.resetFields();
+  router.back();
+}
+
+onBeforeRouteLeave(() => {
+  formRef.value?.resetFields();
+});
+```
+
+### 3. rules 在 data.ts 中独立导出
+
+```typescript
+// data.ts
+export const formRules = {
+  fieldName: [
+    { required: true, message: "请输入字段名", trigger: "blur" },
+    { max: 50, message: "不超过 50 字符", trigger: "blur" },
+  ],
+  status: [{ required: true, message: "请选择状态", trigger: "change" }],
+};
+```
+
+❌ **禁止**：把 rules 写在 `<template>` 字面量里。
+
+---
+
+## 校验时机
+
+| 时机              | 触发                             |
+| ----------------- | -------------------------------- |
+| `blur` 失焦       | 字符串类、必填字段               |
+| `change` 变更     | 选择类（select / date / picker） |
+| 手动 `validate()` | 提交时全量校验                   |
+| 字段间联动        | `watch` + 手动 `validateField()` |
+
+## AI 检查清单
+
+生成 FORM_ROUTE 模板代码时确认：
+
+- [ ] 提交按钮 click 处理函数中调用了 `formRef.value?.validate()`
+- [ ] 取消按钮 / 路由离开钩子中调用了 `resetFields()`
+- [ ] rules 定义在 `data.ts` 而非 `<template>`
+- [ ] 必填字段都加了 `required: true` 校验规则

package/files/.github/standards/12-base-table.md

@@ -0,0 +1,116 @@
+# 12 — BaseTable 渲染与 AGGrid cid 唯一性规范
+
+> **强制度**：🔴 必遵。
+
+---
+
+## 渲染模式（强制）
+
+所有 `BaseTable` 必须默认使用 **AGGrid** 渲染：
+
+```vue
+<BaseTable
+  ref="tableRef"
+  render-type="agGrid"
+  cid="mca-745831"
+  :data="list"
+  :columns="columns"
+  showToolbar
+/>
+```
+
+> 全局配置：`envConfig().componentConfig.table = { renderType: 'agGrid' }`
+> 设置后所有未显式指定 `render-type` 的 BaseTable 默认 AGGrid。
+
+---
+
+## cid 命名规则（核心）
+
+AGGrid 通过 `cid` 持久化列配置（列宽、顺序、显示），**cid 必须全局唯一**。
+
+### 表格级 cid
+
+```
+格式：{页面目录首字母缩写}-{Unix秒后6位}
+```
+
+**生成规则（AI 执行）**：
+
+1. 取页面 kebab-case 目录名，每个单词取首字母拼接为缩写
+2. 取 `Math.floor(Date.now() / 1000).toString().slice(-6)` 作为 6 位时间戳后缀
+3. 用 `-` 连接
+
+**示例**：
+
+| 页面目录                 | 缩写 | cid               |
+| ------------------------ | ---- | ----------------- |
+| `mmwr-customer-archive`  | mca  | `mca-745831`      |
+| `domestic-trade-order`   | dto  | `dto-745832`      |
+| 同页面第二个表格（子表） | mca  | `mca-745831-sub1` |
+| 同页面第三个表格         | mca  | `mca-745831-sub2` |
+
+### 列级 cid
+
+```
+格式：{表格cid的缩写部分}-{fieldName}
+```
+
+```typescript
+// 表格缩写为 mca
+columnsDef(): TableColumnDesc<any>[] {
+  return [
+    { type: 'selection' },
+    { type: 'index' },
+    { label: '取样',     name: 'sampling',           cid: 'mca-sampling',           width: 70 },
+    { label: '线上公告', name: 'onlineAnnouncement', cid: 'mca-onlineAnnouncement', width: 70 },
+  ]
+}
+```
+
+---
+
+## 禁止事项
+
+- ❌ 随机短字符串 `cid="ipiCfsb"`（AI 重新生成时极易碰撞）
+- ❌ 纯字段名 `cid: "sampling"`（不同页面同名字段冲突）
+- ❌ 省略 cid（列配置持久化完全失效）
+- ❌ 跨页面复用同一 cid
+
+---
+
+## Pre-flight 声明示例
+
+```
+✅ cid 已生成：mca-745831（mmwr-customer-archive）
+✅ 列级 cid 前缀：mca-
+```
+
+---
+
+## 完整代码示例
+
+```vue
+<!-- index.vue -->
+<template>
+  <BaseTable
+    ref="tableRef"
+    render-type="agGrid"
+    cid="mca-745831"
+    :data="list"
+    :columns="columns"
+    showToolbar
+  />
+</template>
+```
+
+```typescript
+// data.ts
+columnsDef(): TableColumnDesc<any>[] {
+  return [
+    { type: 'selection' },
+    { type: 'index' },
+    { label: '客户名称', name: 'customerName', cid: 'mca-customerName', minWidth: 120 },
+    { label: '状态',     name: 'status',       cid: 'mca-status',       minWidth: 80 },
+  ]
+}
+```

package/files/.github/standards/13-platform-components.md

@@ -0,0 +1,123 @@
+# 13 — 平台组件合规规范（核心 AI 质量门控）
+
+> **强制度**：🔴 必遵 + 阻断式。
+> 这是防止 AI 绕过平台封装、自由发挥使用 `el-*` 原生组件的核心规则。
+
+---
+
+## 总原则
+
+> **优先使用平台封装组件；无对应封装时才允许使用 `el-*` 原生组件；
+> 跨 3+ 页面相同 `el-*` 模式 → convention-audit 输出"组件提取建议"到 `reports/`，由人工评审决定是否封装。**
+
+---
+
+## 组件强制对照表
+
+| 场景                | 优先使用（有则必用）                          | 替代方案                     |
+| ------------------- | --------------------------------------------- | ---------------------------- |
+| 查询栏              | `BaseQuery`                                   | ❌ el-form 手写查询区        |
+| 工具栏 / 操作按钮行 | `BaseToolbar`                                 | ❌ 自定义按钮排列            |
+| 列表 / 表格         | `BaseTable` (`render-type="agGrid"`)          | ❌ el-table                  |
+| 表单弹窗            | `c_formModal`                                 | ❌ el-dialog + el-form 手写  |
+| 列表选择弹窗        | `c_listModal`                                 | ❌ el-dialog + el-table 手写 |
+| 表单内容分区        | `c_formSections`                              | ❌ 裸分组                    |
+| 分割标题            | `c_spliterTitle`                              | ❌ el-divider                |
+| 复杂路由表单页      | FORM-ROUTE 模板                               | ❌ 完全手写                  |
+| 日期 / 日期范围     | `jh-date` / `jh-date-range`                   | ❌ el-date-picker            |
+| 文件上传            | `jh-file-upload`                              | ❌ el-upload                 |
+| 用户选择            | `jh-user-picker`                              | ❌ 自定义弹窗选人            |
+| 部门选择            | `jh-dept-picker`                              | ❌ 同上                      |
+| 下拉 / 选择器       | `jh-select` / `jh-picker`                     | ❌ el-select 手写 options    |
+| 只读文本展示        | `jh-text`                                     | ❌ span/div 直接渲染         |
+| 分页                | `jh-pagination`                               | ❌ el-pagination             |
+| 上下分栏            | `jh-drag-row`                                 | ❌ 手动 flex/grid            |
+| 左右分割            | `C_Splitter`                                  | ❌ 手动 flex/grid            |
+| 树形面板            | `C_Tree`                                      | ❌ el-tree 手写              |
+| 状态标签            | `C_TagStatus`                                 | ❌ el-tag + 颜色映射         |
+| HTTP 请求           | `getAction/postAction/putAction/deleteAction` | ❌ axios / fetch 直接调用    |
+
+---
+
+## 组件在 template 中的书写顺序
+
+当页面同时存在多个区块时，**有则按下列顺序排列**（**全部可选，不强制必须存在**）：
+
+```
+BaseQuery → BaseToolbar → BaseTable → jh-pagination
+```
+
+✅ 仅有 BaseTable 的页面：直接写 BaseTable，没问题
+✅ 仅 BaseQuery + BaseToolbar 的录入型页面：按此顺序，后接表单区即可
+❌ 顺序颠倒：BaseToolbar 写在 BaseQuery 之前
+
+---
+
+## docs/ 文档前置读取清单
+
+生成涉及以下场景的代码时，AI 必须先读取对应文档（按需，不全读）：
+
+| 涉及组件 / 模式             | 必读文档                                      |
+| --------------------------- | --------------------------------------------- |
+| `jh-date` / `jh-date-range` | `docs/jh-date.md` / `docs/jh-date-range.md`   |
+| `jh-file-upload`            | `docs/jh-file-upload.md`                      |
+| `jh-user-picker`            | `docs/jh-user-picker.md`                      |
+| `jh-dept-picker`            | `docs/jh-dept-picker.md`                      |
+| `jh-select`                 | `docs/jh-select.md`                           |
+| `jh-picker`                 | `docs/jh-picker.md`                           |
+| `jh-text`                   | `docs/jh-text.md`                             |
+| `jh-pagination`             | `docs/jh-pagination.md`                       |
+| `jh-drag-row`               | `docs/jh-drag-row.md`                         |
+| HTTP 请求方式               | `docs/request.md`                             |
+| 页面 Hook 模式              | `docs/page-query-hook-best-practices.md`      |
+| BaseQuery / BaseTable 等    | `src/components/remote/{Component}/README.md` |
+| c_formModal / c_listModal   | `src/components/local/{component}/README.md`  |
+
+> AI 在 Pre-flight 声明中明确列出已读文档。
+
+---
+
+## AbstractPageQueryHook（强制）
+
+所有页面 `data.ts` **必须** `extends AbstractPageQueryHook`：
+
+```typescript
+import { AbstractPageQueryHook } from '@jhlc/common-core/src/page-hooks/page-query-hook.ts'
+
+export function createPage() {
+  let Page = new (class extends AbstractPageQueryHook {
+    constructor() { super({ url: { list: '...' } }) }
+    queryDef() { return [...] }
+    toolbarDef() { return [...] }
+    columnsDef() { return [...] }
+  })()
+  return Page.create() as any
+}
+```
+
+---
+
+## 提取建议触发规则
+
+`convention-audit` 扫描发现 **3+ 个页面**出现相同的未封装 `el-*` 模式时，输出到 `reports/组件提取建议.md`：
+
+```markdown
+| 建议组件名    | 出现次数 | 页面路径                        | 菜单位置（来自文件头）  | 模式描述         |
+| ------------- | -------- | ------------------------------- | ----------------------- | ---------------- |
+| c_statusBadge | 5 处     | src/views/sale/.../index.vue 等 | 销售管理 > 国内贸易订单 | 状态枚举彩色标签 |
+| c_priceFormat | 4 处     | ...                             | ...                     | 千分位金额显示   |
+```
+
+> ⚠️ AI **不自动提取**。人工确认后，触发 template-extract 或手动封装。
+
+---
+
+## AI 检查清单（每次代码生成前自查）
+
+- [ ] 查询区使用了 BaseQuery，没有自己写 el-form？
+- [ ] 表格使用了 BaseTable + agGrid + cid，没有用 el-table？
+- [ ] 弹窗使用了 c_formModal / c_listModal，没有手写 el-dialog？
+- [ ] 日期组件用了 jh-date 系列，没有用 el-date-picker？
+- [ ] HTTP 请求都走 `this.getAction / postAction`，没有 import axios？
+- [ ] data.ts 继承了 AbstractPageQueryHook？
+- [ ] 涉及 jh-_ 组件时已读取对应 docs/jh-_.md？

package/files/.github/standards/index.md

@@ -0,0 +1,89 @@
+# Standards 规范门控（懒加载入口）
+
+> **版本**：v1.0.0 **维护者**：CHENY (工号 409322)
+> **加载策略**：AI 按当前任务类型，**只读取相关条目**，不全量加载。
+
+---
+
+## 13 条规范清单
+
+| 编号 | 文件                        | 主题                   | 强制度         |
+| ---- | --------------------------- | ---------------------- | -------------- |
+| 01   | `01-toolchain.md`           | 工具链前置检测         | 🔴 阻断        |
+| 02   | `02-code-structure.md`      | 代码结构与顺序         | 🔴 必遵        |
+| 03   | `03-comments.md`            | 注释规范               | 🟡 建议        |
+| 04   | `04-coding-basics.md`       | 基础编码（13 条）      | 🔴 必遵        |
+| 05   | `05-logging.md`             | 日志输出               | 🔴 必遵        |
+| 06   | `06-security.md`            | 安全规范               | 🔴 必遵        |
+| 07   | `07-config.md`              | 配置管理               | 🔴 必遵        |
+| 08   | `08-git.md`                 | Git 分支 & 提交        | 🔴 必遵        |
+| 09   | `09-typescript.md`          | TypeScript 类型        | 🟡 建议        |
+| 10   | `10-pinia.md`               | Pinia 状态管理         | 🔴 必遵        |
+| 11   | `11-form-validation.md`     | 表单与校验             | 🔴 必遵        |
+| 12   | `12-base-table.md`          | BaseTable + AGGrid cid | 🔴 必遵        |
+| 13   | `13-platform-components.md` | 平台组件合规（核心）   | 🔴 必遵 + 阻断 |
+
+---
+
+## 任务类型 → 必读规范映射
+
+> AI 按用户意图选取下方匹配的「任务类型」，**仅加载该类型对应的规范文件**。
+
+### 任务类型 A：生成新页面（page-codegen）
+
+```
+必读：01 / 02 / 04 / 12 / 13
+按需：09（TS 类型复杂时） / 10（涉及 Store） / 11（FORM_ROUTE 模板）
+```
+
+### 任务类型 B：修改/重构既有页面
+
+```
+必读：02 / 04 / 13
+按需：09 / 10 / 11
+```
+
+### 任务类型 C：规范审计（convention-audit）
+
+```
+必读：全部 13 条（审计需要完整对照）
+```
+
+### 任务类型 D：模板提取（template-extract）
+
+```
+必读：02 / 13（模板必须遵循结构与组件合规规则）
+```
+
+### 任务类型 E：菜单/字典/权限同步类
+
+```
+必读：07（环境变量与 API 地址不硬编码）
+```
+
+### 任务类型 F：仅 Git 操作 / Commit
+
+```
+必读：08
+```
+
+---
+
+## 加载方式（Pre-flight 声明示例）
+
+```
+✅ 已读取 standards/index.md            → 规范门控，匹配任务类型 A（生成新页面）
+✅ 已读取 standards/02-code-structure.md → 4 文件原则 + 三段式 + script 9 段顺序
+✅ 已读取 standards/12-base-table.md     → AGGrid 必用 + cid 命名规范
+✅ 已读取 standards/13-platform-components.md → 平台组件对照表
+```
+
+> **不要** 一次性读取全部 13 条。错误示范：`✅ 已读取 standards/01 ~ standards/13`（浪费 token，违反懒加载原则）。
+
+---
+
+## 规范变更管理
+
+- 新增规范条目：编号顺序追加，不复用废弃编号
+- 修改既有规范：在文件末尾追加 `## 变更记录` 章节，登记日期 + 变更摘要
+- 整体破坏性变更：升级本文件顶部 `version`，并在根 `CHANGELOG.md` 标注