chore: 明确外卖订单操作入口边界——用户/骑手/商家操作走三个专用控制器（类注释声明职责），PosOrderController 的 add/edit/addorder 标注 @Deprecated（/addorder 2026-09-29 确认废弃，商家端下单走 orderShOprate/createOrder），新增 docs/order-api-usage.md 并同步 CLAUDE.md 与 031 契约闸门调用点表

CLAUDE.md

@@ -35,7 +35,7 @@ Auto-generated from all feature plans. Last updated: 2026-08-18
 - `PosOrderShOprateController` — 商家操作（出餐 chuCan、商家取消）
 - `PosOrderQsOprateController` — 骑手操作（接单/取餐/送达，按 `deliveryStatus` 1/2/3）
 - `UserOrderController` — 用户操作（下单、用户取消）
-- `PosOrderController` — 通用管理接口 `POST /system/order` 的 `add(...)`（新增订单）和 `PUT /system/order` 的 `edit(...)`（修改订单信息）已废弃，代码仅保留备查，不要作为业务入口或在其上增量修改；`/addorder`（下单，含货到付款 sendHdfkMessage）、`/setorderuzt`（平台改状态）及 list 查询仍在用；订单状态流转已迁出
+- `PosOrderController` — 通用管理接口 `POST /system/order` 的 `add(...)`、`PUT /system/order` 的 `edit(...)` 及 `/addorder`（旧代客外送下单，货到付款）均已废弃（2026-09-29 确认），代码仅保留备查，不要作为业务入口或在其上增量修改；商家端下单走 `PosOrderShOprateController` 的 `/createOrder`；`/setorderuzt`（平台改状态）及 list 查询仍在用；订单状态流转已迁出。详见 docs/order-api-usage.md
 
 **推送通道：** `PayPush` 无 Android FCM（cte_server 有，本项目砍掉），仅 iOS uni 云函数（`msduser/msdrider/msdstore`）+ 入库（`PushEvent`→`push_message`）；`cidType` 形同虚设（到处传 `""`）。详见 `specs/012-im-user-integration/code-status.md`。
 

docs/order-api-usage.md

@@ -0,0 +1,44 @@
+# 外卖订单操作入口清单
+
+面向后端维护者的订单接口职责边界。2026-09-29 起明确：**用户、骑手、商家的订单状态流转操作一律走三个专用操作控制器，不使用 `PosOrderController` 的方法**；新增状态流转类功能不得加到 `PosOrderController`。已在四个控制器类注释与 `add`/`edit` 的 `@Deprecated` 标注同步记录。
+
+## 操作入口（在用）
+
+| 角色 | 控制器 | 路由前缀 | 典型操作 |
+|---|---|---|---|
+| 用户 | `UserOrderController` | `/system/userOrder` | 下单（createOrder，含支付方式闸门）、用户取消 |
+| 骑手 | `PosOrderQsOprateController` | `/system/orderQsOprate` | 接单 / 取餐 / 送达（按 `deliveryStatus` 1/2/3） |
+| 商家 | `PosOrderShOprateController` | `/system/orderShOprate` | **商家端下单（/createOrder）**、出餐（chuCan）、商家取消 |
+
+闪送订单不在本清单内，走 `flashdelivery` 包的独立控制器体系。
+
+## PosOrderController（/system/order）职责边界
+
+仍在用：
+
+| 类别 | 接口 |
+|---|---|
+| 查询 | `/getorderlist`、`/getstoreorderlist`、`/getqsorderlist`、`/getqishouorderlist`、`/getorderxq`、`/getorderhout`、`/getuserfootlist`、`/getPsOrdersPosition`、`/list`、`/shlist1`~`/shlist3`、`/export`、`/{id}`、`/{id}/status-context` |
+| 平台改状态 | `/setorderuzt` |
+| 平台管理操作 | `/{id}/status`、`/{id}/line-payment/reconcile`、`/{id}/line-refund`、`/{id}/offline-payment/confirm`、`/{id}/offline-refund/confirm`（Spring Security `@PreAuthorize`，操作留痕 `@Log`） |
+
+已废弃（`@Deprecated` 已标注，代码保留备查，勿增量修改）：
+
+| 接口 | 说明 |
+|---|---|
+| `/addorder` | 旧代客外送下单流程（货到付款 + sendHdfkMessage 推送）；2026-09-29 确认废弃，商家端下单走 `PosOrderShOprateController /createOrder`。内含 031 支付闸门 `assertUsable` 调用点，随入口一并废弃，勿再以此为基准增量开发 |
+| `POST /system/order`（`add`） | RuoYi CRUD 新增订单；用户下单走 `UserOrderController.createOrder` |
+| `PUT /system/order`（`edit`） | 修改订单信息入口不再使用；状态流转已迁出 |
+| `/testYjsdTime` | 随 `setYjsdTime` 停用（依赖已停用的 Mapbox 接口，见 map-api-usage.md） |
+
+## 新改动规则
+
+1. 状态流转类新功能（改 state / deliveryStatus / payStatus / afterSaleStatus 的操作）一律实现到对应角色控制器，不进 `PosOrderController`。
+2. `PosOrderController` 仅维护查询接口、平台管理接口与既有的 `/addorder`、`/setorderuzt`。
+3. 废弃方法不做增量修改；排查问题时也不得以其为基准（同 CLAUDE.md 已废弃代码清单约定）。
+
+## 关联
+
+- `CLAUDE.md` 已废弃代码清单（订单/支付）
+- `specs/030-unified-order-list/`（统一订单列表，列表查询口径）
+- `docs/map-api-usage.md`（`/testYjsdTime`、`setYjsdTime` 停用详情）

ruoyi-admin/src/main/java/com/ruoyi/app/order/PosOrderController.java

@@ -79,7 +79,16 @@ import java.util.stream.Collectors;
 import java.util.stream.Stream;
 
 /**
- * posorderController
+ * 外卖订单通用管理控制器（查询与平台管理向）。
+ *
+ * <p>用户、骑手、商家的订单操作入口不在此类（2026-09-29 记录）：
+ * 用户操作（下单/取消）= UserOrderController，骑手操作（接单/取餐/送达）= PosOrderQsOprateController，
+ * 商家履约操作（出餐/商家取消）= PosOrderShOprateController；状态流转类操作禁止新增到本类。
+ *
+ * <p>本类仍在用的：列表/详情查询（/getorderlist、/getstoreorderlist、/getqsorderlist、/getorderxq 等）、
+ * 平台管理操作（/{id}/status、/{id}/line-refund、/{id}/offline-payment/confirm、/{id}/offline-refund/confirm 等
+ * Spring Security 权限接口）、平台改状态 /setorderuzt；
+ * add/edit 及 /addorder 均已废弃（商家端下单走 PosOrderShOprateController /createOrder），仅保留备查，勿增量修改。
  *
  * @author ruoyi
  * @date 2023-05-23
@@ -1038,7 +1047,9 @@ public class PosOrderController extends BaseController {
 //        Boolean sbsj = dateUtil.isLegalTime(aa,bb);
 //        return success(sbsj);
 //    }
-    //添加新订单
+    //已废弃（2026-09-29 标注）：商家端下单走 PosOrderShOprateController /createOrder；
+    //本入口为旧代客外送下单流程（货到付款），保留备查勿增量修改（内含 031 支付闸门调用点，随入口一并废弃）
+    @Deprecated
     @SneakyThrows
     @Anonymous
     @Auth
@@ -1659,7 +1670,12 @@ public class PosOrderController extends BaseController {
 
     /**
      * 新增posorder
+     *
+     * @deprecated 已废弃（2026-09-29 标注，勿增量修改）：用户下单走 UserOrderController.createOrder，
+     * 商家端下单走 PosOrderShOprateController.createOrder（/system/orderShOprate/createOrder）；
+     * 本 RuoYi CRUD 入口仅保留备查。
      */
+    @Deprecated
     @PreAuthorize("@ss.hasPermi('system:order:add')")
     @Log(title = "posorder", businessType = BusinessType.INSERT)
     @PostMapping
@@ -1669,7 +1685,12 @@ public class PosOrderController extends BaseController {
 
     /**
      * 修改posorder
+     *
+     * @deprecated 已废弃（2026-09-29 标注，勿增量修改）：订单状态流转已迁出到三个操作控制器
+     * （UserOrderController / PosOrderQsOprateController / PosOrderShOprateController），
+     * 修改订单信息的 RuoYi CRUD 入口仅保留备查。
      */
+    @Deprecated
     @Transactional(rollbackFor = Exception.class)
     @PreAuthorize("@ss.hasPermi('system:order:edit')")
     @Log(title = "posorder", businessType = BusinessType.UPDATE)

ruoyi-admin/src/main/java/com/ruoyi/app/order/PosOrderQsOprateController.java

@@ -44,6 +44,10 @@ import java.util.concurrent.TimeUnit;
 import java.util.stream.Collectors;
 import com.ruoyi.app.order.dto.PickupOrderInput;
 
+/**
+ * 外卖订单骑手操作入口（2026-09-29 记录）：接单/取餐/送达（按 deliveryStatus 1/2/3）均在此类实现；
+ * 勿在 PosOrderController 新增骑手操作。
+ */
 @RestController
 @RequestMapping("/system/orderQsOprate")
 public class PosOrderQsOprateController extends BaseController {

ruoyi-admin/src/main/java/com/ruoyi/app/order/PosOrderShOprateController.java

@@ -42,7 +42,8 @@ import java.util.concurrent.TimeUnit;
 import java.util.stream.Collectors;
 
 /**
- * PosOrderShOprateController
+ * 外卖订单商家操作入口（2026-09-29 记录）：商家端下单（/createOrder）、出餐（chuCan）、
+ * 商家取消等均在此类实现；勿在 PosOrderController 新增商家操作。
  *
  * @author ruoyi
  * @date 2023-05-23

ruoyi-admin/src/main/java/com/ruoyi/app/order/UserOrderController.java

@@ -47,6 +47,9 @@ import java.util.stream.Collectors;
 /**
  * 用户订单Controller
  *
+ * 外卖订单用户侧操作唯一入口（2026-09-29 记录）：下单（createOrder）、用户取消等状态流转均在此类实现；
+ * 勿在 PosOrderController 新增用户操作。
+ *
  * @author ruoyi
  * @date 2020-04-01
  */

specs/031-pay-method-config/contracts/api.md

@@ -18,12 +18,12 @@ List<PayMethodOption> listAvailable(GateScope scope, Long payeeUserId)
 enum GateScope { MERCHANT, RIDER_FLASH }
 ```
 
-调用点（**仅此三处 + bankInfo 一处**，禁止新增重复实现）：
+调用点（**在用仅此三处**；`/addorder` 一处随入口废弃留存，清理死代码时须一并移除并更新本表；禁止新增重复实现）：
 
 | 调用方 | 位置 | 参数 |
 |---|---|---|
-| 用户餐饮下单 | `UserOrderController.createOrder`（setPayType 前后） | payType=input.paymentMethod, MERCHANT, 商家主账号 userId |
-| 商家建单 | `PosOrderController /addorder` | payType 固定 "1"(COD), MERCHANT —— COD 默认开，校验保持对称 |
+| 用户餐饮下单 | `UserOrderController.createOrder`（setPayType 前后） | payType=input.paymentMethod, MERCHANT, 商家主账号 userId（US7 起经 `assertUsableForOrder`，见 0.1） |
+| ~~商家建单~~ 旧代客外送下单（**已废弃 2026-09-29**） | `PosOrderController /addorder`（方法已标 `@Deprecated`） | payType 固定 "1"(COD), MERCHANT —— 入口被 `/system/orderShOprate/createOrder` 取代，调用点仅随废弃代码留存，勿作为新改动基准 |
 | 闪送下单 | `FlashDeliveryApplicationService.create`（normalizePayType 处） | payType, RIDER_FLASH, 无收款方（抢单前，只校验平台开关） |
 | 027 bankInfo | `ChantingStoreController.bankInfo` | OFFLINE_TRANSFER, MERCHANT, 商家 userId |