# 订单支付确认改造 —— 实施计划

> 状态：核心订单支付链路已按分步兼容策略实施；旧字段暂保留兼容
> 日期：2026-05-24

说明：本文来自改造前计划，用于保留决策背景。当前分支没有直接删除旧价格/租期字段，也没有删除增量迁移文件；为了避免影响已有页面和开发库，采用 `price`、`rented_at` 等新字段优先、旧字段兜底的兼容迁移方式。

## 目标

将当前"下单即锁定"的流程改造为：

```
下单 → 待支付(pending_payment) → 支付确认 → 冻结锁定 → 待交接(pending_handoff)
```

同时清理 `price_hourly`、`price_daily`、`price_weekly`、`rent_start_at`、`rent_end_at`、`rent_hours` 等时租残留字段。

---

## 改造清单（按依赖顺序）

```
第1层（无依赖，可并行）
├── A. 合并 3 个 SQL 迁移文件 → 1 个 000001_init.sql
│      修改 rental_listings：price + in_transaction
│      修改 rental_orders：rented_at + estimated_duration_hours
│      修改 notifications：category/link_type/link_id/extra_data
│      新增 sms_logs 表
│      同步改 scripts/dev.sh
│
├── B. Go 模型改造
│      model/listing.go → Price + InTransaction
│      model/order.go → RentedAt + EstimatedDurationHours
│      model/notification.go → Category/LinkType/LinkID/ExtraData
│
第2层（依赖第1层）
├── C. Listing 模块清理
│      listing/dto.go → ListingDTO + CreateRequest 适配
│      listing/repository.go → Create/Update/listQuery/toDTO 全部替换
│      listing/service.go → 校验适配
│
├── D. Order DTO 改造
│      order/dto.go → 删 RentStartAt/RentEndAt/RentHours，加 RentedAt/EstimatedDurationHours
│
第3层（依赖第2层）
├── E. Order 核心改造
│      order/service.go → 删 internalOrderHours，加错误，加 Pay()
│      order/repository.go → Create() → pending_payment + in_transaction
│      order/repository.go → 新增 Pay()：余额→扣款→冻结→锁定→通知
│      order/repository.go → Cancel() 适配 pending_payment
│      order/handler.go → 新增 Pay handler
│      路由注册 → POST /orders/:id/pay
│
├── F. 钱包充值
│      wallet/repository.go → Recharge()
│      wallet/service.go → Recharge()
│      wallet/handler.go → Recharge handler
│      路由注册 → POST /wallet/recharge
│
第4层（依赖第3层 E）
└── G. 超时扫描
      job.go → 新增 handlePendingPaymentTimeout（15min 超时取消）
      system_configs → order.pending_payment_timeout_minutes: 15
```

---

## API 变更

| API | 类型 | 说明 |
|-----|------|------|
| `POST /api/orders` | 行为变更 | 返回 `pending_payment`，不锁商品，标记 `in_transaction` |
| `POST /api/orders/{id}/pay` | **新增** | 校验余额→扣款→冻结→锁定→通知 |
| `POST /api/orders/{id}/cancel` | 行为变更 | 允许取消 `pending_payment` |
| `POST /api/wallet/recharge` | **新增** | 开发环境充值 |

---

## 涉及文件

### 修改（17 个）
```
backend/migrations/000001_init.sql
scripts/dev.sh
backend/internal/model/listing.go
backend/internal/model/order.go
backend/internal/model/notification.go
backend/internal/modules/listing/dto.go
backend/internal/modules/listing/repository.go
backend/internal/modules/listing/service.go
backend/internal/modules/order/dto.go
backend/internal/modules/order/service.go
backend/internal/modules/order/repository.go
backend/internal/modules/order/handler.go
backend/internal/modules/wallet/repository.go
backend/internal/modules/wallet/service.go
backend/internal/modules/wallet/handler.go
backend/internal/router/router.go（或同等路由文件）
backend/internal/jobs/ordertimeout/job.go
backend/internal/modules/systemconfig/defaults.go（或同等文件）
```

### 删除（2 个）
```
backend/migrations/000002_order_checkouts.sql
backend/migrations/000003_add_indexes.sql
```
