docs: update creator recovery plan and verification evidence
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
This commit is contained in:
147
docs/plan.md
147
docs/plan.md
@@ -0,0 +1,147 @@
|
||||
# Implementation Plan: v1 Creator 路由恢复与闭环验证
|
||||
|
||||
**Branch**: `[current-working-branch]` | **Date**: 2026-02-07 | **Spec**: 会话需求（修复 `/v1/t/:tenantCode/creator/*` 404）
|
||||
**Input**: 用户需求：开始修复 Creator 路由缺失问题，恢复 Portal 创作者中心 API 可用性并完成回归验证。
|
||||
|
||||
## Summary
|
||||
|
||||
当前 `backend/app/http/v1/creator.go` 仅保留 `GrantCoupon` 方法，但注释块包含大量与该方法签名不匹配的 `@Router` 声明，导致 `atomctl gen route` 未生成任何 `/v1/t/:tenantCode/creator/*` 路由。计划将按“前端真实调用路径 -> 后端服务能力 -> 控制器显式方法”逐项恢复，最小改动修复，随后通过路由生成、Go 测试与关键 API 冒烟验证闭环。
|
||||
|
||||
## Technical Context
|
||||
|
||||
**Language/Version**:
|
||||
- Backend: Go (Fiber + GORM-Gen)
|
||||
- Frontend reference: Vue 3（仅用于接口映射，不改前端）
|
||||
|
||||
**Primary Dependencies**:
|
||||
- `atomctl gen route`（路由生成）
|
||||
- `backend/app/services`（Creator/Tenant/Coupon 服务）
|
||||
- `backend/app/http/v1/dto`（Creator 与 TenantMember DTO）
|
||||
|
||||
**Storage**: PostgreSQL（使用现有 schema 与 seed 数据）
|
||||
|
||||
**Testing**:
|
||||
- `cd backend && env GOCACHE=$PWD/.gocache GOTMPDIR=$PWD/.gotmp go test ./...`
|
||||
- API 冒烟：`/v1/t/:tenantCode/creator/orders` 等关键路径不再 404
|
||||
|
||||
**Target Platform**: Linux 本地环境（backend: `127.0.0.1:18080`）
|
||||
|
||||
**Project Type**: Web backend API
|
||||
|
||||
**Performance Goals**:
|
||||
- 本次以功能恢复为目标，不新增性能指标
|
||||
|
||||
**Constraints**:
|
||||
- 不手改任何 `*.gen.go`
|
||||
- 控制器保持薄层（参数绑定 -> services.* -> 返回）
|
||||
- 路由参数使用 `camelCase`，数值 path 参数使用 `:id<int>`
|
||||
- 仅做最小修复，不做与问题无关重构
|
||||
|
||||
**Scale/Scope**:
|
||||
- 仅修复 `backend/app/http/v1/creator.go` 路由缺失问题
|
||||
- 影响生成文件：`backend/app/http/v1/routes.gen.go`（通过生成器更新）
|
||||
- 更新回归记录：`docs/test-matrix.md`
|
||||
|
||||
## Constitution Check
|
||||
|
||||
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
||||
|
||||
- ✅ 控制器薄层：方法将仅负责绑定和调用 service。
|
||||
- ✅ 生成文件规范：仅通过 `atomctl gen route` 更新路由生成文件。
|
||||
- ✅ 事务与数据访问边界：不在 controller 做任何 DB 操作。
|
||||
- ✅ 验证要求：包含 `go test ./...` + 关键页面流 API 冒烟证据。
|
||||
|
||||
## Project Structure
|
||||
|
||||
### Documentation (this feature)
|
||||
|
||||
```text
|
||||
docs/
|
||||
├── plan.md # 当前计划（本文件）
|
||||
└── test-matrix.md # 回归记录更新
|
||||
```
|
||||
|
||||
### Source Code (repository root)
|
||||
|
||||
```text
|
||||
backend/
|
||||
├── app/http/v1/
|
||||
│ ├── creator.go # 本次主要修复文件
|
||||
│ └── routes.gen.go # 由 atomctl 生成
|
||||
├── app/http/v1/dto/
|
||||
│ ├── creator.go
|
||||
│ ├── creator_report.go
|
||||
│ └── tenant_member.go
|
||||
└── app/services/
|
||||
├── creator.go
|
||||
├── creator_report.go
|
||||
├── tenant_member.go
|
||||
└── coupon.go
|
||||
|
||||
frontend/portal/
|
||||
└── src/api/creator.js # 仅用于接口映射核对
|
||||
```
|
||||
|
||||
**Structure Decision**: 使用现有后端 v1 模块结构，控制器集中恢复，服务层复用现有能力，不新增新模块。
|
||||
|
||||
## Plan Phases
|
||||
|
||||
### Phase 1 — 路由映射与控制器设计
|
||||
- 依据 `frontend/portal/src/api/creator.js` 提取全部 `/creator/*` 调用。
|
||||
- 将调用映射到现有 service 方法（Creator/Tenant/Coupon）。
|
||||
- 为每个 endpoint 设计独立 controller 方法与准确 `@Router/@Bind`。
|
||||
|
||||
### Phase 2 — 控制器实现与路由生成
|
||||
- 重写 `backend/app/http/v1/creator.go`：一条路由一个方法，去除“多路由堆在单方法注释”反模式。
|
||||
- 执行 `atomctl gen route`，确认 `routes.gen.go` 产出完整 `/v1/t/:tenantCode/creator/*` 注册项。
|
||||
|
||||
### Phase 3 — 回归验证与文档更新
|
||||
- 运行 `go test ./...`。
|
||||
- 用 token 对至少以下接口冒烟：
|
||||
- `GET /v1/t/:tenantCode/creator/orders`
|
||||
- `GET /v1/t/:tenantCode/creator/contents`
|
||||
- `GET /v1/t/:tenantCode/creator/settings`
|
||||
- 将修复结果与证据补充到 `docs/test-matrix.md`。
|
||||
|
||||
## Tasks
|
||||
|
||||
- [ ] T1 从 `frontend/portal/src/api/creator.js` 提取 endpoint 清单并建立 service 映射。
|
||||
- [ ] T2 在 `backend/app/http/v1/creator.go` 实现 creator 核心接口：apply/dashboard/contents/orders/settings/payout/withdraw。
|
||||
- [ ] T3 在 `backend/app/http/v1/creator.go` 实现成员与邀请相关接口：members/invites/join-requests/review。
|
||||
- [ ] T4 在 `backend/app/http/v1/creator.go` 实现优惠券相关接口：list/get/create/update/grant。
|
||||
- [ ] T5 在 `backend/app/http/v1/creator.go` 实现报表相关接口：reports/overview 与 reports/export。
|
||||
- [ ] T6 执行 `atomctl gen route` 并确认 `/creator/*` 路由已注册。
|
||||
- [ ] T7 执行 `go test ./...`，修复由本次改动引入的问题。
|
||||
- [ ] T8 执行 Creator 关键接口冒烟并记录结果。
|
||||
- [ ] T9 更新 `docs/test-matrix.md` 记录 Creator 修复闭环结果。
|
||||
|
||||
## Dependencies
|
||||
|
||||
- T1 -> T2/T3/T4/T5（先映射后编码）
|
||||
- T2/T3/T4/T5 -> T6（代码落地后生成路由）
|
||||
- T6 -> T7/T8（先确认路由注册，再跑测试与冒烟）
|
||||
- T7/T8 -> T9（测试证据写入文档）
|
||||
|
||||
## Acceptance Criteria
|
||||
|
||||
1. `backend/app/http/v1/routes.gen.go` 中存在并注册 `/v1/t/:tenantCode/creator/*` 对应路由。
|
||||
2. `GET /v1/t/:tenantCode/creator/orders` 不再返回 404（认证通过前提下）。
|
||||
3. `go test ./...` 通过（若有历史失败，需明确标注非本次引入）。
|
||||
4. `docs/test-matrix.md` 新增 Creator 路由修复结果与可复现命令。
|
||||
|
||||
## Risks
|
||||
|
||||
- **DTO 不匹配风险**：部分接口需复用 `tenant_member` DTO，可能出现绑定字段不一致。
|
||||
- 缓解：按现有 service 签名逐项对齐 `@Bind`。
|
||||
|
||||
- **路由冲突风险**：新增 `/creator/*` 可能与其他路径发生顺序/匹配冲突。
|
||||
- 缓解：依赖生成器产出并通过启动日志核对注册项。
|
||||
|
||||
- **权限语义偏差风险**：Controller 恢复后可能暴露 service 内已有“仅租户主”限制，导致与前端预期不一致。
|
||||
- 缓解：先恢复 404 问题；权限语义差异单独记录为后续优化项。
|
||||
|
||||
## Complexity Tracking
|
||||
|
||||
| Violation | Why Needed | Simpler Alternative Rejected Because |
|
||||
|-----------|------------|-------------------------------------|
|
||||
| N/A | N/A | N/A |
|
||||
|
||||
Reference in New Issue
Block a user