# 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

- [x] T101 补充 Transaction.Create/Pay/Status，调用 `services.Order`，加绑定与 Swagger 注解
- [x] T201 运行 `atomctl gen route/provider/swag` 刷新路由与文档
- [x] T301 快速校验生成文件包含 `/orders`、`/orders/:id/pay`、`/orders/:id/status`
- [x] T401 前端功能验证支付流（Create/Pay/Status）
- [x] 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

无。