# 变更提案: order-payment-snapshot

## 元信息
```yaml
类型: 功能增强
方案类型: implementation
优先级: P1
状态: 执行中
创建: 2026-04-25
```

---

## 1. 需求

### 背景
当前 `Xboard-new` 的订单支付链路在支付成功后仅稳定保留了 `payment_id`、`trade_no`、`callback_no` 与 `paid_at`，后台订单详情页也主要展示基础信息、金额拆解和佣金状态。用户本轮明确要求：订单支付成功后，应额外保存并展示支付渠道、支付方法，并在 `admin-frontend` 的订单详情中以“成功订单”样式补齐支付成功信息块，至少覆盖平台订单号、商户订单号、订单金额、实际支付金额、创建 / 完成时间、支付 IP 与订单状态等关键信息。

### 目标
- 在后端订单模型中补齐支付成功快照字段，避免后续支付配置变更后后台无法追溯真实支付上下文。
- 在支付回调成功时保存支付渠道、支付方法、实际支付金额与支付 IP，并继续兼容人工标记已支付链路。
- 在 `admin-frontend` 订单详情抽屉中新增支付成功信息块，按 Apple 化后台风格集中展示支付渠道 / 方法与支付流水信息。

### 约束条件
```yaml
范围约束: 本轮只补齐后台订单支付快照的保存与展示，不扩展到前台用户订单详情页
技术约束: 延续 Laravel + Vue3 + TypeScript + Element Plus 现有实现，不新增第三方支付 SDK 或前端 UI 依赖
兼容约束: 现有 `payment_id` / `callback_no` / `paid_at` 语义保持不变；支付插件回调字段缺失时必须优雅降级
视觉约束: 订单详情延续 `.helloagents/DESIGN.md` 中 Apple 风格后台基线，不回退为厚重卡片堆叠
```

### 验收标准
- [ ] `v2_order` 新增支付快照字段后，支付成功时可保存支付渠道、支付方法、实际支付金额与支付 IP。
- [ ] TokenPay 回调会优先写入真实回调里的平台单号 / 实付金额 / 支付 IP / 方法信息；缺失字段时后端使用合理回退值，不影响开通流程。
- [ ] 管理端订单详情可展示支付渠道、支付方法、平台订单号、商户订单号、订单金额、实际支付金额、支付时间与支付 IP。
- [ ] 订单详情 UI 仍保持现有黑色 Hero + 白色工作台的信息层级，不引入新的视觉体系。
- [ ] 后端定向测试与 `admin-frontend` 构建验证通过。

---

## 2. 方案

### 技术方案
1. 为 `v2_order` 增加支付快照字段，补齐模型注释与类型转换，确保支付成功后的快照能够稳定落库。
2. 调整支付成功链路：
   - `plugins/TokenPay/Plugin.php` 在回调验签成功后返回更完整的支付元信息。
   - `app/Http/Controllers/V1/Guest/PaymentController.php` 把支付回调元信息传入订单处理链路。
   - `app/Services/OrderService.php` 在 `paid()` 阶段统一写入支付快照，并兼容人工标记已支付与字段缺失场景。
3. 调整后台订单详情：
   - `app/Http/Controllers/V2/Admin/OrderController.php` 补载 `payment` 关系。
   - `admin-frontend/src/types/api.d.ts` 补齐订单支付快照类型。
   - `admin-frontend/src/views/subscriptions/OrderDetailDrawer.vue` 新增“支付成功信息”区块，按字段分组展示。

### 影响范围
```yaml
涉及模块:
  - app/Services
  - app/Http/Controllers/V1/Guest
  - app/Http/Controllers/V2/Admin
  - app/Models
  - plugins/TokenPay
  - database/migrations
  - admin-frontend/src/types
  - admin-frontend/src/views/subscriptions
预计变更文件: 8-10
```

### 风险评估
| 风险 | 等级 | 应对 |
|------|------|------|
| 第三方支付回调字段命名不稳定，无法保证每个字段都存在 | 中 | 采用“真实回调优先 + 支付配置回退 + 空值兜底”策略，避免因快照缺失阻断支付 |
| 管理端订单详情新增字段后，旧订单历史数据为空 | 低 | UI 明确显示 `-`，仅对新成功订单逐步补齐 |
| 金额快照与现有“分”单位格式不一致 | 中 | 后端统一把回调金额规范为“分”存储，前端继续复用 `formatOrderAmount()` |

---

## 3. 成果设计

### 设计方向
- **美学基调**: Apple Admin Ledger。像运营后台里的“支付流水面板”，强调黑色首屏下的精确信息卡片与支付状态可追溯性。
- **记忆点**: 在订单详情抽屉中新增一块“支付成功信息”面板，把支付渠道 / 方法与平台流水信息收束成一眼可读的成功订单摘要。

### 视觉要素
- **配色**: 延续黑色 Hero、白色详情卡、蓝色强调与成功绿色状态点。
- **布局**: 采用“标题说明 + 右侧状态徽章 + 双列信息网格”的后台信息卡结构，与现有基础信息 / 金额拆解区保持统一。
- **状态**: 有支付快照时优先展示成功信息；历史订单缺字段时保留 `-` 占位，不制造伪数据。

---

## 4. 技术决策

### order-payment-snapshot#D001: 支付渠道与支付方法采用“快照字段 + 当前支付配置回退”双轨展示
**日期**: 2026-04-25
**状态**: ✅采纳
**背景**: 仅依赖 `payment_id` 关联会受到后续支付配置改名影响，无法稳定反映订单成交当时的支付上下文。
**决策**: 在订单表新增 `payment_channel / payment_method / payment_amount / payment_ip` 快照字段，并在详情页中优先展示快照，缺失时再回退到当前 `payment` 关联信息。
**理由**: 既满足历史追溯，也兼容旧订单与人工处理场景。

### order-payment-snapshot#D002: 实际支付金额统一以“分”为单位入库
**日期**: 2026-04-25
**状态**: ✅采纳
**背景**: 当前后台订单金额体系统一以“分”为真相源，前端已有 `formatOrderAmount()` 的统一格式化链路。
**决策**: 支付回调里的实际支付金额在后端转换为整数“分”后入库。
**理由**: 避免前后端引入第二套金额口径，复用现有订单金额展示与排序逻辑。