quyun-v2/docs/plan.md

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)

docs/
├── plan.md                 # 当前计划（本文件）
└── test-matrix.md          # 回归记录更新

Source Code (repository root)

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