quyun-v2/docs/plans/2026-02-03.md

Implementation Plan: Payment Transaction Endpoints

Branch: main | Date: 2026-02-03 | Spec: docs/seed_verification.md Input: 前端支付流联调缺口：订单相关路由未注册，服务层已实现。

Summary

为租户侧支付流新增订单创建、支付、状态查询 HTTP handler，并挂载到现有服务逻辑；同步刷新路由/provider/swagger，保证前端 Checkout/Payment 可调用且状态可查。

Technical Context

Language/Version: Go 1.22, Vue 3 (Vite) Primary Dependencies: Fiber, atomctl（路由/Provider/Swagger 生成）, GORM-Gen models Storage: PostgreSQL Testing: go test ./...（如需），前端联调/种子验证参见 docs/seed_verification.md Target Platform: local/staging Project Type: Web application Performance Goals: N/A Constraints: 不手改 *.gen.go；遵循 backend/llm.txt；路由参数使用 camelCase + :id<int> Scale/Scope: 仅补齐支付相关 HTTP 路由与 handler

Constitution Check

• 需先定义 handler，再用 atomctl gen route/provider/swag 生成；不得直接修改生成文件。
• Controller 仅做 bind/校验，业务调用 services.Order.*。

Project Structure

docs/
├── plan.md                  # 本计划
└── plans/                   # 归档目录
backend/app/http/v1/transaction.go   # 新增 create/pay/status handler
backend/app/http/v1/routes.gen.go    # 生成路由（勿手改）
backend/app/http/v1/provider.gen.go  # 生成 provider（勿手改）
backend/docs/swagger.yaml|json|docs.go # 生成文档（勿手改）

Structure Decision: 复用现有 v1 模块，新增 handler，其他结构不变。

Plan Phases

• Phase 1: 控制器补齐 —— 在 transaction.go 编写 Create/Pay/Status handler，完成 Swagger 注解与参数绑定。
• Phase 2: 生成与注入 —— 运行 atomctl gen route, atomctl gen provider, atomctl swag init，确认路由挂载。
• Phase 3: 校验 —— 快速检查生成文件与路径，确认 404 缺口消除（如需再跑 gofmt）。

Tasks

• T101 补充 Transaction.Create/Pay/Status，调用 services.Order，加绑定与 Swagger 注解
• T201 运行 atomctl gen route/provider/swag 刷新路由与文档
• T301 快速校验生成文件包含 /orders、/orders/:id/pay、/orders/:id/status
• T401 前端功能验证支付流（Create/Pay/Status）
• T402 后端回归测试 go test ./...（需与 T401 同时满足方可归档）

Dependencies

• T101 完成后才能执行 T201
• T201 完成后进行 T301 校验

Acceptance Criteria

• transaction.go 存在 Create/Pay/Status handler，路径与 :tenantCode/:id<int> 符合规范，绑定参数正确。
• routes.gen.go 注册 /v1/t/:tenantCode/orders、/v1/t/:tenantCode/orders/:id<int>/pay、/v1/t/:tenantCode/orders/:id<int>/status 路由，provider 注入正常。
• Swagger 文档包含上述接口；前端调用不再 404（需具备可路由）。

Risks

• 本地 atomctl/依赖缺失导致生成失败（需补工具或环境）。
• Swagger/路由注解若与路径不一致可能生成异常，需要一致性检查。

Complexity Tracking

无。