From 3706d7f32d58c52f3f66816a32edb7beb4cb0929 Mon Sep 17 00:00:00 2001 From: John Qiu Date: Mon, 6 Apr 2026 17:43:30 +0930 Subject: [PATCH] =?UTF-8?q?feat(skill):=20REQ-20260406-0004=20=E6=8A=80?= =?UTF-8?q?=E8=83=BD=E4=B8=89=E5=B1=82=E5=88=86=E7=A6=BB=E9=87=8D=E6=9E=84?= =?UTF-8?q?=EF=BC=887=E4=B8=BB=E7=BA=BF+16=E6=8F=92=E4=BB=B6=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 批次1: req-prd 瘦身 + req-design 重定位 + dev-coding 聚焦 批次2: dev-review 新建 + review-checklist 插件 批次3: dev-integration 新建 + req-compare 拆出 批次4: 插件完善 (req-research/db-migration/dev-scaffold/deploy-rollback) 批次5: 平台拆分 (dev-ios/dev-android/dev-mcp/dev-pda) + dev 分组更新 批次6: marketplace.json 32→44 plugins Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude-plugin/marketplace.json | 175 ++++++- .../.claude-plugin/plugin.json | 6 + .../db-migration-plugin/skills/SKILL.md | 105 ++++ .../.claude-plugin/plugin.json | 6 + .../deploy-rollback-plugin/skills/SKILL.md | 102 ++++ .../.claude-plugin/plugin.json | 1 + skills-dev/dev-android-plugin/skills/SKILL.md | 54 +++ .../.claude-plugin/plugin.json | 4 +- skills-dev/dev-coding-plugin/skills/SKILL.md | 370 +------------- .../.claude-plugin/plugin.json | 8 + .../dev-integration-plugin/skills/SKILL.md | 154 ++++++ .../dev-ios-plugin/.claude-plugin/plugin.json | 1 + skills-dev/dev-ios-plugin/skills/SKILL.md | 90 ++++ .../dev-mcp-plugin/.claude-plugin/plugin.json | 1 + skills-dev/dev-mcp-plugin/skills/SKILL.md | 59 +++ .../dev-pda-plugin/.claude-plugin/plugin.json | 1 + skills-dev/dev-pda-plugin/skills/SKILL.md | 49 ++ .../.claude-plugin/plugin.json | 8 + skills-dev/dev-review-plugin/skills/SKILL.md | 280 +++++++++++ .../.claude-plugin/plugin.json | 6 + .../dev-scaffold-plugin/skills/SKILL.md | 78 +++ .../.claude-plugin/plugin.json | 8 + .../checklists/ai-proj.md | 42 ++ .../checklists/coolbuy-paas.md | 20 + .../checklists/general.md | 23 + .../review-checklist-plugin/skills/SKILL.md | 49 ++ .../.claude-plugin/plugin.json | 8 + skills-req/req-compare-plugin/skills/SKILL.md | 210 ++++++++ .../.claude-plugin/plugin.json | 8 + skills-req/req-design-plugin/skills/SKILL.md | 455 ++++++++++++++++++ .../req-dev-plugin/.claude-plugin/plugin.json | 3 +- .../req-prd-plugin/.claude-plugin/plugin.json | 4 +- skills-req/req-prd-plugin/skills/SKILL.md | 283 +---------- .../.claude-plugin/plugin.json | 6 + .../req-research-plugin/skills/SKILL.md | 124 +++++ 35 files changed, 2178 insertions(+), 623 deletions(-) create mode 100644 skills-dev/db-migration-plugin/.claude-plugin/plugin.json create mode 100644 skills-dev/db-migration-plugin/skills/SKILL.md create mode 100644 skills-dev/deploy-rollback-plugin/.claude-plugin/plugin.json create mode 100644 skills-dev/deploy-rollback-plugin/skills/SKILL.md create mode 100644 skills-dev/dev-android-plugin/.claude-plugin/plugin.json create mode 100644 skills-dev/dev-android-plugin/skills/SKILL.md create mode 100644 skills-dev/dev-integration-plugin/.claude-plugin/plugin.json create mode 100644 skills-dev/dev-integration-plugin/skills/SKILL.md create mode 100644 skills-dev/dev-ios-plugin/.claude-plugin/plugin.json create mode 100644 skills-dev/dev-ios-plugin/skills/SKILL.md create mode 100644 skills-dev/dev-mcp-plugin/.claude-plugin/plugin.json create mode 100644 skills-dev/dev-mcp-plugin/skills/SKILL.md create mode 100644 skills-dev/dev-pda-plugin/.claude-plugin/plugin.json create mode 100644 skills-dev/dev-pda-plugin/skills/SKILL.md create mode 100644 skills-dev/dev-review-plugin/.claude-plugin/plugin.json create mode 100644 skills-dev/dev-review-plugin/skills/SKILL.md create mode 100644 skills-dev/dev-scaffold-plugin/.claude-plugin/plugin.json create mode 100644 skills-dev/dev-scaffold-plugin/skills/SKILL.md create mode 100644 skills-dev/review-checklist-plugin/.claude-plugin/plugin.json create mode 100644 skills-dev/review-checklist-plugin/checklists/ai-proj.md create mode 100644 skills-dev/review-checklist-plugin/checklists/coolbuy-paas.md create mode 100644 skills-dev/review-checklist-plugin/checklists/general.md create mode 100644 skills-dev/review-checklist-plugin/skills/SKILL.md create mode 100644 skills-req/req-compare-plugin/.claude-plugin/plugin.json create mode 100644 skills-req/req-compare-plugin/skills/SKILL.md create mode 100644 skills-req/req-design-plugin/.claude-plugin/plugin.json create mode 100644 skills-req/req-design-plugin/skills/SKILL.md create mode 100644 skills-req/req-research-plugin/.claude-plugin/plugin.json create mode 100644 skills-req/req-research-plugin/skills/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 3618fa2..66065f6 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -47,6 +47,44 @@ ], "strict": false }, + { + "name": "db-migration-plugin", + "source": "./skills-dev/db-migration-plugin", + "description": "数据库变更方案插件。Migration 脚本生成、数据迁移策略、回滚方案。挂载在 design 阶段，涉及数据库变更时激活。", + "version": "1.0.0", + "category": "utility", + "keywords": [ + "utility", + "tools" + ], + "strict": false + }, + { + "name": "deploy-rollback-plugin", + "source": "./skills-dev/deploy-rollback-plugin", + "description": "回滚方案插件。部署后发现问题时的回滚策略、数据修复、灰度回退。挂载在 deploy 阶段。", + "version": "1.0.0", + "category": "devops", + "keywords": [ + "devops", + "deployment", + "operations" + ], + "strict": false + }, + { + "name": "dev-android-plugin", + "source": "./skills-dev/dev-android-plugin", + "description": "Android 开发插件。Kotlin + Jetpack Compose + Hilt 依赖注入。按需加载。", + "version": "1.0.0", + "category": "development", + "keywords": [ + "development", + "coding", + "workflow" + ], + "strict": false + }, { "name": "dev-arch-plugin", "source": "./skills-dev/dev-arch-plugin", @@ -76,7 +114,85 @@ { "name": "dev-coding-plugin", "source": "./skills-dev/dev-coding-plugin", - "description": "Plugin for dev-coding", + "description": "软件编码开发技能。Go 后端 + Vue/React 前端编码实现，集成 ai-proj 任务管理。", + "version": "2.0.0", + "category": "development", + "keywords": [ + "development", + "coding", + "workflow" + ], + "strict": false + }, + { + "name": "dev-integration-plugin", + "source": "./skills-dev/dev-integration-plugin", + "description": "前后端联调技能。API 契约验证、联调报告、纯后端需求自动跳过。对应 req 流程 integration 阶段。", + "version": "1.0.0", + "category": "development", + "keywords": [ + "development", + "coding", + "workflow" + ], + "strict": false + }, + { + "name": "dev-ios-plugin", + "source": "./skills-dev/dev-ios-plugin", + "description": "iOS 开发插件。Swift/SwiftUI + MVVM 架构、TestFlight 部署、Xcode 构建。按需加载。", + "version": "1.0.0", + "category": "development", + "keywords": [ + "development", + "coding", + "workflow" + ], + "strict": false + }, + { + "name": "dev-mcp-plugin", + "source": "./skills-dev/dev-mcp-plugin", + "description": "MCP Bridge 开发插件。TypeScript MCP 服务开发、Token 管理、HTTP 客户端模式。按需加载。", + "version": "1.0.0", + "category": "development", + "keywords": [ + "development", + "coding", + "workflow" + ], + "strict": false + }, + { + "name": "dev-pda-plugin", + "source": "./skills-dev/dev-pda-plugin", + "description": "PDA 应用开发插件。Android 原生 + 扫码枪集成 + 离线优先模式。按需加载。", + "version": "1.0.0", + "category": "development", + "keywords": [ + "development", + "coding", + "workflow" + ], + "strict": false + }, + { + "name": "dev-review-plugin", + "source": "./skills-dev/dev-review-plugin", + "description": "代码评审技能。五视角对抗性扫描法（攻击者/泄露者/并发者/边界者/依赖者），CR 报告生成，独立于 req 工作流可单独使用。", + "version": "1.0.0", + "category": "development", + "keywords": [ + "development", + "coding", + "workflow" + ], + "strict": false + }, + { + "name": "dev-scaffold-plugin", + "source": "./skills-dev/dev-scaffold-plugin", + "description": "模块脚手架插件。新建模块时自动生成分层代码骨架（Model/Repository/Service/Handler/Route）。挂载在 dev 阶段。", "version": "1.0.0", "category": "development", "keywords": [ @@ -125,10 +241,48 @@ ], "strict": false }, + { + "name": "review-checklist-plugin", + "source": "./skills-dev/review-checklist-plugin", + "description": "项目级代码评审检查清单。按项目积累的特定检查项，挂载在 dev-review 下自动加载。", + "version": "1.0.0", + "category": "utility", + "keywords": [ + "utility", + "tools" + ], + "strict": false + }, + { + "name": "req-compare-plugin", + "source": "./skills-req/req-compare-plugin", + "description": "对比式需求分析插件。系统平移、竞品借鉴、版本升级时的参考对象对比分析。挂载在 analysis 阶段。", + "version": "1.0.0", + "category": "productivity", + "keywords": [ + "project-management", + "tasks", + "requirements" + ], + "strict": false + }, + { + "name": "req-design-plugin", + "source": "./skills-req/req-design-plugin", + "description": "需求开发设计技能。PRD 到开发设计的转换：API 契约、数据模型变更、任务拆分、风险评估。", + "version": "2.0.0", + "category": "productivity", + "keywords": [ + "project-management", + "tasks", + "requirements" + ], + "strict": false + }, { "name": "req-dev-plugin", "source": "./skills-req/req-dev-plugin", - "description": "Plugin for req-dev", + "description": "[已废弃] 请使用 req-design-plugin。需求开发设计功能已迁移。", "version": "1.0.0", "category": "development", "keywords": [ @@ -154,8 +308,8 @@ { "name": "req-prd-plugin", "source": "./skills-req/req-prd-plugin", - "description": "Plugin for req-prd", - "version": "1.0.0", + "description": "产品需求设计技能。PRD 文档编写、需求分析、用户故事、对比式分析。纯产品视角，不含技术实现。", + "version": "2.0.0", "category": "productivity", "keywords": [ "project-management", @@ -177,6 +331,19 @@ ], "strict": false }, + { + "name": "req-research-plugin", + "source": "./skills-req/req-research-plugin", + "description": "需求调研插件。代码审计、数据库分析、现有功能调研。挂载在 analysis 阶段，需要深度调研时激活。", + "version": "1.0.0", + "category": "productivity", + "keywords": [ + "project-management", + "tasks", + "requirements" + ], + "strict": false + }, { "name": "req-review-plugin", "source": "./skills-req/req-review-plugin", diff --git a/skills-dev/db-migration-plugin/.claude-plugin/plugin.json b/skills-dev/db-migration-plugin/.claude-plugin/plugin.json new file mode 100644 index 0000000..77bb96c --- /dev/null +++ b/skills-dev/db-migration-plugin/.claude-plugin/plugin.json @@ -0,0 +1,6 @@ +{ + "name": "db-migration-plugin", + "description": "数据库变更方案插件。Migration 脚本生成、数据迁移策略、回滚方案。挂载在 design 阶段，涉及数据库变更时激活。", + "version": "1.0.0", + "author": { "name": "qiudl" } +} diff --git a/skills-dev/db-migration-plugin/skills/SKILL.md b/skills-dev/db-migration-plugin/skills/SKILL.md new file mode 100644 index 0000000..7e79bf8 --- /dev/null +++ b/skills-dev/db-migration-plugin/skills/SKILL.md @@ -0,0 +1,105 @@ +--- +name: db-migration +description: 数据库变更方案插件。Migration 脚本生成、数据迁移策略、回滚方案。挂载在 design 阶段，涉及数据库变更时由 req-design 推荐激活。 +--- + +# 数据库变更方案插件 (db-migration) + +## 概述 + +当需求涉及数据库结构变更时使用，确保变更安全、可回滚。 + +**触发条件**： +- 新增/修改/删除表或字段 +- 数据迁移（旧数据转换） +- 索引优化 + +## Migration 规范 + +### 文件命名 + +``` +backend/migrations/YYYYMMDDHHMMSS_description.up.sql # 正向迁移 +backend/migrations/YYYYMMDDHHMMSS_description.down.sql # 回滚迁移 +``` + +### 安全规则 + +| 操作 | 风险等级 | 注意事项 | +|------|---------|---------| +| ADD COLUMN (nullable) | 低 | 安全，无锁表 | +| ADD COLUMN (NOT NULL + DEFAULT) | 中 | PG 12+ 不锁表，旧版本锁表 | +| DROP COLUMN | 高 | 确认无代码引用，先标记废弃 | +| ALTER COLUMN TYPE | 高 | 可能锁表，大表慎用 | +| ADD INDEX | 中 | 使用 CONCURRENTLY 避免锁表 | +| DROP TABLE | 极高 | 必须确认无依赖 | + +### Migration 模板 + +**新增表**： +```sql +-- up.sql +CREATE TABLE IF NOT EXISTS xxx ( + id BIGSERIAL PRIMARY KEY, + tenant_id BIGINT NOT NULL, + -- 业务字段 + name VARCHAR(255) NOT NULL, + status VARCHAR(50) NOT NULL DEFAULT 'active', + -- 审计字段 + created_by BIGINT, + created_at TIMESTAMP NOT NULL DEFAULT NOW(), + updated_at TIMESTAMP NOT NULL DEFAULT NOW(), + deleted_at TIMESTAMP +); + +CREATE INDEX idx_xxx_tenant_id ON xxx(tenant_id); +CREATE INDEX idx_xxx_deleted_at ON xxx(deleted_at); + +-- down.sql +DROP TABLE IF EXISTS xxx; +``` + +**新增字段**： +```sql +-- up.sql +ALTER TABLE xxx ADD COLUMN yyy VARCHAR(255); +-- 如果需要索引 +CREATE INDEX CONCURRENTLY idx_xxx_yyy ON xxx(yyy); + +-- down.sql +DROP INDEX IF EXISTS idx_xxx_yyy; +ALTER TABLE xxx DROP COLUMN IF EXISTS yyy; +``` + +**数据迁移**： +```sql +-- up.sql +-- 1. 先添加新字段 +ALTER TABLE xxx ADD COLUMN new_field VARCHAR(255); + +-- 2. 迁移数据 +UPDATE xxx SET new_field = old_field WHERE new_field IS NULL; + +-- 3. 添加约束（数据迁移完成后） +ALTER TABLE xxx ALTER COLUMN new_field SET NOT NULL; + +-- down.sql +ALTER TABLE xxx ALTER COLUMN new_field DROP NOT NULL; +ALTER TABLE xxx DROP COLUMN IF EXISTS new_field; +``` + +## 大表变更策略 + +当表数据量 > 100 万行时： + +1. **添加索引**：必须使用 `CREATE INDEX CONCURRENTLY` +2. **修改字段类型**：分步执行（新增列→迁移数据→切换引用→删除旧列） +3. **添加 NOT NULL**：先添加 DEFAULT，再 SET NOT NULL +4. **数据迁移**：分批处理，每批 1000-10000 行 + +## 回滚检查 + +每个 Migration 必须有可执行的 down.sql： +- [ ] down.sql 存在且语法正确 +- [ ] down.sql 可以完全撤销 up.sql 的变更 +- [ ] down.sql 不会丢失业务数据（除非是 DROP TABLE） diff --git a/skills-dev/deploy-rollback-plugin/.claude-plugin/plugin.json b/skills-dev/deploy-rollback-plugin/.claude-plugin/plugin.json new file mode 100644 index 0000000..d67a17c --- /dev/null +++ b/skills-dev/deploy-rollback-plugin/.claude-plugin/plugin.json @@ -0,0 +1,6 @@ +{ + "name": "deploy-rollback-plugin", + "description": "回滚方案插件。部署后发现问题时的回滚策略、数据修复、灰度回退。挂载在 deploy 阶段。", + "version": "1.0.0", + "author": { "name": "qiudl" } +} diff --git a/skills-dev/deploy-rollback-plugin/skills/SKILL.md b/skills-dev/deploy-rollback-plugin/skills/SKILL.md new file mode 100644 index 0000000..d5a0566 --- /dev/null +++ b/skills-dev/deploy-rollback-plugin/skills/SKILL.md @@ -0,0 +1,102 @@ +--- +name: deploy-rollback +description: 回滚方案插件。部署后发现问题时的回滚策略和执行步骤。挂载在 deploy 阶段，部署出问题时激活。 +--- + +# 回滚方案插件 (deploy-rollback) + +## 概述 + +当生产部署后发现问题时，提供结构化的回滚决策和执行步骤。 + +**触发条件**： +- 部署后健康检查失败 +- 部署后用户报告问题 +- 部署后监控告警 + +## 回滚决策树 + +``` +问题发现 +├── 服务完全不可用？ +│ └── YES → 立即回滚（紧急） +├── 核心功能异常？ +│ └── YES → 评估影响范围 → 回滚或热修复 +├── 非核心功能异常？ +│ └── 评估修复时间 +│ ├── < 30 分钟 → 热修复 +│ └── > 30 分钟 → 回滚 +└── 性能下降？ + ├── 严重（>5x） → 回滚 + └── 轻微（<2x） → 监控 + 排期修复 +``` + +## 回滚类型 + +### 1. Docker 镜像回滚（最常用） + +```bash +# 查看历史镜像 +docker images | grep ai-proj + +# 回滚到上一版本 +cd deploy +# 修改 docker-compose.prod.yml 中的镜像 tag +docker compose -f docker-compose.prod.yml up -d + +# 验证 +curl -s http://localhost:8080/health | jq . +``` + +### 2. 数据库回滚 + +```bash +# 执行 down migration +cd backend +migrate -path migrations -database "$DB_URL" down 1 + +# 验证表结构 +psql -U user -d db -c "\d affected_table" +``` + +**注意**：数据库回滚可能导致数据丢失，必须先评估影响。 + +### 3. 配置回滚 + +```bash +# 恢复旧配置 +git checkout HEAD~1 -- deploy/config/ +docker compose -f docker-compose.prod.yml restart +``` + +## 回滚检查清单 + +- [ ] 确认问题现象和影响范围 +- [ ] 通知相关人员（用户需知道在维护中） +- [ ] 执行回滚操作 +- [ ] 验证服务恢复正常 +- [ ] 验证数据完整性 +- [ ] 记录回滚原因和过程 +- [ ] 创建修复任务 + +## 回滚记录模板 + +```markdown +## 回滚记录 + +**时间**: YYYY-MM-DD HH:mm +**触发原因**: [问题描述] +**影响范围**: [受影响的功能/用户] +**回滚类型**: Docker 镜像 / 数据库 / 配置 +**回滚操作**: [具体步骤] +**恢复确认**: [验证结果] +**根因分析**: [问题根因] +**修复计划**: [后续修复方案] +``` + +## 预防措施 + +- 部署前确保 Migration 有 down.sql +- 部署前确保 Docker 保留上一版本镜像 +- 大变更使用灰度发布 +- 监控关键指标（错误率、延迟、CPU/内存） diff --git a/skills-dev/dev-android-plugin/.claude-plugin/plugin.json b/skills-dev/dev-android-plugin/.claude-plugin/plugin.json new file mode 100644 index 0000000..863e3ef --- /dev/null +++ b/skills-dev/dev-android-plugin/.claude-plugin/plugin.json @@ -0,0 +1 @@ +{"name":"dev-android-plugin","description":"Android 开发插件。Kotlin + Jetpack Compose + Hilt 依赖注入。按需加载。","version":"1.0.0","author":{"name":"qiudl"}} diff --git a/skills-dev/dev-android-plugin/skills/SKILL.md b/skills-dev/dev-android-plugin/skills/SKILL.md new file mode 100644 index 0000000..ff76626 --- /dev/null +++ b/skills-dev/dev-android-plugin/skills/SKILL.md @@ -0,0 +1,54 @@ +--- +name: dev-android +description: Android 开发插件。Kotlin + Jetpack Compose + Hilt 依赖注入。当涉及 Android 开发任务时按需加载。 +--- + +# Android 开发插件 (dev-android) + +## 架构：MVVM + Hilt + +``` +android-app/app/src/main/ +├── java/com/project/ +│ ├── ui/ # Compose 屏幕 + 组件 +│ ├── data/ # API + Repository + 本地存储 +│ ├── domain/ # 业务逻辑 +│ └── di/ # Hilt 依赖注入 +└── res/ # 资源文件 +``` + +## 代码规范 + +```kotlin +@HiltViewModel +class TaskViewModel @Inject constructor( + private val taskRepository: TaskRepository +) : ViewModel() { + + private val _tasks = MutableStateFlow>(emptyList()) + val tasks: StateFlow> = _tasks.asStateFlow() + + fun fetchTasks() { + viewModelScope.launch { + taskRepository.getTasks() + .collect { _tasks.value = it } + } + } +} + +@Composable +fun TaskListScreen(viewModel: TaskViewModel = hiltViewModel()) { + val tasks by viewModel.tasks.collectAsState() + LazyColumn { + items(tasks) { task -> TaskItem(task = task) } + } +} +``` + +## 构建 + +```bash +./gradlew assembleDebug # Debug 构建 +./gradlew assembleRelease # Release 构建 +./gradlew test # 测试 +``` diff --git a/skills-dev/dev-coding-plugin/.claude-plugin/plugin.json b/skills-dev/dev-coding-plugin/.claude-plugin/plugin.json index e5688b2..7be72cb 100644 --- a/skills-dev/dev-coding-plugin/.claude-plugin/plugin.json +++ b/skills-dev/dev-coding-plugin/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "dev-coding-plugin", - "description": "Plugin for dev-coding", - "version": "1.0.0", + "description": "软件编码开发技能。Go 后端 + Vue/React 前端编码实现，集成 ai-proj 任务管理。", + "version": "2.0.0", "author": { "name": "qiudl" } diff --git a/skills-dev/dev-coding-plugin/skills/SKILL.md b/skills-dev/dev-coding-plugin/skills/SKILL.md index c8f5d54..8160fce 100644 --- a/skills-dev/dev-coding-plugin/skills/SKILL.md +++ b/skills-dev/dev-coding-plugin/skills/SKILL.md @@ -1,43 +1,24 @@ --- name: dev-coding -description: 软件编码开发技能。用于代码编写、功能实现、代码审查、重构优化。集成 ai-proj CLI 进行任务管理和进度跟踪。支持 Go、Vue、React、iOS、Android、小程序等全栈开发。 +description: 软件编码开发技能。用于代码编写、功能实现、重构优化。集成 ai-proj CLI 进行任务管理和进度跟踪。核心支持 Go 后端 + Vue/React 前端开发。 --- # 软件编码开发 Skill (dev-coding) -## ⚠️ REQ 任务自动工作流 - -**当收到 REQ 任务（包含 REQ-YYYYMMDD-XXXX）需要开发时，必须严格按以下顺序执行：** - -1. **读取 ticket** — 从 ai-proj 获取需求详情和关联文档 - ``` - mcp__ai-proj-dev__get_detailed_task_info (通过 REQ 号查找) - mcp__ai-proj-dev__get_task_document (如果有 PRD 文档) - ``` - -2. **进入 Plan Mode** — 调用 `EnterPlanMode` 工具 - - 分析需求，探索代码库，设计实现方案 - - 输出实现计划（涉及的文件、改动范围、测试策略） - - 等待用户审批后再开始编码 - -3. **执行计划** — 用户批准后按计划编码 + 写测试 - -**禁止跳过 plan mode 直接编码。** - ---- - ## 概述 -本技能用于软件编码开发工作，支持多种项目类型： +本技能用于软件编码实现，核心覆盖： - Go 后端 (Gin + GORM) - Vue 3 / React 前端 -- iOS (Swift/SwiftUI) -- Android (Kotlin/Jetpack Compose) -- PDA 应用 -- MCP 桥接服务 -- 微服务架构 -核心集成 **ai-proj CLI** 进行任务管理。 +集成 **ai-proj CLI** 进行任务管理。 + +**不包含**（由其他技能/插件负责）： +- 开发设计（API 契约、任务拆分）→ `req-design` +- 代码评审 → `dev-review`（批次2） +- iOS 开发 → `dev-ios`（插件） +- Android 开发 → `dev-android`（插件） +- MCP 开发 → `dev-mcp`（插件） --- @@ -84,11 +65,11 @@ ai-proj task append-doc --id --content "实现说明" ### 当前项目生态 -| 项目 | 类型 | 后端 | 前端 | 移动端 | -|------|------|------|------|--------| -| TWMS | 仓储物流 | Go+Gin+MySQL | Vue 3 | - | -| AI-Proj | 项目管理 | Go+Gin+PostgreSQL | React 18 | iOS+Android | -| DICIAI | 进销存SaaS | Go+Gin+MySQL | Vue 3 | Android PDA | +| 项目 | 类型 | 后端 | 前端 | +|------|------|------|------| +| TWMS | 仓储物流 | Go+Gin+MySQL | Vue 3 | +| AI-Proj | 项目管理 | Go+Gin+PostgreSQL | React 18 | +| DICIAI | 进销存SaaS | Go+Gin+MySQL | Vue 3 | --- @@ -349,309 +330,6 @@ npm run test:e2e --- -## iOS 开发 (Swift/SwiftUI) - -### 项目结构 - -``` -AI-Proj-iOS/ -├── Core/ # 核心服务 -│ ├── Network/ # 网络层 -│ ├── Storage/ # 本地存储 -│ └── Auth/ # 认证 -├── Features/ # 功能模块 -│ ├── Dashboard/ -│ ├── Tasks/ -│ └── Settings/ -├── Models/ # 数据模型 -└── UI/ # UI 组件 -``` - -### 代码规范 - -```swift -// MVVM 架构 -class TaskViewModel: ObservableObject { - @Published var tasks: [Task] = [] - @Published var isLoading = false - - private let taskService: TaskServiceProtocol - - init(taskService: TaskServiceProtocol = TaskService()) { - self.taskService = taskService - } - - func fetchTasks() async { - isLoading = true - defer { isLoading = false } - - do { - tasks = try await taskService.getTasks() - } catch { - // 错误处理 - } - } -} - -// SwiftUI 视图 -struct TaskListView: View { - @StateObject private var viewModel = TaskViewModel() - - var body: some View { - List(viewModel.tasks) { task in - TaskRow(task: task) - } - .task { - await viewModel.fetchTasks() - } - } -} -``` - -### 构建命令 - -```bash -# Xcode 构建 -xcodebuild -scheme AI-Proj-iOS -configuration Debug - -# 测试 -xcodebuild test -scheme AI-Proj-iOS -``` - -### 常见问题排查 - -#### SwiftLint 沙盒错误 - -**问题描述**： -构建时出现错误： -``` -Sandbox: swiftlint(xxxx) deny(1) file-read-data /path/to/.swiftlint.yml -``` - -**原因**： -Xcode 15+ 默认启用 User Script Sandboxing，限制脚本访问文件系统。 - -**解决方案**： - -方案 1 - 修改项目配置（推荐）： -1. 打开 Xcode → 选择项目 → Build Settings -2. 搜索 "User Script Sandboxing" -3. 将 `ENABLE_USER_SCRIPT_SANDBOXING` 设置为 `NO` - -方案 2 - 命令行构建时禁用： -```bash -xcodebuild -scheme AI-Proj-iOS -configuration Debug \ - ENABLE_USER_SCRIPT_SANDBOXING=NO -``` - -方案 3 - 直接修改 project.pbxproj： -```bash -sed -i '' 's/ENABLE_USER_SCRIPT_SANDBOXING = YES/ENABLE_USER_SCRIPT_SANDBOXING = NO/g' \ - AI-Proj-iOS.xcodeproj/project.pbxproj -``` - -#### Personal Development Team 功能限制 - -**问题描述**： -使用免费 Personal Team 签名时报错： -``` -Cannot create iOS App Development provisioning profile... -Personal development teams do not support the Associated Domains, -Push Notifications and App Groups capabilities. -``` - -**原因**： -Personal Team（免费账户）不支持以下 Entitlements： -- Associated Domains (`com.apple.developer.associated-domains`) -- Push Notifications (`aps-environment`) -- App Groups (`com.apple.security.application-groups`) - -**解决方案**： - -1. 从 Entitlements 文件中移除不支持的功能： - -```xml - - - - - - - keychain-access-groups - - $(AppIdentifierPrefix)com.yourcompany.app - - - -``` - -2. Personal Team 支持的功能： - - Keychain Access Groups ✓ - - In-App Purchase ✓ - - Game Center ✓ - -3. 需要付费 Apple Developer Program 的功能： - - Push Notifications ✗ - - Associated Domains ✗ - - App Groups ✗ - - CloudKit ✗ - - Sign in with Apple ✗ - ---- - -## Android 开发 (Kotlin) - -### 项目结构 - -``` -android-app/app/src/main/ -├── java/com/project/ -│ ├── ui/ # UI 层 -│ │ ├── screens/ # Compose 屏幕 -│ │ └── components/ # 可复用组件 -│ ├── data/ # 数据层 -│ │ ├── api/ # 网络接口 -│ │ ├── repository/ # 仓库模式 -│ │ └── local/ # 本地存储 -│ ├── domain/ # 业务逻辑 -│ └── di/ # 依赖注入 -└── res/ # 资源文件 -``` - -### 代码规范 - -```kotlin -// Hilt 依赖注入 -@HiltViewModel -class TaskViewModel @Inject constructor( - private val taskRepository: TaskRepository -) : ViewModel() { - - private val _tasks = MutableStateFlow>(emptyList()) - val tasks: StateFlow> = _tasks.asStateFlow() - - fun fetchTasks() { - viewModelScope.launch { - taskRepository.getTasks() - .collect { _tasks.value = it } - } - } -} - -// Jetpack Compose -@Composable -fun TaskListScreen( - viewModel: TaskViewModel = hiltViewModel() -) { - val tasks by viewModel.tasks.collectAsState() - - LazyColumn { - items(tasks) { task -> - TaskItem(task = task) - } - } -} -``` - -### 构建命令 - -```bash -# 构建 Debug -./gradlew assembleDebug - -# 构建 Release -./gradlew assembleRelease - -# 测试 -./gradlew test -``` - ---- - -## PDA 应用开发 - -### 特点 - -- Android 原生开发 -- 扫码枪集成 -- 离线优先 -- 简洁 UI - -### 常见功能 - -```kotlin -// 扫码处理 -class ScanReceiver : BroadcastReceiver() { - override fun onReceive(context: Context, intent: Intent) { - val barcode = intent.getStringExtra("SCAN_BARCODE") - // 处理扫码结果 - } -} - -// 离线存储 -@Entity(tableName = "inventory") -data class Inventory( - @PrimaryKey val id: Long, - val barcode: String, - val quantity: Int, - @ColumnInfo(name = "sync_status") - val syncStatus: SyncStatus = SyncStatus.PENDING -) -``` - ---- - -## MCP 桥接开发 - -### 项目结构 - -``` -mcp-task-bridge/ -├── index.ts # 入口 -├── task-service.ts # 任务服务 -├── document-service.ts # 文档服务 -├── base-client.ts # HTTP 基类 -├── types.ts # 类型定义 -└── token-storage.ts # Token 管理 -``` - -### 代码规范 - -```typescript -// 服务类模式 -export class TaskService extends BaseClient { - async createTask( - title: string, - projectId: number = 1, - options: CreateTaskOptions = {} - ): Promise> { - try { - const response = await this.makeRequest( - 'POST', - `/projects/${projectId}/tasks`, - { title, project_id: projectId, ...options } - ); - - if (response.success) { - return { - success: true, - data: response.data, - message: `✅ 任务 "${title}" 创建成功` - }; - } - return response; - } catch (error: any) { - return { - success: false, - error: `创建任务失败: ${error.message}` - }; - } - } -} -``` - ---- - ## 通用开发规范 ### API 响应格式 @@ -695,13 +373,6 @@ try { } catch (error) { message.error(error.message); } - -// Swift -do { - let result = try await service.fetch() -} catch { - // 处理错误 -} ``` --- @@ -811,6 +482,11 @@ fi ## 相关技能 -| 技能 | 用途 | 关系 | -|------|------|------| -| `req-test-gate` | 测试与质量门禁 + Harness Engineering | 建立项目质量门禁和约定自动检测，dev-coding 遵守其建立的 CLAUDE.md 约定 | +| 技能 | 用途 | +|------|------| +| `req-design` | 开发设计（API 契约、任务拆分）— dev-coding 的输入 | +| `dev-test` | 测试与质量门禁 | +| `dev-review` | 代码评审（五视角扫描）| +| `dev-ios` | iOS 开发（插件，按需加载）| +| `dev-android` | Android 开发（插件，按需加载）| +| `dev-mcp` | MCP bridge 开发（插件，按需加载）| diff --git a/skills-dev/dev-integration-plugin/.claude-plugin/plugin.json b/skills-dev/dev-integration-plugin/.claude-plugin/plugin.json new file mode 100644 index 0000000..c491d86 --- /dev/null +++ b/skills-dev/dev-integration-plugin/.claude-plugin/plugin.json @@ -0,0 +1,8 @@ +{ + "name": "dev-integration-plugin", + "description": "前后端联调技能。API 契约验证、联调报告、纯后端需求自动跳过。对应 req 流程 integration 阶段。", + "version": "1.0.0", + "author": { + "name": "qiudl" + } +} diff --git a/skills-dev/dev-integration-plugin/skills/SKILL.md b/skills-dev/dev-integration-plugin/skills/SKILL.md new file mode 100644 index 0000000..651fa15 --- /dev/null +++ b/skills-dev/dev-integration-plugin/skills/SKILL.md @@ -0,0 +1,154 @@ +--- +name: dev-integration +description: 前后端联调技能。API 契约验证、接口对接、联调报告生成。对应 req 流程 integration 阶段。纯后端需求自动跳过。 +--- + +# 前后端联调 Skill (dev-integration) + +## 概述 + +本技能用于前后端联调阶段，确保实际实现与 API 契约一致。 + +**核心价值**：发现契约偏差（字段名不一致、类型不匹配、缺少错误码处理）比测试阶段更早、修复成本更低。 + +--- + +## 技能间契约 + +| 上游 | 本技能输入 | 本技能输出 | 下游 | +|------|-----------|-----------|------| +| dev-coding | 已实现的前后端代码 + API 契约（来自 req-design） | 联调报告（通过/不通过 + 问题列表） | dev-test | + +--- + +## 自动跳过条件 + +以下情况 integration 阶段**自动通过**，无需执行联调： + +| 条件 | 原因 | +|------|------| +| 需求只有后端 implementation 任务（无前端任务） | 没有前端对接，无需联调 | +| 需求只有前端 implementation 任务（无后端任务） | 使用已有 API，无需联调 | +| 需求无 implementation 任务（纯 skill/ops/doc） | 非代码需求 | + +**检测方法**： +``` +get_requirement_tasks → 检查 linkRole=implementation 的任务标题 +含【开发-后端】和【开发-前端】→ 需要联调 +仅含一端 → 自动跳过 +``` + +--- + +## 工作流程 + +``` +1. 检查是否需要联调 + ├── 获取 implementation 任务列表 + ├── 判断是否有前后端双端任务 + └── 仅单端 → 自动跳过，生成跳过说明 + +2. 获取 API 契约 + ├── 从 req-design 文档中提取 API 契约 + └── 无契约 → 从代码反推接口定义 + +3. 契约验证 + ├── 后端实际接口 vs 契约定义 + │ ├── URL 路径是否一致 + │ ├── 请求/响应字段名是否一致 + │ ├── 字段类型是否匹配 + │ └── 错误码是否完整 + ├── 前端调用 vs 契约定义 + │ ├── API service 调用路径是否正确 + │ ├── 请求参数是否完整 + │ └── 响应处理是否覆盖所有错误码 + └── 前端 ↔ 后端一致性 + ├── 字段命名一致（camelCase vs snake_case 转换） + └── 分页参数格式一致 + +4. 功能对接验证 + ├── 前端表单字段 vs 后端 binding 规则 + ├── 前端列表列 vs 后端响应字段 + └── 前端状态流转 vs 后端状态机 + +5. 生成联调报告 + ├── 契约一致性结果 + ├── 发现的偏差列表 + └── 结论：通过/不通过 +``` + +--- + +## 联调报告模板 + +```markdown +## 联调报告 — {需求标题} + +**日期**: YYYY-MM-DD +**API 契约来源**: {req-design 文档 / 代码反推} + +### 契约验证结果 + +| # | 接口 | 契约 | 后端实际 | 前端调用 | 结果 | +|---|------|------|---------|---------|------| +| 1 | POST /api/v1/xxx | ✅ 已定义 | ✅ 一致 | ✅ 一致 | PASS | +| 2 | GET /api/v1/xxx | ✅ 已定义 | ⚠️ 字段名不一致 | ✅ 一致 | FAIL | + +### 发现的偏差 + +| # | 类型 | 接口 | 描述 | 影响 | 建议 | +|---|------|------|------|------|------| +| 1 | 字段名不一致 | GET /api/v1/xxx | 契约定义 `created_at`，后端返回 `createTime` | 前端解析失败 | 统一为 `created_at` | + +### 结论 + +**{通过 / 不通过}** + +{如不通过，列出必须修复的偏差编号} +``` + +--- + +## 插件支持 + +| 插件 | 触发条件 | 说明 | +|------|---------|------| +| `api-contract-verify` | 有 API 变更 | 自动化契约验证（未来） | + +--- + +## 与 ai-proj 集成 + +### req 流程内 + +```typescript +// 创建联调任务（如需要） +mcp__ai-proj__create_task({ title: "【联调】前后端对接: {需求标题}" }) +mcp__ai-proj__link_tasks_to_requirement({ + requirementId, taskIds: [taskId], linkRole: "implementation" +}) + +// 附加联调报告 +mcp__ai-proj__create-and-attach({ + taskId, title: "联调报告", content: "<报告内容>" +}) +``` + +### 自动跳过时 + +```typescript +// 记录跳过原因 +mcp__ai-proj__create-and-attach({ + taskId: <设计任务ID>, + content: "## 联调阶段\n\n自动跳过：仅后端变更，无前端对接。" +}) +``` + +--- + +## 最佳实践 + +1. **契约先行** — API 契约是联调的基准，没有契约就先补 +2. **字段级验证** — 不只检查接口是否通，要检查每个字段名、类型、格式 +3. **错误码覆盖** — 前端必须处理契约中定义的所有错误码 +4. **snake_case 转换** — Go 后端用 snake_case，前端用 camelCase，确认自动转换正确 diff --git a/skills-dev/dev-ios-plugin/.claude-plugin/plugin.json b/skills-dev/dev-ios-plugin/.claude-plugin/plugin.json new file mode 100644 index 0000000..62337ee --- /dev/null +++ b/skills-dev/dev-ios-plugin/.claude-plugin/plugin.json @@ -0,0 +1 @@ +{"name":"dev-ios-plugin","description":"iOS 开发插件。Swift/SwiftUI + MVVM 架构、TestFlight 部署、Xcode 构建。按需加载。","version":"1.0.0","author":{"name":"qiudl"}} diff --git a/skills-dev/dev-ios-plugin/skills/SKILL.md b/skills-dev/dev-ios-plugin/skills/SKILL.md new file mode 100644 index 0000000..f5cd58a --- /dev/null +++ b/skills-dev/dev-ios-plugin/skills/SKILL.md @@ -0,0 +1,90 @@ +--- +name: dev-ios +description: iOS 开发插件。Swift/SwiftUI + MVVM 架构，TestFlight 部署。当涉及 iOS 开发任务时按需加载。 +--- + +# iOS 开发插件 (dev-ios) + +## 架构：SwiftUI + MVVM + +``` +AI-Proj-iOS/ +├── Core/ # 核心层 +│ ├── Architecture/ # AppCoordinator, AppState +│ ├── Components/ # 通用 UI 组件 +│ ├── Config.swift # 配置 +│ ├── Services/ # APIEndpoints, AuthService, NetworkService, DIContainer +│ ├── Theme/ # 主题配置 +│ └── Utilities/ # 设备适配 +├── Features/ # 功能模块（MVVM） +│ └── Requirements/ # 示例：List/Detail View + ViewModel +├── Models/ # 数据模型 + DTOs +└── Resources/ # Assets +``` + +**开发顺序**：Model → DTO → APIEndpoints → ServiceProtocols → ViewModel → View + +## 代码规范 + +```swift +@MainActor +class TaskViewModel: ObservableObject { + @Published private(set) var tasks: [Task] = [] + @Published private(set) var isLoading = false + @Published var error: String? + + private let taskService: TaskServiceProtocol + + init(taskService: TaskServiceProtocol) { + self.taskService = taskService + } + + func loadTasks() async { + guard !isLoading else { return } + isLoading = true + defer { isLoading = false } + + do { + tasks = try await taskService.fetchTasks() + } catch { + self.error = error.localizedDescription + } + } +} +``` + +**规则**： +- ViewModel 使用 `@MainActor` +- Published 属性用 `private(set)` +- 使用协议依赖注入 +- `async/await` 而非 completion handler +- `guard` 提前返回，`defer` 确保状态重置 + +## 命名规范 + +| 类型 | 规范 | 示例 | +|------|------|------| +| 文件/类 | 大驼峰 | `ManualListView.swift` | +| 协议 | 大驼峰 + Protocol | `ManualServiceProtocol` | +| 函数/变量 | 小驼峰 | `loadManuals()`, `isLoading` | +| 枚举 case | 小驼峰 | `case draft` | + +## 构建与部署 + +```bash +# 构建 +xcodebuild -scheme AI-Proj-iOS -configuration Debug + +# 测试 +xcodebuild test -scheme AI-Proj-iOS + +# TestFlight 部署详见 memory: testflight-deploy.md +``` + +## 常见问题 + +### SwiftLint 沙盒错误 +Xcode 15+ 默认启用 User Script Sandboxing → Build Settings → `ENABLE_USER_SCRIPT_SANDBOXING = NO` + +### Personal Team 功能限制 +免费账户不支持 Push Notifications / Associated Domains / App Groups → 从 Entitlements 中移除 diff --git a/skills-dev/dev-mcp-plugin/.claude-plugin/plugin.json b/skills-dev/dev-mcp-plugin/.claude-plugin/plugin.json new file mode 100644 index 0000000..1a19af3 --- /dev/null +++ b/skills-dev/dev-mcp-plugin/.claude-plugin/plugin.json @@ -0,0 +1 @@ +{"name":"dev-mcp-plugin","description":"MCP Bridge 开发插件。TypeScript MCP 服务开发、Token 管理、HTTP 客户端模式。按需加载。","version":"1.0.0","author":{"name":"qiudl"}} diff --git a/skills-dev/dev-mcp-plugin/skills/SKILL.md b/skills-dev/dev-mcp-plugin/skills/SKILL.md new file mode 100644 index 0000000..63b3232 --- /dev/null +++ b/skills-dev/dev-mcp-plugin/skills/SKILL.md @@ -0,0 +1,59 @@ +--- +name: dev-mcp +description: MCP Bridge 开发插件。TypeScript MCP 服务开发，Token 管理，HTTP 客户端模式。当涉及 mcp-task-bridge 开发时按需加载。 +--- + +# MCP Bridge 开发插件 (dev-mcp) + +## 项目结构 + +``` +mcp-task-bridge/ +├── index.ts # 入口，MCP server 注册 +├── task-service.ts # 任务服务 +├── document-service.ts # 文档服务 +├── requirement-service.ts # 需求服务 +├── base-client.ts # HTTP 基类（认证、重试） +├── types.ts # 类型定义 +└── token-storage.ts # Token 持久化 +``` + +## 代码规范 + +```typescript +export class TaskService extends BaseClient { + async createTask( + title: string, + projectId: number = 1, + options: CreateTaskOptions = {} + ): Promise> { + try { + const response = await this.makeRequest( + 'POST', + `/projects/${projectId}/tasks`, + { title, project_id: projectId, ...options } + ); + return response.success + ? { success: true, data: response.data, message: `✅ 任务创建成功` } + : response; + } catch (error: any) { + return { success: false, error: `创建任务失败: ${error.message}` }; + } + } +} +``` + +## 关键规则 + +1. **MCP endpoint 前缀**：所有 MCP 专用后端接口必须包含 `/mcp/` 前缀 +2. **修改后重新构建**：`npm run build` → `pkill -f "mcp-task-bridge/dist/index.js"` +3. **环境一致性**：不要跨环境混用数据（dev/staging/prod） + +## 常用命令 + +```bash +npm run dev # 开发（hot reload） +npm run build # 编译 TypeScript +npm test # 快速测试 +npm run test:integration # 集成测试 +``` diff --git a/skills-dev/dev-pda-plugin/.claude-plugin/plugin.json b/skills-dev/dev-pda-plugin/.claude-plugin/plugin.json new file mode 100644 index 0000000..2f8daad --- /dev/null +++ b/skills-dev/dev-pda-plugin/.claude-plugin/plugin.json @@ -0,0 +1 @@ +{"name":"dev-pda-plugin","description":"PDA 应用开发插件。Android 原生 + 扫码枪集成 + 离线优先模式。按需加载。","version":"1.0.0","author":{"name":"qiudl"}} diff --git a/skills-dev/dev-pda-plugin/skills/SKILL.md b/skills-dev/dev-pda-plugin/skills/SKILL.md new file mode 100644 index 0000000..3831969 --- /dev/null +++ b/skills-dev/dev-pda-plugin/skills/SKILL.md @@ -0,0 +1,49 @@ +--- +name: dev-pda +description: PDA 应用开发插件。Android 原生 + 扫码枪集成 + 离线优先。当涉及 PDA/手持终端开发时按需加载。 +--- + +# PDA 应用开发插件 (dev-pda) + +## 特点 + +- Android 原生开发（Kotlin） +- 扫码枪硬件集成 +- 离线优先（本地 Room DB + 同步队列） +- 简洁 UI（大按钮、大字体、适配小屏幕） + +## 扫码集成 + +```kotlin +class ScanReceiver : BroadcastReceiver() { + override fun onReceive(context: Context, intent: Intent) { + val barcode = intent.getStringExtra("SCAN_BARCODE") + // 处理扫码结果 + } +} +``` + +## 离线存储 + +```kotlin +@Entity(tableName = "inventory") +data class Inventory( + @PrimaryKey val id: Long, + val barcode: String, + val quantity: Int, + @ColumnInfo(name = "sync_status") + val syncStatus: SyncStatus = SyncStatus.PENDING +) + +enum class SyncStatus { PENDING, SYNCED, FAILED } +``` + +## 离线同步策略 + +``` +操作 → 写入本地 DB (PENDING) + ↓ +网络可用 → 批量上传 → 成功 → 标记 SYNCED + ↓ 失败 + 标记 FAILED → 下次重试 +``` diff --git a/skills-dev/dev-review-plugin/.claude-plugin/plugin.json b/skills-dev/dev-review-plugin/.claude-plugin/plugin.json new file mode 100644 index 0000000..584b9bb --- /dev/null +++ b/skills-dev/dev-review-plugin/.claude-plugin/plugin.json @@ -0,0 +1,8 @@ +{ + "name": "dev-review-plugin", + "description": "代码评审技能。五视角对抗性扫描法（攻击者/泄露者/并发者/边界者/依赖者），CR 报告生成，独立于 req 工作流可单独使用。", + "version": "1.0.0", + "author": { + "name": "qiudl" + } +} diff --git a/skills-dev/dev-review-plugin/skills/SKILL.md b/skills-dev/dev-review-plugin/skills/SKILL.md new file mode 100644 index 0000000..35dbd5d --- /dev/null +++ b/skills-dev/dev-review-plugin/skills/SKILL.md @@ -0,0 +1,280 @@ +--- +name: dev-review +description: 代码评审技能。五视角对抗性扫描法，用于 PR 代码审查、安全评审、质量检查。当执行 /req cr 或独立 PR review 时自动激活。 +--- + +# 代码评审 Skill (dev-review) + +## 概述 + +独立的代码评审技能，核心方法论是**五视角对抗性扫描法**。 + +**适用场景**： +- `/req cr [REQ-ID]` — 需求流程中的代码评审阶段 +- 独立 PR review — 不绑定需求的代码审查 +- 安全评审 — 专项安全扫描 + +**核心原则**：实现阶段关注"怎么让它跑通"，评审阶段关注**"怎么让它出错"**。AI 必须切换到对抗性思维。 + +--- + +## 技能间契约 + +| 上游 | 本技能输入 | 本技能输出 | 下游 | +|------|-----------|-----------|------| +| dev-coding | PR diff + 开发设计文档 | CR 报告（五视角扫描 + 发现汇总 + 结论） | dev-test | + +--- + +## 工作流程 + +``` +1. 确定评审范围 + ├── git diff 获取变更文件列表 + ├── 统计文件数、行数 + └── 排除 test 文件（单独审查） + +2. 读取变更代码 + ├── 逐个读取变更���件源码 + ├── 理解业务上下文 + └── 参考开发设计文档（如有） + +3. 五视角扫描（核心） + ├── 攻击���视角 + ├── 泄露者视角 + ├── 并发者视角 + ├── 边界者视角 + └── 依赖者视角 + +4. 加载项目检查清单（如有） + └── review-checklist 插件 + +5. 生成 CR 报告 + ├── 变更概要 + ├── 五视角扫描结果 + ├── 发现汇总表 + └── 结论（通过/有条件通过/需修改） + +6. 创建评审任务（req 流程内） + ├── ai-proj task create【代码评审】 + ├── 关联需求（linkRole=code_review） + └── 附加 CR 报告文档 + +7. 处理发现 + ├── Critical/High → 创建修复任务 + └── Medium/Low → 记录建议 +``` + +--- + +## 五视角对抗性扫描法 + +### 总览 + +| 视角 | 思维模式 | 核心问题 | +|------|---------|---------| +| **1. 攻击者** | "我怎么绕过/���用它？" | 跨租户泄露、越权访问、参数注入、重放攻击 | +| **2. 泄露者** | "它暴露了什么不该暴露的？" | 错误信息泄露、日志敏感数据、响应内部细节 | +| **3. 并发者** | "两个请求同时来会怎样？" | 竞态条件、双重扣款、幂等性缺失、锁粒度 | +| **4. 边界者** | "极端输入会怎样？" | 空值/零值/负值/超长字符串、类型溢出、分页越界 | +| **5. 依赖者** | "外部服务挂了会怎样？" | 超时处理、重试策略、降级方案、连接泄露 | + +### 视角1：攻击者（多租户安全） + +**思维模式**：我是恶意用户，如何绕过权限获取他人数据。 + +扫描清单： +- [ ] 所有 Store/Repository 层查询是否带 `tenant_id` 过滤？ +- [ ] 通过 ID 直接查询的方法是否校验归属？ +- [ ] 用户只能操作自己的数据？（consumer_id 校验） +- [ ] URL/请求参数是否有注入风险？（SQL、URL、命令注入） +- [ ] 外部输入是否直接拼接到查询/URL？（应使用参数化查询或编码） +- [ ] 批量操作是否逐条校验权限？（不能只校验第一条） +- [ ] 文件上传是否有类型/大小限制？ + +**典型发现示例**： +``` +file:line — Store.GetByID(id) 缺少 tenant_id 过滤， +攻击者可通过遍�� ID 获取其他租户数据。 +建议：添加 WHERE tenant_id = ? 条件。 +``` + +### 视角2：泄露者（信息安全） + +**思维模式**：我是安全审计员，检查每个出口是否泄露了不该泄露的信息。 + +扫描清单： +- [ ] 错误消息是否泄露业务状态？（如"手机号未注册"暴露用户存在性） +- [ ] 日志是否打印了密码、token、密钥、身份证号？ +- [ ] 响应是否包含不必要的内部字段？（如内部 ID、数据库字段名、堆栈跟踪） +- [ ] panic recover 后是否返回了内部错误详情？ +- [ ] 导出/下载功能是否过滤了敏感字段？ + +### 视角3：并发者（数据一致性） + +**思维模式**：两个用户同时操作同一条数据，会发生什么。 + +扫描清单： +- [ ] 涉及金额/库存变更是否使用事务 + 悲观锁/乐观锁？ +- [ ] 关键操作是否有幂等保护？（bizNo 唯一索引、幂等键） +- [ ] 全局状态（如进程内计数器、缓存）重启后是否安全？ +- [ ] 是否有 TOCTOU（检查-使用）竞态？（先查状态再操作，中间被修改） +- [ ] 并发创建是否会产生重复数据？（唯一约束） + +### 视角4：边界者（健壮性） + +**思维模��**：用最极端的输入来测试系统的承受能力。 + +扫描清单： +- [ ] 必填参数是否有 `binding:"required"` 校验？ +- [ ] 数值参数是否有范围校验？（min/max，防止负数、溢出） +- [ ] 字符串是否有长度限制？（防止超长输入消耗内存） +- [ ] 分页参数是否有默认值和上限？（page_size 不能为 0 或 999999） +- [ ] 数组参数是否有长度限制？（批量操作不能传 10 万条） +- [ ] 空数组/空字符串是否正确处理？（不应触发不必要的数据库操作） +- [ ] 除零错误？百分比计算分母为 0？ + +### 视角5：依赖者（可靠性） + +**思维模式**：外部服务全部挂掉，系统还能正常运行吗。 + +扫描清单： +- [ ] HTTP 客户端是否设置超时？（connect/read/write timeout） +- [ ] 外部 API 调用失败是否有合理的错误处理？（不能直接 panic） +- [ ] 是否有重试策略？重试是否有退避？是否幂等安全？ +- [ ] 数据库连接池配置是否合理？（max idle/max open/lifetime） +- [ ] Redis 不可用时是否有降级方案？（缓存穿透到数据库） +- [ ] token 过期/刷新逻辑是否正确？（access vs refresh 不同策略） + +--- + +## CR 报告模板 + +```markdown +## 代��评审报告 — {需求标题/PR 标题} + +**日期**: YYYY-MM-DD +**评审范围**: {N} 个文件, {M} 行变更 +**评审人**: AI (dev-review) + +### 变更概要 +{1-3 句描述本次变更的目的和范围} + +### 五视角扫描结果 + +#### 1. 攻击者视角 +{扫描发现，或 "未发现问题"} + +#### 2. 泄露者视角 +{扫描发现，或 "未发现问题"} + +#### 3. 并发者视角 +{扫描发现，或 "未发现问题"} + +#### 4. 边界者视角 +{扫描发现，或 "未发现问题"} + +#### 5. 依赖者视角 +{扫描发现，或 "未发现问题"} + +### 审查发现汇总 + +| # | 严重度 | 文件:行号 | ���角 | 描述 | 建议 | +|---|--------|----------|------|------|------| +| 1 | {Critical/High/Medium/Low} | {file:line} | {视角} | {问题} | {建议} | + +### 统计 + +| 严重度 | 数量 | +|--------|------| +| Critical | 0 | +| High | 0 | +| Medium | 0 | +| Low | 0 | + +### 结论 + +**{通过 / 有条件通过 / 需修改}** + +{结论说明：如果有 Critical/High 必须修复后重新评审} +``` + +--- + +## 严重度定义 + +| 严重度 | 含义 | 处理方式 | +|--------|------|---------| +| **Critical** | 安全漏洞、数据泄露、资金风险 | 必须修复，阻断合并 | +| **High** | 数据一致性风险、业务逻辑错误 | 必须修复，阻断合并 | +| **Medium** | 边界未处理、缺少校验、性能隐患 | 建议修复，不阻断 | +| **Low** | 代码风格、命名优化、文档补充 | 可选修复 | + +--- + +## CR 报告质量门禁 + +`/req next` 从 review 阶段推进时，检查 CR 报告质量： + +| 检查项 | 标准 | +|--------|------| +| 文档存在 | CR 任务有附加文档 | +| 字数 | ≥ 500 字 | +| 代码引用 | 含 `file:line` 格式的引用 | +| 五视角扫描 | 含全部 5 个视角章节 | +| 结论章节 | 含明确的通过/不通过结论 | + +--- + +## 插件支持 + +| 插件 | 触发条件 | 说明 | +|------|---------|------| +| `review-checklist` | 每次 CR | 加载项目特定检查清单 | +| `figma-design-qa` | 有设计稿 | 设计还原度对比 | + +--- + +## 与 ai-proj 集成 + +### req 流程内（/req cr） + +```typescript +// 1. 确认 implementation 任务已完成 +mcp__ai-proj__get_requirement_tasks({ requirementId }) +// 检查所有 linkRole=implementation 的任务状态 + +// 2. 创建 CR 任务 +mcp__ai-proj__create_task({ title: "【代码评审】CR: {需求标题}" }) +mcp__ai-proj__link_tasks_to_requirement({ + requirementId, taskIds: [crTaskId], linkRole: "code_review" +}) + +// 3. 附加 CR 报告 +mcp__ai-proj__create-and-attach({ + taskId: crTaskId, + title: "代码评审报告", + content: "" +}) + +// 4. High/Critical 发现 → 创建修复任务 +mcp__ai-proj__create_task({ title: "【修复】{问题描述}" }) +mcp__ai-proj__link_tasks_to_requirement({ + requirementId, taskIds: [fixTaskId], linkRole: "implementation" +}) +``` + +### 独立 PR review + +不需要 ai-proj 集成，直接输出 CR 报告到对话。 + +--- + +## 最佳实践 + +1. **先理解再审查** — 读完所有变更���件后再开始扫描，避免断章取义 +2. **对抗性思维** — 切换到"怎么让它出错"的心态，不是"怎么让它跑通" +3. **证据驱动** — 每个发现必须引用具体的 `file:line` +4. **严重度准确** — 不要所有问题都标 High，按实际影响分级 +5. **建议可操作** — 每个发现必须附带具体修复建议 +6. **关注变更** — 评审范围是 diff，不要对未变更的代码提意见（除非变更引入了对旧代码的新风险） diff --git a/skills-dev/dev-scaffold-plugin/.claude-plugin/plugin.json b/skills-dev/dev-scaffold-plugin/.claude-plugin/plugin.json new file mode 100644 index 0000000..cf8075c --- /dev/null +++ b/skills-dev/dev-scaffold-plugin/.claude-plugin/plugin.json @@ -0,0 +1,6 @@ +{ + "name": "dev-scaffold-plugin", + "description": "模块脚手架插件。新建模块时自动生成分层代码骨架（Model/Repository/Service/Handler/Route）。挂载在 dev 阶段。", + "version": "1.0.0", + "author": { "name": "qiudl" } +} diff --git a/skills-dev/dev-scaffold-plugin/skills/SKILL.md b/skills-dev/dev-scaffold-plugin/skills/SKILL.md new file mode 100644 index 0000000..905ac44 --- /dev/null +++ b/skills-dev/dev-scaffold-plugin/skills/SKILL.md @@ -0,0 +1,78 @@ +--- +name: dev-scaffold +description: 模块脚手架插件。新建模块时自动生成分层代码骨架。挂载在 dev 阶段，新建模块时激活。 +--- + +# 模块脚手架插件 (dev-scaffold) + +## 概述 + +当需要新建一个完整模块时，自动生成分层代码骨架，避免手动创建大量样板文件。 + +**触发条件**： +- 需求需要新建数据库表 + 完整 CRUD +- 开发设计文档中有"新增"类型的文件 + +## Go 后端脚手架 + +输入模块名（如 `manual`），生成以下文件： + +``` +backend/ +├── models/manual.go # GORM 模型 +├── database/manual_repository.go # Repository +├── services/manual_service.go # Service +├── handlers/manual_handler.go # Handler +├── routes/manual_routes.go # Route +└── migrations/YYYYMMDDHHMMSS_create_manual.up.sql # Migration +``` + +### 生成规则 + +**Model** (`models/{name}.go`): +- struct 定义 + GORM tags +- TableName() 方法 +- 标准字段：ID, TenantID, CreatedBy, CreatedAt, UpdatedAt, DeletedAt + +**Repository** (`database/{name}_repository.go`): +- interface 定义 +- Create, GetByID, List(分页), Update, Delete 方法 +- 所有查询带 tenant_id 过滤 + +**Service** (`services/{name}_service.go`): +- interface 定义 +- 注入 Repository +- 基础 CRUD + 业务校验 + +**Handler** (`handlers/{name}_handler.go`): +- Create, Get, List, Update, Delete 方法 +- 请求参数绑定 + 验证 +- 统一错误处理 + +**Route** (`routes/{name}_routes.go`): +- RESTful 路由注册 +- Auth 中间件 + +**Migration** (`migrations/YYYYMMDDHHMMSS_create_{name}.up.sql`): +- CREATE TABLE + 标准字段 + 索引 + +## React 前端脚手架 + +输入模块名（如 `Manual`），生成： + +``` +frontend/src/ +├── types/manual.ts # TypeScript 类型 +├── services/manualService.ts # API Service +├── pages/ManualListPage.tsx # 列表页 +└── pages/ManualDetailPage.tsx # 详情页（可选） +``` + +## 使用方式 + +``` +用户: "新建 manual 模块的脚手架" +AI: 根据 req-design 的变更文件清单，生成所有骨架文件 +``` + +**注意**：脚手架只生成骨架，具体业务逻辑需在骨架基础上补充。 diff --git a/skills-dev/review-checklist-plugin/.claude-plugin/plugin.json b/skills-dev/review-checklist-plugin/.claude-plugin/plugin.json new file mode 100644 index 0000000..0ad2f48 --- /dev/null +++ b/skills-dev/review-checklist-plugin/.claude-plugin/plugin.json @@ -0,0 +1,8 @@ +{ + "name": "review-checklist-plugin", + "description": "项目级代码评审检查清单。按项目积累的特定检查项，挂载在 dev-review 下自动加载。", + "version": "1.0.0", + "author": { + "name": "qiudl" + } +} diff --git a/skills-dev/review-checklist-plugin/checklists/ai-proj.md b/skills-dev/review-checklist-plugin/checklists/ai-proj.md new file mode 100644 index 0000000..bbd76b9 --- /dev/null +++ b/skills-dev/review-checklist-plugin/checklists/ai-proj.md @@ -0,0 +1,42 @@ +# AI-Proj 代码评审检查清单 + +## 后端（Go + Gin + GORM） + +### 分层架构 +- [ ] Handler 是否直接 import `database/` 包？— 禁止，必须通过 Service 层。教训：架构退化导致循环依赖 +- [ ] 新 Handler 是否在 routes/ 中注册？— 遗漏会导致 404 +- [ ] MCP 专用 endpoint 是否包含 `/mcp/` 前缀？— 教训：缺少前缀导致 MCP bridge 404 + +### 数据库 +- [ ] 新增 Migration 文件名是否符合 `YYYYMMDDHHMMSS_xxx.up.sql` 格式？ +- [ ] Migration 是否有对应的 `.down.sql`？ +- [ ] GORM 查询是否带 `tenant_id` 过滤？（多租户安全） +- [ ] 软删除查询是否正确使用 `Unscoped()`？— 误用导致查不到已删除数据或查出已删除数据 + +### 认证与权限 +- [ ] 新 API 是否配置了 Auth 中间件？— 遗漏导致未授权访问 +- [ ] JWT token 类型是否区分 access/refresh？— 教训：token 混用导致安全漏洞 +- [ ] bcrypt cost 是否使用 12？— 教训：默认 cost 10 导致登录失败 + +### Redis +- [ ] Redis key 是否有 TTL？— 缺少 TTL 导致内存泄露 +- [ ] Redis 不可用时是否降级到数据库？ + +## 前端（React 18 + Ant Design） + +### Modal 安全 +- [ ] `Modal.success/info/warning/error` 之后是否有立即执行的 UI 操作？— 必须放在 `onOk` 回调中。教训：两个 Modal 同时弹出互相遮挡 + +### 状态管理 +- [ ] React Query 的 queryKey 是否正确包含所有依赖参数？— 缺少导致缓存错误 +- [ ] 列表页分页是否正确重置 page？— 教训：筛选条件变更后 page 未重置导致空页 + +### 类型安全 +- [ ] 是否有 `any` 类型？— 应使用具体类型 +- [ ] API 响应是否有 TypeScript 接口定义？ + +## 通用 + +- [ ] `.env` ��凭据文件是否被意外加入 git？ +- [ ] 是否有硬编码的 URL/IP/端口？— 应使用配置 +- [ ] 错误日志是否包含足够的上下文信息？（user_id, tenant_id, request_id） diff --git a/skills-dev/review-checklist-plugin/checklists/coolbuy-paas.md b/skills-dev/review-checklist-plugin/checklists/coolbuy-paas.md new file mode 100644 index 0000000..634d212 --- /dev/null +++ b/skills-dev/review-checklist-plugin/checklists/coolbuy-paas.md @@ -0,0 +1,20 @@ +# Coolbuy PaaS（酷采3.0）代码评审检查清单 + +## 后端（Go + Gin + MySQL） + +### 多租户 +- [ ] 所有查询是否带 `tenant_id` 和 `enterprise_id` 过滤？ +- [ ] 跨租户数据操作是否被阻止？ + +### 数据迁移 +- [ ] 从酷采2.0迁移的字段映射是否正确？（varchar ID → bigint ID） +- [ ] 迁移脚本是否处理了酷采2.0���软删除标记（is_delete → deleted_at）？ + +## 前端（Vue 3 + Ant Design Vue） + +### i18n +- [ ] 新增文案是否使用 `$t()` 国际化？— 不允许硬编码中文 +- [ ] i18n key 是否在 zh-CN 和 en-US 都有定义？ + +### 权限 +- [ ] 按钮/菜单是否有权限控制（v-permission 指令）？ diff --git a/skills-dev/review-checklist-plugin/checklists/general.md b/skills-dev/review-checklist-plugin/checklists/general.md new file mode 100644 index 0000000..45d912e --- /dev/null +++ b/skills-dev/review-checklist-plugin/checklists/general.md @@ -0,0 +1,23 @@ +# 通用代码评审检查清单 + +适用于所有项目，补充五视角扫描法。 + +## API 设计 +- [ ] RESTful 命名是否规范？（复数名词、无动词） +- [ ] 分页参数是否有默认值和上限？ +- [ ] 响应格式是否统一？（code/message/data） + +## 错误处理 +- [ ] 错误是否被正确传播？（不要吞掉错误） +- [ ] 用户可见的错误消息是否友好？（不暴露技术细节） +- [ ] 是否有 panic recover 兜底？ + +## 性能 +- [ ] 列表查询是否有分页？（不允许无限制查询） +- [ ] N+1 查询问题？（循环内查数据库） +- [ ] 是否有不必要的全表扫描？（缺少索引） + +## 可维护性 +- [ ] 魔法数字是否提取为常量？ +- [ ] 复杂业务逻辑是否有注释说明？ +- [ ] 函数是否过长？（超过 100 行考虑拆分） diff --git a/skills-dev/review-checklist-plugin/skills/SKILL.md b/skills-dev/review-checklist-plugin/skills/SKILL.md new file mode 100644 index 0000000..d9b5282 --- /dev/null +++ b/skills-dev/review-checklist-plugin/skills/SKILL.md @@ -0,0 +1,49 @@ +--- +name: review-checklist +description: 项目级代码评审检查清单。按项目积累特定检查项，挂载在 dev-review 下自动加载。每次 CR 时触发。 +--- + +# 代码评审检查清单插件 (review-checklist) + +## 概述 + +本插件为 `dev-review` 提供**项目特定的检查清单**，补充五视角扫描法之外的项目级经验。 + +检查清单按项目独立维护，每个项目文件记录该项目踩过的坑和必查项。 + +## 使用方式 + +1. `dev-review` 执行五视角扫描时，自动加载当前项目的检查清单 +2. 扫描完成后，逐条检查清单项 +3. 检查结果附加到 CR 报告的「项目检查清单」章节 + +## 检查清单文件 + +``` +review-checklist-plugin/ +├── skills/SKILL.md # 本文件 +└── checklists/ + ├── ai-proj.md # AI-Proj 项目清单 + ├── coolbuy-paas.md # 酷采3.0 项目清单 + └── general.md # 通用清单（所有项目适用） +``` + +## 如何添加检查项 + +当 CR 中发现了一个**项目特有**的问题模式，且未来可能复发时： + +1. 打开对应项目的检查清单文件 +2. 添加条目，格式：`- [ ] {检查项} — 教训：{来源}` +3. 标注严重度和适用范围 + +**不要添加**五视角扫描已覆盖的通用安全/并发/边界问题。 + +## CR 报告附加章节 + +```markdown +### 项目检查清单（{项目名}） + +| # | 检查项 | 结果 | 说明 | +|---|--------|------|------| +| 1 | {检查项} | ✅/❌/N/A | {说明} | +``` diff --git a/skills-req/req-compare-plugin/.claude-plugin/plugin.json b/skills-req/req-compare-plugin/.claude-plugin/plugin.json new file mode 100644 index 0000000..76e7fb5 --- /dev/null +++ b/skills-req/req-compare-plugin/.claude-plugin/plugin.json @@ -0,0 +1,8 @@ +{ + "name": "req-compare-plugin", + "description": "对比式需求分析插件。系统平移、竞品借鉴、版本升级时的参考对象对比分析。挂载在 analysis 阶段。", + "version": "1.0.0", + "author": { + "name": "qiudl" + } +} diff --git a/skills-req/req-compare-plugin/skills/SKILL.md b/skills-req/req-compare-plugin/skills/SKILL.md new file mode 100644 index 0000000..31e0c78 --- /dev/null +++ b/skills-req/req-compare-plugin/skills/SKILL.md @@ -0,0 +1,210 @@ +--- +name: req-compare +description: 对比式需求分析插件。系统平移、竞品借鉴、版本升级时使用参考对象对比法编写 PRD。挂载在 analysis 阶段，需要对比分析时由 req-prd 推荐激活。 +--- + +# 对比式需求分析插件 (req-compare) + +## 概述 + +当进行**系统平移、功能迁移、竞品借鉴**时，使用对比分析法编写 PRD，确保新系统功能完整且有所改进。 + +**触发条件**： +- 用户提到"从 XX 系统迁移"、"参考 XX 功能"、"平移"、"借鉴" +- req-prd 检测到需求涉及参考系统 + +## 适用场景 + +| 场景 | 说明 | 示例 | +|------|------|------| +| 系统平移 | 旧系统迁移到新技术栈 | 酷采2.0 → 酷采3.0 | +| 功能借鉴 | 参考竞品功能设计 | 参考飞书设计协作功能 | +| 版本升级 | 基于当前版本优化 | V1.0 → V2.0 重构 | + +--- + +## 对比分析工作流 + +``` +1. 确定参考对象 + ├── 识别参考系统（可以是多个） + ├── 获取访问权限（测试环境、源代码） + └── 明确对比目标 + +2. 参考对象分析 + ├── 功能调研（前端页面操作） + ├── 业务数据分析（核心实体、字段含义） + ├── 业务逻辑分析（规则、流转、校验） + └── 用户体验分析 + +3. 对比分析 + ├── 功能对比表（保留/优化/新增/废弃） + ├── 业务数据对比（实体映射、新增数据项） + ├── 用户体验对比 + └── 非功能需求对比（性能、安全） + +4. PRD 编写 + ├── 背景说明（明确参考来源） + ├── 功能需求（标注来源与变更） + ├── 业务数据需求（实体、字段、规则） + └── 非功能需求（性能、安全、兼容性） +``` + +--- + +## 对比式 PRD 模板 + +```markdown +# [功能模块名称] PRD + +## 1. 文档概述 + +### 1.1 文档信息 +| 项目 | 内容 | +|------|------| +| 文档名称 | [模块名称] 需求文档 | +| 版本 | V1.0 | +| 创建日期 | [日期] | +| **需求来源** | **[参考系统名称] 平移/借鉴** | +| **参考系统** | **[参考系统访问地址]** | + +### 1.2 背景说明 +本需求文档基于 **[参考系统]** 的 [模块名称] 功能分析，将其平移至 [目标系统]。 + +**参考系统信息**： +- 系统地址：[URL] +- 技术栈：[技术栈描述] +- 源码位置：[源码路径]（如有） + +--- + +## 2. 参考系统分析 + +### 2.1 功能截图 +[插入参考系统功能截图] + +### 2.2 业务数据（参考系统） +| 数据实体 | 核心字段 | 业务含义 | +|----------|----------|----------| +| [实体名] | [字段列表] | [业务说明] | + +### 2.3 核心功能（参考系统） +| 功能 | 用户操作 | 业务规则 | +|------|----------|----------| +| [功能名] | [操作描述] | [规则说明] | + +### 2.4 业务逻辑（参考系统） +- 核心业务规则摘要 +- 数据校验规则 +- 状态流转逻辑 + +--- + +## 3. 功能对比分析 + +### 3.1 功能对比表 +| 序号 | 功能 | 参考系统 | 目标系统 | 变更类型 | 说明 | +|------|------|----------|----------|----------|------| +| 1 | [功能1] | ✅ | ✅ | 保留 | 直接平移 | +| 2 | [功能2] | ✅ | ✅+ | 优化 | [优化内容] | +| 3 | [功能3] | ❌ | ✅ | 新增 | [新增原因] | +| 4 | [功能4] | ✅ | ❌ | 废弃 | [废弃原因] | + +### 3.2 业务数据对比 +| 数据项 | 参考系统 | 目标系统 | 变更 | 说明 | +|--------|----------|----------|------|------| +| [数据项] | [描述] | [描述] | 保留/优化/新增/废弃 | [说明] | + +### 3.3 非功能需求对比 +| 维度 | 参考系统 | 目标系统要求 | +|------|----------|-------------| +| 性能 | [现状] | [目标] | +| 安全 | [现状] | [目标] | +| 用户体验 | [现状] | [目标] | + +--- + +## 4. 目标系统设计 + +### 4.1 功能清单 +| 序号 | 功能 | 优先级 | 来源 | 说明 | +|------|------|--------|------|------| +| 1 | [功能] | P0 | 平移 | 从参考系统平移 | + +### 4.2 业务数据需求（目标系统） +| 数据实体 | 核心字段 | 业务规则 | 来源 | +|----------|----------|----------|------| +| [实体名] | [字段列表] | [校验/约束] | 平移/新增 | + +### 4.3 业务规则 +- [ ] 规则1（沿用参考系统） +- [ ] 规则2（优化调整） + +--- + +## 5. 上线优先级 +1. [P0 功能] — 核心路径 +2. [P1 功能] — 重要但可后续迭代 +3. [P2 功能] — 优化项 + +## 6. 注意事项 +- 参考系统中 [xxx] 逻辑需要特别注意 +- 新系统中需改进 [xxx] 问题 +``` + +--- + +## 参考对象分析方法 + +### 1. 前端功能调研 +- 访问参考系统，截图记录页面布局和交互流程 +- 记录用户操作路径（CRUD、搜索、筛选等） +- 标注交互细节（表单校验、提示信息、异常处理） + +### 2. 业务逻辑调研 +- 梳理核心业务规则和状态流转 +- 记录数据校验规则 +- 标注业务异常处理方式 + +> **技术层分析**（代码结构、数据库表结构、API 接口）请在 design 阶段使用 `req-design` 技能完成。 + +--- + +## 竞品分析模板 + +```markdown +# [竞品名称] 分析 + +## 1. 产品概述 +- 定位： +- 核心功能： +- 目标用户： + +## 2. 功能对比 +| 功能 | 我们 | 竞品A | 竞品B | +|------|------|-------|-------| +| 功能1 | ✅/❌/部分 | ... | ... | + +## 3. 优劣势分析 +### 优势 +1. ... + +### 劣势 +1. ... + +## 4. 可借鉴点 +- ... + +## 5. 差异化策略 +- ... +``` + +--- + +## 最佳实践 + +1. **先调研再写 PRD** — 充分理解参考系统后再动笔 +2. **功能对比表必填** — 明确每个功能的保留/优化/新增/废弃决策 +3. **标注来源** — 每个功能需求标注是"平移"还是"新增" +4. **记录废弃原因** — 参考系统有但不做的功能，必须记录原因 +5. **不抄技术实现** — 对比的是业务功能，不是代码结构 diff --git a/skills-req/req-design-plugin/.claude-plugin/plugin.json b/skills-req/req-design-plugin/.claude-plugin/plugin.json new file mode 100644 index 0000000..c525c3b --- /dev/null +++ b/skills-req/req-design-plugin/.claude-plugin/plugin.json @@ -0,0 +1,8 @@ +{ + "name": "req-design-plugin", + "description": "需求开发设计技能。PRD 到开发设计的转换：API 契约、数据模型变更、任务拆分、风险评估。", + "version": "2.0.0", + "author": { + "name": "qiudl" + } +} diff --git a/skills-req/req-design-plugin/skills/SKILL.md b/skills-req/req-design-plugin/skills/SKILL.md new file mode 100644 index 0000000..d75a7cf --- /dev/null +++ b/skills-req/req-design-plugin/skills/SKILL.md @@ -0,0 +1,455 @@ +--- +name: req-design +description: 需求开发设计技能。用于 PRD 到开发设计的转换：API 契约定义、数据模型变更方案、变更文件清单、开发任务拆分、技术风险评估。当用户执行 /req doc 或需要编写开发设计文档时自动激活。 +arguments: +--- + +# 需求开发设计 Skill (req-design) + +## 概述 + +本技能用于将 PRD 文档转换为**开发设计文档**，是产品需求（req-prd）和编码实现（dev-coding）之间的桥梁。 + +**核心输出**： +- API 契约定义（前后端对齐） +- 数据模型变更方案（新增/修改表和字段） +- 变更文件清单（标注层级和改动类型） +- 开发任务拆分（SMART 原则，2-4h 粒度） +- 技术风险评估 + +**不包含**（由其他技能负责）： +- 具体代码实现 → `dev-coding` +- 代码规范和编码模式 → `dev-coding` +- 深度架构设计 → `dev-arch`（插件） +- 数据库迁移细节 → `db-migration`（插件） + +--- + +## 技能间契约 + +| 上游 | 本技能输入 | 本技能输出 | 下游 | +|------|-----------|-----------|------| +| req-prd | PRD 文档（用户故事、业务规则、验收标准） | 开发设计文档 | dev-coding | + +**输出格式要求**： +- API 契约：B 级格式（见下方标准） +- 变更清单：按文件列出，标注层级和改动类型 +- 任务拆分：每任务 2-4h，SMART 原则 + +--- + +## 工作流程 + +``` +0. ⚠️ 需求验证（防浪费，5-10 分钟） + ├── 现有 UI 检查：功能是否已存在？ + ├── 数据检查：字段/API 是否已有？ + └── 价值验证：痛点明确？有更简方案？ + +1. 获取需求信息 + ├── mcp__ai-proj__get_requirement + └── mcp__ai-proj__get_requirement_tasks（找 PRD 任务） + +2. 分析 PRD 文档 + ├── 提取功能点和业务规则 + ├── 识别数据实体和关系 + └── 确定非功能需求（性能、安全） + +3. 探索代码库 + ├── 搜索相关现有代码（Grep/Glob/Explore） + ├── 识别修改文件和可复用代码 + └── 分析依赖关系 + +4. 设计 API 契约 + ├── 定义新增/修改接口（B 级格式） + ├── 定义请求/响应结构 + └── 定义错误码 + +5. 设计数据模型变更 + ├── 新增/修改表和字段 + ├── 索引设计 + └── 数据迁移方案（如需要） + +6. 生成变更文件清单 + ├── 后端：Model → Repository → Service → Handler → Route → Migration + ├── 前端：Types → Services → Components → Pages + └── 标注每个文件的改动类型（新增/修改/删除） + +7. 拆分开发任务 + ├── 按模块/文件拆分子任务 + └── mcp__ai-proj__create_subtask + +8. 技术风险评估 + ├── 影响分析（兼容性、性能） + └── 回退方案 +``` + +--- + +## 需求验证（第 0 步） + +> **教训**：不先验证需求，可能花几小时实现冗余功能。 + +**验证清单**（5-10 分钟）： + +1. **现有功能检查**（最重要） + - 打开相关页面，目视检查功能是否已存在 + - 检查数据库是否已有相关字段 + - 检查 API 是否已返回所需数据 + +2. **价值验证** + - 解决什么具体痛点？ + - 有无更简单的替代方案？ + - 投入产出比是否合理？ + +3. **设计审查** + - UI 设计是否合理？不重复、不混乱？ + - 是否符合现有设计规范？ + +**通过验证后再开始设计！** + +--- + +## API 契约格式标准（B 级） + +所有新增/修改 API 必须使用以下格式定义契约，作为前后端对齐的桥梁： + +``` +### POST /api/v1/enterprises +描述: 创建企业 + +请求体: + - name: string (required) — 企业名称，最长 100 字符 + - code: string (required) — 企业编码，唯一，正则 ^[A-Z0-9-]+$ + - contact_email: string (optional) — 联系邮箱 + +响应 200: + - id: int + - name: string + - code: string + - created_at: datetime + +错误: + - 400: 参数校验失败（name/code 为空或格式错误） + - 409: 编码已存在 + - 403: 无权限创建企业 +``` + +**B 级规则**： +- 列出所有字段、类型、必填/可选 +- 标注校验规则（长度、格式、唯一性） +- 列出所有可能的错误码和含义 +- 不需要 JSON 示例（A 级才需要） + +--- + +## 开发设计文档模板 + +```markdown +# [需求标题] 开发设计文档 + +## 1. 需求概述 + +### 1.1 需求信息 +| 项目 | 内容 | +|------|------| +| 需求编号 | REQ-YYYYMMDD-XXXX | +| 需求标题 | [标题] | +| 优先级 | high/medium/low | +| 预估工时 | Xh | + +### 1.2 功能点清单 +- [ ] 功能点1：[描述] +- [ ] 功能点2：[描述] + +--- + +## 2. 代码库分析 + +### 2.1 相关现有代码 +| 文件路径 | 层级 | 当前功能 | 改动类型 | +|---------|------|----------|---------| +| `backend/models/xxx.go` | Model | 数据模型 | 新增字段 | +| `backend/services/xxx_service.go` | Service | 业务逻辑 | 新增方法 | + +### 2.2 可复用代码 +- [描述已有的可参考实现] + +### 2.3 依赖关系 +- [需要注意的调用链和依赖] + +--- + +## 3. API 契约 + +### 3.1 新增接口 + +### POST /api/v1/xxx +描述: [功能描述] + +请求体: + - field1: type (required) — 说明 + - field2: type (optional) — 说明 + +响应 200: + - field1: type + - field2: type + +错误: + - 400: [说明] + - 404: [说明] + +### 3.2 修改接口 +[列出需要修改的现有接口及变更内容] + +--- + +## 4. 数据模型变更 + +### 4.1 新增表 +| 表名 | 说明 | +|------|------| +| xxx | [用途] | + +**字段设计**： +| 字段 | 类型 | 约束 | 说明 | +|------|------|------|------| +| id | BIGSERIAL | PK | 主键 | +| tenant_id | BIGINT | NOT NULL, INDEX | 租户ID | +| name | VARCHAR(255) | NOT NULL | 名称 | +| created_at | TIMESTAMP | NOT NULL, DEFAULT NOW() | 创建时间 | + +**索引**： +| 索引名 | 字段 | 类型 | 说明 | +|--------|------|------|------| +| idx_xxx_tenant | tenant_id | B-tree | 租户查询 | + +### 4.2 修改表 +| 表名 | 变更 | 说明 | +|------|------|------| +| xxx | 新增字段 yyy | [用途] | + +### 4.3 数据迁移（如需要） +[迁移方案描述] + +--- + +## 5. 变更文件清单 + +### 后端 +| 文件 | 层级 | 改动类型 | 改动说明 | +|------|------|---------|---------| +| `models/xxx.go` | Model | 修改 | 新增字段 | +| `database/xxx_repository.go` | Repository | 修改 | 新增查询方法 | +| `services/xxx_service.go` | Service | 修改 | 新增业务方法 | +| `handlers/xxx_handler.go` | Handler | 修改 | 新增接口 | +| `routes/xxx_routes.go` | Route | 修改 | 注册新路由 | +| `migrations/YYYYMMDD_xxx.up.sql` | Migration | 新增 | 表结构变更 | + +### 前端 +| 文件 | 层级 | 改动类型 | 改动说明 | +|------|------|---------|---------| +| `types/xxx.ts` | Types | 修改 | 新增接口定义 | +| `services/xxxService.ts` | Service | 修改 | 新增 API 调用 | +| `pages/XxxPage.tsx` | Page | 修改 | 新增功能 UI | + +--- + +## 6. 开发任务拆分 + +### 6.1 任务列表 +| # | 任务标题 | 预估工时 | 依赖 | +|---|---------|---------|------| +| 1 | [后端] Model + Migration | 1h | - | +| 2 | [后端] Repository + Service | 2h | #1 | +| 3 | [后端] Handler + Route | 2h | #2 | +| 4 | [前端] Types + Service | 1h | #3 | +| 5 | [前端] 页面开发 | 3h | #4 | +| 6 | [测试] 单元测试 | 2h | #3, #5 | + +### 6.2 实施顺序 +[按依赖关系排列的开发步骤] + +--- + +## 7. 技术风险评估 + +### 7.1 影响分析 +| 改动类型 | 影响范围 | 风险等级 | 应对措施 | +|---------|---------|---------|---------| +| [描述] | [范围] | 高/中/低 | [措施] | + +### 7.2 风险清单 +- [ ] 数据库：是否需要数据迁移？是否影响数据完整性？ +- [ ] API：是否破坏兼容性？是否需要版本管理？ +- [ ] 前端：是否影响现有页面？是否有性能瓶颈？ +- [ ] 业务：是否影响核心流程？是否需要灰度？ + +### 7.3 回退方案 +[如果上线出问题，如何回退] + +--- + +## 8. 注意事项 +[特殊说明、边界情况、兼容性要求] +``` + +--- + +## 任务拆分规则 + +### SMART 原则 + +- **Specific**（具体）：明确要修改哪个文件/模块 +- **Measurable**（可衡量）：清晰的完成标准 +- **Achievable**（可实现）：单个任务 2-4 小时完成 +- **Relevant**（相关）：与需求直接相关 +- **Time-bound**（有时限）：预估工时 + +### 拆分粒度 + +- ✅ 好的粒度：`[Handler] 修改 manual_handler.go 添加发布接口（2h）` +- ❌ 太粗：`[后端] 实现所有后端功能` +- ❌ 太细：`[Handler] 添加 import 语句` + +### 按文件拆分（推荐） +- 每个文件对应一个子任务 +- 格式：`[层级] 修改 文件名 简要说明` + +### 按功能模块拆分（大改动） +- 将相关文件归为一个模块 +- 格式：`[模块] 功能描述` + +### 标准开发顺序 + +``` +第一阶段：数据层 +├── Model 层：定义数据结构 +├── Migration：创建/修改表 +└── Repository 层：实现数据访问 + +第二阶段：业务层 +├── Service 层：实现业务逻辑 +└── 编写单元测试 + +第三阶段：接口层 +├── Handler 层：实现 HTTP 接口 +├── Route 层：注册路由 +└── API 文档（Swagger） + +第四阶段：前端层 +├── Types：定义 TypeScript 接口 +├── Services：封装 API 调用 +├── Components：开发可复用组件 +└── Pages：实现业务页面 + +第五阶段：测试与优化 +├── 后端单元测试 +├── 前端组件测试 +└── E2E 测试 +``` + +--- + +## 技术风险评估框架 + +### 影响分析矩阵 + +| 改动类型 | 影响范围 | 风险等级 | 应对措施 | +|---------|---------|---------|---------| +| 新增字段（非必填） | 低 | 低 | 添加 Migration，向后兼容 | +| 修改字段类型 | 中 | 中 | 数据迁移脚本，充分测试 | +| 删除字段 | 高 | 高 | 确认无依赖，先标记废弃 | +| 新增 API 接口 | 低 | 低 | 接口设计评审 | +| 修改 API 接口 | 中 | 中 | 保留旧接口，添加版本号 | +| 删除 API 接口 | 高 | 高 | 确认无调用，发布公告 | +| 新增前端页面 | 低 | 低 | 路由冲突检查 | +| 修改核心组件 | 高 | 高 | 充分测试所有使用场景 | + +### 性能影响评估 + +| 维度 | 评估项 | +|------|--------| +| 数据库 | 查询复杂度、索引使用、数据量、并发影响 | +| API | 响应时间预期、QPS 预估、缓存策略、限流需求 | +| 前端 | 首屏加载影响、渲染性能、内存占用 | + +--- + +## 与 ai-proj 集成 + +### 文档创建 + +```typescript +// 创建开发设计文档并关联任务 +mcp__ai-proj__create-and-attach({ + taskId: <设计任务ID>, + title: "开发设计文档 - [需求标题]", + content: "<使用上方模板生成的内容>" +}) +``` + +### 子任务拆分 + +```typescript +mcp__ai-proj__create_subtask({ + parentId: <开发任务ID>, + title: "[Handler] 修改 manual_handler.go 添加发布接口" +}) +``` + +### 进度更新 + +```typescript +mcp__ai-proj__update_task_document({ + taskId: <设计任务ID>, + content: "<更新后的设计文档>" +}) +``` + +--- + +## 插件触发 + +| 插件 | 触发条件 | 说明 | +|------|---------|------| +| `dev-arch` | 新模块/新表/复杂架构 | 深度架构设计 | +| `db-migration` | 涉及数据库变更 | 数据库迁移方案 | + +当检测到以上条件时，建议用户启用对应插件。 + +--- + +## 最佳实践 + +1. **先验证再设计** — 5 分钟验证省 3 小时返工 +2. **API 契约先行** — 前后端对齐的桥梁，先定义再实现 +3. **复用优于新建** — 充分探索代码库，识别可复用代码 +4. **风险前置** — 在设计阶段识别风险，而非编码时才发现 +5. **粒度适中** — 任务拆分 2-4h，不要太粗也不要太细 +6. **文档可操作** — 开发者可直接按设计文档实施 + +--- + +## 常见问题 + +### Q1: 如何确定是否需要新增数据库表？ +检查：新数据是否与现有实体有独立生命周期？是否需要独立查询？是否 1:N 或 N:N 关系？任一满足则新增表。 + +### Q2: 什么时候需要创建子任务？ +修改 3 个以上文件 / 预估工时 > 4h / 涉及多个层级 → 创建子任务。 + +### Q3: API 契约需要多详细？ +B 级：字段 + 类型 + 必填/可选 + 校验规则 + 错误码。不需要 JSON 示例。 + +### Q4: 设计文档和 PRD 的边界？ +PRD 说「做什么」（用户故事、业务规则、验收标准），设计文档说「怎么做」（API、数据模型、文件清单）。 + +--- + +## 变更记录 + +| 版本 | 日期 | 变更内容 | +|------|------|----------| +| V1.0 | 2026-01-26 | 初始版本（req-dev） | +| V2.0 | 2026-04-06 | 重构为 req-design：移除架构指南和编码规范，聚焦 API 契约 + 任务拆分 | diff --git a/skills-req/req-dev-plugin/.claude-plugin/plugin.json b/skills-req/req-dev-plugin/.claude-plugin/plugin.json index f74e2a6..dab1d98 100644 --- a/skills-req/req-dev-plugin/.claude-plugin/plugin.json +++ b/skills-req/req-dev-plugin/.claude-plugin/plugin.json @@ -1,7 +1,8 @@ { "name": "req-dev-plugin", - "description": "Plugin for req-dev", + "description": "[已废弃] 请使用 req-design-plugin。需求开发设计功能已迁移。", "version": "1.0.0", + "deprecated": true, "author": { "name": "qiudl" } diff --git a/skills-req/req-prd-plugin/.claude-plugin/plugin.json b/skills-req/req-prd-plugin/.claude-plugin/plugin.json index 1c5708f..ed2cb41 100644 --- a/skills-req/req-prd-plugin/.claude-plugin/plugin.json +++ b/skills-req/req-prd-plugin/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "req-prd-plugin", - "description": "Plugin for req-prd", - "version": "1.0.0", + "description": "产品需求设计技能。PRD 文档编写、需求分析、用户故事、对比式分析。纯产品视角，不含技术实现。", + "version": "2.0.0", "author": { "name": "qiudl" } diff --git a/skills-req/req-prd-plugin/skills/SKILL.md b/skills-req/req-prd-plugin/skills/SKILL.md index 581fce2..18b71a7 100644 --- a/skills-req/req-prd-plugin/skills/SKILL.md +++ b/skills-req/req-prd-plugin/skills/SKILL.md @@ -9,248 +9,23 @@ description: 产品设计与需求管理。用于 PRD 文档编写、需求分 本技能用于辅助产品设计和需求管理工作，包括： - PRD 文档编写与管理 -- **参考对象对比式 PRD 编写**（核心能力） - 需求分析与优先级排序 - 用户故事创建 - 功能设计与规划 - 与 ai-proj 任务系统集成 ---- - -## 参考对象对比式 PRD 编写 - -当进行**系统平移、功能迁移、竞品借鉴**时，应采用对比分析法编写 PRD，确保新系统功能完整且有所改进。 - -### 适用场景 - -| 场景 | 说明 | 示例 | -|------|------|------| -| 系统平移 | 旧系统迁移到新技术栈 | 酷采2.0 → 酷采3.0 | -| 功能借鉴 | 参考竞品功能设计 | 参考飞书设计协作功能 | -| 版本升级 | 基于当前版本优化 | V1.0 → V2.0 重构 | - -### 对比分析工作流 - -``` -1. 确定参考对象 - ├── 识别参考系统（可以是多个） - ├── 获取访问权限（测试环境、源代码） - └── 明确对比目标 - -2. 参考对象分析 - ├── 功能调研（前端页面操作） - ├── 数据模型分析（数据库表结构） - ├── 业务逻辑分析（后端代码） - └── API 接口分析 - -3. 对比分析 - ├── 功能对比表（保留/优化/新增/废弃） - ├── 数据模型对比（字段映射、新增字段） - ├── 技术架构对比 - └── 用户体验对比 - -4. PRD 编写 - ├── 背景说明（明确参考来源） - ├── 功能需求（标注来源与变更） - ├── 数据设计（标注字段来源） - └── 实现建议 -``` - -### 对比式 PRD 模板 - -```markdown -# [功能模块名称] PRD - -## 1. 文档概述 - -### 1.1 文档信息 -| 项目 | 内容 | -|------|------| -| 文档名称 | [模块名称] 需求文档 | -| 版本 | V1.0 | -| 创建日期 | [日期] | -| **需求来源** | **[参考系统名称] 平移/借鉴** | -| **参考系统** | **[参考系统访问地址]** | - -### 1.2 背景说明 -本需求文档基于 **[参考系统]** 的 [模块名称] 功能分析，将其平移至 [目标系统]。 - -**参考系统信息**： -- 系统地址：[URL] -- 技术栈：[技术栈描述] -- 源码位置：[源码路径]（如有） +**插件扩展**： +- `req-compare` — 对比式 PRD 编写（系统平移/竞品借鉴时激活） +- `req-prototype` — UI 原型生成 --- -## 2. 参考系统分析 +## 对比式 PRD 编写 -### 2.1 功能截图 -[插入参考系统功能截图] +> 系统平移、竞品借鉴、版本升级时，使用 `req-compare` 插件进行对比分析。 +> 该插件包含完整的对比工作流、对比式 PRD 模板和竞品分析模板。 -### 2.2 数据模型（参考系统） -```sql --- 参考系统表结构 -CREATE TABLE [表名] ( - -- 从源代码/数据库提取 -); -``` - -### 2.3 API 接口（参考系统） -| 接口 | 方法 | 说明 | -|------|------|------| -| /api/xxx | GET/POST | [描述] | - -### 2.4 业务逻辑（参考系统） -- 核心业务规则摘要 -- 数据校验规则 -- 状态流转逻辑 - ---- - -## 3. 功能对比分析 - -### 3.1 功能对比表 -| 序号 | 功能 | 参考系统 | 目标系统 | 变更类型 | 说明 | -|------|------|----------|----------|----------|------| -| 1 | [功能1] | ✅ | ✅ | 保留 | 直接平移 | -| 2 | [功能2] | ✅ | ✅+ | 优化 | [优化内容] | -| 3 | [功能3] | ❌ | ✅ | 新增 | [新增原因] | -| 4 | [功能4] | ✅ | ❌ | 废弃 | [废弃原因] | - -### 3.2 数据模型对比 -| 参考系统字段 | 目标系统字段 | 类型 | 变更 | 说明 | -|--------------|--------------|------|------|------| -| id (varchar) | id (bigint) | PK | 优化 | 改用自增ID | -| company_id | tenant_id | FK | 重命名 | 统一租户字段 | -| -- | created_by | bigint | 新增 | 审计字段 | - -### 3.3 技术架构对比 -| 层次 | 参考系统 | 目标系统 | -|------|----------|----------| -| 后端框架 | [如: Spring Boot] | [如: Go Gin] | -| 前端框架 | [如: Vue 2] | [如: React 18] | -| 数据库 | [如: MySQL] | [如: PostgreSQL] | - ---- - -## 4. 目标系统设计 - -### 4.1 功能清单 -| 序号 | 功能 | 优先级 | 来源 | 说明 | -|------|------|--------|------|------| -| 1 | [功能] | P0 | 平移 | 从参考系统平移 | - -### 4.2 数据模型（目标系统） -```sql --- 目标系统表结构（基于对比分析设计） -CREATE TABLE [表名] ( - id BIGINT PRIMARY KEY, - -- 字段设计... -); -``` - -### 4.3 API 设计（目标系统） -| 接口 | 方法 | 说明 | 参考接口 | -|------|------|------|----------| -| /api/v1/xxx | GET | [描述] | 参考 /api/xxx | - -### 4.4 业务规则 -- [ ] 规则1（沿用参考系统） -- [ ] 规则2（优化调整） - ---- - -## 5. 实现建议 - -### 5.1 开发顺序 -1. 数据模型迁移 -2. 后端 API 实现 -3. 前端页面开发 -4. 数据迁移脚本 - -### 5.2 注意事项 -- 参考系统中 [xxx] 逻辑需要特别注意 -- 新系统中需改进 [xxx] 问题 -``` - ---- - -### 参考对象分析工具 - -#### 1. 前端分析 -```bash -# 启动浏览器调试模式（macOS） -/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \ - --remote-debugging-port=9222 \ - --user-data-dir=/tmp/chrome-debug - -# 访问参考系统，截图、分析交互 -``` - -#### 2. 后端代码分析 -```bash -# 搜索相关模型 -grep -r "class.*Model" --include="*.java" /path/to/legacy/ - -# 搜索相关控制器 -grep -r "@Controller\|@RestController" --include="*.java" /path/to/legacy/ -``` - -#### 3. 数据库分析 -```sql --- 查看表结构 -SHOW CREATE TABLE table_name; - --- 查看字段注释 -SELECT COLUMN_NAME, COLUMN_COMMENT -FROM information_schema.COLUMNS -WHERE TABLE_NAME = 'table_name'; -``` - ---- - -### 示例：酷采3.0标签管理模块 - -以下是基于酷采2.0平移的标签管理模块对比分析示例： - -#### 参考系统（酷采2.0） - -**数据模型**： -```sql --- 酷采2.0 prd_product_label 表 -CREATE TABLE `prd_product_label` ( - `id` varchar(64) NOT NULL, - `label_name` varchar(256) DEFAULT NULL, - `company_id` varchar(64) DEFAULT NULL, - `input_user_id` varchar(64) DEFAULT NULL, - `input_user_name` varchar(64) DEFAULT NULL, - `input_time` datetime DEFAULT NULL, - `update_user_id` varchar(64) DEFAULT NULL, - `update_user_name` varchar(64) DEFAULT NULL, - `update_time` datetime DEFAULT NULL, - `version` bigint(20) DEFAULT 0, - `is_delete` tinyint(1) DEFAULT 0, - `status` tinyint(1) DEFAULT 1, - `remark` varchar(512) DEFAULT NULL, - `sort_no` int(11) DEFAULT 0, - PRIMARY KEY (`id`) -); -``` - -**代码位置**： -- 后端: `cool_lining/module-provider/.../dao/model/prd/PrdProductLabel.java` -- 前端: `ln_admin/src/views/module/prd/product_label/` - -#### 目标系统（酷采3.0）设计 - -**数据模型对比**： -| 酷采2.0 | 酷采3.0 | 变更 | -|---------|---------|------| -| id (varchar) | id (bigint) | 改用自增ID | -| company_id | tenant_id | 统一租户标识 | -| input_user_id | created_by | 简化字段命名 | -| input_time | created_at | 统一时间字段 | -| is_delete | deleted_at | 改用软删除时间戳 | +**触发方式**：当需求涉及参考系统时，req-prd 自动推荐激活 req-compare 插件。 --- @@ -523,36 +298,9 @@ mcp__ai-proj__export_task_document_to_file --- -## 竞品分析模板 +## 竞品分析 -### 分析框架 - -```markdown -# [竞品名称] 分析 - -## 1. 产品概述 -- 定位： -- 核心功能： -- 目标用户： - -## 2. 功能对比 -| 功能 | 我们 | 竞品A | 竞品B | -|------|------|-------|-------| -| 功能1 | ✅/❌/部分 | ... | ... | - -## 3. 优劣势分析 -### 优势 -1. ... - -### 劣势 -1. ... - -## 4. 可借鉴点 -- ... - -## 5. 差异化策略 -- ... -``` +> 竞品分析模板已移至 `req-compare` 插件。涉及竞品对比时自动激活。 --- @@ -610,13 +358,14 @@ mcp__ai-proj__export_task_document_to_file - [ ] 操作可撤销 - [ ] 符合用户习惯 -### 技术方案检查 +### 非功能需求检查 -- [ ] 技术可行性验证 -- [ ] 性能影响评估 -- [ ] 扩展性考虑 -- [ ] 安全性审查 -- [ ] 兼容性测试 +- [ ] 性能要求已量化（响应时间、并发量） +- [ ] 安全需求已明确（权限、数据保护） +- [ ] 兼容性要求已定义（浏览器、设备） +- [ ] 可用性目标已设定 + +> **技术方案可行性检查**在 design 阶段由 `req-design` 技能完成。 --- diff --git a/skills-req/req-research-plugin/.claude-plugin/plugin.json b/skills-req/req-research-plugin/.claude-plugin/plugin.json new file mode 100644 index 0000000..c459a16 --- /dev/null +++ b/skills-req/req-research-plugin/.claude-plugin/plugin.json @@ -0,0 +1,6 @@ +{ + "name": "req-research-plugin", + "description": "需求调研插件。代码审计、数据库分析、现有功能调研。挂载在 analysis 阶段，需要深度调研时激活。", + "version": "1.0.0", + "author": { "name": "qiudl" } +} diff --git a/skills-req/req-research-plugin/skills/SKILL.md b/skills-req/req-research-plugin/skills/SKILL.md new file mode 100644 index 0000000..23c7b6b --- /dev/null +++ b/skills-req/req-research-plugin/skills/SKILL.md @@ -0,0 +1,124 @@ +--- +name: req-research +description: 需求调研插件。代码审计、数据库分析、现有功能调研、技术可行性评估。挂载在 analysis 阶段，需要深度调研时由 req-prd 推荐激活。 +--- + +# 需求调研插件 (req-research) + +## 概述 + +当 PRD 编写需要**深入了解现有系统**时使用。提供结构化的调研方法。 + +**触发条件**： +- 需求涉及修改现有功能（需了解当前实现） +- 需求涉及数据库表结构变更 +- 需要技术可行性评估 + +## 调研方法 + +### 1. 前端功能调研 + +```bash +# 启动本地开发环境 +cd frontend && npm start + +# 访问相关页面，记录： +# - 页面布局和交互流程 +# - 表单字段和校验规则 +# - 列表列和筛选条件 +# - 异常情况处理（空状态、错误提示） +``` + +**调研模板**： +```markdown +### 页面: [页面名称] ([URL]) +- **功能**: [功能描述] +- **字段**: [列出所有字段] +- **操作**: [CRUD/筛选/排序/导出] +- **校验**: [表单校验规则] +- **截图**: [如有] +``` + +### 2. 后端代码审计 + +```bash +# 搜索相关模型 +Grep(pattern="type.*struct", path="backend/models", glob="*xxx*.go") + +# 搜索相关 Handler +Grep(pattern="func.*Handler.*xxx", path="backend/handlers") + +# 搜索相关路由 +Grep(pattern="xxx", path="backend/routes") + +# 搜索相关 Service +Grep(pattern="func.*Service.*xxx", path="backend/services") +``` + +**审计模板**： +```markdown +### 模块: [模块名] +- **Model**: `backend/models/xxx.go` — [字段数]个字段 +- **Repository**: `backend/database/xxx_repository.go` — [方法数]个方法 +- **Service**: `backend/services/xxx_service.go` — [方法数]个方法 +- **Handler**: `backend/handlers/xxx_handler.go` — [接口数]个接口 +- **Route**: `backend/routes/xxx_routes.go` +- **关键业务逻辑**: [描述] +``` + +### 3. 数据库分析 + +```bash +# 查看表结构（本地） +psql -U ai_user -d ai_project -c "\d table_name" + +# 查看数据量 +psql -U ai_user -d ai_project -c "SELECT COUNT(*) FROM table_name" + +# 查看索引 +psql -U ai_user -d ai_project -c "\di table_name*" +``` + +**分析模板**： +```markdown +### 表: [表名] +- **字段数**: N +- **数据量**: ~N 行 +- **索引**: [列出索引] +- **关联**: [外键关系] +- **特殊字段**: [JSON/Array/Enum 等] +``` + +### 4. API 分析 + +```bash +# 查看 Swagger 文档 +open http://localhost:8080/swagger/index.html + +# 搜索 API 路由 +Grep(pattern="GET|POST|PUT|DELETE.*xxx", path="backend/routes") +``` + +## 调研报告模板 + +```markdown +## 调研报告 — {需求标题} + +### 1. 现有功能 +[页面/功能调研结果] + +### 2. 代码结构 +[代码审计结果，按分层列出] + +### 3. 数据库现状 +[表结构、数据量、索引] + +### 4. 技术可行性 +| 方案 | 优点 | 缺点 | 工时预估 | +|------|------|------|---------| +| 方案A | ... | ... | Xh | +| 方案B | ... | ... | Xh | + +### 5. 建议 +[推荐方案及原因] +```