优化

docs/Context超时控制改进工作总结.md

@@ -0,0 +1,305 @@
+# Context 超时控制改进工作总结
+
+**时间**: 2026-06-10  
+**任务**: Week 3-4 - 为所有核心模块添加 Context 超时控制
+
+---
+
+## 🎯 目标
+
+为所有 Repository 和 Service 层方法添加 `context.Context` 参数，实现：
+1. 数据库操作超时控制
+2. 请求取消传播
+3. 优雅的超时错误处理
+4. 提升系统稳定性和可控性
+
+---
+
+## ✅ 已完成工作
+
+### 1. Wallet 模块（100% 完成）
+
+#### Repository 层
+- ✅ `Account(ctx context.Context, userID uint64) (*AccountDTO, error)`
+- ✅ `Ledger(ctx context.Context, userID uint64, page, pageSize int) (*PaginatedResult, error)`
+- ✅ `Recharge(ctx context.Context, userID uint64, amountCent int64) (*AccountDTO, error)`
+- ✅ `ConfirmRechargeFromChannel(ctx context.Context, userID uint64, bizNo string, amountCent int64) error`
+- ✅ `Withdraw(ctx context.Context, userID uint64, amountCent int64) (*AccountDTO, error)`
+- ✅ `AdminLedger(ctx context.Context, query AdminLedgerQuery) (*PaginatedResult, error)`
+
+#### Service 层
+- ✅ 所有方法签名已更新，添加 `ctx context.Context` 作为第一个参数
+- ✅ 所有对 Repository 的调用已传递 context
+
+#### Handler 层
+- ✅ 所有 handler 方法使用 `c.Request.Context()` 获取请求上下文
+- ✅ Context 从 HTTP 请求传递到 Service 再到 Repository
+
+#### 测试代码
+- ✅ Service 测试已更新（5 个测试）
+- ✅ Repository 集成测试已更新（9 个测试）
+- ✅ Repository 逻辑测试已更新（14 个测试）
+- ✅ 所有测试通过
+
+#### 数据库操作
+- ✅ 所有数据库查询使用 `db.WithContext(ctx)`
+- ✅ 事务操作传播 context
+
+---
+
+## 🔄 待完成工作
+
+### 2. Order 模块（待开始）
+
+**Repository 层方法（预估 ~20 个）**：
+- `Create(ctx context.Context, userID uint64, req CreateRequest)`
+- `Cancel(ctx context.Context, userID uint64, orderID uint64)`
+- `Pay(ctx context.Context, orderID uint64)`
+- `SubmitHandoff(ctx context.Context, userID uint64, orderID uint64, req SubmitHandoffRequest)`
+- `ConfirmReceive(ctx context.Context, userID uint64, orderID uint64)`
+- `SubmitReturn(ctx context.Context, userID uint64, orderID uint64, req SubmitReturnRequest)`
+- `SubmitCheckout(ctx context.Context, userID uint64, orderID uint64, req SubmitCheckoutRequest)`
+- `ConfirmCheckout(ctx context.Context, userID uint64, orderID uint64)`
+- `CounterCheckout(ctx context.Context, userID uint64, orderID uint64, req CounterCheckoutRequest)`
+- `AcceptCheckout(ctx context.Context, userID uint64, orderID uint64)`
+- ... 更多方法
+
+**Service 层**：所有对应方法
+
+**Handler 层**：所有对应 handler
+
+**测试代码**：28 个测试用例需要更新
+
+---
+
+### 3. Payment 模块（待开始）
+
+**Repository 层方法（预估 ~15 个）**：
+- `Start(ctx context.Context, userID uint64, orderID uint64, req StartPaymentRequest, clientIP string)`
+- `Query(ctx context.Context, paymentNo string)`
+- `HandleNotify(ctx context.Context, provider string, data map[string]string)`
+- `StartRefund(ctx context.Context, orderID uint64, amountCent int64, bizType, reason string)`
+- `AdminQuery(ctx context.Context, query AdminPaymentQuery)`
+- ... 更多方法
+
+**Service 层**：所有对应方法
+
+**Handler 层**：所有对应 handler
+
+**测试代码**：41 个测试用例需要更新
+
+---
+
+### 4. Listing 模块（待开始）
+
+**Repository 层方法（预估 ~10 个）**：
+- `Create(ctx context.Context, userID uint64, req CreateListingRequest)`
+- `Update(ctx context.Context, userID uint64, listingID uint64, req UpdateListingRequest)`
+- `Delete(ctx context.Context, userID uint64, listingID uint64)`
+- `List(ctx context.Context, query ListingQuery)`
+- `Detail(ctx context.Context, listingID uint64)`
+- ... 更多方法
+
+---
+
+### 5. 其他模块
+
+- **Dispute 模块**
+- **Realname 模块**
+- **AdminUser 模块**
+- **PaymentConfig 模块**
+
+---
+
+## 📋 实施建议
+
+### 方案 A：手动逐模块修改（推荐）
+
+**优点**：
+- 精确控制每个修改
+- 可以同步优化代码结构
+- 确保测试全部通过
+
+**缺点**：
+- 工作量大（预估 8-12 小时）
+- 需要逐个测试验证
+
+**步骤**：
+1. 按模块优先级排序：order → payment → listing → 其他
+2. 每个模块按层级修改：Repository → Service → Handler → Tests
+3. 每完成一个模块，运行测试验证
+4. 提交一次代码
+
+---
+
+### 方案 B：自动化脚本批量修改（快速但风险高）
+
+**优点**：
+- 快速完成（1-2 小时）
+- 统一规范
+
+**缺点**：
+- 可能引入错误
+- 需要大量测试验证
+- 可能遗漏边界情况
+
+**不推荐原因**：
+- 各模块方法签名差异较大
+- 有些方法可能已有 context 参数
+- 测试代码结构复杂，难以批量处理
+
+---
+
+### 方案 C：分阶段实施（平衡方案）
+
+**第一阶段（本次）**：
+- ✅ Wallet 模块（已完成）
+
+**第二阶段（下次）**：
+- Order 模块（核心业务，优先级最高）
+- Payment 模块（核心业务，优先级最高）
+
+**第三阶段（后续）**：
+- Listing、Dispute、Realname 等模块
+
+**提交策略**：
+- 每完成一个模块，提交一次
+- 保持每次提交的原子性和可回滚性
+
+---
+
+## 🎯 推荐方案
+
+**采用方案 C - 分阶段实施**
+
+### 本次工作范围
+- ✅ Wallet 模块（已完成）
+- 提交本次工作
+- 更新改进计划文档
+
+### 下次工作范围
+- Order 模块 Context 改造
+- Payment 模块 Context 改造
+- 运行所有测试验证
+- 提交代码
+
+### 后续工作
+- 其他模块 Context 改造
+- 全局测试验证
+- 性能测试（验证超时控制效果）
+
+---
+
+## 📊 预估工作量
+
+| 模块 | Repository 方法数 | Service 方法数 | Handler 数 | 测试用例数 | 预估时间 |
+|------|-----------------|---------------|-----------|-----------|---------|
+| ✅ Wallet | 6 | 5 | 5 | 28 | **2h（已完成）** |
+| Order | ~20 | ~20 | ~15 | 28 | 4h |
+| Payment | ~15 | ~15 | ~10 | 41 | 3h |
+| Listing | ~10 | ~10 | ~8 | ~10 | 2h |
+| 其他 | ~15 | ~15 | ~10 | ~20 | 2h |
+| **总计** | **~66** | **~65** | **~48** | **~127** | **13h** |
+
+---
+
+## 🔍 实施细节
+
+### Context 传递链路
+
+```
+HTTP Request
+    ↓
+Handler (c.Request.Context())
+    ↓
+Service (ctx context.Context, ...)
+    ↓
+Repository (ctx context.Context, ...)
+    ↓
+GORM (db.WithContext(ctx))
+```
+
+### 超时控制示例
+
+```go
+// Handler 层设置超时
+func (h *Handler) CreateOrder(c *gin.Context) {
+    ctx, cancel := context.WithTimeout(c.Request.Context(), 5*time.Second)
+    defer cancel()
+    
+    order, err := h.service.Create(ctx, userID, req)
+    // ...
+}
+
+// Repository 层传播 context
+func (r *Repository) Create(ctx context.Context, userID uint64, req CreateRequest) error {
+    return r.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+        // 事务内的所有操作都会使用 ctx 的超时控制
+        // ...
+    })
+}
+```
+
+### 测试代码模式
+
+```go
+func TestRepositoryMethod(t *testing.T) {
+    db := setupTestDB(t)
+    defer cleanupTestDB(t, db)
+    
+    repo := NewRepository(db)
+    ctx := context.Background()
+    
+    result, err := repo.Method(ctx, params)
+    // ...
+}
+```
+
+---
+
+## ✅ 验证清单
+
+每个模块完成后需要验证：
+
+- [ ] 所有 Repository 方法签名已更新
+- [ ] 所有 Service 方法签名已更新
+- [ ] 所有 Handler 方法已传递 context
+- [ ] 所有数据库操作使用 `WithContext(ctx)`
+- [ ] 所有测试代码已更新
+- [ ] 所有测试通过（`go test ./internal/modules/<module> -v`）
+- [ ] 代码编译通过（`go build ./internal/modules/<module>`）
+- [ ] 无 lint 错误（`golangci-lint run ./internal/modules/<module>`）
+
+---
+
+## 📝 注意事项
+
+1. **向后兼容性**：这是一个破坏性变更（breaking change），所有调用方都需要更新
+2. **超时时间设置**：
+   - 简单查询：2-5s
+   - 复杂查询：5-10s
+   - 事务操作：10-30s
+   - 外部 API 调用：根据 SLA 设置
+3. **错误处理**：需要区分超时错误和业务错误
+4. **测试覆盖**：确保所有路径都覆盖到 context 取消场景
+
+---
+
+## 🚀 下一步行动
+
+### 立即行动（本次会话）
+1. ✅ 提交 Wallet 模块 Context 改造
+2. ✅ 更新改进计划文档
+3. ✅ 创建本文档作为工作记录
+
+### 后续行动（下次会话）
+1. 开始 Order 模块 Context 改造
+2. 完成 Payment 模块 Context 改造
+3. 运行所有测试验证
+4. 提交代码
+
+---
+
+**当前状态**: Wallet 模块已完成，准备提交  
+**下一目标**: Order 和 Payment 模块 Context 改造  
+**预计完成时间**: 剩余 11 小时工作量