# 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 |