From 5862018e7c97f4e8501a0a94f25a8b98e39ae221 Mon Sep 17 00:00:00 2001 From: huang Date: Fri, 27 Mar 2026 21:52:09 +0800 Subject: [PATCH] docs(01): capture phase context --- .planning/phases/01-p0/01-CONTEXT.md | 127 ++++++++++++++++++++ .planning/phases/01-p0/01-DISCUSSION-LOG.md | 69 +++++++++++ 2 files changed, 196 insertions(+) create mode 100644 .planning/phases/01-p0/01-CONTEXT.md create mode 100644 .planning/phases/01-p0/01-DISCUSSION-LOG.md diff --git a/.planning/phases/01-p0/01-CONTEXT.md b/.planning/phases/01-p0/01-CONTEXT.md new file mode 100644 index 0000000..1ce56fb --- /dev/null +++ b/.planning/phases/01-p0/01-CONTEXT.md @@ -0,0 +1,127 @@ +# Phase 1: P0 紧急修复 - Context + +**Gathered:** 2026-03-27 +**Status:** Ready for planning + + +## Phase Boundary + +修复 8 个已知的代码路径断点（CRITICAL-01~08），使"充值→自动购包→佣金计算→实名激活"的主链路可端到端跑通。无新功能，无 API 新增，只改现有文件。 + + + + +## Implementation Decisions + +### CRITICAL-06 修复范围（sellerCostPrice） + +- **D-01:** 对 `internal/service/order/service.go` 中 6 处 `sellerCostPrice = buyerCostPrice` 逐一语义审查，按场景决定是否修改 +- **D-02:** 语义审查依据：修正业务完整方案中的五种购买场景对应表（`.sisyphus/plans/修正业务-完整方案.md` 方案 A-5 段落） +- **D-03:** 不做模式匹配式全量替换，有些场景使用 `buyerCostPrice` 可能是正确的 + +### 执行顺序与分组 + +- **D-04:** 分 2 批执行： + - 第 1 批（主链路）：CRITICAL-01 → CRITICAL-02 → CRITICAL-03 → CRITICAL-04 → CRITICAL-05 + - 第 2 批（独立 Bug）：CRITICAL-06 → CRITICAL-07 → CRITICAL-08 +- **D-05:** 每个 Bug 修复后独立一个 commit（回滚粒度细，便于定位问题） +- **D-06:** 依赖约束：CRITICAL-02 必须在 CRITICAL-01 之后执行；CRITICAL-05 必须在 CRITICAL-04 之后执行 + +### Bootstrap 依赖注入 + +- **D-07:** CRITICAL-03（PollingHandler 注入 asynqClient）和 CRITICAL-04（recharge.Service 注入 queueClient + 注册 AutoPurchaseHandler）分开处理，各自一个 commit +- **D-08:** CRITICAL-04 涉及两个修改点： + - API 侧：`internal/bootstrap/services.go` 的 `rechargeSvc.New()` 调用新增 `deps.QueueClient` 参数（`QueueClient` 已在 `deps` 中，无需新增字段） + - Worker 侧：`pkg/queue/handler.go` 新增 `registerAutoPurchaseHandler()` 方法并在 `RegisterHandlers()` 中调用 +- **D-09:** 无需修改 `worker_services.go`（recharge.Service 不在 Worker bootstrap 链路中） + +### 验证策略 + +- **D-10:** 每个 Bug 修复后执行 `go build ./...` 确认编译通过，然后提交 +- **D-11:** 不要求自动化测试，人工验收方式：`rg` 确认代码路径 + DBHub 验证数据 + 日志关键字 +- **D-12:** 方案文档中每个 Bug 都有"人工验收清单"，按清单逐一核对 + +### the Agent's Discretion + +- 具体代码片段已在 `.sisyphus/plans/修正业务-完整方案.md` 中提供，agent 应直接按文档实现，不需要重新设计 +- 日志消息使用中文（项目规范） +- 所有注释使用中文 + + + + +## Canonical References + +**Downstream agents MUST read these before planning or implementing.** + +### 修复规格（核心参考） +- `.sisyphus/plans/修正业务-完整方案.md` — 完整修复规格书：每个 Bug 的业务背景、代码现状（含文件路径+行号）、完整代码片段、人工验收清单 + - 方案 A-1（CRITICAL-01）：第 59-128 行 + - 方案 A-2（CRITICAL-02）：第 132-163 行 + - 方案 A-3（CRITICAL-03）：第 165-299 行 + - 方案 A-4 P0-3（CRITICAL-04）：第 301-441 行 + - 方案 A-4 P0-4（CRITICAL-05）：第 442-575 行 + - 方案 A-5（CRITICAL-06）：第 579-618 行 + - 方案 A-6（CRITICAL-07）：第 621-670 行 + - 方案 A-7（CRITICAL-08）：第 673-705 行 + +### 需要修改的核心文件 +- `internal/task/polling_handler.go` — CRITICAL-01 (parseRealnameStatus), CRITICAL-03 (asynqClient 注入) +- `internal/model/iot_card.go` — CRITICAL-01 (注释修正) +- `pkg/constants/iot.go` — CRITICAL-01 (常量确认) +- `internal/service/client_order/service.go` — CRITICAL-02 (实名判断) +- `internal/bootstrap/services.go` — CRITICAL-04 (rechargeSvc.New() 添加 queueClient) +- `internal/service/recharge/service.go` — CRITICAL-04 (HandlePaymentCallback 触发购包) +- `pkg/queue/handler.go` — CRITICAL-03 (NewPollingHandler asynqClient), CRITICAL-04 (registerAutoPurchaseHandler) +- `internal/task/auto_purchase.go` — CRITICAL-05 (ProcessTask 触发佣金) +- `internal/service/order/service.go` — CRITICAL-06 (sellerCostPrice 6 处审查) +- `pkg/utils/excel.go` — CRITICAL-07 (DeviceRow IMEI 字段) +- `internal/task/device_import.go` — CRITICAL-07 (导入时填充 IMEI) +- `internal/service/my_commission/service.go` — CRITICAL-08 (RowsAffected 校验) + +### 项目规范 +- `AGENTS.md` — 语言要求（中文注释/日志）、错误处理规范、架构分层规范 +- `.planning/research/PITFALLS.md` — 已知陷阱：sellerCostPrice 6 处全量检查要求 + + + + +## Existing Code Insights + +### 已确认的代码现状 +- `sellerCostPrice = buyerCostPrice`：6 处确认（order/service.go 第 187, 262, 472, 548, 734, 809 行） +- RPush 降级 + `_ = task`：polling_handler.go 第 1101-1114 行确认 +- `AutoPurchaseHandler`：已存在于 `internal/task/auto_purchase.go`，但 `pkg/queue/handler.go` 未注册 +- `QueueClient`：已在 `internal/bootstrap/dependencies.go:24` 中定义，已传入 Order、IotCardImport、DeviceImport 服务 + +### Established Patterns +- 错误处理：Service 层用 `errors.New(code)` / `errors.Wrap(code, err)`，禁止 `fmt.Errorf` +- Asynq 任务提交：Worker 内直接用 `h.asynqClient.EnqueueContext()`；Service 层用 `deps.QueueClient.EnqueueTask()` +- 日志：`zap.Logger`，字段用具体类型（`zap.Uint`、`zap.Error` 等），消息用中文 + +### Integration Points +- Worker bootstrap：`pkg/queue/handler.go:RegisterHandlers()` → 任务注册 +- API bootstrap：`internal/bootstrap/services.go:initServices()` → 服务初始化 +- 轮询调度：`internal/polling/scheduler.go` 驱动，不直接受此次改动影响 + + + + +## Specific Ideas + +- CRITICAL-04 的 AutoPurchaseHandler 注入参数列表中有多个 nil 占位符（见方案 A-4 代码片段），agent 应检查当前 `NewAutoPurchaseHandler` 的签名，确保传入参数与现有定义匹配，而非照搬规格书里可能过时的 nil 列表 +- CRITICAL-06 修复时，需对照"五种购买场景表"逐一确认每个分支的"卖家"身份（场景 1/2/3/4/5），不要只看变量名 + + + + +## Deferred Ideas + +None — discussion stayed within phase scope + + + +--- + +*Phase: 01-p0* +*Context gathered: 2026-03-27* diff --git a/.planning/phases/01-p0/01-DISCUSSION-LOG.md b/.planning/phases/01-p0/01-DISCUSSION-LOG.md new file mode 100644 index 0000000..cc0c26a --- /dev/null +++ b/.planning/phases/01-p0/01-DISCUSSION-LOG.md @@ -0,0 +1,69 @@ +# Phase 1: P0 紧急修复 - Discussion Log + +> **Audit trail only.** Do not use as input to planning, research, or execution agents. +> Decisions are captured in CONTEXT.md — this log preserves the alternatives considered. + +**Date:** 2026-03-27 +**Phase:** 01-P0 紧急修复 +**Areas discussed:** CRITICAL-06 修复范围, Bug 执行顺序与分组, Bootstrap 动态限制 + +--- + +## CRITICAL-06 修复范围 + +| Option | Description | Selected | +|--------|-------------|----------| +| 逐一语义审查，按场景修复 | 对每处确认"卖家是谁"再决定是否改；有些场景 buyerCostPrice 可能是正确的 | ✓ | +| 模式匹配全量改为 operatorCostPrice | 出现即改，快但风险高；场景 1/2/3 可能并不需要改 | | + +**User's choice:** 逐一语义审查 +**Notes:** 审查依据为修正业务文档中的五种购买场景对应表 + +--- + +## Bug 执行顺序与分组 + +| Option | Description | Selected | +|--------|-------------|----------| +| 按优先级顺序分 2 批 | 第 1 批主链路（01→02→03→04→05），第 2 批独立 Bug（06/07/08） | ✓ | +| 全部串行，一个 agent 按顶部清单执行 | 简单，但失败时难定位哪一步 | | + +**每个 Bug 一个 commit：** +| Option | Description | Selected | +|--------|-------------|----------| +| 每个 Bug 一个 commit | 回滚粒度细 | ✓ | +| 每批 Bug 一个 commit | 提交记录少 | | + +**User's choice:** 分 2 批，每个 Bug 独立 commit +**Notes:** 无 + +--- + +## Bootstrap 动态限制 + +| Option | Description | Selected | +|--------|-------------|----------| +| 分开处理，各自一个 commit | CRITICAL-03 改 polling handler 注入；CRITICAL-04 改 recharge service + AutoPurchase 注册 | ✓ | +| 合并处理，一个 commit | Worker 初始化路径相关 | | + +**API vs Worker bootstrap 确认：** +经代码确认：`recharge.Service` 只在 API 侧 `services.go` 初始化，`QueueClient` 已在 `deps` 中。Worker 侧 `worker_services.go` 不需要改。 + +| Option | Description | Selected | +|--------|-------------|----------| +| 只改 worker bootstrap（worker_services.go） | | | +| 确认 API 侧是否也用到 recharge.Service | 经查：recharge 在 API services.go，不在 worker | ✓ | + +**User's choice:** API services.go + worker handler.go 各改一处，两个独立 commit +**Notes:** `QueueClient` 已在 `deps` 中，无需新增字段 + +--- + +## the Agent's Discretion + +- 日志消息使用中文 +- 具体代码实现参照规格书提供的代码片段 + +## Deferred Ideas + +None