convention-audit

name	convention-audit
description	Use when: auditing project source code against the 14 modular standards in .wl-skills/standards/. Outputs deviation report and component-extraction suggestions to reports/. Triggers on: 规范审计, 规范检查, 代码审计, 对齐规范, 规范偏差, 接手新项目, 存量代码分析, 项目体检, audit code, check conventions, onboard project.

Skill: 规范审计（convention-audit）v2

以 .wl-skills/standards/ 14 条规范为唯一基线，扫描项目源码，输出偏差报告和组件提取建议到 reports/ 目录。

核心理念：审查全覆盖、结果强量化、规则场景化、新增严格 + 存量渐进。 本 Skill 只负责发现偏差并给出整改建议，不自动修复（修复由 code-fix Skill 完成）。

---

触发词

规范审计 / 规范检查 / 代码审计 / 对齐规范 / 规范偏差 / audit code

---

Pre-flight 声明（执行前必须输出）

🚀 已触发技能 convention-audit/SKILL.md → 规范审计：扫描源码 + 偏差报告 + 提取建议
✅ 已读取 standards/index.md          → 规范门控
✅ 已读取 standards/01 ~ 14           → 完整 14 条规范基线（审计场景需全量加载）
✅ 已读取 reports/规范审查报告.md      → 现有报告（用于追加，不覆盖）
✅ 审计范围：{用户指定的目录或单文件}
✅ 工具链检测：ESLint {状态} / tsc {状态} / Husky {状态}

---

适用场景

场景	说明
新项目导入 wl-skills-kit 后	扫描旧代码，输出整改清单，逐步迁移
日常 Code Review 辅助	比对单文件或目录，快速发现偏差
项目迁移/升级	老项目引入新架构，批量评估改造量
团队培训	新成员提交代码前，用审计验证是否符合规范
page-codegen 后置自检	页面生成完成后自动跑一次审计，确认合规
修复闭环复扫	code-fix 修复后复扫，生成前后对比
CI/CD（PLANNED）	PR 上自动跑审计，不合规 PR 阻断合并

---

复扫模式（--quick，v2.11+ 新增）

闭环专用：code-fix 修复后快速验证，不做全量 14 条扫描，仅复查上次报告中的 🔴🟡 项。

触发方式

复扫验证 / 复扫上次审计 / convention-audit --quick / 确认修复效果

执行逻辑

1. 读取 reports/规范审查报告.md 最新章节中的 🔴🟡 偏差清单
2. 仅对这些偏差涉及的文件重新检测（不扫描全项目）
3. 对比上次报告数据，输出变化矩阵
4. 追加复扫结果到报告

复扫报告格式

## 🔄 复扫 {YYYY-MM-DD HH:mm} | 触发：code-fix 后自动复扫

| 指标 | 修复前 | 修复后 | 变化 |
|---|---:|---:|---|
| 🔴 严重 | {N} | {N} | {-N} ✅ |
| 🟡 警告 | {N} | {N} | {-N} ✅ |
| 未解决 | - | {N} | 待处理 |

### 结论
- ✔ 闭环完成，可提交
- 或：✖ 仍有 {N} 个未解决项，建议继续处理

与全量审计的区别

	全量审计	--quick 复扫
规范覆盖	14 条全部	仅上次报告中的偏差项
扫描范围	指定目录或全项目	仅偏差涉及文件
token 消耗	高	低（约全量的 10%）
适用场景	首次体检/定期审计	code-fix 后闭环验证
输出	完整报告 12 章	复扫对比矩阵

---

审计范围（14 条规范全覆盖）

审计方式分层

方式	说明
静态扫描	文件存在性检测、正则匹配（高可信度）
工具链委托	ESLint / tsc --noEmit / Git 命令（高可信度，不浪费 AI 算力）
AI 场景判断	页面类型识别、豁免判定（中可信度，需人工确认）

14 条规范审计维度

编号	审计维度	审计方式	严重度判定
01	工具链就绪	静态扫描	缺少 .prettierrc.js / eslint.config.ts / .husky/ → 🔴
02	三文件分离 + 接口契约	静态 + AI 场景判断	应拆未拆 data.ts → 🔴（新增）/🟡（存量）；api.md 缺失见场景规则；index.vue 含业务逻辑 → 🔴/🟡；段落顺序乱 → 🟡
03	注释规范	静态扫描	死代码注释 → 🟡；TODO 不规范 → 🟡；显而易见注释 → 🟢；文件头缺失 → 🟢
04	基础编码（14 条）	ESLint + 静态扫描	var / for...in / 字符串拼接 / .then() / ::v-deep → 🟡
05	console 残留	静态扫描	src/ 下无守卫的 console → 🟡
06	安全规范	静态扫描	v-html 无注释 / import axios / eval / new Function → 🔴
07	配置管理	静态扫描	硬编码 http:// IP → 🔴；API 路径散落 → 🟡
08	Git 规范	Git 命令 + 文件检测	工具链缺失 → 🔴；分支名不规范 → 🟡；近期提交不规范 → 🟡；历史 → 🟢
09	TypeScript 类型 + 类型错误	R14（vue-tsc/tsc 委托）+ AI	类型检查器缺失 → 🔴；vue-tsc --noEmit 非 0 → 🔴；any 滥用 → 🟡
10	Pinia	静态扫描	data.ts 内 import Store → 🔴
11	表单校验	AI 场景判断	FORM_ROUTE 缺 validate / resetFields → 🔴
12	BaseTable + cid	静态 + 场景判断	主列表用 el-table → 🔴；cid 缺失/重复 → 🔴；弹窗小表格见豁免规则
13	平台组件合规	静态扫描	业务页面用 el-form/el-table/el-date-picker 替代封装 → 🔴；封装组件内部 → ⚠️ 待确认；3+ 复用 → 提取建议
14	布局容器	静态扫描	业务代码用 C_Splitter → 🔴（必须替换为 jh-drag-row/jh-drag-col）

---

目录分层审查

不同目录类型适用不同规则强度，避免封装组件内部与业务页面混淆。

目录	规则强度	说明
src/views/**	最严格	业务页面，全规范覆盖
.wl-skills/src/components/local/**	中等	业务封装组件，检查复用性和命名
.wl-skills/src/components/**（基础/历史）	宽松	不套页面三文件原则；内部使用 el-* 需单独评审

---

新增 vs 存量代码区分

类型	处理策略
新增页面（AI 生成 / 手动新增）	必须全规约，阻断项严格执行
本次修改页面	不新增违规，触碰范围内尽量修
存量未触碰页面	报告记录，后续治理，不阻断

---

执行流程

步骤 1：确定审计范围

用户输入	范围
"审计整个项目"	src/views/
"审计 produce/mmwr"	该子目录
"审计 mmwr-customer-archive 页面"	单页面文件

步骤 2：加载规范基线 + 工具链检测

1. 读取 standards/01 ~ 14 全部规范文件
2. 检测工具链状态：
   • ESLint：是否可执行
   • TypeScript：vue-tsc --noEmit（回退 tsc --noEmit）是否可执行、是否 0 error（R14）
   • Git：当前分支 / 最近提交
   • Husky：.husky/pre-commit、.husky/pre-push、.husky/commit-msg 是否存在
3. 读取 package.json 获取项目脚本名称
4. 读取豁免配置（v2.11.4+）：如项目根存在 .wl-skills-validate.json，解析其中所有豁免条目（paths / rules / reason），在报告中单列"豁免项复核清单"，供人工逐条确认是否仍需豁免

步骤 3：扫描源码

逐个文件检查 14 个维度。同时记录：

• 扫描统计：目录数、文件数、页面数、类型分布
• 跨页面相同 el-* 模式（统计出现次数和位置）
• 每个偏差所在文件的菜单位置（从 koroFileHeader 文件头注释解析）
• 页面类型识别：判断是否需要 data.ts、api.md，是否属于豁免场景
• code-fix 能力评估：每个偏差标注是否可自动修复

步骤 4：追加写入两份报告

报告 A：reports/规范审查报告.md（追加，最新章节在顶）

## 🕐 {YYYY-MM-DD HH:mm} | 范围：{范围} | 触发：{user / page-codegen / CI}

### 1. 扫描范围与数据量

| 指标 | 值 |
|---|---|
| 扫描根目录 | {路径} |
| 扫描目录数 | {N} |
| 扫描文件数 | {N} |
| Vue 文件数 | {N} |
| TS/JS 文件数 | {N} |
| SCSS/CSS 文件数 | {N} |
| 业务页面目录数 | {N} |
| 豁免/不适用页面数 | {N} |

### 2. 工具链与 Git 状态

| 项目 | 状态 |
|---|---|
| ESLint | {已配置 / 未配置 / 执行失败} |
| Prettier | {.prettierrc.js 存在 / 缺失} |
| TypeScript | {tsc 可用 / 不可用} |
| Husky | {pre-commit ✓ commit-msg ✓ / 缺失} |
| @robot-admin/git-standards | {已初始化 / 未安装} |
| 当前分支 | {分支名} — {符合规范 / 不符合规范} |
| 最近提交规范性 | {N}/{总数} 条符合 type(scope): 格式 |

### 3. 14 条规范覆盖矩阵

| 规范 | 审查方式 | 结果 | 🔴 | 🟡 | 🟢 |
|---|---|---|---:|---:|---:|
| 01 工具链 | 文件检测 | {结果} | {N} | {N} | {N} |
| 02 结构 | 静态+AI | {结果} | {N} | {N} | {N} |
| 03 注释 | 静态扫描 | {结果} | {N} | {N} | {N} |
| 04 基础编码 | ESLint/静态 | {结果} | {N} | {N} | {N} |
| 05 日志 | 静态扫描 | {结果} | {N} | {N} | {N} |
| 06 安全 | 静态扫描 | {结果} | {N} | {N} | {N} |
| 07 配置 | 静态扫描 | {结果} | {N} | {N} | {N} |
| 08 Git | Git+文件 | {结果} | {N} | {N} | {N} |
| 09 TS | tsc/ESLint | {结果} | {N} | {N} | {N} |
| 10 Pinia | 静态扫描 | {结果} | {N} | {N} | {N} |
| 11 表单校验 | 场景扫描 | {结果} | {N} | {N} | {N} |
| 12 BaseTable | 静态+场景 | {结果} | {N} | {N} | {N} |
| 13 平台组件 | 静态扫描 | {结果} | {N} | {N} | {N} |
| 14 布局容器 | 静态扫描 | {结果} | {N} | {N} | {N} |

### 4. 🔴 严重偏差（必须整改）

#### {编号}. 违反规范 {XX}（{规范名}）— {问题描述}

- **影响文件数**：{N}
- **出现次数**：{N}
- **菜单位置**（来自文件头）：{位置}
- **现状**：{描述}
- **应为**：{描述}
- **整改建议**：{建议}
- **自动修复**：{✅ 可自动修 / ⚠️ 需确认 / ❌ 人工处理}
- **涉及文件 Top N**：
  1. `src/views/.../index.vue` — {N} 处
  2. ...

（按规范条目分组列出全部偏差）

### 5. 🟡 警告偏差（建议整改）

（同格式，增加自动修复标记）

### 6. 🟢 提示与后续关注

（注释、TS 类型优化、存量历史问题等）

### 7. 豁免 / 不适用清单

| 文件/目录 | 规则 | 原因 | 结论 |
|---|---|---|---|
| {路径} | data.ts | 纯静态说明页 | 不适用 |
| {路径} | api.md | 无接口调用 | 豁免 |
| {路径} | AGGrid | 弹窗小型明细表 | 待人工确认 |
| {路径} | el-dialog | 封装组件内部实现 | 合理 |

### 8. 本次建议 code-fix 修复清单

| 问题 | 影响文件数 | 自动修复 | 建议 |
|---|---:|---|---|
| console 清理 | {N} | ✅ | 本轮修复 |
| var → const/let | {N} | ✅ | 本轮修复 |
| ::v-deep → :deep() | {N} | ✅ | 本轮修复 |
| BaseTable 缺 cid | {N} | ✅ | 本轮修复 |
| 简单 .then() → async/await | {N} | ⚠️ | 需确认 |

### 9. 本次不建议修复 / 后续治理清单

| 问题 | 原因 | 建议时间 |
|---|---|---|
| 存量页面迁移 data.ts | 大规模重构 | 按模块渐进 |
| el-table 全量迁移 | 需逐页面验证 | P1 分批 |
| 存量 api.md 补齐 | 非阻断项 | 后续补充 |

### 10. 目录/模块问题分布

| 模块目录 | 🔴 | 🟡 | 🟢 | 合计 | 建议 |
|---|---:|---:|---:|---:|---|
| {模块路径}/ | {N} | {N} | {N} | {N} | {建议} |

### 11. 推荐整改路线

| 优先级 | 整改项 | 建议方式 |
|---|---|---|
| P0 | {工具链缺失项} | 先备份配置，再初始化 |
| P1 | {严重偏差项} | code-fix / 立即修复 |
| P2 | {警告偏差项} | 分批修 |
| P3 | {存量治理项} | 渐进迁移 |

### 12. 修复闭环与复扫

| 指标 | 本次值 | 上次值 | 变化 |
|---|---:|---:|---|
| 🔴 严重 | {N} | {N/-} | {±N} |
| 🟡 警告 | {N} | {N/-} | {±N} |
| el-table 文件数 | {N} | {N/-} | {±N} |
| console 文件数 | {N} | {N/-} | {±N} |

> 📌 后续提交必须使用 `git cz`，不符合规范的提交视为闭环失败。

> 报告生成时间：{YYYY-MM-DD} | @agile-team/wl-skills-kit@{version} | {项目名}@{branch} branch
> 扫描工具：@agile-team/wl-skills-kit scanner + AI 代码全量扫描
> 执行人：{姓名} | {工号}

---

（历史章节自然下沉）

报告 B：reports/组件提取建议.md（追加）

## 🕐 {YYYY-MM-DD HH:mm} | 范围：{范围}

### 📦 组件提取建议（共 N 处）

| 建议组件名 | 出现次数 | 页面路径 | 菜单位置 | 模式描述 |
|---|---|---|---|---|
| c_statusBadge | 5 处 | src/views/sale/.../{a,b,c,d,e}/index.vue | 销售管理 > 多个子菜单 | 状态枚举彩色标签 |

> ⚠️ 以上为建议，不自动提取。
> 人工确认后，触发 `template-extract` Skill（页面级模板）或手动封装为 `c_*` 组件。

步骤 5：输出摘要

📦 审计完成
─────────────────────────────────────────────────────
📊 扫描：{N} 个目录 / {N} 个文件 / {N} 个业务页面
✅ reports/规范审查报告.md  → 已追加（🔴{N} 🟡{N} 🟢{N}）
✅ reports/组件提取建议.md  → 已追加 {M} 条
─────────────────────────────────────────────────────
📌 后续步骤：
   1. 人工 review 报告，确认豁免清单和修复优先级
   2. 触发 code-fix 修复"本次建议修复清单"中 ✅ 项
   3. 需确认项（⚠️）人工评审后决定是否 code-fix
   4. 提取建议人工评审 → template-extract 或手动封装
   5. 修复后复扫，生成前后对比指标
   6. 所有修复提交使用 git cz，确保 Git 规范合规
─────────────────────────────────────────────────────

---

偏差严重度定义

级别	标记	定义	自动修复
🔴	严重	架构性违反，影响可维护性 / 安全 / 团队协作	部分可自动修，部分需人工
🟡	警告	风格不统一 / 最佳实践偏离，不影响功能	大部分可自动修
🟢	提示	优化建议，可逐步改进	按需

code-fix 能力标记

标记	含义	处理方式
✅ 可自动修复	模式明确、风险低	直接交给 code-fix
⚠️ 需确认后修复	有业务风险	人工确认后 code-fix
❌ 人工处理	需要理解业务	不自动修
👀 后续关注	本轮不修	持续观察

---

阻断条件

以下问题视为阻断项，修复闭环前必须解决：

• 工具链缺失（husky / commitlint / prettierrc / eslint）
• 新增 AI 页面缺 api.md
• 新增业务页面应拆未拆 data.ts
• 新增页面主列表使用 el-table
• 明显安全问题：eval、未声明的 v-html、硬编码 secret
• 修复后提交不符合 Git 规范

以下问题不阻断，作为后续治理：

• 注释规范问题
• 存量复杂页面缺 api.md
• 存量页面未拆 data.ts
• 部分 TS any
• 历史提交信息不规范
• 弹窗小表格 AGGrid 待确认

---

报告可信度说明

审计报告应在概要处标注各检查方式的可信度，便于人工评审。

检查类型	可信度
文件是否存在	高
正则匹配（el-table / console / var 等）	高
工具链输出（ESLint / tsc）	高
Git 提交历史	高
页面是否需要 data.ts	中（需人工确认）
AGGrid 是否适配弹窗表格	中（需人工确认）
复杂业务逻辑是否应提取	中

---

与其他 Skill 的关系

Skill	关系
page-codegen	审计发现偏差后，可调用 page-codegen 重新生成合规代码
template-extract	审计输出的"组件提取建议"，确认后可触发 template-extract
code-fix	审计报告中 ✅/⚠️ 标记项作为修复输入
spec-doc-parse	提供 spec 对齐模式的基准：用规范线解析出的 page-spec 与生成代码比对，输出 GAP 报告
CI/CD	审计可作为 PR 检查项，不合规 PR 阻断合并

---

注意事项

1. 规范基线唯一：以 standards/index.md 加载的 14 条文件为准，不接受"旧代码一直这么写"的辩解
2. 追加不覆盖：每次审计追加新章节到报告，不删除历史，便于追溯整改进度
3. 菜单位置解析：依赖 koroFileHeader 文件头注释，缺失文件头时标记 菜单位置：未知
4. AI 自我审计：page-codegen 生成代码后，建议立即跑一次单页审计验证合规
5. 工具链优先：TS 类型 / ESLint 规则优先借助工具链扫描，AI 负责监督验证和归类，不浪费算力逐文件做语义分析
6. 场景化判定：data.ts / api.md / AGGrid 均按场景规则判定，不机械检查文件数量

---

spec 对齐扫描（GAP 报告）

闭环能力：与 core/spec-doc-parse 联动。当页面代码来自「规范线」（wl-skills-design 说明书 → spec-doc-parse → page-codegen）时，本模式把 原始 spec 定义的字段 与 代码中实际存在的字段 逐项比对，生成 GAP 报告，验证「说明书 → 代码」是否零损耗。

触发

审计 {页面目录} --mode spec-align --spec .wl-skills/docs/spec/{项目代号}/4.x-{子模块}.md

或自然语言：「检查 {页面} 是否跟说明书对齐」。

比对维度

维度	检查点	偏差判定
查询字段	spec query[] vs 代码 queryDef()	spec 有代码缺 → 🔴 漏字段；代码多出 → 🟡 超出 spec
表格列	spec columns[] vs 代码 columnsDef()	同上，且顺序不一致 → 🟡
工具栏	spec toolbar[] vs 代码 toolbarDef()	按钮缺失/多出 → 🔴/🟡
表单字段	spec formSections[].fields[] vs 弹窗组件	必填字段缺失 → 🔴
接口 URL	spec 推算 URL vs 代码 API_CONFIG	路径不一致 → 🟡 待确认
权限码	spec notes 权限码候选 vs 代码 v-permission	未挂载 → 🟡，建议 permission-sync

GAP 报告（reports/SPEC_GAP_{模块}_{日期}.md）

# Spec 对齐 GAP 报告
- 生成时间：{YYYY-MM-DD HH:mm}
- spec 来源：.wl-skills/docs/spec/{项目代号}/4.x-{子模块}.md
- 代码范围：src/views/.../{页面}/

## GAP 摘要
- spec 字段总数：N  代码实现：N  漏：N  多：N  顺序不一致：N

## 漏字段（spec 有、代码无 → 🔴）
| # | 类型 | spec 字段 | 所在功能 | 建议 |
|---|------|----------|---------|------|
| 1 | query | customerType | PMMB001 | 补入查询项 |

## 多余字段（代码有、spec 未定义 → 🟡）
| # | 类型 | 代码字段 | 建议 |
|---|------|----------|------|
| 1 | column | remark | 确认是否需要，否则反馈 design 补 spec |

## 下一步
→ 漏字段交 code-fix / page-codegen 补齐；多余字段反馈上游 design 补 spec。

spec 对齐模式只对规范线生成的页面生效；原型线（prototype-scan）生成的页面无 spec 基准，跳过本模式。