@zhouhao4221/devflow-skills 0.3.6 → 0.3.7

package/plugins/req/templates/requirement-template.md

@@ -0,0 +1,256 @@
+# REQ-XXX: 需求标题
+
+## 元信息
+
+| 属性 | 值 |
+|-----|-----|
+| 编号 | REQ-XXX |
+| 类型 | 后端 / 前端 / 全栈 |
+| 状态 | 草稿 |
+| 模块 | - |
+| 优先级 | P2 |
+| 创建日期 | YYYY-MM-DD |
+| 负责人 | - |
+| branch | - |
+| issue | - |
+
+## 生命周期
+
+<!-- 需求状态流转：草稿 → 待评审 → 评审通过 → 开发中 → 测试中 → 已完成 -->
+
+- [ ] 草稿（编写中）
+- [ ] 待评审
+- [ ] 评审通过
+- [ ] 开发中
+- [ ] 测试中
+- [ ] 已完成
+
+---
+
+## 一、需求描述
+
+### 1.1 背景
+
+简要说明需求产生的背景...
+
+### 1.2 目标
+
+- **功能目标**：本需求要实现的能力...
+- **效果目标**：上线后的预期效果（尽量量化，如提效 XX%、减少 XX 次人工操作）...
+
+### 1.3 客户场景
+
+> 记录客户提出的原始业务场景和诉求
+
+- **场景1**：客户描述...
+- **场景2**：客户描述...
+
+### 1.4 价值
+
+实现后带来的业务价值...
+
+### 1.5 范围与边界
+
+> 明确本期做什么、不做什么，防止范围蔓延
+
+- **本期包含**：...
+- **本期不做**：相关但不纳入当前需求的场景，列出以便对齐预期...
+
+### 1.6 干系人
+
+> 除了提出方，还有哪些人会因此变化受影响
+
+| 角色 | 关注点 | 备注 |
+|------|-------|------|
+| 提出方 | - | - |
+| - | - | - |
+
+---
+
+## 二、功能清单
+
+> 列出所有功能点，开发完成后勾选
+
+- [ ] **功能点1**：描述...
+- [ ] **功能点2**：描述...
+- [ ] **功能点3**：描述...
+
+---
+
+## 三、业务规则
+
+| 类型 | 规则 | 说明 |
+|------|-----|------|
+| 数据校验 | 规则1 | 详细说明 |
+| 状态转换 | 规则2 | 详细说明 |
+| 权限控制 | 规则3 | 详细说明 |
+| 非功能约束 | 规则4 | 性能 / 安全 / 兼容性等约束说明 |
+
+---
+
+## 四、使用场景
+
+### 场景1：XXX
+
+- **角色**：XXX
+- **前置条件**：XXX
+- **基本流程**：
+  1. 用户操作... → 系统响应...
+  2. 用户操作... → 系统响应...
+  3. 用户操作... → 系统响应...
+- **异常流程**：
+  - 条件A → 预期结果
+  - 条件B → 预期结果
+
+### 场景2：XXX
+
+- **角色**：XXX
+- **前置条件**：XXX
+- **基本流程**：
+  1. ...
+- **异常流程**：
+  - ...
+
+---
+
+## 五、数据与交互
+
+> 根据需求类型填写不同内容：
+> - **后端 / 全栈**：描述需要的接口能力和业务语义，技术方案在 `/req:dev` 阶段生成
+> - **前端**：描述页面交互逻辑，`/req:dev` 阶段自动匹配后端接口
+
+### 后端/全栈：接口需求
+
+| 能力 | 输入 | 输出 | 说明 |
+|------|------|------|------|
+| 创建XXX | 业务字段描述 | 创建结果 | 业务语义说明 |
+| 查询XXX | 筛选条件描述 | 列表/详情 | 业务语义说明 |
+
+### 前端：交互逻辑
+
+> 按页面/模块描述用户操作和数据流转，不指定具体接口
+
+**页面：XXX**
+
+| 操作/区域 | 用户行为 | 数据需求 | 交互反馈 |
+|----------|---------|---------|---------|
+| 列表区域 | 进入页面 | 分页数据（字段1、字段2...） | 加载中 → 展示列表 / 空状态 |
+| 搜索 | 输入关键词、选择筛选条件 | 按条件过滤列表 | 实时刷新列表 |
+| 操作按钮 | 点击审核/删除/导出 | 提交操作结果 | 成功提示 / 失败原因 |
+
+---
+
+## 六、测试要点
+
+### 6.1 技术测试
+
+- [ ] 测试点1：描述测试场景和预期结果
+- [ ] 测试点2：描述测试场景和预期结果
+
+### 6.2 验收标准
+
+> 产品/业务方验收时的确认项，描述可观测的业务结果
+
+- [ ] 验收项1：在什么页面/入口，执行什么操作，能看到什么结果
+- [ ] 验收项2：...
+
+### 6.3 手动测试用例
+
+> 执行 `/req:test_new REQ-XXX --type=manual` 生成，供测试人员逐条复测
+
+_待生成_
+
+---
+
+## 七、图示（可选）
+
+> 用 Mermaid 绘制，GitHub/Gitea 原生渲染。主题建议统一用 `neutral`（打印友好、明暗模式兼容）。
+> 无图可删除本节，按需保留下方子节。
+
+### 7.1 流程图（业务流程、用户操作路径）
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+flowchart LR
+  A[开始] --> B{判断}
+  B -->|条件1| C[操作A]
+  B -->|条件2| D[操作B]
+  C --> E[结束]
+  D --> E
+```
+
+### 7.2 时序图（接口调用链、前后端交互）
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+sequenceDiagram
+  participant U as 用户
+  participant F as 前端
+  participant B as 后端
+  U->>F: 触发操作
+  F->>B: 调用接口
+  B-->>F: 返回结果
+  F-->>U: 展示
+```
+
+### 7.3 ER 图 / 状态图（按需）
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+stateDiagram-v2
+  [*] --> 草稿
+  草稿 --> 待审核: 提交
+  待审核 --> 已通过: 审批
+  待审核 --> 已驳回: 驳回
+  已通过 --> [*]
+```
+
+---
+
+## 八、评审记录
+
+| 日期 | 评审人 | 结论 | 意见 |
+|-----|-------|------|------|
+| - | - | - | - |
+
+---
+
+## 九、变更记录
+
+| 日期 | 变更内容 | 影响范围 |
+|-----|---------|---------|
+| YYYY-MM-DD | 初始版本 | - |
+
+---
+
+## 十、关联信息
+
+- **关联需求**：REQ-XXX（前端/后端对应需求，dev 阶段自动读取其 API 设计进行接口映射）
+- **相关文档**：链接
+- **假设**：相信为真但未验证的前提，一旦不成立需重新评估方案（如"假设第三方接口可用率 > 99.9%"、"假设用户规模不超过 10 万"）
+- **外部依赖**：依赖的第三方接口 / 其他团队交付 / 基础设施等，标注预计就绪时间
+- **风险项**：技术风险（方案不确定）/ 数据风险（存量迁移）/ 时间风险（依赖外部排期）
+
+---
+
+## 十一、实现方案
+
+> 本章节在 `/req:dev` 阶段由 AI 分析代码后自动生成，创建需求时无需填写。
+
+### 11.1 数据模型
+
+_开发阶段填充_
+
+### 11.2 API 设计
+
+> 基于第五章接口需求，结合项目代码和 CLAUDE.md API 风格，生成具体技术方案
+
+_开发阶段填充_
+
+### 11.3 文件改动清单
+
+_开发阶段填充_
+
+### 11.4 实现步骤
+
+_开发阶段填充_

package/plugins/req/templates/scripts/test-env.sh

@@ -0,0 +1,226 @@
+#!/bin/bash
+
+# 测试环境启动脚本模板
+# 复制到项目 scripts/ 目录并根据需要修改
+
+set -e
+
+# 颜色定义
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# 配置
+DOCKER_COMPOSE_FILE="docker-compose.test.yml"
+BACKEND_PORT=8080
+FRONTEND_PORT=3000
+MYSQL_PORT=3307
+REDIS_PORT=6380
+
+# 日志函数
+log_info() { echo -e "${GREEN}[INFO]${NC} $1"; }
+log_warn() { echo -e "${YELLOW}[WARN]${NC} $1"; }
+log_error() { echo -e "${RED}[ERROR]${NC} $1"; }
+
+# 等待端口就绪
+wait_for_port() {
+    local host=$1
+    local port=$2
+    local timeout=${3:-30}
+    local counter=0
+
+    while ! nc -z "$host" "$port" 2>/dev/null; do
+        counter=$((counter + 1))
+        if [ $counter -ge $timeout ]; then
+            log_error "等待 $host:$port 超时"
+            return 1
+        fi
+        sleep 1
+    done
+    return 0
+}
+
+# 启动 Docker 容器
+start_docker() {
+    log_info "启动 Docker 容器..."
+    docker-compose -f "$DOCKER_COMPOSE_FILE" up -d
+
+    log_info "等待 MySQL 就绪..."
+    wait_for_port localhost $MYSQL_PORT 60
+    log_info "MySQL 已就绪"
+
+    log_info "等待 Redis 就绪..."
+    wait_for_port localhost $REDIS_PORT 30
+    log_info "Redis 已就绪"
+}
+
+# 启动后端服务
+start_backend() {
+    log_info "启动后端服务..."
+
+    # 检查是否已运行
+    if lsof -i:$BACKEND_PORT > /dev/null 2>&1; then
+        log_warn "后端服务已在运行 (端口 $BACKEND_PORT)"
+        return 0
+    fi
+
+    # 设置测试环境变量
+    export APP_ENV=test
+    export DB_HOST=localhost
+    export DB_PORT=$MYSQL_PORT
+    export DB_NAME=test_db
+    export DB_USER=test_user
+    export DB_PASSWORD=test123
+    export REDIS_HOST=localhost
+    export REDIS_PORT=$REDIS_PORT
+
+    # 启动后端（后台运行）
+    go run main.go > /tmp/backend-test.log 2>&1 &
+    echo $! > /tmp/backend-test.pid
+
+    log_info "等待后端服务就绪..."
+    wait_for_port localhost $BACKEND_PORT 60
+    log_info "后端服务已就绪"
+}
+
+# 启动前端服务（E2E 测试需要）
+start_frontend() {
+    log_info "启动前端服务..."
+
+    # 检查是否已运行
+    if lsof -i:$FRONTEND_PORT > /dev/null 2>&1; then
+        log_warn "前端服务已在运行 (端口 $FRONTEND_PORT)"
+        return 0
+    fi
+
+    # 进入前端目录并启动
+    if [ -d "frontend" ]; then
+        cd frontend
+        npm run dev > /tmp/frontend-test.log 2>&1 &
+        echo $! > /tmp/frontend-test.pid
+        cd ..
+
+        log_info "等待前端服务就绪..."
+        wait_for_port localhost $FRONTEND_PORT 60
+        log_info "前端服务已就绪"
+    else
+        log_warn "未找到 frontend 目录，跳过前端启动"
+    fi
+}
+
+# 停止所有服务
+stop_all() {
+    log_info "停止测试环境..."
+
+    # 停止后端
+    if [ -f /tmp/backend-test.pid ]; then
+        kill $(cat /tmp/backend-test.pid) 2>/dev/null || true
+        rm /tmp/backend-test.pid
+        log_info "后端服务已停止"
+    fi
+
+    # 停止前端
+    if [ -f /tmp/frontend-test.pid ]; then
+        kill $(cat /tmp/frontend-test.pid) 2>/dev/null || true
+        rm /tmp/frontend-test.pid
+        log_info "前端服务已停止"
+    fi
+
+    # 停止 Docker
+    docker-compose -f "$DOCKER_COMPOSE_FILE" down
+    log_info "Docker 容器已停止"
+}
+
+# 清理测试数据
+clean_data() {
+    log_info "清理测试数据..."
+    docker-compose -f "$DOCKER_COMPOSE_FILE" down -v
+    log_info "测试数据已清理"
+}
+
+# 显示状态
+status() {
+    echo ""
+    echo "=== 测试环境状态 ==="
+    echo ""
+
+    # Docker 容器
+    echo "Docker 容器："
+    docker-compose -f "$DOCKER_COMPOSE_FILE" ps 2>/dev/null || echo "  未启动"
+    echo ""
+
+    # 后端服务
+    echo -n "后端服务 (端口 $BACKEND_PORT): "
+    if lsof -i:$BACKEND_PORT > /dev/null 2>&1; then
+        echo -e "${GREEN}运行中${NC}"
+    else
+        echo -e "${RED}未运行${NC}"
+    fi
+
+    # 前端服务
+    echo -n "前端服务 (端口 $FRONTEND_PORT): "
+    if lsof -i:$FRONTEND_PORT > /dev/null 2>&1; then
+        echo -e "${GREEN}运行中${NC}"
+    else
+        echo -e "${RED}未运行${NC}"
+    fi
+
+    echo ""
+}
+
+# 使用说明
+usage() {
+    echo "测试环境管理脚本"
+    echo ""
+    echo "用法: $0 <command>"
+    echo ""
+    echo "命令:"
+    echo "  start       启动完整测试环境（Docker + 后端 + 前端）"
+    echo "  start-api   仅启动 API 测试环境（Docker + 后端）"
+    echo "  stop        停止所有服务"
+    echo "  clean       停止并清理测试数据"
+    echo "  status      查看环境状态"
+    echo "  docker      仅启动 Docker 容器"
+    echo "  backend     仅启动后端服务"
+    echo "  frontend    仅启动前端服务"
+    echo ""
+}
+
+# 主逻辑
+case "${1:-}" in
+    start)
+        start_docker
+        start_backend
+        start_frontend
+        status
+        ;;
+    start-api)
+        start_docker
+        start_backend
+        status
+        ;;
+    stop)
+        stop_all
+        ;;
+    clean)
+        stop_all
+        clean_data
+        ;;
+    status)
+        status
+        ;;
+    docker)
+        start_docker
+        ;;
+    backend)
+        start_backend
+        ;;
+    frontend)
+        start_frontend
+        ;;
+    *)
+        usage
+        exit 1
+        ;;
+esac

package/plugins/req/templates/tests/e2e/playwright.config.ts

@@ -0,0 +1,86 @@
+import { defineConfig, devices } from '@playwright/test';
+
+/**
+ * Playwright 配置模板
+ * 复制到项目 tests/e2e/ 目录并根据需要修改
+ *
+ * 参考文档: https://playwright.dev/docs/test-configuration
+ */
+export default defineConfig({
+  // 测试目录
+  testDir: '.',
+
+  // 测试文件匹配模式
+  testMatch: '**/*.spec.ts',
+
+  // 完全并行运行测试
+  fullyParallel: true,
+
+  // CI 环境下禁止 test.only
+  forbidOnly: !!process.env.CI,
+
+  // 失败重试次数
+  retries: process.env.CI ? 2 : 0,
+
+  // 并行工作进程数
+  workers: process.env.CI ? 1 : undefined,
+
+  // 报告器配置
+  reporter: [
+    ['html', { outputFolder: 'playwright-report' }],
+    ['list'],
+  ],
+
+  // 全局配置
+  use: {
+    // 基础 URL
+    baseURL: process.env.FRONTEND_URL || 'http://localhost:3000',
+
+    // 收集失败测试的 trace
+    trace: 'on-first-retry',
+
+    // 失败时截图
+    screenshot: 'only-on-failure',
+
+    // 失败时录制视频
+    video: 'on-first-retry',
+
+    // 超时设置
+    actionTimeout: 10000,
+    navigationTimeout: 30000,
+  },
+
+  // 全局超时
+  timeout: 60000,
+
+  // 预期超时
+  expect: {
+    timeout: 10000,
+  },
+
+  // 浏览器配置
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    // 可选：添加更多浏览器
+    // {
+    //   name: 'firefox',
+    //   use: { ...devices['Desktop Firefox'] },
+    // },
+    // {
+    //   name: 'webkit',
+    //   use: { ...devices['Desktop Safari'] },
+    // },
+  ],
+
+  // 本地开发时自动启动前端服务
+  // 注意：测试环境脚本会预先启动服务，这里设置 reuseExistingServer: true
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    reuseExistingServer: true,
+    timeout: 120000,
+  },
+});

package/plugins/uat/templates/flow-template.md

@@ -0,0 +1,116 @@
+# <功能名称> 测试流程
+
+## 元信息
+
+| 属性 | 值 |
+|------|-----|
+| 模块 | <module> |
+| 平台 | web |
+| 入口 | http://localhost:3000 |
+| 创建日期 | YYYY-MM-DD |
+| 最后执行 | - |
+| 生成方式 | 手动（/uat:new）|
+
+> 平台可选值：`web`（浏览器）/ `desktop`（桌面应用）/ `mobile-web`（移动端浏览器）
+> 生成方式可选值：`手动（/uat:new）` / `代码分析（/uat:analyze）` / `手动 + 补充分析`
+
+---
+
+## 测试数据
+
+全局复用的测试数据，场景中直接引用字段名：
+
+| 字段 | 值 | 说明 |
+|------|-----|------|
+| 用户名 | test@example.com | 测试账号 |
+| 密码 | test123456 | - |
+
+---
+
+## 已知结论
+
+已验证、本次直接跳过的路径（执行时标记 SKIP，不重复验证）：
+
+- （示例：`手工新增接口返回 500` — 已知 Bug，跳过 S02 手工新增场景）
+
+---
+
+## S01 <场景名称>
+
+**前置条件**：已打开入口页面，用户未登录
+
+**数据准备**（可选）：
+- 在系统中提前创建所需数据（参见测试数据说明）
+
+**数据清理**（新增场景必填）：
+- 找到「测试客户」这条记录，点击删除，确认弹窗
+
+**步骤**：
+1. 在客户名称输入框输入「测试客户」
+2. 点击保存按钮
+3. 确认列表中出现「测试客户」这条记录
+
+> **步骤写法说明**：
+> - 用自然语言描述操作意图，不需要写选择器
+> - 如果知道 `data-testid` 可以写在括号里作为提示，如：点击保存按钮（testid: customer-submit-button）
+> - 下拉/级联选择直接写目标值：「在省市区选择框选择「广东省 → 广州市 → 天河区」」
+> - 预期结果写可观察的状态：文字出现/消失、页面跳转、提示内容
+
+**预期结果**：
+- 列表中出现「测试客户」这条记录
+- 页面显示「保存成功」提示
+
+---
+
+## S02 <场景名称>
+
+**前置条件**：...
+
+**数据准备**（可选）：...
+
+**步骤**：
+1. ...
+
+**预期结果**：
+- ...
+
+---
+
+## SXX 表单边界 & 字符类型（推荐随业务场景同步补充）
+
+> 对每个有「新增 / 编辑」表单的功能，补充此场景。
+
+**前置条件**：已打开表单，处于可输入状态
+
+**字段清单**（按实际表单填写）：
+
+| 字段 | 最大长度 | 最小长度 | 类型约束 |
+|------|---------|---------|---------|
+| 客户名称 | 50 | 1 | 中英文数字 |
+| 手机号 | 11 | 11 | 数字 |
+
+**测试矩阵**（对每个字段逐一执行）：
+
+| # | 输入类型 | 示例输入 | 预期结果 |
+|---|---------|---------|---------|
+| B1 | 空值 / 必填 | （清空） | 内联提示「XX 不能为空」，不提交 |
+| B2 | 最大长度 + 1 | 超出 maxLength 1 位的字符串 | 截断输入 或 提示超限，不提交 |
+| B3 | 最小长度 - 1 | 少于 minLength 1 位 | 提示长度不足，不提交 |
+| C1 | 纯中文 | 张三李四 | 正常接受并保存 |
+| C2 | 中英文混合 | abc张三 | 正常接受并保存 |
+| C3 | 特殊字符 | `< > & " '` | 正常保存（展示时转义，不破坏页面） |
+| C4 | 潜在 XSS | `<script>alert(1)</script>` | 正常保存，展示为文本，脚本不执行 |
+| C5 | 首尾空格 | ` 测试 ` | 自动 trim 或原样保留（明确业务规则） |
+| C6 | Emoji | | 正常接受 或 提示不支持（视业务规则） |
+| C7 | 全角字符 | ａｂｃ１２３ | 正常接受 或 提示仅支持半角（视业务规则） |
+
+> 按需裁剪：不适用的行可删除；字段有特殊约束（仅数字、手机格式等）需额外补充。
+
+**步骤**（对每个字段，按测试矩阵逐行执行）：
+1. 清空字段，输入当前测试行的示例值
+2. 点击提交按钮，等待页面反馈
+3. 记录实际结果，对比预期
+
+**预期结果**：
+- B1-B3（边界）：验证失败时表单内联提示，不提交
+- C1-C7（字符）：合法字符正常保存；详情页展示不乱码、不执行脚本