docs(02-01): 完成 PERM+FIN+POLL 9项修复计划 PERM-01/02 FIN-01/02/03 POLL-01/02/03/04

2026-03-28 10:46:10 +08:00
parent 754bbcdf3b
commit e1ec024904
18 changed files with 5548 additions and 28 deletions
--- a/.planning/phases/02-perm-fin-realname-poll/02-01-SUMMARY.md
+++ b/.planning/phases/02-perm-fin-realname-poll/02-01-SUMMARY.md
@@ -0,0 +1,148 @@
+---
+phase: 02-perm-fin-realname-poll
+plan: "01"
+subsystem: perm-fin-poll
+tags:
+  - permissions
+  - finance
+  - polling
+  - enterprise
+  - concurrency
+dependency_graph:
+  requires: []
+  provides:
+    - PERM-01
+    - PERM-02
+    - FIN-01
+    - FIN-02
+    - FIN-03
+    - POLL-01
+    - POLL-02
+    - POLL-03
+    - POLL-04
+  affects:
+    - internal/handler/admin/asset.go
+    - internal/service/commission_withdrawal/service.go
+    - internal/handler/admin/commission_withdrawal.go
+    - internal/service/commission_withdrawal_setting/service.go
+    - internal/store/postgres/wechat_config_store.go
+    - internal/polling/scheduler.go
+    - internal/service/iot_card/stop_resume_service.go
+    - internal/service/asset/service.go
+    - internal/store/postgres/package_store.go
+    - internal/service/package_series/service.go
+tech_stack:
+  added: []
+  patterns:
+    - gorm.io/gorm/clause FOR UPDATE 行锁防并发
+    - go-playground/validator 参数校验
+    - 函数签名扩展（分页参数）
+key_files:
+  created: []
+  modified:
+    - internal/handler/admin/asset.go
+    - internal/service/commission_withdrawal/service.go
+    - internal/handler/admin/commission_withdrawal.go
+    - internal/service/commission_withdrawal_setting/service.go
+    - internal/store/postgres/wechat_config_store.go
+    - internal/polling/scheduler.go
+    - internal/service/iot_card/stop_resume_service.go
+    - internal/service/asset/service.go
+    - internal/model/dto/asset_dto.go
+    - internal/store/postgres/package_store.go
+    - internal/service/package_series/service.go
+    - internal/bootstrap/handlers.go
+    - internal/bootstrap/services.go
+    - pkg/openapi/handlers.go
+decisions:
+  - 企业账号权限边界：Resolve 可查（删除拦截），Refresh 不可主动刷新（新增拦截）
+  - GetPackages 分页在内存中排序后切片，避免改动 Store 层查询逻辑
+  - Series 删除检查在 Service 层实现（非 DB 约束），符合项目禁止外键规范
+  - CommissionWithdrawalHandler 新增 validator 字段注入，与其他 Handler 保持一致
+metrics:
+  duration: "约 10 分钟"
+  completed_date: "2026-03-28"
+  tasks: 2
+  files: 14
+---
+
+# Phase 02 Plan 01: PERM + FIN + POLL 9项独立修复 Summary
+
+企业账号权限边界（Resolve 可查/Refresh 只读）、提现流程数据完整性（审批人字段/remark 必填/激活并发锁）、轮询调度和停复机安全修复，全部为独立小修，共 9 个需求 8 个 commit。
+
+## 执行结果
+
+所有 9 个需求（PERM-01/02, FIN-01/02/03, POLL-01/02/03/04）均已修复，`go build ./...` 零新增错误（已有两个预存在的 `service/package` 字段缺失错误不在本 plan 范围内）。
+
+## Task 1: PERM + FIN 修复
+
+### PERM-01 (commit: 2a92ab6)
+- **文件**: `internal/handler/admin/asset.go`
+- **变更**: 删除 `Resolve` 方法中对企业账号的错误拦截（企业账号应可查询资产）
+
+### PERM-02 (commit: 2a92ab6)  
+- **文件**: `internal/handler/admin/asset.go`
+- **变更**: `Refresh` 方法开头新增企业账号拦截（企业账号只读，不允许主动触发运营商刷新）
+
+### FIN-01 (commit: 8f62496)
+- **文件**: `internal/service/commission_withdrawal/service.go`
+- **变更**: `Approve` 的 `updates` map 补充 `approved_by` 和 `approved_at` 字段
+
+### FIN-02 (commit: 9ee2f0b)
+- **文件**: `internal/handler/admin/commission_withdrawal.go`, `internal/bootstrap/handlers.go`, `pkg/openapi/handlers.go`
+- **变更**: `CommissionWithdrawalHandler` 新增 `validator` 字段；`RejectWithdrawal` 补充 `validator.Struct` 参数验证，确保 `remark` 必填
+
+### FIN-03 (commit: bdac4ab)
+- **文件**: `internal/service/commission_withdrawal_setting/service.go`, `internal/store/postgres/wechat_config_store.go`
+- **变更**: 激活配置事务内首步加 `clause.Locking{Strength: "UPDATE"}` 行锁，防止并发时两个事务同时置 `is_active=true`
+
+## Task 2: POLL 修复
+
+### POLL-01 (commit: 922a3d0)
+- **文件**: `internal/polling/scheduler.go`
+- **变更**: `processSchedule` 新增 `TaskTypePollingProtect` 的 `processManualQueue` 和 `processTimedQueue` 调用
+
+### POLL-02 (commit: 8a53123)
+- **文件**: `internal/service/iot_card/stop_resume_service.go`
+- **变更**: `stopCardWithRetry` 和 `resumeCardWithRetry` 中 `gatewayClient==nil` 时返回 `errors.New(CodeInternalError, ...)` 而非 `nil`（原来假装成功会误更新卡状态）
+
+### POLL-03 (commit: 8553a46)
+- **文件**: `internal/model/dto/asset_dto.go`, `internal/service/asset/service.go`, `internal/handler/admin/asset.go`, `internal/handler/app/client_asset.go`
+- **变更**: 新增 `AssetPackagesResult` DTO；`GetPackages` 签名新增 `page/pageSize` 参数（默认 page=1, pageSize=50, max=100）；admin handler 从 Query 参数读取；client_asset.go 调用处同步更新
+
+### POLL-04 (commit: 47aa5f8)
+- **文件**: `internal/store/postgres/package_store.go`, `internal/service/package_series/service.go`, `internal/bootstrap/services.go`
+- **变更**: `PackageStore` 新增 `CountBySeriesID` 方法；`PackageSeries.Service` 注入 `packageStore` 字段；`Delete` 前检查关联套餐数量，有则拒绝删除
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] pkg/openapi/handlers.go 需同步更新签名**
+- **Found during**: Task 1 FIN-02 完成后最终编译验证
+- **Issue**: `CommissionWithdrawalHandler` 构造函数新增了 `validator` 参数，`pkg/openapi/handlers.go` 中文档生成器调用处仍使用旧签名导致编译失败
+- **Fix**: `admin.NewCommissionWithdrawalHandler(nil)` 改为 `admin.NewCommissionWithdrawalHandler(nil, nil)`
+- **Files modified**: `pkg/openapi/handlers.go`
+- **Commit**: 754bbcd
+
+## Known Stubs
+
+无 — 所有修复均为实际业务逻辑，无留桩或占位符。
+
+## Commits
+
+| Commit | Message |
+|--------|---------|
+| 2a92ab6 | fix(perm): 修复企业账号资产权限边界 PERM-01/02 |
+| 8f62496 | fix(fin): 补全提现审批人字段 FIN-01 |
+| 9ee2f0b | fix(fin): 提现拒绝补 remark 必填校验 FIN-02 |
+| bdac4ab | fix(fin): 激活配置并发行锁保护 FIN-03 |
+| 922a3d0 | fix(poll): polling:protect 接入调度器 POLL-01 |
+| 8a53123 | fix(poll): gatewayClient=nil 时停复机返回错误而非成功 POLL-02 |
+| 8553a46 | fix(poll): GetPackages 接口新增分页 POLL-03 |
+| 47aa5f8 | fix(poll): Series 删除前检查关联套餐 POLL-04 |
+| 754bbcd | fix(fin): 同步更新 openapi handlers 中 CommissionWithdrawalHandler 签名 |
+
+## Self-Check: PASSED
+
+所有关键文件存在，所有 commits 均可在 git log 中查到。