@specpow/framework 0.5.11 → 0.5.12

package/builtin/skills/business-code-review/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: business-code-review
+description: SpecPow business-code-review skill
+---
+
+# 代码审查
+
+> 对变更进行结构化代码审查，输出审查报告
+
+## 触发条件
+
+- 用户要求审查代码 / review
+- SDD 引擎的审查阶段 - 提交 PR/MR 前
+
+## 铁律
+
+1. **不主观臆断** — 每个 Finding 必须有代码行号引用
+2. **分级明确** — Critical / Major / Minor / Suggestion
+3. **可操作** — 每个 Finding 附带修复建议
+4. **不阻塞小问题** — Suggestion 不阻塞合并
+
+## 审查维度
+
+### 1. 规范合规性
+- 命名规范（类名、方法名、变量名）
+- 代码分层（Controller 不写业务逻辑）
+- 注释完整性
+
+### 2. 代码质量
+- 重复代码
+- 过长方法（>50 行）
+- 过深嵌套（>3 层）
+- 魔法数字
+
+### 3. 安全性
+- SQL 注入风险
+- XSS 风险
+- 敏感信息硬编码
+- 权限校验缺失
+
+### 4. 性能
+- N+1 查询
+- 大对象未分页
+- 循环内数据库调用
+- 未使用索引的查询
+
+### 5. 测试
+- 新增代码是否有测试
+- 测试是否覆盖关键路径
+- Mock 使用是否合理
+
+## 输出格式
+
+```markdown
+# 代码审查报告
+
+## 概要
+- 审查范围: commit abc123..def456
+- 文件数: 12
+- 发现数: 5 (1 Critical, 2 Major, 2 Minor)
+
+## 发现
+
+### [Critical] SQL 注入风险
+- 文件: `XxxMapper.java:45`
+- 问题: 使用字符串拼接构建 SQL
+- 建议: 使用参数化查询 #{param}
+
+### [Major] 缺少事务注解
+- 文件: `XxxServiceImpl.java:78`
+- 问题: 多步数据库操作未加 @Transactional
+- 建议: 添加 @Transactional(rollbackFor = Exception.class)
+```
+
+## 红旗
+
+- 发现 Critical 级别问题 → 必须修复后才能合并
+- 安全漏洞 → 立即通知负责人

package/builtin/skills/business-db-design/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: business-db-design
+description: SpecPow business-db-design skill
+---
+
+# 数据库设计
+> 根据 PRD 或需求描述，设计数据库表结构，输出 DDL + 索引建议 + 状态码
+
+## 触发条件
+
+- 用户要求设计数据库/表结构
+- PRD 中包含数据模型需求
+- 用户提到"建表"/"DDL"/"字段设计"
+
+## 铁律
+
+1. **命名规范** — 表名小写下划线，字段名小写下划线
+2. **必备字段** — id, create_time, update_time, is_deleted
+3. **索引合理** — 查询条件建索引，不滥用联合索引
+4. **注释完整** — 表注释、字段注释、枚举值说明
+
+## 工作流
+
+### 阶段 1：需求分析
+1. 读取 PRD 或需求描述
+2. 识别实体和关系（1:1, 1:N, M:N）
+3. 确认字段列表和数据类型
+4. 识别查询场景（决定索引策略）
+
+### 阶段 2：表结构设计
+
+**每个表包含：**
+```sql
+CREATE TABLE `table_name` (
+  `id` bigint(20) NOT NULL AUTO_INCREMENT COMMENT '主键ID',
+  -- 业务字段
+  `create_by` varchar(64) DEFAULT '' COMMENT '创建人',
+  `create_time` datetime DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+  `update_by` varchar(64) DEFAULT '' COMMENT '更新人',
+  `update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
+  `is_deleted` tinyint(1) DEFAULT 0 COMMENT '逻辑删除(0正常 1删除)',
+  PRIMARY KEY (`id`),
+  -- 索引
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='表注释';
+```
+
+### 阶段 3：索引设计
+- 等值查询字段 → 单列索引
+- 范围查询 → 联合索引（最左前缀）
+- 唯一约束 → UNIQUE 索引
+- 避免过多索引（单表 ≤ 5 个）
+
+### 阶段 4：状态码/枚举分配
+
+```
+字段: status
+0 - 草稿
+1 - 待审核
+2 - 已通过
+3 - 已拒绝
+```
+
+## 输出格式
+
+1. DDL 脚本（可直接执行）
+2. 索引建议说明
+3. 枚举值对照表
+4. ER 关系图（Mermaid）
+
+## 红旗
+
+- 字段超过 30 个 → 考虑拆表
+- 需要 TEXT/BLOB → 确认是否应该独立表
+- 多对多关系 → 确认中间表设计

package/builtin/skills/business-deploy-check/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: business-deploy-check
+description: SpecPow business-deploy-check skill
+---
+
+# 部署检查
+> 在部署前执行全面检查，确保代码、配置、依赖就绪
+
+## 触发条件
+
+- 用户提到"部署"/"发布"/"上线"
+- 准备合并到主分支前
+- CI/CD 流水线触发前
+
+## 检查清单
+
+### 1. 代码完整性
+- [ ] 所有任务已完成（tasks.md 全部 [x]）
+- [ ] 无未提交的变更（git status clean）
+- [ ] 分支已 rebase 到最新主分支
+
+### 2. 构建验证
+- [ ] 后端编译通过（mvn clean package）
+- [ ] 前端构建通过（npm run build）
+- [ ] 无编译警告（或警告已评估）
+
+### 3. 测试验证
+- [ ] 单元测试全部通过
+- [ ] 测试覆盖率 ≥ 阈值
+- [ ] 集成测试通过（如有）
+
+### 4. 配置检查
+- [ ] 环境变量已配置
+- [ ] 数据库变更脚本已准备
+- [ ] 配置文件无硬编码敏感信息
+- [ ] 多环境配置一致（dev/test/prod）
+
+### 5. 依赖检查
+- [ ] 无 SNAPSHOT 版本依赖
+- [ ] 新增依赖已审批
+- [ ] 依赖安全扫描通过
+
+### 6. 文档检查
+- [ ] API 文档已更新
+- [ ] 变更日志已编写
+- [ ] 运维手册已更新（如需要）
+
+## 输出格式
+
+```markdown
+# 部署检查报告
+
+## 检查结果: ✅ 通过 / ❌ 未通过
+
+### 通过项 (8/10)
+- ✅ 代码完整性
+- ✅ 构建验证
+...
+
+### 未通过项
+- ❌ 测试覆盖率 58% < 60% 阈值
+  - 建议: 补充 XxxService 的测试用例
+
+### 风险提示
+- 新增依赖: xxx-lib 2.0.0（首次引入）
+```
+
+## 红旗
+
+- 任何"代码完整性"检查失败 → 阻止部署
+- 安全扫描发现高危漏洞 → 阻止部署
+- 配置不一致 → 警告并确认

package/builtin/skills/business-doc-sync/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: business-doc-sync
+description: SpecPow business-doc-sync skill
+---
+
+# 文档同步
+
+> 确保代码变更后，相关文档同步更新
+
+## 触发条件
+
+- 代码变更完成后
+- API 接口发生变化
+- 数据库结构发生变更
+- 用户提到"更新文档"/"同步文档"
+
+## 铁律
+
+1. **代码即文档** — 代码变更必须伴随文档更新
+2. **自动检测** — 扫描变更文件，识别需要同步的文档
+3. **不遗漏** — API、数据库、配置变更必须同步
+
+## 检查维度
+
+### 1. API 文档
+- Controller 变更 → 更新 Swagger/接口文档
+- 新增接口 → 添加接口说明
+- 修改参数 → 更新参数说明
+- 删除接口 → 标记废弃
+
+### 2. 数据库文档
+- DDL 变更 → 更新数据字典
+- 新增表 → 添加表说明
+- 修改字段 → 更新字段说明
+
+### 3. 配置文档
+- 新增配置项 → 更新配置说明
+- 修改默认值 → 更新配置示例
+
+### 4. README / CHANGELOG
+- 功能变更 → 更新 README
+- 版本发布 → 编写 CHANGELOG
+
+## 工作流
+
+1. **扫描变更** — 获取 git diff 或变更文件列表
+2. **识别影响** — 判断哪些文档需要同步
+3. **生成更新** — 自动更新受影响的文档
+4. **验证一致性** — 检查文档与代码是否一致
+
+## 输出格式
+
+```markdown
+# 文档同步报告
+
+## 需要同步的文档 (3)
+1. `docs/api/user-api.md` — 新增 2 个接口
+2. `docs/data-dictionary.md` — 新增 1 张表
+3. `CHANGELOG.md` — 添加 v1.2.0 变更记录
+
+## 已自动更新
+- ✓ docs/api/user-api.md
+- ✓ docs/data-dictionary.md
+
+## 需要手动确认
+- ⚠️ README.md — 建议添加新功能说明
+```
+
+## 红旗
+
+- API 变更但无文档更新 → 警告
+- 数据库变更但数据字典未更新 → 警告

package/builtin/skills/business-java-codegen/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: business-java-codegen
+description: SpecPow business-java-codegen skill
+---
+
+# Java 代码生成
+
+> 根据设计文档和数据库表结构，生成符合项目规范的 Java 后端代码（Entity/Mapper/Service/Controller 四层）
+
+## 技术栈配置
+
+本技能的**默认**技术栈为 MyBatis-Plus + Spring Boot，但会根据项目实际使用的框架自动适配：
+
+- **ORM 框架** — 优先使用项目已有的 ORM（MyBatis-Plus / JPA / MyBatis / JDBC Template）
+- **基类** — 扫描项目已有 BaseEntity、BaseController 等基类并继承
+- **包名规范** — 从已有代码推断包结构，而非硬编码
+- **返回格式** — 使用项目已有的统一返回类型（Result / Response / ApiResponse）
+
+如果项目无已有代码可参考，则在阶段 1 询问用户确认技术选型。
+
+## 触发条件
+
+- 用户要求生成 Java 代码
+- 执行 apply-change 时涉及后端任务
+- 用户提到"生成接口"/"写 Service"/"创建 Controller"
+
+## 铁律
+
+1. **先查 DB 再生成** — 必须确认表结构已存在，字段名以数据库为准
+2. **四层齐全** — Entity、Mapper(XML)、Service(Interface+Impl)、Controller 缺一不可
+3. **不造轮子** — 使用项目已有的基类（BaseEntity、BaseController 等）
+4. **注释完整** — 类注释、方法注释、关键逻辑行注释
+
+## 工作流
+
+### 阶段 1：上下文收集
+
+1. 读取 design.md 获取接口定义和数据模型
+2. 查询数据库表结构（DDL 或已有 Entity）
+3. **扫描项目已有代码，识别技术栈**（ORM 框架、基类、包名、返回格式）
+4. 如果项目无已有代码，询问用户确认技术选型
+
+### 阶段 2：代码生成
+
+按以下顺序生成：
+
+**2.1 Entity（实体类）**
+```
+- 继承 BaseEntity（如有）
+- 字段与数据库列一一对应
+- 使用 @Table、@Column 注解
+- 包含 getter/setter 或 @Data
+```
+
+**2.2 Mapper（数据访问层）**
+```
+- 继承 BaseMapper<T>（MyBatis-Plus）或对应基类
+- 自定义 SQL 写在 XML 中
+- 复杂查询方法命名：select + By + 条件
+```
+
+**2.3 Service（业务逻辑层）**
+```
+- 接口 + 实现分离
+- 继承 IService<T> / ServiceImpl（如有基类）
+- 事务注解 @Transactional 加在实现类方法上
+- 业务异常使用自定义 BusinessException
+```
+
+**2.4 Controller（控制层）**
+```
+- 继承 BaseController（如有）
+- RESTful 风格：GET 查询、POST 创建、PUT 更新、DELETE 删除
+- 参数校验使用 @Valid + DTO
+- 统一返回 Result<T> 格式
+```
+
+### 阶段 3：验证
+
+1. 编译检查：确保无语法错误
+2. 依赖检查：所有 import 可解析
+3. 规范检查：命名、注释、分层符合规范
+
+## 输出格式
+
+每个文件输出时标注：
+```
+文件: src/main/java/com/company/xxx/entity/XxxEntity.java
+类型: Entity
+依赖: BaseEntity, Lombok
+```
+
+## 红旗（立即停止）
+
+- 数据库表不存在 → 先执行 DB 设计
+- 项目无基类且用户未指定 → 询问用户
+- 发现已有同名类 → 报告冲突，不覆盖

package/builtin/skills/business-menu-register/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: business-menu-register
+description: SpecPow business-menu-register skill
+---
+
+# 菜单注册
+
+> 根据新增页面/功能，生成系统菜单注册 SQL 和路由配置
+
+## 触发条件
+
+- 新增页面需要注册到系统菜单
+- 用户提到"注册菜单"/"添加菜单"/"系统菜单"
+- 新模块的权限配置
+
+## 铁律
+
+1. **层级正确** — 一级菜单 → 二级菜单 → 按钮权限
+2. **ID 唯一** — 菜单 ID 不与已有冲突
+3. **路径一致** — 菜单路径与前端路由一致
+4. **权限编码规范** — 模块:功能:操作
+
+## 菜单结构
+
+```sql
+-- 一级菜单（目录）
+INSERT INTO sys_menu (menu_id, menu_name, parent_id, order_num, path, menu_type, visible, status)
+VALUES (2000, '模块名称', 0, 1, '/module', 'M', '0', '0');
+
+-- 二级菜单（页面）
+INSERT INTO sys_menu (menu_id, menu_name, parent_id, order_num, path, component, menu_type, visible, status)
+VALUES (2001, '页面名称', 2000, 1, 'page', 'module/page/index', 'C', '0', '0');
+
+-- 按钮权限
+INSERT INTO sys_menu (menu_id, menu_name, parent_id, order_num, menu_type, perms, visible, status)
+VALUES (2011, '新增', 2001, 1, 'F', 'module:entity:add', '0', '0');
+INSERT INTO sys_menu (menu_id, menu_name, parent_id, order_num, menu_type, perms, visible, status)
+VALUES (2012, '修改', 2001, 2, 'F', 'module:entity:edit', '0', '0');
+INSERT INTO sys_menu (menu_id, menu_name, parent_id, order_num, menu_type, perms, visible, status)
+VALUES (2013, '删除', 2001, 3, 'F', 'module:entity:remove', '0', '0');
+INSERT INTO sys_menu (menu_id, menu_name, parent_id, order_num, menu_type, perms, visible, status)
+VALUES (2014, '查询', 2001, 4, 'F', 'module:entity:query', '0', '0');
+```
+
+## 工作流
+
+1. **扫描已有菜单** — 查询最大 menu_id，避免冲突
+2. **确认菜单层级** — 目录(M) → 菜单(C) → 按钮(F)
+3. **生成 SQL** — 按层级顺序生成 INSERT 语句
+4. **生成路由** — 对应的前端路由配置
+5. **验证** — 检查 ID 唯一性和路径一致性
+
+## 输出格式
+
+1. 菜单注册 SQL（可直接执行）
+2. 前端路由配置
+3. 权限编码清单
+
+## 红旗
+
+- 菜单 ID 冲突 → 重新分配
+- 路径与已有路由冲突 → 报告冲突
+- 缺少父级菜单 → 先创建目录

package/builtin/skills/business-prd-writer/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: business-prd-writer
+description: SpecPow business-prd-writer skill
+---
+
+# PRD 编写
+
+> 将用户口述、会议纪要、原型截图转化为结构化 PRD 文档
+
+## 触发条件
+
+- 用户描述一个新功能/需求
+- 用户提到"写 PRD"/"需求文档"/"产品需求"
+- 项目启动阶段的需求梳理
+
+## 铁律
+
+1. **不替用户决定** — 不确定的地方标注 [待确认]
+2. **用例驱动** — 每个功能点至少 1 个用例
+3. **可验证** — 每个需求有明确的验收标准
+4. **边界清晰** — 明确"做什么"和"不做什么"
+
+## PRD 结构
+
+```markdown
+# [功能名称] PRD
+
+## 1. 背景与目标
+- 业务背景
+- 核心目标（可量化）
+- 成功指标
+
+## 2. 用户角色
+| 角色 | 描述 | 核心诉求 |
+|------|------|----------|
+
+## 3. 功能需求
+### 3.1 [功能模块]
+- 用例 UC-001: [用例名称]
+  - 前置条件:
+  - 主流程:
+  - 备选流程:
+  - 异常流程:
+
+## 4. 非功能需求
+- 性能要求
+- 安全要求
+- 兼容性要求
+
+## 5. 数据需求
+- 核心实体
+- 字段清单
+- 数据流向
+
+## 6. 界面原型
+- 页面列表
+- 关键交互说明
+
+## 7. 排期建议
+- 优先级排序（P0/P1/P2）
+- 依赖关系
+
+## 8. 待确认项
+- [ ] 问题1
+- [ ] 问题2
+```
+
+## 工作流
+
+1. **收集信息** — 与用户对话，提取关键需求
+2. **结构化** — 按 PRD 模板整理
+3. **补充细节** — 推断合理的用例和边界
+4. **标注不确定** — 用 [待确认] 标记
+5. **用户确认** — 输出后请用户审核
+
+## 红旗
+
+- 用户描述模糊 → 提出澄清问题，不猜测
+- 需求超出当前迭代 → 标注"后续迭代"
+- 涉及其他系统 → 标注集成依赖

package/builtin/skills/business-test-gen/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: business-test-gen
+description: SpecPow business-test-gen skill
+---
+
+# 测试代码生成
+
+> 根据业务层代码，生成单元测试
+
+## 技术栈配置
+
+本技能的**默认**技术栈为 JUnit5 + Mockito（Java），但会根据项目实际使用的测试框架自动适配：
+
+- **测试框架** — 优先使用项目已有的框架（JUnit5 / JUnit4 / TestNG / Jest / Vitest / pytest）
+- **Mock 工具** — 匹配项目已有 Mock 方案（Mockito / Sinon / unittest.mock / gomock）
+- **断言库** — 使用项目已有的断言风格（AssertJ / Hamcrest / Jest expect / chai）
+- **运行命令** — 从项目 package.json / pom.xml / build.gradle 推断测试运行命令
+
+## 触发条件
+
+- 用户要求生成测试代码
+- 执行 apply-change 中任务包含验证步骤
+- 用户提到"写测试"/"单测"/"覆盖率"
+
+## 铁律
+
+1. **测行为不测实现** — 测试输入→输出，不关心内部怎么实现
+2. **Mock 外部依赖** — 数据库、RPC、HTTP 全部 Mock
+3. **边界必测** — null、空集合、极值、异常路径
+4. **失败自修** — 测试失败自动修复，最多 3 轮
+
+## 工作流
+
+### 阶段 1：分析被测代码
+1. 读取目标 Service/Mapper 类
+2. 识别所有 public 方法
+3. 分析方法依赖（需要 Mock 的对象）
+4. 提取业务规则和边界条件
+
+### 阶段 2：生成测试
+
+**测试类结构：**
+```java
+@ExtendWith(MockitoExtension.class)
+class XxxServiceTest {
+
+    @InjectMocks
+    private XxxServiceImpl xxxService;
+
+    @Mock
+    private XxxMapper xxxMapper;
+
+    // 每个方法至少 2 个测试：正常路径 + 异常路径
+    @Test
+    @DisplayName("方法名 - 场景描述")
+    void methodName_scenario() {
+        // Given
+        // When
+        // Then
+    }
+}
+```
+
+**覆盖场景类型：**
+- 正常输入 → 预期输出
+- null 参数 → 抛出异常或返回默认值
+- 空集合 → 正确处理
+- 数据库无记录 → 返回 null
+- 业务规则违反 → 抛出 BusinessException
+
+### 阶段 3：执行与自修
+
+1. 运行测试：`mvn test -Dtest=XxxServiceTest`
+2. 如果失败，分析错误原因
+3. 修复测试代码（不修改被测代码）
+4. 最多 3 轮，仍失败则报告问题
+
+## 红旗
+
+- 被测类不存在 → 先生成业务代码
+- 项目无测试框架 → 询问用户选择测试框架
+- 覆盖率低于 60% → 补充测试用例