# Implementation Plan: 订单状态四字段分离

**Branch**: `test` | **Date**: 2026-05-15 | **Spec**: [spec.md](spec.md)
**Input**: Feature specification from `/specs/006-orderstate/spec.md`

## Summary

将现有 `pos_order` 表中混用的 `state` 字段拆分为四个独立字段（`state`、`delivery_status`、`pay_status`、`after_sale_status`），参考美团订单状态机设计。涉及数据库变更、实体类扩展、MyBatis Mapper 更新、三端（用户/商家/骑手）操作接口改造、新订单列表接口开发、定时任务调整、以及平台管理端前端适配。

## Technical Context

**Language/Version**: Java 21
**Primary Dependencies**: Spring Boot 3.3.5, MyBatis 3.0.3 (mybatis-spring-boot-starter),若依框架
**Storage**: MySQL
**Testing**: 手动测试（项目无自动化测试框架）
**Target Platform**: Linux/Windows Server
**Project Type**: Web Service (REST API + 管理端前端)
**Performance Goals**: 无特殊性能要求，常规 CRUD
**Constraints**: 数据库变更写 SQL 脚本（`updatesql/sql.md`），不直接执行
**Scale/Scope**: 3 个 Controller 改造 + 3 个新列表接口 + 1 个前端项目调整

### 关键文件清单

| 文件 | 路径 | 变更类型 |
|------|------|---------|
| PosOrder.java | `ruoyi-system/.../domain/PosOrder.java` | 新增3个字段 |
| PosOrderMapper.xml | `ruoyi-system/.../mapper/system/PosOrderMapper.xml` | resultMap + SQL 更新 |
| PosOrderShOprateController | `ruoyi-admin/.../app/order/PosOrderShOprateController.java` | 改造接单/出餐 + 新增列表接口 |
| PosOrderQsOprateController | `ruoyi-admin/.../app/order/PosOrderQsOprateController.java` | 改造骑手操作 + 新增列表接口 |
| UserOrderController | `ruoyi-admin/.../app/order/UserOrderController.java` | 改造创建订单 + 新增列表接口 |
| OrderAppealController | `ruoyi-admin/.../app/order/OrderAppealController.java` | 改造取消订单 |
| TestTask.java | `ruoyi-admin/.../app/order/TestTask.java` | 定时任务改造 |
| sql.md | `updatesql/sql.md` | 新增 ALTER TABLE 语句 |
| 平台管理前端 | `E:\QtwCode\foodie\foodie-admin-vue\src\views\system\order\index.vue` | 筛选/展示改造 |

## Constitution Check

*Constitution 为模板状态，无自定义约束。跳过 gate 检查。*

## Project Structure

### Documentation (this feature)

```text
specs/test/
├── plan.md              # This file
├── research.md          # Phase 0 output
├── data-model.md        # Phase 1 output
├── quickstart.md        # Phase 1 output
├── contracts/           # Phase 1 output
└── tasks.md             # Phase 2 output (via /speckit.tasks)
```

### Source Code (repository root)

```text
ruoyi-system/src/main/java/com/ruoyi/system/
├── domain/PosOrder.java                  # 实体类
├── mapper/PosOrderMapper.java            # Mapper接口
└── service/                              # Service层

ruoyi-system/src/main/resources/mapper/system/
└── PosOrderMapper.xml                    # MyBatis XML

ruoyi-admin/src/main/java/com/ruoyi/app/order/
├── PosOrderShOprateController.java       # 商家操作
├── PosOrderQsOprateController.java       # 骑手操作
├── UserOrderController.java              # 用户操作
├── OrderAppealController.java            # 售后/取消
└── TestTask.java                         # 定时任务

updatesql/
└── sql.md                                # SQL迁移脚本

# 前端（外部项目）
E:\QtwCode\foodie\foodie-admin-vue\
└── src/views/system/order/index.vue      # 平台管理端订单页
```

**Structure Decision**: 后端遵循若依多模块 Maven 结构。前端在独立仓库中。

## Complexity Tracking

| Violation | Why Needed | Simpler Alternative Rejected Because |
|-----------|------------|-------------------------------------|
| 四字段拆分增加查询复杂度 | 自取/堂食订单无配送状态，单字段无法表达 | 单 state 字段混用已导致无法支持新订单类型 |

## 2026-08-24 增量实施设计

### 配送费归零

在三个有效下单入口构造 `PosOrder` 时按订单类型归一化配送费：`type=1` 固定写入 `0D`，其他类型沿用请求值。规则在 Controller 边界落库前执行，不修改数据库结构，也不回写请求 DTO。

### 推送文案分流

复用 `PosOrderShOprateController.dispatchOrder()` 的现有 `chuCan(...)` 推送链路。根据订单 `type` 选择内容 key：自取使用新增专属 i18n key，并把 `pickUpNum` 作为消息参数；其他类型继续使用 `no.message.push.merchant.ready.content`。复用 `PayPush` 的用户语言解析、App 推送和 `PushEvent -> push_message` 入库能力。

### 测试策略

- 定向测试三个下单入口的自取配送费归零，并保留至少一个非自取配送费不变用例。
- 定向测试出餐推送内容选择：自取使用专属 key 和取餐码参数，非自取使用原通用 key。
- 修改完成后运行受影响定向测试及 `ruoyi-admin` 模块构建；完整回归结果单独记录。

## 2026-08-28 增量实施设计

外送订单继续复用 `state`、`deliveryStatus`、`payStatus` 和 `qsId`，不增加数据库字段。`deliveryStatus=0` 从“商家出餐后等待骑手”调整为“订单已支付并等待骑手”；骑手接单只推进配送状态，商家随后推进订单状态。

新增订单配送推送服务统一处理两类跨入口副作用：到付创建或在线支付成功后通知附近可接单骑手，以及已分配骑手订单取消后的相关方通知。用户聚合下单、旧 `/addorder` 到付入口、LINE Pay 和 OMG 支付成功入口共用同一开放条件，避免不同支付方式形成不同履约顺序。

商家接单和出餐在原支付、归属校验基础上增加骑手分配校验；骑手新任务查询增加 `state=0` 和 `payStatus=1` 条件。骑手占用查询只统计 `state IN (0,1,2)` 且 `deliveryStatus IN (1,2)` 的有效履约订单，取消订单不继续占用骑手。