docs: 新增支付流程流程图 — 覆盖订单创建/支付/退款/提现全链路

docs/flows/payment-flow.md

@@ -0,0 +1,306 @@
+# 用户使用流程图 — 支付与结算
+
+> **端口说明**: 📱 小程序 | 🖥 管理后台 | 📋 规划师端 | ⚙️ 系统自动
+>
+> **分层说明**: 🏠 页面 → 🔗 API → ⚙️ Service → 📦 数据实体
+
+## 支付场景
+
+系统支持三种支付场景，共享同一套支付网关：
+
+| 场景 | 订单类型 | 触发角色 | 前端端口 |
+|------|---------|---------|---------|
+| 商品购买 | 实物/虚拟商品订单 | 家长 | 📱小程序 |
+| 测评订单 | 测评服务订单 | 家长 | 📱小程序 |
+| 模板购买 | 任务模板包订单 | 家长/规划师 | 📱小程序/📋规划师端 |
+
+```mermaid
+flowchart TD
+    %% ============ 颜色定义 ============
+    classDef page fill:#e3f2fd,stroke:#1565c0,stroke-width:2px
+    classDef api fill:#fff3e0,stroke:#f57c00,stroke-width:1px
+    classDef service fill:#e8f5e9,stroke:#388e3c,stroke-width:1px
+    classDef data fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px
+    classDef external fill:#fce4ec,stroke:#d32f2f,stroke-width:1px,stroke-dasharray:3 2
+    classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px,stroke-dasharray:5 3
+
+    %% ============ 角色 ============
+    A0(("👤 家长")):::actor
+    B0(("📋 规划师")):::actor
+    C0(("🏦 微信/支付宝")):::actor
+    D0(("🖥 管理员")):::actor
+
+    %% ================================================================
+    %% 阶段一：订单创建
+    %% ================================================================
+    subgraph 阶段一[阶段一：创建订单]
+        direction TB
+
+        P1["🏠 选择商品/测评/模板"]:::page
+        P1 -->|"商品ID, 数量, 收货地址"| P1a["🏠 商品确认页"]:::page
+        P1a --> A1["🔗 POST /api/product/order/create"]:::api
+        A1 -->|"商品ID, 数量, 支付方式, 优惠券ID"| S1["⚙️ ProductOrderService.create()"]:::service
+        S1 -->|"写入订单, 状态=pending"| D1["📦 product_orders 表"]:::data
+
+        P1 -->|"孩子ID, 规划师ID, 套餐ID"| P1b["🏠 测评确认页"]:::page
+        P1b --> A1a["🔗 POST /api/dan-assessment/order/create"]:::api
+        A1a -->|"孩子ID, 规划师ID, 套餐ID, 家庭ID"| S1a["⚙️ AssessmentOrderService.createOrder()"]:::service
+        S1a -->|"写入订单, 状态=pending"| D1a["📦 assessment_orders 表"]:::data
+
+        P1 -->|"套餐ID, 支付方式"| P1c["🏠 模板确认页"]:::page
+        P1c --> A1b["🔗 POST /api/payment/create"]:::api
+        A1b -->|"套餐ID, 支付方式, 优惠券ID"| S1b["⚙️ PackagePaymentService.createOrder()"]:::service
+        S1b -->|"写入订单, 状态=pending"| D1b["📦 package_orders 表"]:::data
+    end
+
+    %% ================================================================
+    %% 阶段二：支付处理
+    %% ================================================================
+    subgraph 阶段二[阶段二：支付处理]
+        D1 --> P2["🏠 选择支付方式"]:::page
+        P2 -->|"微信支付"| A2["🔗 POST /api/payment/wechat/create"]:::api
+        A2 -->|"订单号, 商品描述, 金额(分)"| S2["⚙️ PaymentService.createWechatPayOrder()"]:::service
+        S2 -->|"调用微信JSAPI, 获取prepay_id"| E2["🏦 微信支付收银台"]:::external
+        E2 -->|"用户确认支付"| S2a["⚙️ 微信异步回调"]:::service
+        S2a -->|"支付结果通知"| A2a["🔗 POST /api/payment/wechat/callback"]:::api
+        A2a -->|"订单号, 微信交易号"| S2b["⚙️ PaymentService.handlePaymentCallback()"]:::service
+        S2b -->|"更新订单状态=paid"| D2["📦 对应订单表: product_orders<br>或 assessment_orders 或 package_orders"]:::data
+
+        P2 -->|"支付宝"| A2b["🔗 POST /api/payment/alipay/create"]:::api
+        A2b -->|"订单号, 商品描述, 金额"| S2c["⚙️ PaymentService.createAlipayOrder()"]:::service
+        S2c -->|"调用支付宝, 获取form"| E2a["🏦 支付宝收银台"]:::external
+        E2a -->|"用户确认支付"| S2d["⚙️ 支付宝异步回调"]:::service
+        S2d -->|"支付结果通知"| A2c["🔗 POST /api/payment/alipay/callback"]:::api
+        A2c -->|"订单号, 支付宝交易号"| S2e["⚙️ PaymentService.handlePaymentCallback()"]:::service
+        S2e -->|"更新订单状态=paid"| D2
+
+        D2 -->|"订单号"| P2a["🏠 支付成功页"]:::page
+    end
+
+    %% ================================================================
+    %% 阶段三：支付后处理
+    %% ================================================================
+    subgraph 阶段三[阶段三：支付后处理]
+        D2 -->|"商品订单paid"| P3["🏠 商品订单：等待发货"]:::page
+        P3 --> A3["🔗 POST /api/product/order/handlePaymentSuccess"]:::api
+        A3 -->|"订单号, 支付方式, 交易号"| S3["⚙️ 订单后处理"]:::service
+        S3 -->|"更新支付信息, 记录流水"| D3["📦 product_orders 表<br>更新pay_time, transaction_id"]:::data
+
+        D2 -->|"测评订单paid"| P3a["🏠 测评订单：等待预约"]:::page
+        P3a --> A3a["🔗 POST /api/dan-assessment/order/pay"]:::api
+        A3a -->|"订单号, 支付方式"| S3a["⚙️ AssessmentOrderService.payOrder()"]:::service
+        S3a -->|"更新状态=paid, 创建预约"| D3a["📦 assessment_orders 表<br>+ assessment_appointments 表"]:::data
+
+        D2 -->|"模板订单paid"| P3b["🏠 模板订单：应用模板"]:::page
+        P3b --> A3b["🔗 POST /api/payment/apply"]:::api
+        A3b -->|"订单ID, 孩子ID, 选中项"| S3b["⚙️ TaskPlanService.applyPackage()"]:::service
+        S3b -->|"生成任务计划实例"| D3b["📦 task_plan_instances 表<br>下发生成任务"]:::data
+    end
+
+    %% ================================================================
+    %% 阶段四：退款
+    %% ================================================================
+    subgraph 阶段四[阶段四：退款处理]
+        D3 -->|"已支付订单"| P4["🏠 申请退款"]:::page
+        P4 -->|"退款原因"| A4["🔗 POST /api/product/order/refund/apply"]:::api
+        A4 -->|"订单ID, 退款原因, 退款金额"| S4["⚙️ 退款申请处理"]:::service
+        S4 -->|"写入退款记录, 状态=refunding"| D4["📦 pending_refund 表"]:::data
+
+        D4 -->|"待审核退款"| P4a["🖥 管理员：退款审核页"]:::page
+        P4a -->|"审核通过/驳回"| A4a["🔗 POST /api/admin/product/order/refund/approve<br>或 /api/admin/product/order/refund/reject"]:::api
+        A4a -->|"退款ID, 审核结果"| S4a["⚙️ 退款审核处理"]:::service
+        S4a -->|"通过: 发起退款, 状态=refunded<br>驳回: 状态=rejected"| D4a["📦 订单退款状态更新"]:::data
+    end
+
+    %% ================================================================
+    %% 阶段五：提现
+    %% ================================================================
+    subgraph 阶段五[阶段五：佣金提现]
+        D2 -->|"佣金收入"| P5["📋 规划师/管家：提现页"]:::page
+        P5 -->|"输入金额, 账户信息"| A5["🔗 POST /api/withdrawal/apply"]:::api
+        A5 -->|"提现金额, 账户信息"| S5["⚙️ WithdrawalService.apply()"]:::service
+        S5 -->|"写入提现申请, 状态=pending"| D5["📦 withdrawal_requests 表"]:::data
+
+        D5 -->|"待审核提现"| P5a["🖥 管理员：提现审核页"]:::page
+        P5a -->|"审核通过/驳回"| A5a["🔗 POST /api/admin/withdrawal/approve<br>或 /api/admin/withdrawal/reject"]:::api
+        A5a -->|"提现ID, 审核结果"| S5a["⚙️ 提现审核处理"]:::service
+        S5a -->|"通过: 打款, 状态=completed<br>驳回: 状态=rejected"| D5a["📦 withdrawal_requests 表<br>状态更新"]:::data
+    end
+
+    %% ================================================================
+    %% 角色关联
+    %% ================================================================
+    A0 -.- P1
+    A0 -.- P2
+    A0 -.- P3
+    A0 -.- P4
+    B0 -.- P1c
+    B0 -.- P5
+    C0 -.- E2
+    C0 -.- E2a
+    D0 -.- P4a
+    D0 -.- P5a
+```
+
+## 端点明细
+
+### 支付核心
+
+| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
+|------|------|------|---------|---------|
+| `POST /api/payment/wechat/create` | 创建微信支付订单 | ⚙️系统 | 订单号, 商品描述, 金额(分) | prepay_id, 签名参数 |
+| `POST /api/payment/alipay/create` | 创建支付宝订单 | ⚙️系统 | 订单号, 商品描述, 金额(分) | 支付宝form表单 |
+| `POST /api/payment/wechat/callback` | 微信支付回调 | ⚙️系统 | 订单号, 微信交易号 | 成功/失败 |
+| `POST /api/payment/alipay/callback` | 支付宝回调 | ⚙️系统 | 订单号, 支付宝交易号 | 成功/失败 |
+| `POST /api/payment/order/status/{orderNo}` | 查询订单状态 | 📱小程序 | 路径: 订单号 | 订单完整信息 |
+
+### 商品订单
+
+| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
+|------|------|------|---------|---------|
+| `POST /api/product/order/create` | 创建商品订单 | 📱小程序 | 商品ID, 数量, 支付方式, 收货地址, 优惠券ID | 订单信息 |
+| `POST /api/product/order/pay` | 支付商品订单 | 📱小程序 | 订单号, 支付方式 | 支付参数 |
+| `POST /api/product/order/cancel` | 取消订单 | 📱小程序 | 订单号 | 成功/失败 |
+| `POST /api/product/order/handlePaymentSuccess` | 支付成功处理 | ⚙️系统 | 订单号, 支付方式, 交易号 | 成功/失败 |
+| `POST /api/product/order/notify` | 支付异步通知 | ⚙️系统 | 微信/支付宝通知数据 | XML响应 |
+| `POST /api/product/order/refund/apply` | 申请退款 | 📱小程序 | 订单ID, 退款原因, 退款金额 | 成功/失败 |
+| `POST /api/product/order/confirm` | 确认收货 | 📱小程序 | 订单号 | 成功/失败 |
+| `POST /api/product/order/my` | 我的订单列表 | 📱小程序 | 页码, 页大小, 状态筛选 | 分页订单列表 |
+| `POST /api/product/order/detail` | 订单详情 | 📱小程序 | 订单号 | 订单完整信息 |
+
+### 测评订单
+
+| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
+|------|------|------|---------|---------|
+| `POST /api/dan-assessment/order/create` | 创建测评订单 | 📱小程序 | 孩子ID, 规划师ID, 套餐ID, 家庭ID, 用户ID | 订单信息 |
+| `POST /api/dan-assessment/order/pay` | 支付测评订单 | 📱小程序 | 订单号, 支付方式 | 成功/失败 |
+| `POST /api/dan-assessment/order/cancel` | 取消测评订单 | 📱小程序 | 订单号 | 成功/失败 |
+| `POST /api/dan-assessment/order/detail` | 订单详情 | 📱小程序 | 订单号 | 订单信息 |
+| `POST /api/dan-assessment/order/family` | 家庭测评订单列表 | 📱小程序 | 家庭ID | 订单列表 |
+
+### 模板订单
+
+| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
+|------|------|------|---------|---------|
+| `POST /api/payment/create` | 创建模板订单 | 📱📋 | 套餐ID, 支付方式, 优惠券ID | 订单信息 |
+| `POST /api/payment/wechat params` | 获取微信支付参数 | 📱📋 | 订单ID, 微信openid | 微信JSAPI参数 |
+| `POST /api/payment/notify` | 支付回调通知 | ⚙️系统 | 微信XML通知 | XML响应 |
+| `POST /api/payment/apply` | 支付后应用模板 | 📱📋 | 订单ID, 孩子ID, 选中项ID列表 | 任务计划实例 |
+| `POST /api/payment/orders/{orderId}` | 查询订单 | 📱📋 | 路径: 订单ID | 订单信息 |
+| `POST /api/payment/orders/{orderId}/cancel` | 取消订单 | 📱📋 | 路径: 订单ID | 成功/失败 |
+
+### 退款与提现
+
+| 端点 | 说明 | 端口 | 请求数据 | 响应数据 |
+|------|------|------|---------|---------|
+| `POST /api/withdrawal/apply` | 申请提现 | 📋规划师 | 提现金额, 账户信息 | 成功/失败 |
+| `POST /api/withdrawal/history` | 提现记录 | 📋规划师 | 页码, 页大小 | 分页提现记录 |
+| `POST /api/admin/product/order/refund/approve` | 审核通过退款 | 🖥管理后台 | 退款ID | 成功/失败 |
+| `POST /api/admin/product/order/refund/reject` | 驳回退款 | 🖥管理后台 | 退款ID, 驳回原因 | 成功/失败 |
+| `POST /api/admin/withdrawal/approve` | 审核通过提现 | 🖥管理后台 | 提现ID | 成功/失败 |
+| `POST /api/admin/withdrawal/reject` | 驳回提现 | 🖥管理后台 | 提现ID, 驳回原因 | 成功/失败 |
+
+## 数据实体关系
+
+```mermaid
+erDiagram
+    ProductOrder ||--o{ PendingRefund : "退款"
+    AssessmentOrder ||--o{ AssessmentAppointment : "支付后创建预约"
+    PackageOrder ||--o{ TaskPlanInstance : "支付后应用模板"
+
+    ProductOrder {
+        Long id PK
+        string orderNo UK "订单号"
+        Long productId FK
+        Long buyerId FK
+        Long familyId FK
+        int totalAmount "总价(分)"
+        int moneyAmount "现金支付(分)"
+        int pointsUsed "积分抵扣"
+        string status "pending/paid/shipped/completed/refunded/cancelled"
+        string paymentMethod "wechat/alipay/points"
+        string transactionId "微信/支付宝交易号"
+        datetime paidAt
+        datetime createdAt
+    }
+
+    AssessmentOrder {
+        Long id PK
+        string orderNo UK
+        Long familyId FK
+        Long userId FK
+        Long childId FK
+        Long guideId FK
+        Long packageId FK
+        string status "pending/paid/cancelled/refunded"
+        string payType "wechat/alipay"
+        string transactionId
+        Long appointmentId FK "支付后自动创建"
+    }
+
+    PackageOrder {
+        Long id PK
+        string orderNo UK
+        Long userId FK
+        Long familyId FK
+        Long packageId FK
+        int totalAmount
+        string status "pending/paid/cancelled"
+        string paymentMethod
+        datetime paidAt
+    }
+
+    PendingRefund {
+        Long id PK
+        Long orderId FK
+        string orderType "product/assessment"
+        string orderNo
+        int refundAmount
+        string reason
+        string status "pending/approved/rejected/refunded"
+        datetime createdAt
+    }
+
+    WithdrawalRequest {
+        Long id PK
+        Long userId FK
+        int amount
+        string accountInfo
+        string status "pending/approved/rejected/completed"
+        datetime createdAt
+        datetime processedAt
+    }
+```
+
+## 完整性分析
+
+### 流程完整性
+- ✅ 三种订单类型（商品/测评/模板）的创建→支付→后处理完整覆盖
+- ✅ 微信和支付宝两种支付渠道
+- ✅ 支付回调处理（同步+异步）
+- ✅ 退款申请→审核→处理全流程
+- ✅ 佣金提现申请→审核→打款全流程
+
+### 异常路径
+- ❌ 支付超时处理（订单自动取消）未在流程图中体现
+- ❌ 支付金额校验失败路径未标注
+- ❌ 微信/支付宝回调签名验证失败的处理
+- ❌ 退款到原路失败的处理
+
+### 角色覆盖
+- ✅ 家长（创建订单、支付、申请退款）
+- ✅ 规划师（购买模板、提现）
+- ✅ 管理员（审核退款、审核提现）
+- ❌ 系统（定时任务取消超时订单）未标注
+
+### 数据流向
+- ✅ 创建订单 → 写入订单表 → 调用支付网关 → 回调更新 → 后处理
+- ✅ 退款申请 → 写入退款表 → 管理员审核 → 退款处理
+- ✅ 提现申请 → 写入提现表 → 管理员审核 → 打款
+
+### 遗漏端点
+| 端点 | 说明 | 建议补充 |
+|------|------|---------|
+| `POST /api/admin/refund/list` | 退款列表 | 管理员退款审核页 |
+| `POST /api/admin/withdrawal/list` | 提现列表 | 管理员提现审核页 |
+| 定时任务自动取消超时未支付订单 | 系统自动 | 阶段一异常路径 |