diff --git a/changelogs/2026-04/2026-04-23_order-complaint-module.md b/changelogs/2026-04/2026-04-23_order-complaint-module.md
new file mode 100644
index 0000000..82787f3
--- /dev/null
+++ b/changelogs/2026-04/2026-04-23_order-complaint-module.md
@@ -0,0 +1,204 @@
+# 订单投诉模块 - 小程序发起 + 后台只读列表
+
+- **变更日期**: 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 路由）