# 用户使用流程图 — 支付与结算

> **端口说明**: 📱 小程序 | 🖥 管理后台 | 📋 规划师端 | ⚙️ 系统自动
>
> **分层说明**: 🏠 页面 → 🔗 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` | 提现列表 | 管理员提现审核页 |
| 定时任务自动取消超时未支付订单 | 系统自动 | 阶段一异常路径 |