From b3731eaac6d477dc170c621811a9a9b80828a88d Mon Sep 17 00:00:00 2001 From: Rogee Date: Wed, 4 Feb 2026 14:58:35 +0800 Subject: [PATCH] docs: update plans and agent instructions Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus --- AGENTS.md | 2 + docs/plan.md | 96 ++++++++++++++++++++++------------------ docs/plans/2026-02-03.md | 71 ++++++++++++++++------------- docs/plans/2026-02-04.md | 69 +++++++++++++++++++++++++++++ 4 files changed, 165 insertions(+), 73 deletions(-) create mode 100644 docs/plans/2026-02-04.md diff --git a/AGENTS.md b/AGENTS.md index aecd9e2..306c923 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -45,6 +45,8 @@ When driving browser tests via Chrome DevTools MCP, consult: - Use `docs/plan.md` as the active plan for the current phase. - When the phase completes, move `docs/plan.md` to `docs/plans/.md` for archival. - After archiving, clear `docs/plan.md` to await the next plan. +- If a plan covers frontend interfaces, completion requires BOTH frontend functional testing of the impacted flows and backend `go test ./...`; only then may the plan be marked complete/archived. +- Acceptance for frontend-involved work must be validated via frontend **page flows** (browser/UI) to confirm front-back integration. `curl`/API smoke is allowed only for quick backend checks and does **not** count as acceptance for frontend-related tasks. ## Commit & Pull Request Guidelines diff --git a/docs/plan.md b/docs/plan.md index 25a74e3..a2b363b 100644 --- a/docs/plan.md +++ b/docs/plan.md @@ -1,76 +1,88 @@ -# Implementation Plan: Payment Flow Rules & Verification +# Implementation Plan: backend-test-coverage -**Branch**: `main` | **Date**: 2026-02-03 | **Spec**: `docs/seed_verification.md` -**Input**: 统一支付流程规则，完善前后端联调与验证路径。 +**Branch**: `[test-coverage-t3-t4]` | **Date**: 2026-02-04 | **Spec**: N/A +**Input**: Continuation of test coverage tasks (T3/T4) from prior session; no feature spec. ## Summary -明确支付流程的接口契约与前端交互（创建订单→支付→状态查询），补齐规则并制定验证步骤，确保页面交互与数据库状态一致。 +Complete backend service test coverage for content access policies (T3) and superadmin write operations (T4), ensuring existing behavior is validated without altering production logic. ## Technical Context -**Language/Version**: Go 1.22, Vue 3 (Vite) -**Primary Dependencies**: Fiber, Vite, existing `/orders`/`/pay`/`/status` APIs -**Storage**: PostgreSQL -**Testing**: 页面自动化（MCP）+ 手动校验 -**Target Platform**: local/staging -**Project Type**: Web application -**Performance Goals**: N/A -**Constraints**: 不改生成文件；遵循 `backend/llm.txt` -**Scale/Scope**: 支付流程规范与验证 +**Language/Version**: Go 1.x (project standard) +**Primary Dependencies**: Fiber, GORM-Gen, Testify +**Storage**: PostgreSQL (via GORM) +**Testing**: `go test` (service tests under `backend/app/services/*_test.go`) +**Target Platform**: Linux server +**Project Type**: Web application (frontend + backend) +**Performance Goals**: N/A (test-only changes) +**Constraints**: No changes to generated files; keep tests aligned with existing service patterns +**Scale/Scope**: Backend service tests only (no frontend scope) ## Constitution Check -- 仅文档/规则梳理，若后续改代码需遵守生成文件不可直改规则。 +- Follow `backend/llm.txt` for backend conventions. +- Keep controllers thin; service tests only (no controller edits). +- Avoid editing generated files (`routes.gen.go`, `docs.go`). +- Run `go test` for impacted service packages. ## Project Structure +### Documentation (this feature) + ```text -docs/ -├── plan.md # 本计划 -├── seed_verification.md # 页面→操作→数据验证清单 -└── plans/ # 归档目录 -frontend/portal/src/views/order/ # Checkout/Payment -backend/app/http/v1/transaction.go # orders/pay/status/webhook +specs/[###-feature]/ +└── (not used for this task) ``` -**Structure Decision**: 在现有前后端目录内完善支付契约说明与测试步骤，不新增结构。 +### Source Code (repository root) + +```text +backend/ +├── app/ +│ ├── services/ +│ │ ├── content_test.go +│ │ └── super_test.go +└── app/http/v1/dto/ + └── content.go +``` + +**Structure Decision**: Web application structure; scope is backend service tests in `backend/app/services`. ## Plan Phases -### Phase 1: 规则梳理 -- 明确 `/orders` 创建所需字段与返回字段（价格、content_title、status、id）。 -- 明确 `/orders/:id/pay` 入参与预期状态变更；`/orders/:id/status` 响应格式。 - -### Phase 2: 前后端对齐点 -- 若后端缺字段/逻辑，提出对齐要求；前端 Checkout/Payment 显示金额、商品名、状态并可发起 pay/模拟成功。 - -### Phase 3: 验证与记录 -- 执行创建→支付→状态流；校验页面与 DB (`orders`, `order_items`, `content_access`) 一致；记录缺口（若 pay 未实现则记为待补）。 +1. Inspect DTO definitions used by content tests to fix T3 assertions. +2. Implement remaining content access policy tests (T3) and verify via `go test`. +3. Implement superadmin write operation tests (T4) and verify via `go test`. ## Tasks -- [ ] T001 梳理 `/orders` 创建与返回字段（content_id, price_amount, id/status） -- [ ] T002 梳理 `/orders/:id/pay` 入参与成功/失败状态定义 -- [ ] T003 梳理 `/orders/:id/status` 响应字段（status, amount_paid/original, content_title） -- [ ] T010 前端显示与调用对齐（Checkout 显示金额/标题，Payment 调用 pay+轮询） -- [ ] T020 验证创建→支付→状态→订单详情链路；记录 DB 状态变化 -- [ ] T030 汇总缺口（如 pay 未实现、字段缺失），更新 `docs/seed_verification.md` +1. Read `backend/app/http/v1/dto/content.go` and update T3 test assertions to match actual DTO fields. +2. Extend `backend/app/services/content_test.go` with missing content access policy cases and run targeted tests. +3. Extend `backend/app/services/super_test.go` for superadmin write operations; run service test suite. +4. Verify all added tests pass without modifying production logic. ## Dependencies -- Phase 1 → Phase 2 → Phase 3 +- Task 1 must complete before Task 2 (DTO fields drive assertions). +- Task 2 should complete before Task 3 to isolate failures. ## Acceptance Criteria -- 支付接口契约（字段/状态）明确并记录。 -- 前端 Checkout/Payment 能显示金额/商品名并调用 pay+轮询；若后端未实现，缺口已记录。 -- 手动/自动化验证创建→支付→状态→订单详情链路，DB 状态与页面一致。 +- `backend/app/services/content_test.go` has passing T3 coverage for unauthenticated access constraints. +- `backend/app/services/super_test.go` includes T4 coverage for create-tenant side effects and superadmin write operations. +- `go test ./backend/app/services/...` passes. +- No generated files modified. ## Risks -- 后端 pay/status 未实现或字段缺失导致无法完成闭环（需记录缺口）。 +- DTO field changes may require adjusting test assertions; mitigate by verifying struct definitions. +- Service behavior may differ from assumptions in prior session; mitigate by aligning with existing tests. ## Complexity Tracking -无。 +> **Fill ONLY if Constitution Check has violations that must be justified** + +| Violation | Why Needed | Simpler Alternative Rejected Because | +|-----------|------------|-------------------------------------| +| N/A | N/A | N/A | diff --git a/docs/plans/2026-02-03.md b/docs/plans/2026-02-03.md index 80360f5..be16150 100644 --- a/docs/plans/2026-02-03.md +++ b/docs/plans/2026-02-03.md @@ -1,64 +1,73 @@ -# Implementation Plan: Consolidate UI Testing Artifacts +# Implementation Plan: Payment Transaction Endpoints -**Branch**: `main` | **Date**: 2026-01-26 | **Spec**: `docs/backups/seed_verification.md` -**Input**: 将测试清单文档从备份位置合并回正式目录，确保符合 AGENTS.md 的计划要求并归档/清空。 +**Branch**: `main` | **Date**: 2026-02-03 | **Spec**: `docs/seed_verification.md` +**Input**: 前端支付流联调缺口：订单相关路由未注册，服务层已实现。 ## Summary -把 `docs/backups/seed_verification.md` 的页面测试清单合并回 `docs/seed_verification.md`，保证计划文档更新，并按规则归档 `docs/plan.md`。 +为租户侧支付流新增订单创建、支付、状态查询 HTTP handler，并挂载到现有服务逻辑；同步刷新路由/provider/swagger，保证前端 Checkout/Payment 可调用且状态可查。 ## Technical Context -**Language/Version**: Markdown docs -**Primary Dependencies**: N/A -**Storage**: N/A -**Testing**: N/A -**Target Platform**: repo docs -**Project Type**: Documentation +**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**: 遵循 AGENTS 计划要求；不改生成文件 -**Scale/Scope**: 文档归拢 +**Constraints**: 不手改 `*.gen.go`；遵循 `backend/llm.txt`；路由参数使用 camelCase + `:id` +**Scale/Scope**: 仅补齐支付相关 HTTP 路由与 handler ## Constitution Check -- 遵循 `backend/llm.txt`（无代码改动）。 -- 仅修改文档。 +- 需先定义 handler，再用 `atomctl gen route/provider/swag` 生成；不得直接修改生成文件。 +- Controller 仅做 bind/校验，业务调用 `services.Order.*`。 ## Project Structure -```text -docs/ -├── plan.md -├── seed_verification.md -└── backups/seed_verification.md ``` +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: Merge doc -- 将备份版检查表合并为正式版 `docs/seed_verification.md`。 - -### Phase 2: Plan archive -- 将当前 plan 归档到 `docs/plans/.md` 并清空 `docs/plan.md`。 +- 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 -- [ ] T001 Merge backup checklist into docs/seed_verification.md -- [ ] T002 Archive plan to docs/plans/.md and clear docs/plan.md +- [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 -- Phase 1 → Phase 2 +- T101 完成后才能执行 T201 +- T201 完成后进行 T301 校验 ## Acceptance Criteria -- `docs/seed_verification.md` 包含最新清单内容。 -- `docs/plan.md` 归档并清空。 +- `transaction.go` 存在 Create/Pay/Status handler，路径与 `:tenantCode`/`:id` 符合规范，绑定参数正确。 +- `routes.gen.go` 注册 `/v1/t/:tenantCode/orders`、`/v1/t/:tenantCode/orders/:id/pay`、`/v1/t/:tenantCode/orders/:id/status` 路由，provider 注入正常。 +- Swagger 文档包含上述接口；前端调用不再 404（需具备可路由）。 ## Risks -- 无 +- 本地 `atomctl`/依赖缺失导致生成失败（需补工具或环境）。 +- Swagger/路由注解若与路径不一致可能生成异常，需要一致性检查。 ## Complexity Tracking -无 +无。 diff --git a/docs/plans/2026-02-04.md b/docs/plans/2026-02-04.md new file mode 100644 index 0000000..bdae87b --- /dev/null +++ b/docs/plans/2026-02-04.md @@ -0,0 +1,69 @@ +# Implementation Plan: Portal Payment Page Hardening + +**Branch**: `main` | **Date**: 2026-02-04 | **Spec**: `docs/seed_verification.md` +**Input**: 前端支付页仍含 DEV 模拟逻辑，支付错误提示/加载与轮询节流不足，金额/商品信息展示不完整。 + +## Summary + +清理支付页 DEV 模拟逻辑，增强支付失败与加载态提示，补全金额/商品信息展示，并对状态轮询做节流，确保真实支付链路稳定可用。 + +## Technical Context + +**Language/Version**: Vue 3 (Vite) +**Primary Dependencies**: Pinia, Vue Router, PrimeVue +**Storage**: PostgreSQL（后端服务已就绪） +**Testing**: 前端页面流验证；后端 `go test ./...`（规则要求前端改动需二者并行） +**Target Platform**: local/staging +**Project Type**: Web application +**Performance Goals**: 减少轮询负载，提升用户反馈 +**Constraints**: 遵循 `backend/llm.txt`、前端接口涉及需跑页面流 + go test；不手改生成文件 +**Scale/Scope**: 仅 Portal 支付页（PaymentView.vue）及相关 API/状态展示 + +## Constitution Check + +- 所有前端接口相关改动需完成页面流验证和后端 `go test ./...` 方可归档。 +- 禁止保留 DEV-only 模拟逻辑于生产代码。 + +## Project Structure + +- `frontend/portal/src/views/order/PaymentView.vue` +- `frontend/portal/src/api/order.js`（若需补充错误/数据处理） +- `frontend/portal/src/utils/request.js`（如需请求拦截/错误提示，视需要） + +**Structure Decision**: 仅修改支付页与关联 API，避免全局侵入。 + +## Plan Phases + +- Phase 1: 行为清理 —— 移除/隔离 DEV 模拟支付逻辑，确保真实 pay 调用。 +- Phase 2: 体验增强 —— 添加支付中/loading/错误提示；补全金额、商品标题展示；轮询节流与完成后停止。 +- Phase 3: 验证 —— 前端页面流支付冒烟 + 后端 `go test ./...`。 + +## Tasks + +- [x] T101 移除或显式守护 DEV 模拟支付按钮（生产隐藏/剔除），确保真实 pay 请求。 +- [x] T102 支付提交/轮询的加载与错误提示：提交中禁用按钮，失败 toast/提示，并在错误时停止 loading。 +- [x] T103 订单金额/商品信息展示：优先用 status 返回的 `amount_paid/amount_original` 与 `content_title`，保持 0 元也可显示。 +- [x] T104 轮询节流与完成停止：调整轮询间隔/次数，支付成功即停止，避免过度请求。 +- [x] T201 前端页面流验证支付（登录→Checkout→Pay→Status paid）。 +- [x] T202 后端回归测试 `go test ./...`（与 T201 同时满足）。 + +## Dependencies + +- T101 完成后执行 T102~T104。 +- T104 完成后执行 T201；T201/T202 完成后归档。 + +## Acceptance Criteria + +- 支付页无 DEV-only 模拟逻辑暴露；“立即支付”触发真实 `/pay`，状态能更新为 `paid`。 +- 支付/轮询有明显 loading/错误反馈；轮询成功后自动停；按钮在提交中禁用。 +- 金额与商品标题在支付页正确显示（含 0 元订单）。 +- 前端页面流验证通过（登录→下单→支付→订单状态 paid）；后端 `go test ./...` 通过。 + +## Risks + +- 轮询过度或停止条件遗漏导致请求风暴；通过节流与成功后清理计时器规避。 +- 错误提示未覆盖网络异常；需在提交与轮询 catch 中统一处理。 + +## Complexity Tracking + +暂无。