pdd-skills 3.1.1 → 3.1.3

package/README.md

@@ -1,14 +1,15 @@
 # PDD-Skills v3.0
 
-[![Version](https://img.shields.io/badge/version-3.1.0-blue.svg null)](https://github.com/pdd-skills/pdd-skills)
+[![Version](https://img.shields.io/badge/version-3.1.2-blue.svg null)](https://github.com/pdd-skills/pdd-skills)
 [![Node](https://img.shields.io/badge/node-%3E%3D18.0.0-green.svg null)](https://nodejs.org/)
 [![License](https://img.shields.io/badge/license-MIT-orange.svg null)](LICENSE)
 [![Patterns](https://img.shields.io/badge/bug_patterns-14-purple.svg null)](config/bug-patterns.yaml)
 [![Gate](https://img.shields.io/badge/gate_rules-30-critical.svg null)](config/prd-rules.yaml)
+[![Skills](https://img.shields.io/badge/skills-41+-brightgreen.svg null)](skills/)
 
 > **PRD 驱动的 AI 原生软件开发工作流框架**
 >
-> 从需求文档到代码交付的全链路自动化平台 — **7 大 Phase**、**双脚手架**、**14 个 Bug 模式**、**30 条 PRD 规则**、**4 级质量门控**
+> 从需求文档到代码交付的全链路自动化平台 — **7 大 Phase**、**41+ 技能**、**14 个 Bug 模式**、**30 条 PRD 规则**、**4 级质量门控**
 
 ***
 
@@ -230,14 +231,15 @@ scaffolds/python-fullstack/
 
 | 指标          | 数值                                            |
 | ----------- | --------------------------------------------- |
-| **版本**      | v3.1.0                                        |
-| **核心技能**    | 11 个（全双语 🇨🇳🇺🇸）                            |
-| **专家技能**    | 4 个（安全 + 性能 + 若依 + Activiti）                                  |
-| **PR技能**    | 5 个（模板引擎 + 多轮审查 + PR创建/审查/合并）                 |
+| **版本**      | v3.1.2                                        |
+| **核心技能**    | 12 个（全双语 🇨🇳🇺🇸）                            |
+| **专家技能**    | 12 个（安全/性能/MySQL/若依/若依权限/Activiti/Vue3/微服务/Bug修复/测试/架构） |
+| **熵减技能**    | 4 个（审计 + 架构约束 + 代码质量 + 自动重构）              |
+| **OpenSpec技能**| 10 个（变更管理全生命周期）                         |
+| **PR技能**    | 7 个（模板引擎 + 多轮审查 + PR创建/审查/合并/批量/任务管理）    |
 | **Bug模式库**  | 14 个（7通用 + 7若依专用），集中式管理 `config/bug-patterns.yaml` |
 | **PRD规则**   | 30 条（6大类），集中式管理 `config/prd-rules.yaml`      |
 | **质量门控**    | 4级（Blocker/Critical/Warning/Info）+ 0-100评分    |
-| **脚手架模板**   | 2 个（Python Fullstack + 若依RuoYi）               |
 | **协议支持**    | RESTful + MCP + gRPC + SSE                    |
 | **SDK 语言**  | JavaScript + Python                           |
 
@@ -399,7 +401,7 @@ pdd config --get key                              # 读取配置项
 
 ### Phase 2: 核心能力增强
 
-11 个核心技能 + 五大行为塑造机制。
+12 个核心技能 + 五大行为塑造机制。
 
 #### 核心技能列表
 
@@ -416,6 +418,7 @@ pdd config --get key                              # 读取配置项
 | `pdd-doc-gardener`      | 文档清理与维护     | ✅  |
 | `pdd-entropy-reduction` | 技术债务治理      | ✅  |
 | `official-doc-writer`   | 党政机关公文生成    | ✅  |
+| `pdd-vm`                | PDD Visual Manager 可视化监控 | ✅  |
 
 #### 行为塑造三层防御
 
@@ -444,9 +447,39 @@ pdd config --get key                              # 读取配置项
 | ---------------------- | --------------------------------------- | -------------------------------------- |
 | **expert-security**    | SQL注入 / XSS / CSRF / 命令注入 / 路径遍历 / SSRF | OWASP Top 10 2021 完整覆盖，8 条安全铁律         |
 | **expert-performance** | CPU / 内存 / I/O / 网络 / 锁竞争诊断             | HikariCP / Redis多级缓存 / G1 GC调优 / P99指标 |
+| **expert-mysql**       | SQL优化 / 索引设计 / 表结构分析 / 慢查询诊断         | MySQL官方文档参考，执行计划分析，索引优化建议          |
 | **expert-ruoyi**       | 若依框架全流程开发 / 代码生成 / 权限配置 / 菜单管理          | 7个若依Bug模式(PATTERN-R001~R007) + Spec模板参考 |
+| **expert-ruoyi-permission** | 若依框架权限配置 / 权限校验失败诊断 / 菜单按钮权限 | 四端一致原则 + @PreAuthorize + v-hasPermi |
 | **expert-activiti**    | Activiti 7工作流引擎 / BPMN 2.0 / 流程部署管理      | 流程设计规范 + BPMN校验规则                       |
+| **expert-vue3**        | Vue3 组件开发 / 状态管理 / 性能优化 / 组合式 API     | Vue3 生态最佳实践，响应式系统深度解析                 |
+| **expert-springcloud** | 微服务架构 / 服务治理 / 配置中心 / 网关路由           | Spring Cloud Alibaba 全栈解决方案               |
+| **expert-bug-fixer**   | Bug 根因分析 / 修复方案生成 / 回归测试建议           | 智能诊断 + 修复策略推荐                            |
+| **expert-testcases**   | 测试用例设计 / 边界值分析 / 覆盖率优化              | 多维度测试策略，自动化测试生成                       |
+| **software-architect** | 架构模式设计 / 技术选型 / 性能权衡 / 可扩展性规划       | 生产级架构设计，60+ 界面组件模式参考                  |
+| **software-engineer**  | 代码实现 / 重构优化 / 设计模式应用 / 测试驱动开发       | 生产级代码，清洁架构，错误处理完善                    |
+| **system-architect**   | 系统架构设计 / 模块化设计 / 安全最佳实践 / 代码规范      | PEP8/ESLint 标准，项目初始化，技术栈选择              |
 
+### Phase 3.5: 熵减治理系统
+
+> **对抗系统腐化，持续偿还技术债务**
+
+PDD 熵减体系通过 4 个协同技能，实现从审计到重构的闭环治理：
+
+| 熵减技能 | 职责 | 触发场景 |
+|---------|------|---------|
+| **expert-entropy-auditor** | 技术债务审计 / PRD一致性检查 / AI残渣检测 | 每周定时审计、PR合并后、代码提交后 |
+| **expert-arch-enforcer** | 架构约束检查 / 依赖方向验证 / 模块边界监控 | 代码提交后自动触发、架构检查请求 |
+| **expert-code-quality** | 代码审查 / 重构建议 / 设计模式应用 / SOLID原则 | 代码审查请求、质量改进需求 |
+| **expert-auto-refactor** | 自动化重构 / 消除重复 / 简化复杂度 / 模式归集 | 熵减审计后、重构任务分配 |
+
+**治理流程**:
+
+```
+entropy-auditor (审计发现) → arch-enforcer (约束检查) → code-quality (质量评估) → auto-refactor (自动修复)
+        ↑                                                                            |
+        └──────────────────────── 持续监控循环 ←──────────────────────────────────────┘
+```
+  
 ### Phase 4: 平台化建设
 
 将核心能力暴露为标准化接口，支持远程调用和多语言接入。
@@ -1023,18 +1056,35 @@ skills/
 │   ├── pdd-entropy-reduction/
 │   └── official-doc-writer/
 │
-├── expert/                  # 专家技能 (按需加载)
+├── expert/                  # 专家技能 (12个，按需加载)
 │   ├── expert-security/    # 安全审计专家
 │   ├── expert-performance/ # 性能优化专家
+│   ├── expert-mysql/       # MySQL数据库专家
 │   ├── expert-ruoyi/       # 若依框架专家 (含Bug模式库R001~R007)
-│   └── expert-activiti/    # Activiti工作流专家
+│   ├── expert-ruoyi-permission/ # 若依权限配置专家
+│   ├── expert-activiti/    # Activiti工作流专家
+│   ├── expert-vue3/        # Vue3前端专家
+│   ├── expert-springcloud/ # SpringCloud微服务专家
+│   ├── expert-bug-fixer/   # Bug修复专家
+│   ├── expert-testcases/   # 测试用例专家
+│   ├── software-architect/ # 软件架构师
+│   ├── software-engineer/  # 软件工程师
+│   └── system-architect/   # 系统架构师
 │
-├── pr/                      # PR与交付技能
+├── entropy/                 # 熵减治理技能 (4个)
+│   ├── expert-entropy-auditor/   # 技术债务审计
+│   ├── expert-arch-enforcer/     # 架构约束强制
+│   ├── expert-code-quality/      # 代码质量专家
+│   └── expert-auto-refactor/     # 自动重构专家
+│
+├── pr/                      # PR与交付技能 (7个)
 │   ├── pdd-template-engine/    # PRD感知动态模板引擎
-│   ├── pdd-multi-review/       # 三轮代码审查
+│   ├── pdd-multi-review/       # 多轮代码审查
 │   ├── pdd-pr-create/          # PR创建
 │   ├── pdd-pr-review/          # PR审查
-│   └── pdd-pr-merge/           # PR合并
+│   ├── pdd-pr-merge/           # PR合并
+│   ├── pdd-pr-batch/           # 批量PR处理
+│   └── pdd-task-manager/       # 任务管理
 │
 ├── openspec/                # OpenSpec 协作技能
 │   ├── openspec-explore/
@@ -1582,56 +1632,30 @@ pdd-skills-v3/
 │               ├── on-phase-change.js
 │               └── on-quality-alert.js
 │
-├── scaffolds/                  # ★ 脚手架模板系统 (v3.0.1+ 新增)
-│   └── python-fullstack/      # Python 全栈模板 (FastAPI + Vue3)
-│       ├── template_config.yaml    # 模板元数据 & Hooks & 变量配置
-│       ├── README.md               # 模板使用指南
-│       ├── docs/                   # 4份架构设计文档
-│       │   ├── architecture-design.md
-│       │   ├── database-design.md
-│       │   ├── api-design.md
-│       │   └── deployment-guide.md
-│       ├── backend/                # 后端代码 (FastAPI + SQLAlchemy)
-│       │   ├── app/core/           # 核心模块 (权限/OAuth/工作流)
-│       │   ├── app/api/            # API 路由层
-│       │   ├── app/models/         # 数据模型
-│       │   ├── app/schemas/        # 请求/响应模型
-│       │   ├── app/services/       # 业务逻辑层
-│       │   ├── alembic/            # 数据库迁移
-│       │   └── tests/              # 单元 & 集成测试
-│       ├── frontend/               # 前端代码 (Vue3 + Vite + TS)
-│       │   ├── src/views/          # 页面组件 (响应式布局)
-│       │   ├── src/components/     # UI 组件库
-│       │   ├── src/stores/         # Pinia 状态管理
-│       │   ├── src/api/            # API 请求封装
-│       │   └── tailwind.config.js  # 6档断点配置
-│       ├── docker-compose.yml      # 一键部署编排
-│       └── .github/workflows/      # CI 流水线
-│
-├── skills/                    # 技能文件
-│   ├── core/                   # 11 个核心技能
-│   ├── expert/                 # 2 个专家技能
-│   └── openspec/               # 10 个 OpenSpec 技能
+├── skills/                    # 技能文件 (41+ 个)
+│   ├── core/                   # 12 个核心技能
+│   ├── expert/                 # 11 个专家技能
+│   ├── entropy/                # 4 个熵减技能
+│   ├── openspec/               # 10 个 OpenSpec 技能
+│   └── pr/                     # 7 个 PR 技能
 │
 ├── scripts/                   # 工具脚本
 │   ├── linter/                # PRD Linter 工具链
 │   │   ├── prd-linter.js      # PRD Linter 引擎
-│   │   ├── prd-rules.yaml     # (符号链接→config/)
-│   │   ├── gate-engine.js     # 4级门控引擎 (读取config/gate-config.yaml)
 │   │   ├── report-generator.js# 报告生成器
-│   │   └── run-linters.js     # Linter运行器 (集成Gate Engine)
-│   ├── openapi-contract-sync.js # OpenAPI契约同步工具
-│   ├── skill-linter.py        # Skill 文件检查器
-│   ├── i18n-checker.js         # 双语合规检查
-│   └── token-analyzer.js       # Token 分析
+│   │   └── run-linters.js     # Linter运行器
+│   ├── cso-analyzer.js        # CSO 触发准确率分析
+│   ├── eval-runner.js         # Evals 测试运行器
+│   ├── i18n-checker.js        # 双语合规检查
+│   ├── token-analyzer.js      # Token 分析
+│   └── windows-compat-check.js # Windows 兼容性检查
 │
-├── docs/                       # 社区文档 (~10,700 行)
-│   ├── user-guide/
-│   ├── developer-guide/
-│   ├── api-reference/
-│   ├── operations/
-│   ├── plugin-market/
-│   └── tasks.md               # 任务跟踪 (153/100%)
+├── docs/                       # 项目文档
+│   ├── i18n-spec.md           # i18n 规范
+│   ├── lessons.md             # 经验教训
+│   ├── tasks.md               # 任务跟踪
+│   ├── token-checklist.md     # Token 检查清单
+│   └── vm-tasks.md            # VM 任务清单
 │
 ├── templates/                 # 项目模板
 ├── config/                    # 配置中心 (Single Source of Truth)
@@ -1645,7 +1669,7 @@ pdd-skills-v3/
 │   ├── ruff.toml              # Python Ruff配置
 │   └── sqlfluff.cfg           # SQL SQLFluff配置
 ├── hooks/                     # Hook 配置
-└── package.json               # v3.1.0
+└── package.json               # v3.1.2
 ```
 
 ***
@@ -1730,8 +1754,9 @@ CLI 参数 > 环境变量 > .pddrc.local > .pddrc > defaults
 
 | 版本         | 日期         | 重要变更                                                                                                                                            |
 | ---------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| **v3.1.0** | 2026-04-15 | **智能能力+生态集成**: Bug模式库集中化(14模式), PRD Linter扩展(30规则6大类), 4级门控引擎(Blocker/Critical/Warning/Info), OpenAPI契约同步, PRD感知动态模板, MVP分层交付策略, 上下文注入+微验证, expert-ruoyi+expert-activiti专家技能, 若依RuoYi脚手架支持, 种子数据分层设计 |
-| **v3.0.2** | 2026-04-12 | **脚手架系统发布**: python-fullstack 全栈模板(FastAPI+Vue3), 数据权限引擎, OAuth2六平台认证, 工作流状态机引擎, 响应式前端, 4份架构设计文档, Docker一键部署, CI流水线 |
+| **v3.1.2** | 2026-04-10 | **技能生态大扩展**: 新增 7 个专家技能(expert-mysql/expert-vue3/expert-springcloud/expert-bug-fixer/expert-testcases/software-architect/software-engineer/system-architect), 新增 4 个熵减技能(entropy-auditor/arch-enforcer/code-quality/auto-refactor), PR技能扩展至7个(新增pdd-pr-batch/pdd-task-manager), 核心技能增至12个(pdd-vm), 总计41+技能 |
+| **v3.1.1** | 2026-04-08 | **Windows兼容性+项目结构优化**: 添加 Windows 终端兼容支持, 优化项目初始化流程, 更新目录结构规范, 完善 .npmignore 配置 |
+| **v3.1.0** | 2026-04-05 | **智能能力+生态集成**: Bug模式库集中化(14模式), PRD Linter扩展(30规则6大类), 4级门控引擎(Blocker/Critical/Warning/Info), OpenAPI契约同步, PRD感知动态模板, MVP分层交付策略, 上下文注入+微验证, expert-ruoyi+expert-activiti专家技能, 若依RuoYi脚手架支持, 种子数据分层设计 |
 | **v3.0.1** | 2026-04-07 | **PDD Visual Manager 发布**: Web Dashboard + Terminal TUI 双形态可视化监控, 11个REST API端点, SSE实时推送, Canvas图表引擎, ANSI TUI组件库 |
 | **v3.0.0** | 2026-04-05 | **正式发布版**: 6大Phase全部完成 + 插件系统 + OpenClaw + gRPC + Python SDK + 暂缓清零                                                             |
 | v2.x       | 2026-03    | 内部迭代版本: MCP/SDK/缓存/Token/质量/迭代                                                                                                                  |
@@ -1754,9 +1779,9 @@ CLI 参数 > 环境变量 > .pddrc.local > .pddrc > defaults
 ***
 
 <p align="center">
-  <b>PDD-Skills v3.1 — 让 AI 成为你的全职结对编程伙伴 🤖</b>
+  <b>PDD-Skills v3.1.2 — 让 AI 成为你的全职结对编程伙伴 🤖</b>
 </p>
 
 <p align="center">
-  <sub>14 Bug Patterns ✅ · 30 PRD Rules ✅ · 4-Level Gate ✅ · Dual Scaffold ✅</sub>
+  <sub>41+ Skills ✅ · 14 Bug Patterns ✅ · 30 PRD Rules ✅ · 4-Level Gate ✅ · 4 Entropy Skills ✅</sub>
 </p>

package/bin/pdd.js

@@ -371,4 +371,110 @@ vmCmd
 
 program.addCommand(vmCmd);
 
+// === deps 子命令组 (依赖链感知引擎) ===
+const depsCmd = new Command()
+  .name('deps')
+  .description('依赖链感知引擎 - 分析前后端依赖关系 / Dependency Chain Engine');
+
+depsCmd
+  .command('scan')
+  .description('扫描项目文件关系 / Scan project file relationships')
+  .option('-d, --dir <path>', '项目目录', '.')
+  .option('--backend-dir <path>', '后端源码目录', 'src/main/java')
+  .option('--frontend-api-dir <path>', '前端API目录', 'src/api')
+  .option('--json', 'JSON格式输出')
+  .action(async (options) => {
+    const { DependencyChainEngine } = await import('../lib/dependency-chain/index.js');
+    const engine = new DependencyChainEngine(options.dir, {
+      backendDir: options.backendDir,
+      frontendApiDir: options.frontendApiDir
+    });
+    const graph = await engine.scan();
+    if (options.json) {
+      console.log(engine.toJSON());
+    } else {
+      console.log(chalk.bold('\n🔗 依赖链扫描结果\n'));
+      console.log(`   后端端点: ${graph.controllers.length}`);
+      console.log(`   前端API调用: ${graph.frontendApis.length}`);
+      console.log(`   状态映射: ${graph.statusMaps.length}`);
+      console.log(`   依赖边: ${graph.edges.length}`);
+      console.log(`\n   孤立API: ${engine.findOrphanedApis().length} (可能的PATTERN-R008)`);
+      console.log(`   不完整状态映射: ${engine.findIncompleteStatusMaps().length} (可能的PATTERN-R011)`);
+    }
+  });
+
+depsCmd
+  .command('impact <file>')
+  .description('分析修改某文件的影响范围 / Analyze impact of modifying a file')
+  .option('-d, --dir <path>', '项目目录', '.')
+  .action(async (file, options) => {
+    const { DependencyChainEngine } = await import('../lib/dependency-chain/index.js');
+    const engine = new DependencyChainEngine(options.dir);
+    await engine.scan();
+    const result = engine.analyzeImpact(file);
+    console.log(chalk.bold(`\n📊 修改 ${file} 的影响分析\n`));
+    if (result.impactedFiles.length === 0) {
+      console.log(chalk.yellow('   未发现直接依赖关系'));
+    } else {
+      result.impactedFiles.forEach((item, i) => {
+        console.log(`   ${i + 1}. ${chalk.cyan(item.file)}`);
+        item.reasons.forEach(r => console.log(`      └── ${r}`));
+      });
+    }
+    console.log(`\n   总影响文件数: ${result.totalImpacted}`);
+  });
+
+depsCmd
+  .command('orphans')
+  .description('查找孤立的前端API调用 / Find orphaned frontend API calls')
+  .option('-d, --dir <path>', '项目目录', '.')
+  .action(async (options) => {
+    const { DependencyChainEngine } = await import('../lib/dependency-chain/index.js');
+    const engine = new DependencyChainEngine(options.dir);
+    await engine.scan();
+    const orphans = engine.findOrphanedApis();
+    console.log(chalk.bold(`\n⚠️ 孤立API调用 (可能的PATTERN-R008)\n`));
+    if (orphans.length === 0) {
+      console.log(chalk.green('   无孤立API，所有前端调用都有对应后端端点'));
+    } else {
+      orphans.forEach((api, i) => {
+        console.log(`   ${i + 1}. ${chalk.red(api.url)} (${api.method})`);
+        console.log(`      文件: ${api.file}:${api.line}`);
+      });
+    }
+  });
+
+program.addCommand(depsCmd);
+
+// === contract 子命令 (契约自动发现引擎) ===
+program
+  .command('contract')
+  .description('契约自动发现 - AST级前后端契约分析 / Contract Discovery - AST-level analysis')
+  .option('-d, --dir <path>', '项目目录', '.')
+  .option('--backend-dir <path>', '后端源码目录', 'src/main/java')
+  .option('--frontend-api-dir <path>', '前端API目录', 'src/api')
+  .option('-o, --output <path>', '输出报告路径')
+  .option('--json', 'JSON格式输出')
+  .action(async (options) => {
+    const { ContractDiscovery } = await import('../lib/contract-discovery/index.js');
+    const discovery = new ContractDiscovery(options.dir, {
+      backendDir: options.backendDir,
+      frontendApiDir: options.frontendApiDir
+    });
+    const result = await discovery.analyze();
+
+    if (options.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      const report = discovery.generateContractReport();
+      if (options.output) {
+        const fs = await import('fs');
+        fs.writeFileSync(options.output, report, 'utf-8');
+        console.log(chalk.green(`\n✅ 契约报告已生成: ${options.output}`));
+      } else {
+        console.log(report);
+      }
+    }
+  });
+
 program.parse();

package/config/bug-patterns.yaml

@@ -14,9 +14,9 @@
 #   - 未来脚手架: PATTERN-JNNN (Java/Spring), PATTERN-GNNN (Go) 等
 
 meta:
-  version: "1.0.0"
-  last_updated: "2026-04-15"
-  source: "资产评估处置管理系统首次项目实践复盘"
+  version: "1.1.0"
+  last_updated: "2026-04-28"
+  source: "资产评估处置管理系统首次项目实践复盘 + 共识Bug分析报告"
   maintainers: ["pdd-skills-v3"]
 
 categories:
@@ -291,3 +291,135 @@ categories:
           public AjaxResult remove(@PathVariable Long[] ids) { ... }
         related_rules: []
         tags: ["ruoyi", "audit", "logging"]
+
+      - id: PATTERN-R013
+        name: @DataScope注解缺失
+        description: 导致跨部门数据泄露
+        trigger: 实现select*List() Mapper方法
+        prevention: 所有列表查询必须添加注解
+        severity: critical
+        detection: [3种检测方式]
+        fix_example: [❌错误 vs ✅正确 代码示例]
+        related_rules: ["dm-permission-matrix"]
+        tags: ["ruoyi", "data-scope", "security"]
+
+      - id: PATTERN-R008
+        name: "API路径拼接断层"
+        name_en: "API path concatenation mismatch"
+        description: "前端API路径遗漏了Controller类级别的@RequestMapping路径段，导致请求404"
+        trigger: "新增前端API调用或修改后端Controller路径"
+        prevention: "前端API路径 = Controller类@RequestMapping + 方法@XXXMapping，编写前必须完整拼接"
+        severity: critical
+        detection:
+          - "前端请求返回404 Not Found"
+          - "前端API路径与后端Controller完整路径不一致"
+          - "Controller类有多级@RequestMapping但前端只取了方法级路径"
+        fix_example: |
+          # ❌ 错误: 遗漏了类级别路径 /evaluation/approval
+          request({ url: '/review/manage/detail/' + id })
+          # ✅ 正确: 完整拼接类级别 + 方法级别
+          request({ url: '/evaluation/approval/review/manage/detail/' + id })
+        related_rules: []
+        tags: ["ruoyi", "api", "frontend-backend", "404"]
+
+      - id: PATTERN-R009
+        name: "附件入参类型错误"
+        name_en: "File upload parameter type mismatch"
+        description: "前端已通过通用上传接口获取文件URL，但后端业务接口仍使用MultipartFile接收，导致参数解析异常"
+        trigger: "实现包含文件附件的业务接口"
+        prevention: "若前端使用了通用上传（/common/upload），后端业务接口必须使用List<String>接收URL列表，不要用MultipartFile"
+        severity: critical
+        detection:
+          - "后端报Content-Type不支持或参数解析异常"
+          - "前端已调用/common/upload但业务接口仍声明MultipartFile参数"
+          - "前端传递的是文件URL字符串但后端期望的是文件流"
+        fix_example: |
+          // ❌ 错误: 前端已通过通用上传获取URL，不应再用MultipartFile
+          @PostMapping
+          public AjaxResult add(@RequestParam("files") MultipartFile[] files, EvalProject project) { ... }
+          // ✅ 正确: 接收URL列表
+          @PostMapping
+          public AjaxResult add(@Validated @RequestBody EvalProjectBo bo) {
+              // bo.getAttachments() 返回 List<String>，每项为文件URL
+          }
+        related_rules: []
+        tags: ["ruoyi", "file-upload", "parameter", "frontend-backend"]
+
+      - id: PATTERN-R010
+        name: "状态流转审批日志遗漏"
+        name_en: "Missing approval log during state transition"
+        description: "状态变更操作未在同一事务中记录审批日志，导致审批历史中缺少某个节点的记录"
+        trigger: "实现涉及status字段变更的业务方法"
+        prevention: "涉及状态流转的方法必须添加@Transactional，并在同方法内插入审批记录"
+        severity: critical
+        detection:
+          - "审批历史页面中缺少某个节点的审批记录"
+          - "状态变更方法中无审批日志插入语句"
+          - "状态变更和日志记录不在同一个@Transactional事务中"
+        fix_example: |
+          // ❌ 错误: 只改状态未记录审批日志
+          public void approve(Long id) {
+              project.setStatus("approved");
+              projectMapper.updateById(project);
+          }
+          // ✅ 正确: 同一事务中记录审批日志
+          @Transactional
+          public void approve(Long id) {
+              project.setStatus("approved");
+              projectMapper.updateById(project);
+              // 记录审批日志
+              EvalApprovalRecord record = new EvalApprovalRecord();
+              record.setProjectId(id);
+              record.setAction("approve");
+              record.setOperator(SecurityUtils.getUsername());
+              approvalRecordMapper.insert(record);
+          }
+        related_rules: []
+        tags: ["ruoyi", "approval", "transaction", "audit"]
+
+      - id: PATTERN-R011
+        name: "状态字典映射不完整"
+        name_en: "Incomplete status dictionary mapping"
+        description: "新增状态值后，未在所有包含状态映射的文件中同步添加，导致状态显示为英文原文或标签颜色异常"
+        trigger: "新增或修改业务状态值"
+        prevention: "新增状态值时，必须全局搜索所有getStatusLabel/getNodeLabel/getStatusTagType方法并同步更新"
+        severity: warning
+        detection:
+          - "状态值在页面上显示为英文原文（如'approved'而非'已通过'）"
+          - "状态标签颜色异常（如显示为默认灰色或红色）"
+          - "部分页面状态翻译正确但另一些页面不正确"
+        fix_example: |
+          // ❌ 错误: 在A页面加了新状态映射但B页面没加
+          // fileA.vue
+          getStatusLabel(status) {
+            const map = { draft: '草稿', pending: '待审批', approved: '已通过', rejected: '已驳回' }
+            return map[status] || status
+          }
+          // fileB.vue - 缺少 rejected 状态
+          getStatusLabel(status) {
+            const map = { draft: '草稿', pending: '待审批', approved: '已通过' }
+            return map[status] || status  // rejected 会显示英文原文
+          }
+          // ✅ 正确: 抽离到统一的 constants.js
+          // src/utils/constants.js
+          export const STATUS_MAP = { draft: '草稿', pending: '待审批', approved: '已通过', rejected: '已驳回' }
+          // 所有页面引用同一份映射
+        related_rules: ["dm-enum-convention"]
+        tags: ["ruoyi", "status", "dictionary", "frontend"]
+
+      - id: PATTERN-R012
+        name: "MyBatis多参数@Param缺失"
+        name_en: "Missing @Param annotation for MyBatis multi-parameter methods"
+        description: "Mapper方法有多个参数但未使用@Param注解，导致MyBatis参数绑定异常"
+        trigger: "Mapper接口方法有2个以上参数"
+        prevention: "Mapper方法有2个以上参数时，每个参数必须添加@Param注解"
+        severity: critical
+        detection:
+          - "运行时报MyBatis参数绑定异常(BindingException)"
+          - "Mapper方法有多个参数但无@Param注解"
+          - "XML中的#{param}无法匹配到方法参数"
+        fix_example: |
+          // ❌ 错误: 多参数未加@Param
+          List<EvalProject> selectByStatusAndDept(String status, Long deptId);
+          // ✅ 正确: 每个参数加@Param
+          List<EvalProject> selectByStatusAndDept(@Param("status") String status, @Param("deptId") Long deptId);