@chenmk/superflow 0.1.0

package/assets/skills/superflow-pipeline/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "SDD Router"
+  short_description: "优先路由到 OpenSpec 技能，并补充 SDD 质量门"
+  default_prompt: "Use $superflow-pipeline to choose the right OpenSpec or SDD phase skill for this request."

package/assets/skills/superflow-pipeline/references/api-design-template.md

@@ -0,0 +1,431 @@
+# 接口设计文档模板
+
+独立于 tests.md 的接口规格说明，用于完整描述每个接口的契约。
+
+## API 先行硬规则
+
+- 涉及前后端联调时，必须先输出粗接口草案给编程人员确认，再生成正式 `api.md`。
+- 正式 `api.md` 必须在 `design.md`、`tasks.md`、`tests.md` 和实现 prompt 之前冻结。
+- `design.md` 必须引用已冻结 `api.md` 的字段和错误语义，不得另起一套字段口径。
+- 页面、原型和产品文字都没有，且编程人员未确认的字段，不得设为 API 必填项。
+- 后端必需但前端不提交的字段，必须在字段映射中标记为"后端默认"或"后端推导"。
+
+## 文档结构
+
+```markdown
+# API 设计文档：<模块名称>
+
+## 0. 变更概览（本次提测变更）
+
+> **本节为提测变更增量视图，完整历史见第 8 节。变更标注规则详见 `api-doc-changelog` 技能。**
+
+首次版本：
+```markdown
+## 0. 变更概览（本次提测变更）
+
+> 首个版本，全部接口为新增。详见接口列表。
+```
+
+迭代版本（更新时必须填写）：
+```markdown
+## 0. 变更概览（本次提测变更）
+
+> 基线版本：v1.0 | 当前版本：v1.1 | 变更日期：2026-05-22
+
+### 新增接口
+
+| 接口 | 说明 |
+|------|------|
+| `POST /api/xxx` | 新增 xxx 功能 |
+
+### 修改接口
+
+| 接口 | 变更摘要 |
+|------|----------|
+| `GET /api/yyy` | 新增 query 参数 `keyword`；响应增加 `tag` 字段 |
+
+### 废弃接口
+
+| 接口 | 替代方案 | 移除计划 |
+|------|----------|----------|
+| `GET /api/old` | 使用 `GET /api/new` | v2.0 移除 |
+```
+
+**变更标注规则：**
+- 变更接口标题后加标签：`[新增]` / `[修改]` / `[废弃]`
+- 变更字段说明列末尾加标注：`【本次新增】` / `【本次变更：具体改了什么】` / `【本次废弃】`
+- 下一轮提测时清除上一轮所有标签和标注
+- 详细规则参见 `api-doc-changelog` 技能
+
+---
+
+## 1. 通用约定
+
+### 1.0 参数命名约束
+- 在填写接口参数前，**必须先检查目标仓库现有 Controller、Query DTO、分页基类、历史 `api.md`**，复用已有命名。
+- 不得因为新文档是 AI 生成就擅自切换参数口径，例如已有代码主流使用 `pageNo/pageSize` 时，不得写成 `pageNum/pageSize`。
+- 分页、排序、筛选字段优先跟随现有代码模型命名，而不是套用通用模板名。
+
+### 1.0.1 前端契约对账约束
+- 涉及页面、弹窗、列表、下拉框或前端联调时，先列出原始需求/原型字段，再映射到 API 字段、DTO/VO 字段和数据库字段。
+- 字段名不一致时必须写明兼容策略：后端兼容前端字段、前端改字段、或双字段过渡。
+- 字段被合并表达时必须写明规则，例如前端 `{limitType} + {limitValue}` 如果映射为后端 `{businessLimit}`，必须说明每个哨兵值和正数值的业务含义。
+- 下拉框必须有数据来源接口。若复用既有接口，必须写原路径、请求参数、响应字段和鉴权方式；若需要新增 facade，必须写新增路径。
+- 页面、原型和产品文字都没有的字段，默认不得作为必填入参；若后端确实需要，必须写明由后端默认或后端推导。
+
+### 1.1 基础信息
+- **Base URL**: `http://{host}:{port}{context-path}`
+- **Content-Type**: `application/json`
+- **字符编码**: UTF-8
+- **时间格式**: `yyyy-MM-dd HH:mm:ss`
+
+### 1.2 认证方式
+- [ ] JWT Bearer Token（Header: `Authorization: Bearer {token}`）
+- [ ] HMAC-SHA256 签名（Headers: `X-Timestamp`, `X-Nonce`, `X-Sign`）
+- [ ] API Key（Header: `X-Api-Key`）
+- [ ] 其他：____
+
+### 1.3 通用响应格式
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {}
+}
+```
+
+### 1.4 全局错误码
+
+| 错误码 | 说明 | HTTP 状态码 |
+|--------|------|-------------|
+| 0 | 成功 | 200 |
+| 400 | 请求参数错误 | 400 |
+| 401 | 未授权 | 401 |
+| 403 | 禁止访问 | 403 |
+| 404 | 资源不存在 | 404 |
+| 500 | 服务器内部错误 | 500 |
+| 1001 | 业务错误：____ | 200 |
+
+---
+
+## 2. 接口列表
+
+### 2.1 接口名称
+
+#### 基本信息
+- **接口路径**: `POST /api/v1/xxx`
+- **接口说明**: ____
+- **调用方**: [前端 / 移动端 / 第三方 / 内部服务]
+- **是否需要认证**: [是 / 否]
+
+#### 请求参数
+
+**Path 参数**
+| 参数名 | 类型 | 必填 | 说明 |
+|--------|------|------|------|
+| id | Long | 是 | 资源 ID |
+
+**Query 参数**
+| 参数名 | 类型 | 必填 | 说明 | 示例 |
+|--------|------|------|------|------|
+| pageNo | Integer | 否 | 页码，默认 1；若仓库已有分页对象使用其他命名，则必须以源码为准 | 1 |
+| pageSize | Integer | 否 | 每页大小，默认 20；若仓库已有分页对象使用其他命名，则必须以源码为准 | 20 |
+
+**请求体（Body）**
+```json
+{
+  "field1": "string",    // 必填，说明
+  "field2": 0,           // 可选，说明，默认 0
+  "field3": ["item"]     // 可选，数组说明
+}
+```
+
+| 字段 | 类型 | 必填 | 说明 | 校验规则 |
+|------|------|------|------|----------|
+| field1 | String | 是 | ____ | 长度 1-64 |
+| field2 | Integer | 否 | ____ | 范围 0-100 |
+| field3 | Array | 否 | ____ | 元素个数 0-10 |
+
+#### 字段映射与兼容
+
+| 原型/前端字段 | API 字段 | DTO/VO 字段 | DB 字段 | 取值/枚举 | 来源 | 策略 |
+|---|---|---|---|---|---|---|
+| ____ | ____ | ____ | ____ | ____ | PRD / 原型 / 源码 / 后端推导 | 前端提交 / 后端默认 / 后端推导 / 后端兼容 / 前端改名 / 双字段过渡 / 废弃 |
+
+#### 条件必填与互斥
+
+| 条件 | 必填字段 | 必须为空字段 | 失败提示 |
+|---|---|---|---|
+| ____ | ____ | ____ | ____ |
+
+#### 响应示例
+
+**成功（code = 0）**
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "id": 1,
+    "field1": "value",
+    "createdAt": "2026-05-09 10:00:00"
+  }
+}
+```
+
+**失败（code ≠ 0）**
+```json
+{
+  "code": 1001,
+  "message": "参数错误：field1 不能为空",
+  "data": null
+}
+```
+
+#### 边界说明
+- 字段为 null 时的处理：____
+- 数组为空时的处理：____
+- 并发调用时的限制：____
+- 参数命名与现有源码差异：____（若无差异，明确写“无，沿用现有命名”）
+- 前端兼容策略：____（如无兼容需求，明确写“无，前后端字段名一致”）
+
+#### 联调验收 curl
+
+```bash
+curl -s -X POST "http://localhost:{port}{context-path}/api/..." \
+  -H "Content-Type: application/json" \
+  -H "token: $TOKEN" \
+  -d '{...}'
+```
+
+断言：
+- `message.code` / `code`: ____
+- `data` 关键字段：____
+```
+
+---
+
+## 3. 前端真实动作矩阵（强制）
+
+每个页面的按钮/入口必须拆解为具体接口。不得只写"导出""导入""查询"等笼统描述。
+
+```markdown
+### 动作矩阵
+
+| # | 页面/按钮/入口 | Method | URL | Content-Type | 参数位置 | 成功响应形态 | 失败响应形态 | 前端成功判定字段 | 相关角色 | 是否需要外部依赖 |
+|---|---|---|---|---|---|---|---|---|---|---|
+| 1 | {页面}-{按钮} | POST | /api/v1/xxx | application/json | body | JSON: {code:0,data:{}} | JSON: {code:1001,message:""} | code === 0 | 超管/运营商/子账号 | 否 |
+| 2 | {页面}-{导出按钮} | GET | /api/v1/xxx/export | - | query | 文件流(application/octet-stream) | JSON: {code:1001,message:""} | Content-Disposition 存在 | 超管/运营商 | 否 |
+```
+
+参数位置可选项：`path` / `query` / `body` / `form-data` / `file`
+
+### 动作矩阵红线
+
+- 每个前端按钮必须对应一个 Controller mapping，不得一个接口对应多个前端动作。
+- 批量操作（如批量开通/续费/退费）必须为每个动作单独定义接口，不得合并。
+- 模板下载是独立接口，不得复用导入接口。
+- 前端成功判定字段必须写明：JSON 响应用 `code`，文件响应用 `Content-Disposition`。
+
+---
+
+## 4. 文件接口契约（强制，涉及导出/下载/上传时必须填写）
+
+凡是文件导出、文件下载、模板下载、文件上传相关接口，必须在本节明确契约。
+
+```markdown
+### 文件接口契约
+
+| # | 接口 | 类型 | 成功 Content-Type | Content-Disposition | 文件名规则 | 失败响应 | 前端如何判断成功 | 复用列表筛选 | 受分页影响 |
+|---|---|---|---|---|---|---|---|---|---|
+| 1 | GET /api/v1/xxx/export | 导出 | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | attachment; filename="{name}.xlsx" | {模块}_{日期}.xlsx | JSON: {code:1001,message:""} | 响应头含 Content-Disposition | 是 | 否 |
+| 2 | GET /api/v1/xxx/template | 模板下载 | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | attachment; filename="template.xlsx" | {功能}_导入模板.xlsx | JSON: {code:1001,message:""} | 响应头含 Content-Disposition | 否 | 否 |
+```
+
+### 文件接口红线
+
+- 文件流接口成功时不得被统一 JSON 响应包装。Controller 方法必须直接操作 `HttpServletResponse`，不得返回 `Response<T>`。
+- 成功时必须设置 `Content-Type` 和 `Content-Disposition` 响应头。
+- 失败时才返回 JSON 格式的错误信息。
+- 导出接口复用列表筛选条件时，不得受分页参数影响（应导出全部符合条件的记录）。
+- tests.md 必须验证：响应头 Content-Type、Content-Disposition，文件体非空且可打开。
+
+---
+
+## 5. Excel 导入/导出契约（强制，涉及 Excel 导入时必须填写）
+
+```markdown
+### Excel 导入契约
+
+#### 模板定义
+
+| 列序号 | 列头名称 | 对应 DTO 字段 | 必填 | 允许为空 | 数据校验规则 | 说明 |
+|---|---|---|---|---|---|---|
+| 1 | 站点名称 | siteName | 是 | 否 | 长度 1-64 | |
+| 2 | 生效日期 | effectiveDate | 是 | 否 | 日期格式：yyyy-MM-dd 或 yyyy-MM-dd HH:mm:ss | 只有日期时补 00:00:00 |
+| 3 | 业务名称 | recordName | 否 | 是 | 长度 0-64 | |
+
+#### 导入响应
+
+成功导入全部行：
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "totalCount": 10,
+    "successCount": 10,
+    "failureCount": 0,
+    "failureRows": []
+  }
+}
+```
+
+部分失败：
+```json
+{
+  "code": 1002,
+  "message": "部分数据导入失败",
+  "data": {
+    "totalCount": 10,
+    "successCount": 8,
+    "failureCount": 2,
+    "failureRows": [
+      {"row": 3, "reason": "站点不存在"},
+      {"row": 7, "reason": "日期格式错误"}
+    ]
+  }
+}
+```
+
+#### 导入规则
+- failureCount > 0 时，业务 code 必须为非 0（前端通过 code !== 0 判断失败）。
+- 单次导入上限：____ 行。
+- 是否允许同一文件包含多业务类型/多站点/多对象：____。
+- 日期格式必须兼容 yyyy-MM-dd 和 yyyy-MM-dd HH:mm:ss。
+- 行级错误必须保留具体行号和原因。
+```
+
+### Excel 导入红线
+
+- 模板下载 DTO 的 @ExcelProperty 列头必须与导入解析 DTO 的列头完全一致。
+- failureCount > 0 时，禁止使用 `Response.ok(result)` 返回 code=0。
+- 日期字段必须至少覆盖 `yyyy-MM-dd`（Excel 默认短日期）和 `yyyy-MM-dd HH:mm:ss`。
+- tests.md 必须包含短日期和完整时间两种格式的测试用例。
+
+---
+
+## 6. 数据权限（强制，访问业务数据的接口必须填写）
+
+凡是分页、列表、详情、导出、编辑、删除等访问业务数据的接口，都必须先判断是否需要数据权限约束。
+如果需要，必须识别并复用当前仓库已有的数据权限模型和成熟实现，不得凭字段名猜测权限边界。
+如果不确定是否需要，必须在需求/SDD 阶段主动询问用户，未确认前不得进入实现。
+
+### 6.1 每个接口的数据权限字段
+
+每个访问业务数据的接口必须增加以下字段：
+
+```markdown
+**数据权限：**
+- 是否访问业务数据：是/否
+- 是否需要数据权限：需要/不需要/不确定
+- 判断依据：（参考哪个已有接口或需求说明）
+- 权限边界：（当前仓库实际模型，不写死字段名）
+- 复用实现：（参考哪个已有接口、工具类、注解或 AOP）
+- 超管/平台管理员行为：
+- 普通管理员行为：
+- 子账号/普通用户行为：
+- 详情越权响应：（返回"无权限"还是"数据不存在"）
+- 导出是否复用列表权限：是/否
+- 待确认问题：（如有）
+```
+
+已确认示例：
+```markdown
+**数据权限：**
+- 是否访问业务数据：是
+- 是否需要数据权限：需要
+- 判断依据：参考现有订单列表接口的数据范围处理
+- 权限边界：复用当前仓库已有的组织/租户/业务主体数据范围模型
+- 复用实现：参考 `OrderController#page` 和 `DataScopeUtil`
+- 超管行为：不追加业务主体过滤，但保留基础状态/删除过滤
+- 普通管理员行为：只能查看所属业务主体范围内的数据
+- 子账号行为：复用当前仓库子账号授权范围
+- 详情越权响应：返回稳定业务错误，不泄露敏感数据
+- 导出是否复用列表权限：是
+```
+
+不确定示例：
+```markdown
+**数据权限：**
+- 是否访问业务数据：是
+- 是否需要数据权限：不确定
+- 不确定原因：PRD 未说明该列表是否按组织/商户/运营主体隔离
+- 待确认问题：超管、普通管理员、子账号分别能看到哪些数据？
+- 状态：阻塞实现
+```
+
+### 6.2 数据权限红线
+
+- 不得凭字段名猜测权限边界（如看到 operatorId 就假设是权限字段）。
+- 不得临时发明一套和当前仓库其他接口不一致的数据过滤逻辑。
+- 列表和导出必须使用同一数据权限口径，除非需求明确不同。
+- 详情/编辑/删除必须防止越权访问，不能只靠前端隐藏按钮。
+- 如果无法判断是否需要数据权限，停止实现，向用户确认。
+
+### 6.3 不做数据权限的说明
+
+如果某个接口不做数据权限，必须说明原因，例如：
+- 公开字典/枚举/配置接口
+- 无业务敏感数据
+- 只返回当前用户上下文
+- 已由统一注解/AOP/网关控制
+- 需求明确要求全局可见
+
+### 6.4 待确认问题格式
+
+如果存在不确定项，必须列出并询问用户：
+
+```markdown
+## 数据权限待确认
+
+接口：`GET /xxx/page`
+当前判断：不确定
+不确定原因：该接口访问业务数据，但需求未说明不同角色的数据范围。
+
+请确认以下选项：
+A. 超管看全量，普通管理员/子账号看所属范围
+B. 所有角色都只看所属范围
+C. 这是公共数据，不做数据权限
+D. 复用某个已有接口的数据权限规则，请指定参考接口
+
+确认前该接口不进入实现。
+```
+
+---
+
+## 7. 外部依赖契约（强制，涉及 SDK/第三方/RPC/MQ 时必须填写）
+
+```markdown
+### 外部依赖契约
+
+| # | 依赖名称 | 类型 | SDK 版本 | 参数来源 | 字段含义 | 成功响应样例 | 失败响应样例 | 阻塞时的处理 |
+|---|---|---|---|---|---|---|---|---|
+| 1 | XX SDK | Java SDK | 1.2.3 | 页面表单提交 -> DTO -> SDK Request | appId: 应用ID | {"code":0,"data":{...}} | {"code":500,"message":"timeout"} | 记录阻塞证据，标记外部阻塞 |
+```
+
+### 外部依赖红线
+
+- SDK 参数来源必须写明，不得凭字段名猜测含义。
+- SDK 版本变更必须记录原因和影响范围。
+- 真实环境可用时，不得仅用 mock 代替。必须在 tests.md 记录真实请求/响应。
+- 外部服务不可用时，只能标记为"外部阻塞"或"Mock 验证"，不得宣称真实链路通过。
+
+---
+
+## 8. 接口变更记录
+
+| 版本 | 日期 | 变更内容 | 影响范围 |
+|------|------|----------|----------|
+| v1.0 | 2026-05-09 | 初始版本 | 全部 |

package/assets/skills/superflow-pipeline/references/architecture-design-template.md

@@ -0,0 +1,119 @@
+# 架构设计文档模板（0→1 全新系统）
+
+用于从零开始构建系统的顶层设计文档。增量变更（1→1.1）不需要此文档，使用 design.md 的变更矩阵即可。
+
+## 文档结构
+
+```markdown
+# 架构设计：<系统名称>
+
+## 1. 项目背景与目标
+
+- 业务场景描述
+- 核心目标（1-3 句话）
+- 非目标（明确不做的事）
+
+## 2. 技术选型
+
+| 层级 | 技术 | 版本 | 选型理由 |
+|------|------|------|----------|
+| 后端框架 | Spring Boot | 3.x | 项目技术栈 |
+| ORM | MyBatis / MyBatis-Plus | - | 复杂 SQL 可控 |
+| 数据库 | MySQL | 8.0 | 关系型数据，事务支持 |
+| 缓存 | Redis / Caffeine | - | 按需选择 |
+| 前端 | Vue 3 + Vite | - | 项目前端技术栈 |
+| 构建工具 | Maven / Gradle | - | 按项目约定 |
+| 容器化 | Docker | - | 部署标准化 |
+
+## 3. 系统架构
+
+### 3.1 整体架构图（文字描述）
+
+```
+[前端] → [Nginx] → [Spring Boot 应用] → [MySQL]
+                        ↓
+                    [Redis/缓存]
+                        ↓
+                    [外部服务/Mock]
+```
+
+### 3.2 模块划分
+
+| 模块 | 职责 | 对应包路径 |
+|------|------|-----------|
+| controller | HTTP 接口暴露 | `com.example.module.controller` |
+| service | 业务逻辑编排 | `com.example.module.service` |
+| mapper/dao | 数据访问 | `com.example.module.mapper` |
+| model/entity | 实体定义 | `com.example.module.model` |
+| config | 配置类 | `com.example.module.config` |
+| client | 外部服务调用 | `com.example.module.client` |
+
+## 4. 数据模型
+
+### 4.1 核心实体关系
+
+```
+User 1:N Order
+Order 1:N OrderItem
+```
+
+### 4.2 核心表结构
+
+| 表名 | 说明 | 核心字段 |
+|------|------|----------|
+| `tb_user` | 用户表 | id, username, status, created_at |
+| `tb_order` | 订单表 | id, user_id, status, amount |
+
+## 5. 接口概览
+
+| 接口 | 方法 | 路径 | 说明 |
+|------|------|------|------|
+| 用户注册 | POST | /api/v1/users | 创建用户 |
+| 用户登录 | POST | /api/v1/auth/login | 返回 JWT |
+
+详见 [api-design-template.md](api-design-template.md) 编写完整接口文档。
+
+## 6. Mock 策略
+
+外部依赖清单及 Mock 方案：
+
+| 外部依赖 | 实际能力 | Mock 方式 | 替代验证方式 |
+|----------|----------|-----------|-------------|
+| 支付网关 | 真实支付 | Spring MockBean | 固定返回 success |
+| 短信服务 | 真实发送 | WireMock | 验证调用次数 |
+| 设备回调 | 硬件触发 | 本地模拟 HTTP 服务 | 手动调接口模拟 |
+
+详见 [mock-strategy-guide.md](mock-strategy-guide.md)。
+
+## 7. 部署架构
+
+```
+开发环境：本地 IDEA + H2/MySQL
+测试环境：Docker Compose（MySQL + Redis + App）
+生产环境：K8s / 物理机
+```
+
+### Dockerfile 示例
+
+```dockerfile
+FROM eclipse-temurin:17-jdk-alpine
+COPY target/*.jar app.jar
+ENTRYPOINT ["java", "-jar", "/app.jar"]
+```
+
+## 8. 安全设计
+
+- 认证：JWT Bearer Token
+- 鉴权：RBAC 角色权限
+- 敏感数据：密码 BCrypt 加密
+- 接口安全：防重放（timestamp + nonce + sign）
+
+## 9. 非功能性设计
+
+| 维度 | 方案 |
+|------|------|
+| 性能 | 数据库索引、缓存、分页 |
+| 并发 | 乐观锁 / 分布式锁 |
+| 日志 | SLF4J + Logback，结构化日志 |
+| 监控 | Actuator + 自定义指标 |
+| 异常 | 全局异常处理器，统一错误码 |