# 退款退货功能实现报告

## 实现概览

已完成退款退货全链路，包含数据库、API、前台页面、Admin管理页。

---

## 1. 数据库迁移

**文件**: `migrations/versions/007_add_refund_requests.py`

```sql
CREATE TABLE refund_requests (
  id bigint PK,
  tenant_id bigint FK→tenants,
  order_id bigint FK→orders,
  order_no varchar(50),
  customer_id bigint FK→customers,
  type varchar(20),          -- refund/return/exchange
  reason text,
  status varchar(20),         -- pending/approved/rejected/processing/completed
  refund_amount decimal(12,2),
  return_items JSON,
  images JSON,
  admin_note text,
  admin_id bigint FK→users,
  tracking_no varchar(100),
  processed_at datetime(3),
  completed_at datetime(3),
  created_at datetime(3),
  updated_at datetime(3),
  UNIQUE uk_refund_order_unique(tenant_id, order_id)
)
```

- 迁移已执行成功，表已创建
- 索引: tenant_id, order_id, customer_id, status, created_at

---

## 2. ORM 模型

**文件**: `app/core/models/refund.py`

`RefundRequest` 模型，继承 `Base + TenantMixin + TimestampMixin`

关键字段: id, tenant_id, order_id, order_no, customer_id, type, reason, status, refund_amount, return_items(JSON), images(JSON), admin_note, admin_id, tracking_no, processed_at, completed_at

关联: tenant, order, customer, admin

---

## 3. 后端 API

### 3.1 前台 API (`/api/store/refund-requests`)

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/store/refund-requests` | 发起退款申请 |
| GET | `/api/store/refund-requests` | 我的退款列表（分页+状态过滤） |
| GET | `/api/store/refund-requests/{id}` | 退款详情（含关联订单快照） |

**业务规则**:
- 仅 paid/shipped/completed 订单可申请退款
- refund_amount ≤ order.grand_total
- 每订单只能有一个 pending 状态的申请（409 冲突检测）

### 3.2 Admin API (`/api/admin/refund-requests`)

| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/admin/refund-requests` | 列表（分页+状态过滤） |
| GET | `/api/admin/refund-requests/{id}` | 详情 |
| PUT | `/api/admin/refund-requests/{id}?action=approve` | 审核通过 |
| PUT | `/api/admin/refund-requests/{id}?action=reject` | 审核拒绝 |
| POST | `/api/admin/refund-requests/{id}/process` | 处理完成（退款到账） |
| POST | `/api/admin/refund-requests/{id}/reject` | 拒绝退款 |

**业务规则**:
- 审核通过 → 订单状态改为 completed + 退回积分（按退款比例）
- 处理完成 → status=completed + 记录快递单号
- 拒绝 → status=rejected + 记录 admin_note

---

## 4. 前台退款页面

**文件**: `frontend/store/pages/account/refund.vue`

功能:
- 退款申请列表（状态 tab 筛选）
- 选择订单（仅 paid/shipped/completed 订单）
- 填写退款类型/原因/金额/凭证图片/备注
- 查看退款进度详情
- 状态颜色: pending→橙, approved→蓝, rejected→红, processing→紫, completed→绿

入口已集成到账户页侧边栏 tab + account/index.vue 模板中

---

## 5. Admin 退款管理页

**文件**: `frontend/admin/src/views/refunds/RefundList.vue`

功能:
- 表格: 订单号/客户/类型/金额/状态/时间
- 状态筛选 tabs
- 点进看详情抽屉（商品/图片/原因/处理历史）
- 操作: 审核通过/拒绝（带备注）/ 处理完成（带快递单号弹窗）
- 汇总条: 总笔数/待处理/退款总额

路由已注册: `path: 'refunds', name: 'RefundList'`

---

## 6. API 验证

```bash
# 健康检查
curl -s http://localhost:8000/health

# refund API 已注册（openapi.json）
/api/admin/refund-requests
/api/admin/refund-requests/{refund_id}
/api/admin/refund-requests/{refund_id}/process
/api/admin/refund-requests/{refund_id}/reject
/api/store/refund-requests
/api/store/refund-requests/{refund_id}
```

---

## 7. main.py 修复

启动时发现 main.py 有孤立代码块（`inventory_alerts_router` 和 `audit_logs_router` 的 include_router 在 import 之前），已清理。

---

## 状态机

```
pending → approved → processing → completed
        ↘ rejected
```