@guanlin4924/devflow-pi 0.1.0

package/plugins/devflow-quality/skills/code-review/references/cross-layer-checklist.md

@@ -0,0 +1,70 @@
+# 跨层检查清单
+
+> 这些检查需要同时看多个层级的代码，容易被单层审查遗漏。
+
+## 接口方法一致性
+
+- [ ] Service 接口的每个方法是否都有 Handler 调用方？
+- [ ] Repository 接口的每个方法是否都有 Service 调用方？
+- [ ] DAO 接口的每个方法是否都有 Repository 调用方？
+- [ ] 如果某方法无调用方，标记为"未使用方法"，建议删除
+
+**检查方法**：对接口中的每个方法名，用 Grep 搜索调用方。
+
+## 数据流转完整性
+
+- [ ] Handler → Service：是否通过 `req.ToDomain()` 转换，而非手动构造 domain 对象
+- [ ] Service → Repository：参数和返回值是否都是 domain 类型
+- [ ] Repository → DAO：是否通过 `toModel`/`toDomain` 转换
+- [ ] DAO → Repository → Service → Handler：返回路径上每层是否只关心自己该关心的类型
+
+## 分页数据流（如果有列表接口）
+
+- [ ] VO 层：`Page`（从 1 开始）+ `PageSize`，带校验规则
+- [ ] Domain 层：定义 `GetOffset()` 和 `GetLimit()` 方法
+- [ ] Repository 层：调用 `domain.GetOffset()`/`GetLimit()` 转换为 DAO 参数
+- [ ] DAO 层：使用 `Offset int` + `Limit int`，不自行计算分页
+- [ ] Handler 层：使用 `SuccessPage(voList, total, req.PageSize, req.Page)` 返回
+
+## 错误处理链路
+
+- [ ] DAO 层：直接返回 GORM 错误，不包装
+- [ ] Repository 层：透传 DAO 错误或定义别名（`var ErrXxxNotFound = dao.ErrDataNotFound`）
+- [ ] Service 层：捕获 Repo 错误 → 打日志 → 返回 `*errs.ServiceError`
+- [ ] Handler 层：`h.respHelper.Fail(ctx, err)` 统一处理
+
+## 日志职责
+
+- [ ] Handler 层：不打日志
+- [ ] Service 层：打日志（Error 级别），包含 method 名称
+- [ ] Repository 层：不打日志
+- [ ] DAO 层：不打日志
+
+## 兼容性影响检查
+
+### 前端兼容性
+
+当修改建议涉及以下内容时，**必须**在问题清单中标注前端兼容风险并给出兼容方案：
+
+- [ ] 返回 VO 的 `json` tag 是否有变更（重命名、删除）→ 前端解析会断
+- [ ] 响应结构是否有层级变化（如分页字段从 `total` 改为 `total_count`）→ 前端字段映射会断
+- [ ] 错误码数值是否有变更 → 前端可能基于错误码做了逻辑判断
+- [ ] 接口路径或请求参数的 `form`/`json` key 是否有变更 → 前端请求会失败
+
+**处理原则**：不直接改，而是「加新保旧」— 新增符合规范的字段，旧字段保留兼容，标注为待前端升级后清理。
+
+### 数据库兼容性
+
+当修改建议涉及以下内容时，**必须**在问题清单中标注数据库兼容风险：
+
+- [ ] Model 字段是否有重命名或删除 → 需要 DDL 迁移，可能影响线上数据
+- [ ] `TableName()` 返回值是否有变更 → 需要 DDL 迁移
+- [ ] 是否新增了非空字段且无默认值 → INSERT 时报错
+- [ ] 索引或唯一约束是否有变更 → 可能与现有数据冲突
+
+**处理原则**：不直接改 model 字段映射，标注为「需 DDL 迁移」，给出迁移步骤建议（加新列 → 数据迁移 → 改代码 → 删旧列）。
+
+## Mock 文件同步
+
+- [ ] 接口变更后，mock 文件是否已重新生成
+- [ ] mock 文件路径是否与 `//go:generate` 指令一致

package/plugins/devflow-quality/skills/code-review/references/dao-checklist.md

@@ -0,0 +1,70 @@
+# DAO 层检查清单
+
+> 来源：`dao.md`、`pagination.md`、`go.md`
+
+## ⚠️ 审查方法论（必读）
+
+**经验教训**：方法签名是最基础的规范，必须第一时间检查，不能凭印象判断。
+
+**正确的审查流程**：
+1. **先对比方法签名** — 把规范示例和实际代码并排对比，逐个方法检查
+2. **再检查实现逻辑** — 确认方法体内的实现是否符合规范
+3. **最后检查细节** — 注释、命名、性能优化等
+
+**常见失误**：
+- ❌ 凭记忆判断"Create 方法看起来没问题"
+- ✅ 对比规范 `Create(ctx, obj) (model.Xxx, error)` vs 实际代码 `Create(ctx, obj) (int64, error)`
+
+---
+
+## 方法签名检查（最高优先级，必须第一个检查）
+
+**检查方法**：打开规范文档，逐个方法对比签名
+
+- [ ] **Create 方法签名**：`Create(ctx context.Context, obj model.Xxx) (model.Xxx, error)`
+  - ⚠️ 常见错误：返回 `(int64, error)` 而不是 `(model.Xxx, error)`
+  - 规范依据：`dao.md:97-100`
+- [ ] **FindById 方法签名**：`FindById(ctx context.Context, id int64) (model.Xxx, error)`
+- [ ] **UpdateById 方法签名**：`UpdateById(ctx context.Context, id int64, values map[string]any) error`
+- [ ] **List 方法签名**：`List(ctx context.Context, in GetXxxListParam) ([]model.Xxx, error)`
+- [ ] **Count 方法签名**：`Count(ctx context.Context, in GetXxxListParam) (int64, error)`
+
+## 定义规范检查
+
+- [ ] **接口 + 结构体**：结构体命名使用 `GORM` 前缀（如 `GORMXxxDAO`）
+- [ ] **`//go:generate mockgen`**：接口上方是否有 mock 生成指令
+- [ ] **接口方法注释**：每个接口方法是否有注释说明用途
+- [ ] **构造函数注释**：`NewGORMXxxDAO` 是否有注释
+
+## 接口设计检查
+
+- [ ] 接口中是否存在**无调用方的方法** — 用 Grep 检查 Repository 层对每个 DAO 方法的调用
+- [ ] 方法参数和返回值是否使用 model 类型（不使用 domain）
+
+## 查询参数结构体检查（如果有列表查询）
+
+- [ ] 分页参数是否使用 `Offset int` + `Limit int`（而非 `Page`/`PageSize`）
+- [ ] 查询条件超过 2 个是否封装为结构体
+- [ ] 是否定义了 `buildGormQuery` 方法构建动态条件
+- [ ] `buildGormQuery` 使用指针接收者（`*GetXxxListParam`）
+
+## 方法实现检查
+
+- [ ] **所有查询使用 `dao.db.WithContext(ctx)`**
+- [ ] 排序默认 `created_at desc`（除非有业务理由）
+- [ ] 列表查询是否拆为 `List`（带分页）+ `Count`（不带分页）两个独立方法
+- [ ] `List` 是否使用 `Offset(in.Offset).Limit(in.Limit)`
+- [ ] **不处理业务逻辑**，只做数据库操作
+- [ ] **不记录日志**，由上层处理
+- [ ] 所有函数（含私有）是否都有注释
+- [ ] **嵌套深度是否超过 3 层**（for/if/switch 均计入）→ 超过时提取子函数（参考 L005）
+
+## 事务检查（如果有）
+
+- [ ] 事务内是否使用 `tx` 而非 `dao.db`
+- [ ] 复杂事务是否在事务内创建新的 DAO 实例
+
+## 更新操作检查
+
+- [ ] 是否优先使用指定字段更新（`map[string]any`）
+- [ ] 除非用户明确要求，否则不检查 `RowsAffected`

package/plugins/devflow-quality/skills/code-review/references/handler-checklist.md

@@ -0,0 +1,48 @@
+# Handler 层检查清单
+
+> 来源：`handler.md`、`go.md`
+
+## 结构检查
+
+- [ ] 接口守卫：是否有 `var _ handler = (*XxxHandler)(nil)`
+- [ ] struct 字段：是否只包含必要的 service 依赖 + `respHelper *ResponseHelper`
+- [ ] struct 字段：是否包含了不该有的依赖（`logger`、`dao` 包类型、`redis` 等）
+- [ ] 构造函数：`NewXxxHandler` 是否有注释
+
+## 路由注册检查
+
+- [ ] 是否实现了 `RegisterRoutes` 方法
+- [ ] 管理端路由是否使用三件套中间件（AdminOperation + AdminJwt + AdminAuth）
+- [ ] 用户端路由是否使用 `LoginJwtMiddlewareBuilder`
+- [ ] ginx 包装器选择是否正确（有 req 用 WrapWithReq*，有 claims 用 *WithClaims）
+
+## 方法实现检查
+
+- [ ] **业务逻辑禁入**：Handler 方法中是否有业务逻辑（状态判断、权限校验、数据组装）
+- [ ] **VO→Domain 转换**：是否使用 `req.ToDomain()` 而非手动构造 domain 对象
+- [ ] **Domain→VO 转换**：是否使用 VO 层的 `Format` 函数而非手动构造返回数据
+- [ ] **成功响应**：是否使用 `h.respHelper.Success(...)` 而非手动构造 `Result{}`
+- [ ] **失败响应**：是否使用 `h.respHelper.Fail(ctx, err)` 而非手动构造错误响应
+- [ ] **分页响应**：列表接口是否使用 `SuccessPage(voList, total, req.PageSize, req.Page)`
+- [ ] **聚合禁入**：列表接口中是否出现连续两次 `svc.Count + svc.List` 调用 → 应合并为 `svc.ListWithCount`，Handler 不承担聚合职责
+
+## 注释检查
+
+- [ ] 公开方法：有 Swagger godoc 注释即满足要求
+- [ ] 构造函数、私有方法、`RegisterRoutes`：必须有标准 Go 注释
+
+## 代码清洁检查
+
+- [ ] **嵌套深度是否超过 3 层**（for/if/switch/goroutine 均计入）→ 超过时提取子函数（参考 L005）
+
+## 禁止事项
+
+以下内容**绝对不能出现**在 Handler 文件中：
+
+- [ ] 无 Redis / 缓存操作
+- [ ] 无数据校验逻辑（时间校验、业务规则校验）
+- [ ] 无权限校验逻辑（中间件级别鉴权除外）
+- [ ] 无 `dao` 包的 import
+- [ ] 无 `logger` 依赖
+- [ ] 无 `Result{Code: xxx, Message: xxx}` 手动构造
+- [ ] 无多次 svc 调用聚合结果（如 `svc.Count` + `svc.List`）→ 聚合逻辑属于 Service 层

package/plugins/devflow-quality/skills/code-review/references/repository-checklist.md

@@ -0,0 +1,44 @@
+# Repository 层检查清单
+
+> 来源：`repository.md`、`go.md`
+
+## 定义规范检查
+
+- [ ] **接口 + 结构体**：结构体命名使用 `Cache` 前缀（如 `CacheXxxRepository`）
+- [ ] **`//go:generate mockgen`**：接口上方是否有 mock 生成指令
+- [ ] **接口方法注释**：每个接口方法是否有注释说明用途
+- [ ] **构造函数注释**：`NewCacheXxxRepository` 是否有注释
+
+## 接口设计检查
+
+- [ ] 列表接口是否拆为 `List`（返回数据）+ `Count`（返回总数）两个方法
+- [ ] 所有方法参数和返回值是否使用 domain 类型（不暴露 model）
+- [ ] 接口中是否存在**无调用方的方法** — 用 LSP findReferences 或 Grep 检查每个方法
+
+## 构造函数检查
+
+- [ ] 依赖注入：`dao.XxxDAO` + `redis.Cmdable`
+- [ ] 返回具体结构体指针（`*CacheXxxRepository`）
+
+## 转换方法检查
+
+- [ ] 是否定义了 `toDomain`（model → domain）
+- [ ] 是否定义了 `toModel`（domain → model）
+- [ ] 是否定义了 `toDomains`（批量转换）
+- [ ] `toDomains` 是否使用 `make([]T, len(objs))` + 索引赋值模式
+- [ ] `toModel` 是否**不赋值** `CommonTimestampsField`（CreatedAt/UpdatedAt 由 GORM 管理）
+- [ ] 状态字段是否使用 domain 枚举转换（如 `domain.XxxStatus(obj.Status)`）
+- [ ] 无未使用的转换方法
+
+## 方法实现检查
+
+- [ ] **不包含业务逻辑**（校验、默认值设置放 Service/Domain 层）
+- [ ] 错误返回时是否使用 `domain.Xxx{}`（零值）而非 `nil`（对于值类型）
+- [ ] List 方法错误返回时是否返回 `nil`（而非空 slice `[]domain.Xxx{}`）
+- [ ] 所有函数（含私有）是否都有注释
+- [ ] **嵌套深度是否超过 3 层**（for/if/switch 均计入）→ 超过时提取子函数（参考 L005）
+
+## DAO 参数转换检查（如果有列表查询）
+
+- [ ] 是否定义了 `toDAOListParam` 转换方法
+- [ ] Offset/Limit 是否使用 domain 的 `GetOffset()`/`GetLimit()` 计算

package/plugins/devflow-quality/skills/code-review/references/service-checklist.md

@@ -0,0 +1,57 @@
+# Service 层检查清单
+
+> 来源：`service.md`、`errors.md`、`logging.md`、`go.md`
+
+## 定义规范检查
+
+- [ ] **接口 + 私有结构体**：接口导出，实现结构体不导出（小写开头）
+- [ ] **`//go:generate mockgen`**：接口上方是否有 mock 生成指令
+- [ ] **接口方法注释**：每个接口方法是否有注释说明用途
+- [ ] **结构体字段命名**：Repository 依赖字段命名为 `xxxRepo`（而非 `repo`）
+
+## 构造函数检查
+
+- [ ] 命名 `NewXxxService`，参数逐个列出所有依赖
+- [ ] 返回接口类型（而非 `*xxxService`）
+- [ ] 注入 `logger.Logger` 依赖
+- [ ] 有标准 Go 注释
+
+## 错误处理检查
+
+- [ ] **所有返回的 error 必须是 `*errs.ServiceError` 类型**
+- [ ] 禁止返回 `fmt.Errorf`、标准库 `error`、或原始 GORM 错误
+- [ ] 依赖调用（Repo/其他 Service）出错：先打日志，再返回 `errs.ErrServiceFail` 或 `errs.NewServiceError`
+- [ ] 业务校验出错：直接返回 `errs.NewServiceError`，无需打日志
+
+## 日志检查
+
+- [ ] **只在 Service 层打日志**，不在 DAO/Repository 层
+- [ ] Error 日志是否包含 `logger.String("method", "方法名")`
+- [ ] Error 日志是否包含 `logger.Error(err)`
+- [ ] 是否传递 `ctx` 作为第一个参数
+- [ ] 使用注入的 `s.logger`，不使用全局 `zap.L()`
+
+## Domain 充血模型检查
+
+- [ ] 业务校验是否封装为 domain 方法（如 `EnsureDefaults`、`Validate`）
+- [ ] Service 层是否调用 domain 方法而非内联实现
+- [ ] 状态判断是否内联（如 `obj.Status == domain.XxxStatusPending`）→ 应封装为 `obj.IsPending()`
+- [ ] 状态变更 + 字段设置是否内联（如 `obj.Status = Rejected; obj.Remark = remark`）→ 应封装为 `obj.Reject(remark)`
+- [ ] 时间判断是否内联（如 `obj.StartTime.Before(time.Now())`）→ 应封装为 `obj.IsStarted()`
+- [ ] 基于类型的分支逻辑是否内联 → 应封装为 domain 方法
+- [ ] **判断原则**：逻辑只依赖 domain 对象自身字段（不需要 repo/svc 等外部依赖）→ 应下沉到 domain
+
+## 代码清洁检查
+
+- [ ] 无未使用的私有方法
+- [ ] 无未使用的参数
+- [ ] 无未使用的 import
+- [ ] 方法参数 ≥3 个（不含 ctx）时是否封装为 domain 结构体
+- [ ] 函数体是否超过 100 行
+- [ ] 所有函数（含私有）是否都有注释
+- [ ] **嵌套深度是否超过 3 层**（for/if/switch/goroutine 均计入）→ 超过时提取子函数（参考 L005）
+
+## 分页逻辑检查（如果有 GetList）
+
+- [ ] 是否先 Count 再 List
+- [ ] total 为 0 或已越界时是否直接返回空列表

package/plugins/devflow-quality/skills/code-review/references/spec-checklist.md

@@ -0,0 +1,34 @@
+# 规范加载清单
+
+> 审查前根据涉及层级加载对应规范文件，确保不遗漏。
+
+## 规范文件路径
+
+所有规范文件位于 `.context/spec/backend/` 目录下。
+
+## 加载矩阵
+
+| 涉及层级 | 必读规范文件 | 关联规范 |
+|---------|------------|---------|
+| **任何层级** | `index.md`, `go.md` | `lessons/README.md` |
+| Handler | `handler.md` | `vo.md`（VO 转换规范在 handler.md 中引用） |
+| VO | `vo.md` | — |
+| Service | `service.md` | `errors.md`, `logging.md` |
+| Repository | `repository.md` | — |
+| DAO | `dao.md` | — |
+| 有分页 | `pagination.md` | 影响 VO + Domain + DAO 三层 |
+
+## 如何判断是否涉及分页
+
+文件中出现以下任一特征即涉及分页：
+- 方法名包含 `List` / `GetList`
+- 参数中有 `Page` / `PageSize` / `Offset` / `Limit`
+- 返回值包含 `total` / `count`
+- Handler 中调用 `SuccessPage`
+
+## 加载顺序
+
+1. 先读 `index.md` 获取核心规则摘要
+2. 再读 `go.md` 获取通用编码规范
+3. 然后按层级从外到内加载：Handler → VO → Service → Repository → DAO
+4. 最后读 `lessons/README.md` 获取历史踩坑经验

package/plugins/devflow-quality/skills/code-review/references/vo-checklist.md

@@ -0,0 +1,26 @@
+# VO 层检查清单
+
+> 来源：`vo.md`、`pagination.md`
+
+## 请求 VO 结构检查
+
+- [ ] **Tag 三件套**：每个字段是否都有 `form` + `json` + `valid` 三个 tag
+- [ ] **Rules 方法**：是否定义了 `Rules() map[string][]string`
+- [ ] **Messages 方法**：是否定义了 `Messages() map[string][]string`，每条 Rule 对应一条中文提示
+- [ ] **ToDomain 方法**：是否定义了 `ToDomain()` 将 VO 转为 domain 对象
+
+## 分页请求 VO 检查（如果有）
+
+- [ ] `page` 字段校验规则是否包含 `min:1`
+- [ ] `page_size` 字段校验规则是否包含 `min:1` 和 `max:100`
+
+## 返回 VO 检查
+
+- [ ] 是否定义了 `Format` 系列转换函数（`FormatXxxResp` / `FormatXxxItems`）
+- [ ] 批量转换函数是否使用 `make([]T, len(objs))` + 索引赋值模式（而非 `append`）
+- [ ] 空列表初始化是否使用 `make` 而非 `var`（避免 JSON 序列化为 `null`）
+
+## 重构场景特殊规则
+
+- [ ] **不修改已有 VO 字段定义**（字段名、类型、json tag 不动）
+- [ ] 仅补全缺失的 `form` / `valid` tag，不改变字段语义

package/plugins/devflow-quality/skills/workflow-audit-milestone/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: workflow-audit-milestone
+description: "Use when a milestone needs completion audit against original requirements, phase outputs, verification evidence, and archive readiness."
+---
+
+<objective>
+Verify milestone achieved its definition of done. Check requirements coverage, cross-phase integration, and end-to-end flows.
+
+**This command IS the orchestrator.** Reads existing VERIFICATION.md files (phases already verified during execute-phase), aggregates tech debt and deferred gaps, then spawns integration checker for cross-phase wiring.
+</objective>
+
+<execution_context>
+references/audit-milestone.md
+</execution_context>
+
+<context>
+Version: $ARGUMENTS (optional — defaults to current milestone)
+
+Core planning files are resolved in-workflow (`init milestone-op`) and loaded only as needed.
+
+When `.planning/code-index/` exists, milestone integration checks should use it for source-level route/call/import/data-flow/test relationships and read source evidence before reporting wiring gaps. The detailed policy lives in `references/audit-milestone.md`.
+
+**Completed Work:**
+Glob: .planning/phases/*/*-SUMMARY.md
+Glob: .planning/phases/*/*-VERIFICATION.md
+</context>
+
+<process>
+Execute the audit-milestone workflow from references/audit-milestone.md end-to-end.
+Preserve all workflow gates (scope determination, verification reading, integration check, requirements coverage, routing).
+</process>