pipexerp/ai-proj-helper
6
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity

refactor: 通用技能按类别拆分为独立目录

Browse Source 
skills/ → skills-dev(9), skills-req(10), skills-ops(4),
skills-integration(8), skills-biz(4), skills-workflow(7)

generate-marketplace.py 改为自动扫描所有 skills-* 目录。

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
John Qiu
2026-03-14 11:31:58 +10:30
parent ea266e9cce
commit 712063071c
170 changed files with 341 additions and 346 deletions
Download Patch File Download Diff File Expand all files Collapse all files

115
skills-req/req-plugin/docs/code-review-guide.md Normal file
View File

@@ -0,0 +1,115 @@
# 代码评审指南 (Code Review Guide)
代码评审是测试阶段的前置条件，确保代码质量在测试前得到验证。
## 评审时机
```
开发完成 → 代码评审 → 测试
↑ ↓
└── 发现问题，修复后重新评审
```
## 评审检查清单
### 1. 代码风格
- [ ] 符合项目编码规范（Go/TypeScript）
- [ ] 命名清晰有意义
- [ ] 代码格式统一（已运行 lint/format）
### 2. 安全性
- [ ] 无 SQL 注入风险
- [ ] 无 XSS 漏洞
- [ ] 无敏感信息硬编码（密码、密钥）
- [ ] 权限检查完善
### 3. 错误处理
- [ ] 异常捕获完善
- [ ] 错误信息友好（不暴露内部细节）
- [ ] 边界条件处理
### 4. 性能
- [ ] 无 N+1 查询
- [ ] 无不必要的循环/递归
- [ ] 大数据量有分页处理
### 5. 日志与监控
- [ ] 关键操作有日志
- [ ] 日志级别适当
- [ ] 无敏感信息输出到日志
### 6. 测试覆盖
- [ ] 关键逻辑有单元测试
- [ ] 测试用例有效
### 7. 文档
- [ ] 复杂逻辑有注释
- [ ] API 有文档说明
## 评审方式
| 方式 | 适用场景 |
|------|----------|
| 自评 (Self Review) | AI 开发的代码，Claude 自动检查 |
| 他人评审 (Peer Review) | 团队协作，提交 PR 等待评审 |
| 结对评审 (Pair Review) | 复杂功能，实时讨论 |
## 执行流程
### `/req cr` 命令执行步骤
1. **验证开发完成**
```
检查所有 implementation 任务状态 = completed
```
2. **生成变更摘要**
```bash
git diff --stat HEAD~N # N = 开发期间的提交数
git diff --name-only HEAD~N
```
3. **显示检查清单**
- 输出上述检查清单
- 逐项确认或标记问题
4. **记录评审结果**
- 通过：创建 code_review 任务并标记 completed
- 不通过：列出问题，等待修复后重新评审
## 常见问题
### Go 后端
- 未检查 `error` 返回值
- 缺少 `defer` 关闭资源
- 并发访问未加锁
### TypeScript 前端
- `any` 类型滥用
- 缺少空值检查
- 未处理异步错误
### 数据库
- 缺少索引
- 大事务未拆分
- 未考虑并发更新
## 评审不通过时
```
/req cr REQ-XXXX
→ 发现问题:
⚠️ handlers/task_handler.go:245 - 缺少错误处理
⚠️ pages/TaskList.tsx:88 - 存在 XSS 风险
→ 请修复后重新执行 /req cr
```
## 跳过评审（紧急情况）
```bash
/req test REQ-XXXX --skip-cr --reason="紧急生产修复"
```
> 跳过评审需记录原因，事后补充评审。

273
skills-req/req-plugin/docs/deploy-guide.md Normal file
View File

@@ -0,0 +1,273 @@
# 部署指南
## 部署流程概览
```
Staging 部署（手动） Production 部署（Jenkins）
↓ ↓
本地构建 :test 镜像 本地构建 :latest 镜像
↓ ↓
推送到 DockerHub 推送到 DockerHub
↓ ↓
显示部署命令 调用 Jenkins API
↓ ↓
用户手动执行 自动触发部署
↓ ↓
验证 API 轮询构建状态
↓
验证 API
```
## 环境说明
| 环境 | 触发方式 | 镜像标签 | 用途 |
|------|----------|----------|------|
| staging | 手动 SSH | `:test` | 预发布测试 |
| production | Jenkins API | `:latest` | 正式生产 |
## 镜像构建规范
> ⚠️ **重要**: 必须理解 Dockerfile target 和镜像标签的区别
### Dockerfile Target vs 镜像标签
| 概念 | 说明 | 示例 |
|------|------|------|
| **Dockerfile Target** | 构建阶段，决定镜像内容 | `--target production`, `--target test` |
| **镜像标签** | 版本标识，决定部署环境 | `:test`, `:latest` |
### 正确的构建方式
| 用途 | Dockerfile Target | 镜像标签 | 镜像大小 |
|------|-------------------|----------|----------|
| **Staging 部署** | `--target production` | `:test` | ~50MB |
| **Production 部署** | `--target production` | `:latest` | ~50MB |
| **运行单元测试** | `--target test` | 无需推送 | ~900MB+ |
### 常见错误
❌ **错误做法**：用 `--target test` 构建部署镜像
```bash
# 错误！这会生成 900MB+ 的镜像，包含测试框架和源代码
docker buildx build --target test -t xxx:test ...
```
✅ **正确做法**：用 `--target production` 构建部署镜像
```bash
# 正确！生成 ~50MB 的精简镜像，只包含二进制文件
docker buildx build --target production -t xxx:test ...
```
### Staging vs Production 镜像区别
两者都使用 `--target production` 构建，区别在于：
| 区别点 | Staging (`:test`) | Production (`:latest`) |
|--------|-------------------|------------------------|
| 镜像标签 | `:test` | `:latest` |
| 前端 API URL | `staging.ai.pipexerp.com` | `ai.pipexerp.com` |
| 后端代码 | 完全相同 | 完全相同 |
| 部署服务器 | singapore | tools_ai_proj |
> **注意**: 不是把 staging 镜像部署到生产，而是测试通过后用生产 URL **重新构建** `:latest` 镜像
## Staging 部署
### 前置条件
> ⚠️ **必须完成本机测试才能部署 staging**
| 检查项 | 说明 |
|--------|------|
| 代码评审 | `/req cr` 已完成 |
| 后端单元测试 | `go test ./... -v` 全部通过 |
| **前端截图验证** | 使用 chrome-dev MCP 截图确认 UI 正确显示 |
如果本机测试未通过，将拒绝部署并提示：
```
→ ❌ 本机测试未完成，禁止部署到 staging
→ 请先执行: /req test REQ-XXX
```
### 命令格式
```bash
/req deploy REQ-XXX --env staging [--service <service>]
```
### 支持的服务
| 服务 | 说明 |
|------|------|
| `backend` | 后端 API 服务 |
| `frontend` | 前端 Web 应用 |
| `all` | 全部服务（默认） |
### 执行流程
1. **构建镜像**（本地执行）
```bash
# 后端
docker buildx build --platform linux/amd64 \
-f backend/Dockerfile --target production \
-t saltthing123/ai-proj-backend:test --push backend/
# 前端（注意 API URL 配置）
docker buildx build --platform linux/amd64 \
-f frontend/Dockerfile.prod --target production \
--build-arg REACT_APP_API_URL=https://staging.ai.pipexerp.com/api/v1 \
--build-arg REACT_APP_API_BASE_URL=https://staging.ai.pipexerp.com/api/v1 \
-t saltthing123/ai-proj-frontend:test --push frontend/
```
2. **部署命令**（用户手动执行）
```bash
ssh singapore "cd /opt/ai-project-staging && \
sudo docker-compose pull && \
sudo docker-compose up -d"
```
3. **验证**
```bash
curl -s https://staging.ai.pipexerp.com/api/v1/health | jq .
```
## Production 部署
### 命令格式
```bash
/req deploy REQ-XXX --env production [--service <service>]
```
### 支持的服务
| 服务 | 镜像名 | Jenkins 参数 |
|------|--------|--------------|
| `backend` | saltthing123/ai-proj-backend | SERVICE=backend |
| `frontend` | saltthing123/ai-proj-frontend | SERVICE=frontend |
| `ios` | - | SERVICE=ios |
| `android` | - | SERVICE=android |
| `all` | 全部 | SERVICE=all（默认） |
### 执行流程
1. **构建镜像**（本地执行）
```bash
# 后端
docker buildx build --platform linux/amd64 \
-f backend/Dockerfile --target production \
-t saltthing123/ai-proj-backend:latest --push backend/
# 前端
docker buildx build --platform linux/amd64 \
-f frontend/Dockerfile.prod --target production \
--build-arg REACT_APP_API_URL=https://ai.pipexerp.com/api/v1 \
--build-arg REACT_APP_API_BASE_URL=https://ai.pipexerp.com/api/v1 \
-t saltthing123/ai-proj-frontend:latest --push frontend/
```
2. **触发 Jenkins 部署**
```bash
source ~/.config/devops/credentials.env
curl -X POST "$JENKINS_URL/job/ai-proj/buildWithParameters" \
-u "$JENKINS_USER:$JENKINS_TOKEN" \
--data "SERVICE=backend&IMAGE_TAG=latest"
```
3. **查看构建状态**
```bash
source ~/.config/devops/credentials.env
curl -s "$JENKINS_URL/job/ai-proj/lastBuild/api/json" \
-u "$JENKINS_USER:$JENKINS_TOKEN" | jq '.result, .building'
```
4. **验证**
```bash
curl -s https://ai.pipexerp.com/api/v1/health | jq .
```
## 安全约束
- **禁止自动 SSH 部署到生产服务器**
- 生产环境部署必须通过 Jenkins API 触发
- Staging 部署命令只显示，由用户手动执行
- 构建失败时必须显示错误原因和解决方案
## 项目配置
### AI-Proj
| 配置项 | 值 |
|--------|-----|
| Jenkins Job | ai-proj |
| Staging 服务器 | singapore |
| Production 服务器 | tools_ai_proj |
| DockerHub 用户 | saltthing123 |
### Coolbuy-Paas
| 配置项 | 值 |
|--------|-----|
| Jenkins Job | coolbuy-paas |
| Staging 服务器 | fnos 测试环境 |
| Production 服务器 | 39.106.88.83 |
| DockerHub 用户 | saltthing123 |
## 常见问题
### Docker 推送失败
**错误**: `push access denied`
**解决**:
```bash
docker login
# 输入 Docker Hub 凭据
```
### Jenkins 构建失败
**查看日志**:
```bash
source ~/.config/devops/credentials.env
curl -s "$JENKINS_URL/job/ai-proj/lastBuild/consoleText" \
-u "$JENKINS_USER:$JENKINS_TOKEN" | tail -100
```
### 镜像架构不匹配
**错误**: `exec format error`
**原因**: 在 ARM64 (M1/M2 Mac) 构建的镜像部署到 AMD64 服务器
**解决**: 构建时必须指定 `--platform linux/amd64`
### 镜像体积异常大（900MB+）
**错误**: 构建的镜像超过 100MB
**原因**: 使用了错误的 Dockerfile target
**检查**:
```bash
# 查看镜像层大小
docker history <image>:<tag> --no-trunc --format "{{.Size}}\t{{.CreatedBy}}" | head -10
```
**常见原因**:
| 层内容 | 大小 | 说明 |
|--------|------|------|
| `go mod download` | 600MB+ | Go 依赖包（不应出现在生产镜像） |
| `ginkgo/gomega` | 200MB+ | 测试框架（不应出现在生产镜像） |
| `COPY . .` | 100MB+ | 源代码（不应出现在生产镜像） |
**解决**: 确保使用 `--target production` 而不是 `--target test`
```bash
# 错误
docker buildx build --target test ...
# 正确
docker buildx build --target production ...
```

55
skills-req/req-plugin/docs/hook-sync.md Normal file
View File

@@ -0,0 +1,55 @@
# Hook 自动同步机制
Hook 机制可在特定事件发生时自动触发同步，无需手动执行。
## 支持的 Hook 事件
| 事件 | 触发条件 | 自动执行操作 |
|------|---------|-------------|
| `requirement.created` | 创建新需求 | 同步需求到远程 |
| `requirement.submitted` | 提交评审 | 发送评审通知 |
| `requirement.approved` | 需求评审通过 | 同步需求 + 关联任务到远程 |
| `requirement.archived` | 需求归档 | 最终同步 + 同步到思源笔记 + 发送通知 |
| `task.completed` | 任务完成 | 同步任务状态到远程 |
## 配置 Hook
在 `.claude/settings.local.json` 中配置：
```json
{
"hooks": {
"requirement.approved": {
"enabled": true,
"actions": ["sync_requirement_to_remote", "sync_tasks_to_remote"]
},
"requirement.archived": {
"enabled": true,
"actions": ["sync_requirement_to_remote", "sync_to_siyuan", "send_notification"]
},
"task.completed": {
"enabled": true,
"actions": ["sync_task_to_remote"]
}
}
}
```
## 手动触发 Hook
```bash
/req hook trigger requirement.approved REQ-2026-0010
```
## 查看 Hook 执行历史
```bash
/req hook history REQ-2026-0010
```
## 禁用/启用 Hook
```bash
/req hook disable REQ-2026-0010
/req hook enable REQ-2026-0010
```

64
skills-req/req-plugin/docs/mcp-auth-config.md Normal file
View File

@@ -0,0 +1,64 @@
# MCP 认证配置
## 环境选择原则
> 需求和任务的主数据源是**生产环境 (ai.pipexerp.com)**。
> 所有需求创建、任务创建、查询、更新操作必须在生产环境执行。
| 环境 | 用途 | API 地址 |
|------|------|----------|
| **生产环境** | 需求创建、任务创建、数据管理 | https://ai.pipexerp.com/api/v1 |
| 本地环境 | 代码开发调试、功能测试 | http://localhost:8080/api/v1 |
## MCP 配置
确保 `~/.claude/.mcp.json` 配置：
```json
{
"mcpServers": {
"ai-proj": {
"type": "stdio",
"command": "node",
"args": ["/path/to/mcp-task-bridge/dist/index.js"],
"env": {
"TASK_API_BASE": "https://ai.pipexerp.com/api/v1",
"TASK_API_TOKEN": "aiproj_pk_xxxxxxxx...",
"SYNC_REMOTE_API_BASE": "https://ai.pipexerp.com/api/v1",
"SYNC_REMOTE_API_KEY": "aiproj_pk_xxxxxxxx..."
}
}
}
}
```
## 认证方式
### PAT 秘钥（推荐）
- 格式: `aiproj_pk_` + 64 字符十六进制（共 74 字符）
- 优势: 长期有效，无需频繁更新
### dev-quick-login（备选）
仅在 PAT 秘钥不可用时使用：
```bash
curl -s -X POST "http://localhost:8080/api/v1/auth/dev-quick-login" \
-H "Content-Type: application/json" \
-d '{"username":"qiudl"}' | jq -r '.data.access_token'
```
> JWT token 有效期 24 小时，日常使用推荐 PAT 秘钥。
## 验证 PAT 秘钥
```bash
# 测试本地
curl -s -H "X-API-Key: aiproj_pk_xxx..." \
"http://localhost:8080/api/v1/tasks?limit=1" | jq '.success'
# 测试远程
curl -s -H "Authorization: Bearer aiproj_pk_xxx..." \
"https://ai.pipexerp.com/api/v1/tasks?limit=1" | jq '.success'
```

42
skills-req/req-plugin/docs/notification-config.md Normal file
View File

@@ -0,0 +1,42 @@
# 通知与自动化配置
## 邮件通知
### 默认邮件组
| 收件人 |
|--------|
| qiudl@zhiyuncai.com |
| fuxing@zhiyuncai.com |
| haiqing@zhiyuncai.com |
| wuweier@zhiyuncai.com |
### 通知类型
| 类型 | 触发时机 | 邮件主题 | 附件文档 |
|------|----------|----------|----------|
| `prd` | PRD完成 | [REQ-PRD] REQ-XXXX PRD文档已完成 | 01-PRD.md |
| `dev` | 开发完成 | [REQ-开发] REQ-XXXX 开发完成 | 02-开发设计.md |
| `test` | 测试完成 | [REQ-测试] REQ-XXXX 测试完成 | 03-测试报告.md |
| `deploy` | 发布完成 | [REQ-发布] REQ-XXXX 已发布 | 04-发布记录.md |
| `archive` | 归档 | [REQ-归档] REQ-XXXX 已归档 | 05-生命周期总结.md |
### 使用方式
```bash
# 使用默认邮件组
/req notify REQ-2026-0007 --type deploy
# 自定义收件人
~/.claude/skills/req/notify.sh -r REQ-2026-0007 -t deploy -e "user1@example.com,user2@example.com"
# 不发送附件
~/.claude/skills/req/notify.sh -r REQ-2026-0007 -t archive -n
```
## 脚本文件
| 脚本 | 功能 | 位置 |
|------|------|------|
| notify.sh | 发送邮件通知 | ~/.claude/skills/req/ |
| update-siyuan-release.sh | 更新思源笔记发布记录 | ~/.claude/skills/req/ |

126
skills-req/req-plugin/docs/prd-review-guide.md Normal file
View File

@@ -0,0 +1,126 @@
# PRD 评审方法论
> 评审 PRD 是需求流程中的关键质量关卡。
## 评审流程
1. **结构完整性检查** - 检查 PRD 是否包含所有必要章节
2. **需求清晰度评估** - 验证需求描述是否明确无歧义
3. **技术可行性分析** - 评估技术方案是否可实现
4. **数据模型验证** - 检查数据结构设计是否合理
5. **API 设计审查** - 验证接口设计是否符合规范
## PRD 评审检查清单
### 一、结构完整性检查
| 检查项 | 必须 | 说明 |
|--------|------|------|
| 基本信息 | ✓ | 需求编号、标题、创建日期、作者 |
| 需求背景 | ✓ | 为什么需要这个功能 |
| 目标用户 | ✓ | 明确功能面向的用户群体 |
| 功能描述 | ✓ | 详细的功能需求说明 |
| 用户故事 | ○ | As a... I want... So that... |
| 数据模型 | ✓ | 数据库表结构设计 |
| API 设计 | ✓ | RESTful 接口定义 |
| 页面原型 | ○ | 界面布局和交互说明 |
| 非功能需求 | ○ | 性能、安全、可用性要求 |
| 验收标准 | ✓ | 明确的功能验收条件 |
> ✓ = 必须包含, ○ = 建议包含
### 二、需求清晰度评估（SMART 原则）
| 原则 | 检查点 | 示例 |
|------|--------|------|
| **S**pecific | 需求描述是否具体明确 | ❌ "支持搜索" → ✅ "支持按需求编号、标题模糊搜索" |
| **M**easurable | 是否有量化指标 | ❌ "快速响应" → ✅ "响应时间 < 200ms" |
| **A**chievable | 技术上是否可行 | 评估现有技术栈能否支持 |
| **R**elevant | 是否与业务目标相关 | 功能是否解决实际问题 |
| **T**ime-bound | 是否有明确的时间范围 | 开发周期、上线日期 |
### 三、技术可行性分析
| 检查维度 | 评估内容 |
|----------|----------|
| 技术栈兼容性 | 现有技术栈是否支持所需功能 |
| 系统架构影响 | 是否需要修改现有架构 |
| 第三方依赖 | 是否引入新的外部依赖 |
| 性能影响 | 对系统性能的潜在影响 |
| 安全考量 | 是否存在安全风险 |
| 数据迁移 | 是否需要数据迁移方案 |
### 四、数据模型验证
| 检查项 | 说明 |
|--------|------|
| 表结构设计 | 字段类型、约束、索引是否合理 |
| 关联关系 | 外键、多对多关系是否正确 |
| 命名规范 | 表名、字段名是否符合项目规范 |
| 扩展性 | 是否预留扩展字段 |
| 数据量预估 | 数据增长预估和存储方案 |
| 查询性能 | 常用查询是否有索引支持 |
### 五、API 设计审查
| 检查项 | 标准 |
|--------|------|
| RESTful 规范 | URL 使用名词、HTTP 方法语义正确 |
| 响应格式 | 统一的响应结构 `{success, data, message}` |
| 错误处理 | 明确的错误码和错误信息 |
| 分页设计 | 列表接口支持分页 `?page=1&page_size=20` |
| 参数验证 | 必填参数、类型、范围说明 |
| 版本控制 | API 路径包含版本 `/api/v1/...` |
## 评审意见模板
### 通过模板
```
✅ PRD 评审通过
【评审结论】
PRD 文档结构完整，需求描述清晰，技术方案可行，建议批准进入开发阶段。
【肯定之处】
- 需求背景阐述清晰
- 数据模型设计合理
- API 接口规范
【建议改进】（非阻塞）
- 建议补充性能测试用例
- 建议增加边界条件说明
【评审人】xxx
【评审时间】2026-01-24 10:00
```
### 驳回模板
```
❌ PRD 评审驳回
【驳回原因】
1. 数据模型缺少索引设计
2. API 接口缺少错误处理说明
3. 搜索功能需求描述模糊
【修改要求】
□ 补充数据表索引设计
□ 明确 API 错误码定义
□ 细化搜索功能的具体实现方式
【驳回人】xxx
【驳回时间】2026-01-24 10:00
```
## 常见驳回原因
| 类别 | 常见问题 | 改进建议 |
|------|----------|----------|
| 结构缺失 | 缺少数据模型或 API 设计 | 补充完整的技术设计章节 |
| 需求模糊 | 功能描述不够具体 | 按 SMART 原则重新描述 |
| 边界不清 | 缺少边界条件和异常处理 | 补充边界条件和错误场景 |
| 设计缺陷 | 数据模型或 API 设计不合理 | 重新设计并说明理由 |
| 范围过大 | 需求范围过大难以实现 | 拆分为多个小需求 |
| 验收不明 | 缺少验收标准 | 补充可验证的验收条件 |

50
skills-req/req-plugin/docs/siyuan-integration.md Normal file
View File

@@ -0,0 +1,50 @@
# 思源笔记集成
需求的 5 阶段文档统一存储到思源笔记中。
## 文档结构
```
需求管理/
└── REQ-2026-XXXX/
├── 01-PRD.md # 产品需求文档
├── 02-开发设计.md # 开发技术文档
├── 03-测试报告.md # 测试验收报告
├── 04-发布记录.md # CI/CD发布记录
└── 05-生命周期总结.md # 需求归档总结
```
## 同步命令
```bash
/req sync-siyuan REQ-2026-0007
```
## 自动同步时机
| 阶段 | 触发命令 | 同步文档 |
|------|---------|---------|
| PRD 完成 | `/req review` | 01-PRD.md |
| 开发完成 | `/req test` | 02-开发设计.md |
| 测试完成 | `/req deploy` | 03-测试报告.md |
| 发布完成 | 发布任务完成 | 04-发布记录.md |
| 归档完成 | `/req done` | 05-生命周期总结.md (全量同步) |
## MCP 工具调用
```python
# 创建文档
mcp__siyuan__createDocWithMd(
notebook="需求管理",
path="/REQ-2026-0007/01-PRD",
markdown=prd_content
)
```
## 配置
环境变量（可选）：
```bash
export SIYUAN_URL="http://100.118.62.18:6806"
export SIYUAN_TOKEN="your-token"
```

177
skills-req/req-plugin/docs/test-guide.md Normal file
View File

@@ -0,0 +1,177 @@
# 测试环境流程指南
> 测试必须按照以下环境顺序依次进行，每个环境通过后才能进入下一个环境。
## 测试环境流程
```
[1] 本机环境 ─── 通过 ──→ [2] 预发布环境 ─── 通过 ──→ [3] 生产环境
│ │ │
↓ 失败 ↓ 失败 ↓ 失败
修复并重测 回到步骤[1] 回到步骤[1]
```
## 项目环境配置表
| 项目 | 本机环境 | 预发布环境 | 生产环境 |
|------|---------|-----------|---------|
| ai-proj | localhost:3000/8080 | staging.ai.pipexerp.com | ai.pipexerp.com |
| coolbuy-paas | localhost | fnos 测试环境 | 39.106.88.83:8888 |
| coolbuy-platform | localhost | fnos 测试环境 | 生产服务器 |
## 第一阶段：本机测试环境
> ⚠️ **关键约束**：本机测试必须全部通过，才能部署到 staging 环境。
**测试内容**：
- 单元测试 - 测试单个函数/方法，Mock 外部依赖
- 集成测试 - 测试模块间交互，使用测试数据库
- 功能验证 - 验证功能逻辑正确性
- **前端截图验证** - 使用 chrome-dev MCP 截图确认 UI 显示正确
### 后端测试
```bash
# Go 后端单元测试
go test ./... -v
# 指定模块测试
go test ./backend/handlers/... -v
go test ./backend/services/... -v
```
### 前端截图验证（⚠️ 必须步骤）
> **重要**：前端改动必须通过截图验证，不能只测后端 API。这一步经常被忽略，导致功能未正确显示。
**验证流程**：
1. **确保本机服务运行**
```bash
# 终端1：后端
cd backend && go run main.go
# 终端2：前端
cd frontend && npm start
```
2. **使用 chrome-dev MCP 截图验证**
```python
# 步骤1：导航到目标页面
mcp__chrome-dev__navigate_page(url="http://localhost:3000/requirements/686")
# 步骤2：等待页面加载完成（可选）
mcp__chrome-dev__wait_for(selector=".requirement-detail")
# 步骤3：截图
mcp__chrome-dev__take_screenshot()
# 步骤4：检查截图中功能是否正确显示
# - 新增的列/字段是否显示
# - 样式是否正确
# - 数据是否正确渲染
```
3. **常见验证场景**
| 改动类型 | 验证页面 | 检查项 |
|---------|---------|--------|
| 列表新增列 | 列表页面 | 新列是否显示、数据是否正确 |
| 表单新增字段 | 表单页面 | 字段是否显示、能否正常输入 |
| 样式调整 | 相关页面 | 样式是否生效、布局是否正确 |
| 权限控制 | 相关页面 | 按钮/菜单是否正确显示/隐藏 |
4. **截图保存**
- 截图应保存到测试任务文档中作为验证记录
- 命名规范：`REQ-XXXXX-本机测试-功能名称.png`
### 前端截图验证示例
```
/req test REQ-20260125-0002
→ 检查代码评审... ✓ 已完成
→ 验证开发任务... ✓ 已完成
=== 本机测试阶段 ===
1. 后端单元测试
→ go test ./backend/handlers/requirement_handler_test.go -v
→ ✓ 3/3 测试通过
2. 前端截图验证
→ 启动 chrome-dev MCP...
→ 导航到: http://localhost:3000/requirements/687
→ 截图验证...
→ ✓ 任务ID列正确显示 (#5284 格式)
→ ✓ 列宽度和样式正确
→ 截图已保存
=== 本机测试通过 ===
→ 可以执行: /req deploy REQ-20260125-0002 --env staging
```
### 通过标准
- [ ] 所有后端单元测试通过
- [ ] **前端截图验证通过**（有前端改动时必须）
- [ ] 功能在本地环境正常运行
- [ ] 无控制台错误
- [ ] 截图已保存到测试文档
### 跳过前端验证
仅当改动不涉及前端时，可使用 `--backend-only` 参数：
```bash
/req test REQ-XXXXX --backend-only
```
## 第二阶段：预发布环境
**测试内容**：
- E2E 测试 - 测试完整用户流程
- 跨浏览器测试 - Chrome、Firefox、Safari
- 性能测试 - 页面加载时间、API 响应时间
**通过标准**：
- [ ] 功能在预发布环境正常运行
- [ ] 与生产环境配置一致
- [ ] 无跨环境兼容性问题
## 第三阶段：生产环境
**测试内容**：
- UAT 验收 - 用户验收测试
- 冒烟测试 - 核心功能快速验证
- 回归测试 - 确保未破坏现有功能
**通过标准**：
- [ ] 功能在生产环境正常运行
- [ ] 用户验收通过
- [ ] 无生产环境特有问题
## API 验证清单
```bash
# 1. 本机环境
curl -s "http://localhost:8080/api/v1/requirements?search=REQ-2026" \
-H "Authorization: Bearer $TOKEN" | jq '.data | length'
# 2. 预发布环境
curl -s "https://staging.ai.pipexerp.com/api/v1/requirements?search=REQ-2026" \
-H "X-API-Key: $SYNC_REMOTE_API_KEY" | jq '.data | length'
# 3. 生产环境
curl -s "https://ai.pipexerp.com/api/v1/requirements?search=REQ-2026" \
-H "X-API-Key: $SYNC_REMOTE_API_KEY" | jq '.data | length'
```
## 测试失败处理
| 失败阶段 | 处理方式 |
|---------|---------|
| 本机测试 | 修复代码，重新运行本机测试 |
| 预发布测试 | 修复代码，重新从本机测试开始 |
| 生产环境测试 | 修复代码，重新从本机测试开始 |
> 任何阶段测试失败，修复后必须从本机测试环境重新开始。

120
skills-req/req-plugin/docs/workflow-example.md Normal file
View File

@@ -0,0 +1,120 @@
# 完整开发工作流示例
以「酷采3.0 标签管理模块」为例的完整需求生命周期。
## 第一步：创建需求
```bash
/req new 酷采3.0 商品标签管理模块
```
执行：`mcp__ai-proj__create_requirement` → 自动分配 display_id（如 REQ-2026-0006）
## 第二步：编写 PRD 文档
调用 `req-prd` 技能：
1. 创建 PRD 任务并关联到需求
2. 调用 `mcp__ai-proj__create-and-attach` 写入 PRD 文档
## 第三步：创建开发子任务
```python
# 创建子任务
mcp__ai-proj__create_subtask(parentId=PRD任务ID, title="后端：数据模型设计")
mcp__ai-proj__create_subtask(parentId=PRD任务ID, title="后端：Store/Biz实现")
mcp__ai-proj__create_subtask(parentId=PRD任务ID, title="后端：API Handler实现")
mcp__ai-proj__create_subtask(parentId=PRD任务ID, title="前端：页面开发")
# 批量关联到需求
mcp__ai-proj__link_tasks_to_requirement(requirementId=需求ID, taskIds=[...])
```
## 第四步：提交并审批需求
```bash
/req review # draft → pending
/req review pass # pending → approved
```
## 第五步：执行开发任务
```bash
/req dev REQ-2026-0006
```
按分层架构开发：Model → Store → Biz → Handler → Router
## 第六步：代码评审
```bash
/req cr REQ-2026-0006
```
开发完成后必须进行代码评审，评审通过后才能进入测试。
## 第七步：创建测试任务
```python
mcp__ai-proj__create_subtask(parentId=测试父任务, title="后端：单元测试")
mcp__ai-proj__create_subtask(parentId=测试父任务, title="后端：集成测试")
mcp__ai-proj__create_subtask(parentId=测试父任务, title="E2E：端到端测试")
mcp__ai-proj__create_subtask(parentId=测试父任务, title="UAT：用户验收测试")
```
## 第八步：执行测试
```bash
/req test REQ-2026-0006
```
按环境顺序：本机 → 预发布 → 生产
## 第九步：CI/CD 发布
```bash
/req deploy REQ-2026-0006 --env staging
```
## 第十步：完成归档
```bash
/req done REQ-2026-0006
```
自动生成需求生命周期总结文档，归档需求。
---
## 标准任务结构
```
需求: REQ-2026-XXXX
├── PRD 任务 (父任务，包含 PRD 文档)
│ ├── 后端：数据模型设计 (implementation)
│ ├── 后端：业务层实现 (implementation)
│ ├── 后端：API 实现 (implementation)
│ └── 前端：页面开发 (implementation)
│
├── 代码评审任务 (code_review) ← 必须步骤
│
├── 测试任务 (父任务)
│ ├── 单元测试 (test)
│ ├── 集成测试 (test)
│ ├── E2E测试 (test)
│ └── UAT验收 (test, 包含测试报告)
│
└── 发布任务 (父任务，包含发布记录)
├── Docker 镜像构建 (deploy)
├── 前端资源构建 (deploy)
└── 部署到环境 (deploy)
```
## 5 阶段文档
| 序号 | 文档 | 阶段 |
|------|------|------|
| 01 | PRD | 需求定义 |
| 02 | 开发设计 | 开发实现 |
| 03 | 测试报告 | 测试验收 |
| 04 | 发布记录 | CI/CD部署 |
| 05 | 生命周期总结 | 归档 |