# 订单投诉模块 - 小程序发起 + 后台只读列表

- **变更日期**: 2026-04-23
- **PR**: #1221（主） + #1222/#1223/#1225/#1235（配套 hotfix）
- **Closes**: #1220
- **影响面**: 小程序端（新增 5 接口） + 管理端（新增 2 接口 + 1 菜单）
- **兼容性**: **纯新增**，无既有接口变更

---

## 🎯 业务背景

客户在行程中任意一天（含"整程"）可发起投诉；后端自动通过**企业微信 + 短信**双链路通知订单负责的定制师（管理员）。管理后台侧边栏新增"投诉管理"一级菜单，定制师只读查看自己订单的投诉，超管/主管看全部。无审批流，客户本人可填/改解决备注。

---

## 🛒 小程序端接口（/mp/complaint/**）

统一前缀 `/mp/complaint`，userId 从网关注入的 token 取，前端无需传。

### 1. 发起投诉

```http
POST /mp/complaint/create
Authorization: Bearer <mp-token>
Content-Type: application/json

{
  "orderId": 99988,
  "dayNumber": 2,              // 0 或 null = "整程投诉"; 1..N = 第 N 天
  "types": ["ITINERARY", "VEHICLE"], // 字典 complaint_type: ITINERARY / VEHICLE / HOTEL / OTHER
  "content": "第二天酒店入住流程混乱...",  // 必填 1~500 字
  "imageUrls": ["https://oss/.../1.jpg"],  // ≤9,前端 OSS 直传后给后端 URL
  "videoUrl": "https://oss/.../1.mp4"      // 可空 ≤1
}

返回:
{"code":200,"data":{"complaintId":1024},"success":true}
```

**错误码**：
| Code | 含义 | 附加字段 |
|------|------|------|
| 20301 | 10 分钟冷却中（同一单同一天） | `remainingSeconds` |
| 20302 | 订单不属于当前用户 | — |
| 20303 | dayNumber 超出已发生范围 | `maxDayNumber` |

### 2. 撤回投诉（10 分钟内本人可）

```http
POST /mp/complaint/{id}/cancel
返回: {"code":200,"data":{"success":true}}

错误:
- 20305 非本人投诉
- 20306 已超 10 分钟
```

### 3. 我的投诉列表

```http
GET /mp/complaint/my-page?pageNo=1&pageSize=10

返回: Page<MpComplaintSimpleRespVO>:
- id / orderNo / groupCode
- dayNumber / dayLabel（"整程" 或 "第N天"）
- types: [{code, label}]
- contentSnippet（前 50 字）
- imageCount / videoCount
- isResolved（resolutionNote 非空）
- resolutionEditCount / createdAt
```

### 4. 投诉详情

```http
GET /mp/complaint/{id}

返回 MpComplaintRespVO（在 SimpleRespVO 基础上 + content/imageUrls/videoUrl/resolutionNote/resolutionUpdatedAt/canCancel/canEditResolution）

错误: 20304 不存在或已撤回 / 20305 非本人
```

### 5. 填/改解决备注（最多 2 次）

```http
PUT /mp/complaint/{id}/resolution
{
  "resolutionNote": "已与定制师沟通完毕"
}

返回: {"code":200,"data":{"editCountLeft":1}}

错误:
- 20305 非本人
- 20307 已达 2 次上限
```

---

## 🧑‍💼 管理端接口（/admin/complaint/**，只读）

### 1. 投诉列表（含权限过滤）

```http
GET /admin/complaint/page?pageNo=1&pageSize=10&keyword=&orderNo=&groupCode=&customizerNickname=&types=ITINERARY&isResolved=false&dateFrom=2026-04-01&dateTo=2026-04-23&dayScope=ALL

dayScope: ALL(默认) / WHOLE(整程=dayNumber=0) / SPECIFIC(具体天>=1)

返回 Page<ComplaintRespVO>:
- id / orderId / orderNo / groupCode
- customizerId / customizerNickname
- userId / userNickname
- contactName / contactPhoneMasked（列表脱敏后 4 位）
- dayNumber / dayLabel
- types / content / contentSnippet / imageUrls / videoUrl
- resolutionNote / resolutionEditCount / resolutionUpdatedAt / isResolved
- notifyWechatStatus / notifySmsStatus（PENDING/SUCCESS/FAIL/SKIP）
- status / createdAt / updatedAt
```

### 2. 投诉详情

```http
GET /admin/complaint/{id}

同 Page 返回结构 + contactPhoneDecrypted（明文，仅 complaint:detail 权限 + 非 :self 或本人订单才返）
```

### 3. 权限模型（R4）

| 按钮权限 | 效果 |
|---------|------|
| `complaint:list:self` | 定制师：强制 SQL WHERE customizer_id = currentAdminId |
| `complaint:list:all` | 超管/主管：无过滤 |
| `complaint:detail` | 查看详情（基础权限） |

已配菜单 + 角色绑定：
- SUPER_ADMIN(1) / ADMIN(2) → :all + :detail
- CUSTOMIZER(3) → :self + :detail

---

## 🔔 通知链路（后端自动，前端不关心）

投诉创建成功后 `afterCommit` → 异步双链路发给 `order.customizerId`：

- **企业微信**（已有 WechatMessageDTO + MQ 优先 / Feign 降级）：
  ```
  【客户投诉】
  团号：NM20260422001
  订单号：DD20260422001
  联系人：张三 13800138000
  第 2 天 · 行程/车
  内容：第二天酒店入住流程混乱（50字摘要）
  图片 3 视频 0
  ```
- **短信**（阿里云模板 `aliyun.sms.template.complaint-notify`，签名"呼籁旅行"）：
  ```
  【呼籁旅行】团号${groupCode}订单${orderNo}${day}收到客户投诉(${type})，请登录后台查看。
  ```
  ⚠️ 当前测试服 `SMS_MOCK_TBD`（不真发），运营去阿里云控制台申请模板后 Nacos 替换即生效。

---

## 📂 数据字典（已执行）

- `complaint_type`：ITINERARY=行程 / VEHICLE=车 / HOTEL=房 / OTHER=其他
- 菜单 `投诉管理`（1250 系列，侧边栏末尾压底）

---

## 🎨 前端对接清单

### 管理端（hl-ui admin）
- [ ] 侧边栏自动渲染"投诉管理"（后端 menu tree 已返回）
- [ ] 列表页：表格 + 筛选（6 条件 + dayScope）
- [ ] 详情页（只读）：图/视频预览 + 完整文字 + 解决备注（客人本人写的）+ 通知状态
- [ ] 字段精度：id/orderId 全部 Long 序列化为 String（防 JS 精度丢失，沿用项目全局 Jackson）
- [ ] 按钮权限：根据登录人 roleCodes 走 `complaint:list:self` 或 `:all` 两套菜单，无管理操作按钮

### 小程序端（hl-mp）
- [ ] 订单详情页"整程投诉"入口（dayNumber=null/0）
- [ ] 每日行程卡片"本日投诉"入口（dayNumber=具体天）
- [ ] 投诉表单：类型多选 + 文字（1~500）+ OSS 直传图片（≤9）/ 视频（≤1）
- [ ] 冷却拦截：20301 时展示"10 分钟后再试，剩余 {remainingSeconds}s"
- [ ] "我的投诉"列表 + 详情 + canCancel 显示撤回按钮 + canEditResolution 显示"填写解决备注"

---

## ⚠️ 注意

- 投诉表 `order_complaint` 已在测试服 `hl_order_service_v2` 建好（29 字段 + UNIQUE 防刷 + 4 索引）
- 企微通知依赖 `order.customizerId → admin_user.enterprise_wechat_id → wechat_user.mobile/name`，定制师未绑企微则自动 SKIP 短信/企微两路
- 同一用户 + 同一订单 + 同一 dayNumber 10 分钟只能一次（Redis SETNX + DB UNIQUE 双层兜底）

---

## 🚨 需要后端重启的服务（已完成，此处仅记录）

- hl-user-service（Feign: getAdminNotifyProfile + sendComplaintSms + 字典菜单）
- hl-order-service-v2（投诉主逻辑 + admin controller + internal api）
- hl-mp-service（MpComplaintController + Feign client + VO）
- hl-gateway（admin-complaint-service 路由）