### 1.3 Forge 已有代码

```
forge-server/forge-business/forge-hotel/src/main/java/com/mdframe/forge/business/core/hotel/
├── controller/
│   ├── HotelQrCodeController.java      ✅ 二维码管理
│   ├── HotelBusinessHoursController.java ✅ 营业时段管理
│   ├── HotelDishSpecController.java    ✅ 菜品规格管理（规格组 + 选项）
│   └── open/
│       └── HotelOpenController.java    ✅ 开放接口（扫码查询）
├── domain/
│   ├── HotelQrCode.java                ✅ 二维码实体
│   ├── HotelQrBindLog.java             ✅ 绑定日志实体
│   ├── HotelRoom.java                  ✅ 房间实体
│   ├── HotelRoomType.java              ✅ 房型实体
│   ├── HotelBusinessHours.java         ✅ 营业时段实体
│   ├── HotelDishSpecGroup.java         ✅ 规格组实体
│   └── HotelDishSpecOption.java        ✅ 规格选项实体
├── dto/
│   ├── QrCodeBatchGenerateDTO.java     ✅
│   ├── QrCodeBindDTO.java              ✅
│   ├── QrCodeQueryDTO.java             ✅
│   ├── HotelRoomDTO.java               ✅
│   └── HotelRoomTypeDTO.java           ✅
├── vo/
│   ├── HotelQrCodeVO.java              ✅
│   ├── HotelQrBindLogVO.java           ✅
│   ├── QrCodeScanVO.java               ✅
│   ├── HotelRoomVO.java                ✅
│   └── HotelRoomTypeVO.java            ✅
├── mapper/
│   ├── HotelQrCodeMapper.java          ✅
│   ├── HotelQrBindLogMapper.java       ✅
│   ├── HotelRoomMapper.java            ✅
│   ├── HotelRoomTypeMapper.java        ✅
│   ├── HotelBusinessHoursMapper.java   ✅
│   ├── HotelDishSpecGroupMapper.java   ✅
│   └── HotelDishSpecOptionMapper.java  ✅
├── service/
│   ├── HotelQrCodeService.java         ✅
│   ├── HotelBusinessHoursService.java  ✅
│   ├── HotelDishSpecGroupService.java  ✅
│   ├── HotelDishSpecOptionService.java ✅
│   └── impl/
│       ├── HotelQrCodeServiceImpl.java ✅
│       ├── HotelBusinessHoursServiceImpl.java ✅
│       ├── HotelDishSpecGroupServiceImpl.java ✅
│       └── HotelDishSpecOptionServiceImpl.java ✅
├── constant/
│   └── HotelQrConstants.java           ✅
└── utils/
    └── QrCodeUtils.java                ✅

forge-admin-ui/src/views/hotel/
├── qrcode.vue                          ✅ 二维码管理页面（AiCrudPage）
├── room.vue                            ✅ 房间管理页面（AiCrudPage）
├── dish.vue                            ✅ 菜品管理页面（AiCrudPage，含图片预览/上下架/售罄）
├── dishCategory.vue                    ✅ 菜品分类管理页面（AiCrudPage，含启禁用）
├── dishSpec.vue                        ✅ 菜品规格管理（AiCrudPage + 选项管理弹窗）
└── businessHours.vue                   ✅ 营业时段管理（AiCrudPage，时间段下拉选择）

forge-admin-ui/src/api/
└── hotel.js                            ✅ 酒店模块 API（含菜品/分类/规格/营业时段接口）

forge-h5-ui/src/pages/hotel/
└── scan-bind.vue                       ✅ 扫码绑定页面
```

---

## 二、模块迁移状态总览

| # | 模块 | 后端 | 数据库 | 前端 PC | 前端 H5 | 状态 |
|---|------|------|--------|--------|--------|------|
| 1 | room（房间/房型管理） | ✅ | ✅ | ✅ | ✅ | **已完成** |
| 2 | qrcode（二维码管理） | ✅ | ✅ | ✅ | ✅ | **已完成** |
| 3 | open（开放扫码接口） | ✅ | — | — | ✅ | **已完成** |
| 4 | dish-spec（菜品规格管理） | ✅ | ✅ | ✅ | — | **已完成** |
| 5 | business-hours（营业时段） | ✅ | ✅ | ✅ | — | **已完成** |
| 6 | hotelconfig（酒店基础配置） | ❌ | ❌ | ❌ | — | **暂缓**（暂不需要，配送费 + 预计配送时长待讨论） |
| 7 | dish（菜品管理） | ✅ | ✅ | ✅ | — | **核心已完成**（加料/日志待开发） |
| 8 | order（订单管理） | ❌ | ❌ | ❌ | ❌ | **待开发** |
| 9 | notification（实时通知） | ❌ | — | ❌ | — | **待开发** |

---

## 三、各模块详细任务清单

### 3.1 hotelconfig — 酒店基础配置 ⏸️ 暂缓

> **状态**: 暂缓开发。暂时用不到，其中**配送费**和**预计配送时长**功能待后续讨论后再实现。

#### 后端（待开发）

- [ ] 实体：`HotelConfig.java` — 酒店基础配置（名称/主题/配送费/预计配送时长）
- [ ] Mapper: `HotelConfigMapper.java` + XML
- [ ] Service: `HotelConfigService.java` — 获取/保存配置
- [ ] Controller: `HotelConfigController.java` — 配置接口

#### 数据库（待开发）

- [ ] 建表：`hotel_config`（IF NOT EXISTS）
- [ ] 菜单：酒店配置管理（sys_resource）

#### 前端（待开发）

- [ ] 页面：`forge-admin-ui/src/views/hotel/config.vue` — 酒店基础配置表单

#### ⚠️ 待讨论项

- **配送费规则**：按距离/按区域/固定费用？是否支持阶梯定价？
- **预计配送时长**：固定值还是动态计算？单位分钟？
- 这两项功能需要与业务方确认具体需求后再开发

#### 源框架参考

| 文件 | 说明 |
|------|------|
| `hotelconfig/domain/HotelConfig.java` | 配置实体 |
| `hotelconfig/domain/HotelBusinessHours.java` | 营业时段实体 |
| `hotelconfig/controller/HotelConfigController.java` | 全部接口 |
| `hotelconfig/service/HotelConfigService.java` | 全部业务逻辑 |
| `hotelconfig/mapper/xml/HotelConfigMapper.xml` | 配置查询 SQL |
| 前端：`views/hotel/admin/HotelConfigManagement.vue` | 配置管理页面 |
| 前端：`views/hotel/admin/BusinessHoursManagement.vue` | 营业时段页面 |
| 前端：`views/hotel/admin/BusinessHoursForm.vue` | 营业时段表单 |
| 前端：`api/hotel/HotelConfigService.js` | 配置 API |
| 前端：`api/hotel/HotelBusinessHoursService.js` | 营业时段 API |

---

### 3.2 dish — 菜品管理 ⭐⭐⭐

#### 后端

- [x] 实体：`HotelDish.java` — 菜品主表
- [x] 实体：`HotelDishCategory.java` — 菜品分类
- [x] 实体：`HotelDishSpecGroup.java` — 规格组（源框架同时存在 spec 和 spec_group，Forge 统一用 spec_group）
- [x] 实体：`HotelDishSpecOption.java` — 规格选项
- [x] 实体：`HotelDishAddition.java` — 加料
- [x] 实体：`HotelDishLog.java` — 操作日志
- [x] DTO: `HotelDishDTO.java` — 菜品传输对象
- [x] DTO: `HotelDishCategoryDTO.java` — 分类传输对象
- [x] DTO: `DishBatchOperationDTO.java` — 批量操作传输对象
- [x] VO: `HotelDishVO.java` / `HotelDishCategoryVO.java` — 视图对象
- [x] Mapper: `HotelDishMapper.java` + XML（含管理后台分页查询）
- [x] Mapper: `HotelDishCategoryMapper.java` + XML（含分页查询）
- [x] Mapper: `HotelDishSpecGroupMapper.java`
- [x] Mapper: `HotelDishSpecOptionMapper.java`
- [x] Mapper: `HotelDishAdditionMapper.java` + XML
- [x] Mapper: `HotelDishLogMapper.java`
- [x] Service: `HotelDishService.java` — 菜品 CRUD + 上下架 + 售罄/恢复 + 删除
- [x] Service: `HotelDishCategoryService.java` — 分类 CRUD + 启用/禁用
- [x] Service: `HotelDishSpecGroupService.java` — 规格组 CRUD + 级联删除选项
- [x] Service: `HotelDishSpecOptionService.java` — 规格选项 CRUD
- [x] Controller: `HotelDishController.java` — 菜品接口（分页/详情/新增/修改/删除/上下架/售罄/恢复）
- [x] Controller: `HotelDishCategoryController.java` — 分类接口（分页/新增/修改/删除/启禁用）
- [x] Controller: `HotelDishSpecController.java` — 规格组 + 规格选项统一接口
- [ ] Controller: 加料/日志 Controller（待开发）

#### 数据库

- [x] 建表：`hotel_dish`（IF NOT EXISTS）— 含 image（主图）+ images（附加图片）字段
- [x] 建表：`hotel_dish_category`（IF NOT EXISTS）
- [x] 建表：`hotel_dish_spec_group`（IF NOT EXISTS）
- [x] 建表：`hotel_dish_spec_option`（IF NOT EXISTS）
- [x] 建表：`hotel_dish_addition`（IF NOT EXISTS）
- [x] 建表：`hotel_dish_log`（IF NOT EXISTS）
- [x] 字典：`hotel_dish_status`（ON_SALE/OFF_SHELF）
- [x] 字典：`hotel_dish_sold_out`（0=正常/1=售罄）
- [x] 菜单：菜品管理 + 菜品分类管理（sys_resource）
- [x] 菜单权限：菜品增删改查按钮权限
- 迁移脚本：`V1.0.101__add_hotel_dish_module_tables.sql`

#### 前端

- [x] 页面：`forge-admin-ui/src/views/hotel/dish.vue` — 菜品管理（AiCrudPage）
  - 序号列、主图缩略图（AuthImage）、全屏图片预览（主图 + 副图左右切换）
  - 编辑按钮（仅下架可编辑）、上架/下架、售罄/恢复、删除
  - 编辑表单：主厨推荐 (Switch)、状态 (Radio)、价格/制作时长/排序 (inputNumber)、主图/附加图片 (imageUpload)
- [x] 页面：`forge-admin-ui/src/views/hotel/dishCategory.vue` — 菜品分类管理（AiCrudPage）
  - 编辑按钮、启用/禁用操作
- [x] API: `forge-admin-ui/src/api/hotel.js` 中追加菜品/分类相关接口

#### 源框架参考

| 文件 | 说明 |
|------|------|
| `dish/domain/HotelDish.java` | 菜品实体 |
| `dish/domain/HotelDishCategory.java` | 分类实体 |
| `dish/domain/HotelDishSpecGroup.java` | 规格组实体 |
| `dish/domain/HotelDishSpecOption.java` | 规格选项实体 |
| `dish/domain/HotelDishAddition.java` | 加料实体 |
| `dish/domain/HotelDishLog.java` | 日志实体 |
| `dish/controller/HotelDishController.java` | 菜品全部接口 |
| `dish/controller/HotelDishCategoryController.java` | 分类接口 |
| `dish/controller/HotelDishSpecGroupController.java` | 规格组接口 |
| `dish/controller/HotelDishSpecOptionController.java` | 规格选项接口 |
| `dish/service/HotelDishService.java` | 菜品业务逻辑（417 行） |
| `dish/service/HotelDishCategoryService.java` | 分类业务逻辑 |
| `dish/mapper/xml/HotelDishMapper.xml` | 菜品 SQL |
| `dto/DishBatchOperationDTO.java` | 批量操作 DTO |
| 前端：`views/hotel/dish/DishManagement.vue` | 菜品管理页面 |
| 前端：`views/hotel/dish/DishForm.vue` | 菜品表单 |
| 前端：`views/hotel/dish/CategoryManagement.vue` | 分类管理 |
| 前端：`views/hotel/dish/CategoryForm.vue` | 分类表单 |
| 前端：`api/hotel/HotelDishService.js` | 菜品 API |
| 前端：`api/hotel/HotelDishSpecService.js` | 规格 API |

#### 注意事项

- 源框架同时存在 `hotel_dish_spec` 和 `hotel_dish_spec_group` 两张表，Forge 统一使用 `hotel_dish_spec_group`
- 源框架删除菜品时校验未完成订单 → 需要依赖 order 模块（可先预留校验接口，order 完成后再联通）
- 菜品价格使用 `BigDecimal`，金额单位与源框架保持一致（元）

---

### 3.3 order — 订单管理 ⭐⭐⭐⭐（最复杂）

#### 后端

- [ ] 实体：`HotelOrder.java` — 订单主表
- [ ] 实体：`HotelOrderItem.java` — 订单明细
- [ ] DTO: `OrderCreateDTO.java` — 创建订单请求
- [ ] DTO: `OrderDashboardDTO.java` — 看板统计响应
- [ ] VO: `HotelOrderVO.java` — 订单视图对象
- [ ] Mapper: `HotelOrderMapper.java` + XML（含看板统计/今日营收/订单号生成）
- [ ] Mapper: `HotelOrderItemMapper.java` + XML
- [ ] Service: `HotelOrderService.java` — 订单完整生命周期（创建/接单/拒单/备餐/出餐/配送/完成/退单）
- [ ] Controller: `HotelOrderController.java` — 订单全部接口（约 20+ 个）

#### 数据库

- [ ] 建表：`hotel_order`（IF NOT EXISTS）
- [ ] 建表：`hotel_order_item`（IF NOT EXISTS）
- [ ] 字典：`hotel_order_status`（PLACED/ACCEPTED/PREPARING/READY/DELIVERING/COMPLETED/REJECTED/REFUNDED/REFUND_REQUESTED）
- [ ] 字典：`hotel_pay_method`（MOCK/CASH/ONLINE 等）
- [ ] 字典：`hotel_delivery_time_type`（ASAP/CUSTOM）
- [ ] 菜单：订单管理（sys_resource）
- [ ] 菜单权限：订单查看/接单/拒单/备餐/配送/退单审核 按钮权限

#### 前端

- [ ] 页面：`forge-admin-ui/src/views/hotel/order.vue` — 订单管理列表（AiCrudPage）
- [ ] 页面：`forge-admin-ui/src/views/hotel/orderDashboard.vue` — 订单看板（卡片统计 + 实时通知）
- [ ] API: `forge-admin-ui/src/api/hotel.js` 中追加订单相关接口

#### 源框架参考

| 文件 | 说明 |
|------|------|
| `order/domain/HotelOrder.java` | 订单实体 |
| `order/domain/HotelOrderItem.java` | 订单明细实体 |
| `order/controller/HotelOrderController.java` | 全部接口（430 行） |
| `order/service/HotelOrderService.java` | 订单业务逻辑（749 行） |
| `order/mapper/xml/HotelOrderMapper.xml` | 订单 SQL |
| `order/mapper/xml/HotelOrderItemMapper.xml` | 明细 SQL |
| `dto/OrderCreateDTO.java` | 创建订单 DTO |
| `dto/OrderDashboardDTO.java` | 看板 DTO |
| 前端：`views/hotel/hotelfront/HotelFrontOrders.vue` | 前台订单页面 |
| 前端：`views/hotel/kitchen/KitchenOrders.vue` | 厨房订单页面 |
| 前端：`views/hotel/restaurant/RestaurantOrders.vue` | 餐厅订单页面 |
| 前端：`views/hotel/customer/CustomerMenu.vue` | 顾客点餐页面 |
| 前端：`api/hotel/HotelOrderService.js` | 订单 API |

#### 订单状态机

```
PLACED（已下单）
  ├── → ACCEPTED（已接单）→ PREPARING（备餐中）→ READY（出餐）→ DELIVERING（配送中）→ COMPLETED（已完成）
  ├── → REJECTED（已拒单）
  └── → REFUNDED（已退单，未接单时直接退）

ACCEPTED（已接单）
  └── → REFUND_REQUESTED（退单待审核）
         ├── → REFUNDED（审核通过）
         └── → ACCEPTED（审核驳回，恢复）
```

#### 注意事项

- 源框架使用 `synchronized` 防止并发接单 → Forge 应使用 Redisson 分布式锁（`@Idempotent` 或手动加锁）
- 源框架创建订单时自动计算金额（不信任前端价格）→ Forge 保持此安全策略
- 源框架订单完成后自动累加菜品销量 → 需要依赖 dish 模块
- 源框架退单流程较复杂（客户退单 + 前台退单 + 审核退单），需完整迁移

---

### 3.4 notification — 实时通知 ⭐⭐

#### 后端

- [ ] Config: `RedisPubSubConfig.java` — Redis 消息监听容器
- [ ] Service: `OrderNotificationService.java` — 发布消息到 Redis 频道
- [ ] Listener: `OrderNotificationListener.java` — 监听 Redis 消息 → 转发 SSE
- [ ] Manager: `SseEmitterManager.java` — 管理 SSE 长连接 + 广播
- [ ] Controller: `NotificationController.java` — SSE 订阅/取消/连接数

#### 数据库

- 无需新建表（使用 Redis 频道 `hotel:order:notification`）

#### 前端

- [ ] 组件：SSE 订阅工具（EventSource 封装）
- [ ] 集成：订单看板/订单列表页面接收实时通知

#### 源框架参考

| 文件 | 说明 |
|------|------|
| `notification/config/RedisPubSubConfig.java` | Redis Pub/Sub 配置 |
| `notification/service/OrderNotificationService.java` | 通知发布服务 |
| `notification/listener/OrderNotificationListener.java` | Redis 消息监听器 |
| `notification/manager/SseEmitterManager.java` | SSE 连接管理器 |
| `notification/controller/NotificationController.java` | SSE 端点 |

#### 注意事项

- 源框架使用 `javax.annotation.Resource` → Forge 改用 `@RequiredArgsConstructor`
- 源框架使用 `ResponseUtil` → Forge 改用 `RespInfo`
- SSE 在 Forge 框架中需要走 Sa-Token 拦截器配置（排除或放行）
- 此模块依赖 order 模块的事件发布，需在 order 之后或同步开发

---

## 四、框架适配速查表

| 适配项 | jeeplus（源） | Forge（目标） |
|--------|--------------|--------------|
| 实体基类 | `BaseEntity` | `TenantEntity`（含 tenantId + 审计字段） |
| ID 生成 | `UUID.randomUUID()` | `@TableId(type = IdType.ASSIGN_ID)` 雪花算法 |
| 响应体 | `ResponseEntity` / `ResponseUtil` | `RespInfo.success(data)` / `RespInfo.error(msg)` |
| 注入方式 | `@Resource` | `@RequiredArgsConstructor` + `private final` |
| 权限注解 | `@PreAuthorize("hasAuthority('xxx')")` | `@SaCheckPermission("xxx")` |
| 日志注解 | `@ApiLog` | `@OperationLog` |
| SQL 位置 | Service 层 `QueryWrapper` | Mapper XML（DataScopeInterceptor 要求） |
| 逻辑删除 | 手动 `setDelFlag(1)` + `updateById` | `@TableLogic(value="0", delval="id")` 自动 |
| 租户隔离 | 无 | `TenantLineInnerInterceptor` 自动追加 `tenant_id` |
| 字典 | 硬编码状态值 | `DictSelect` / `DictTag` / `useDict()` |
| 前端列表 | 手写 NInput/NSelect | `AiCrudPage` 配置化 |
| 分页参数 | `Page<T>` | `pageNum` + `pageSize`（`@RequestParam`） |
| 分布式锁 | `synchronized` | Redisson（`@Idempotent` 或手动） |

---

## 五、建议开发顺序

```
✅ 1. room（房间/房型管理）     ← 已完成
✅ 2. qrcode（二维码管理）      ← 已完成
✅ 3. open（开放扫码接口）      ← 已完成
✅ 4. dish-spec（菜品规格管理） ← 已完成
✅ 5. business-hours（营业时段）← 已完成
⏸️ 6. hotelconfig（酒店配置）   ← 暂缓（配送费/配送时长待讨论）
 7. dish（加料/日志）         ← 待开发
⬜ 8. order（订单管理）         ← 依赖 dish + room，最复杂
⬜ 9. notification（实时通知）  ← 依赖 order 事件发布
```

---

## 六、数据库表汇总

### 已完成（Forge 已有）

| 表名 | 说明 |
|------|------|
| `hotel_qr_code` | 二维码表 |
| `hotel_qr_bind_log` | 二维码绑定日志表 |
| `hotel_room` | 房间表 |
| `hotel_room_type` | 房型表 |

### 待创建

| 表名 | 说明 | 所属模块 |
|------|------|--------|
| `hotel_config` | 酒店基础配置 | hotelconfig（暂缓） |
| `hotel_order` | 订单 | order |
| `hotel_order_item` | 订单明细 | order |

### 已完成（dish + dish-spec + business-hours 模块）

| 表名 | 说明 | 迁移脚本 |
|------|------|--------|
| `hotel_dish` | 菜品（含主图/附加图片/主厨推荐/售罄/上下架） | V1.0.101 |
| `hotel_dish_category` | 菜品分类 | V1.0.101 |
| `hotel_dish_spec_group` | 菜品规格组 | V1.0.101（建表）+ V1.0.102（菜单） |
| `hotel_dish_spec_option` | 规格选项 | V1.0.101（建表） |
| `hotel_dish_addition` | 加料 | V1.0.101 |
| `hotel_dish_log` | 菜品操作日志 | V1.0.101 |
| `hotel_business_hours` | 营业时段 | V1.0.103（建表 + 菜单 + 字典） |

### 已完成字典

| 字典类型 | 说明 | 迁移脚本 |
|---------|------|--------|
| `hotel_dish_status` | 菜品状态（在售/下架） | V1.0.101 |
| `hotel_dish_sold_out` | 售罄状态（正常/售罄） | V1.0.101 |
| `hotel_meal_type` | 餐段类型（早餐/午餐/晚餐） | V1.0.103 |
| `hotel_business_hours_status` | 营业时段状态（启用/禁用） | V1.0.103 |

### 待新增字典

| 字典类型 | 说明 | 所属模块 |
|---------|------|--------|
| `hotel_order_status` | 订单状态（9 种） | order |
| `hotel_pay_method` | 支付方式 | order |
| `hotel_delivery_time_type` | 配送时间类型 | order |

---

## 七、前端页面汇总

### 已完成

| 页面 | 路径 | 组件 | 说明 |
|------|------|------|------|
| 二维码管理 | `views/hotel/qrcode.vue` | AiCrudPage | 批量生成/绑定/解绑/下载 |
| 房间管理 | `views/hotel/room.vue` | AiCrudPage | 房间/房型 CRUD |
| 菜品管理 | `views/hotel/dish.vue` | AiCrudPage | 图片预览/上下架/售罄/主厨推荐 |
| 菜品分类 | `views/hotel/dishCategory.vue` | AiCrudPage | 分类 CRUD + 启禁用 |
| 菜品规格 | `views/hotel/dishSpec.vue` | AiCrudPage | 规格组列表 + 选项管理弹窗 |
| 营业时段 | `views/hotel/businessHours.vue` | AiCrudPage | 时段列表 + 时间段下拉选择 + 启禁用 |
| 扫码绑定 (H5) | `forge-h5-ui/src/pages/hotel/scan-bind.vue` | UniApp | 扫码绑定房间 |

### 待开发

| 页面 | 路径 | 说明 | 源框架参考 |
|------|------|------|-----------|
| 酒店配置 | `views/hotel/config.vue` | 单例配置表单（暂缓） | `HotelConfigManagement.vue` |
| 订单管理 | `views/hotel/order.vue` | AiCrudPage | `HotelFrontOrders.vue` |
| 订单看板 | `views/hotel/orderDashboard.vue` | 卡片统计+SSE | 无直接参考 |

---

## 八、关键决策记录

### 8.1 暂缓开发项

| 模块 | 原因 | 待讨论点 |
|------|------|--------|
| hotelconfig（酒店基础配置） | 暂不需要 | 配送费规则（按距离/区域/固定？）、预计配送时长（固定/动态？） |

### 8.2 技术决策

| 决策 | 说明 |
|------|------|
| 规格组统一命名 | 源框架同时存在 `hotel_dish_spec` 和 `hotel_dish_spec_group`，Forge 统一使用 `hotel_dish_spec_group` |
| 营业时段时间选择 | 使用下拉选择（09:00~23:30，每 30 分钟一档），而非时间选择器 |
| 餐段类型 | 仅保留早餐/午餐/晚餐三种，移除夜宵 |
| 前端组件规范 | 统一使用 AiCrudPage 配置化页面，保持分页/筛选/操作列格式一致 |

---

*文档最后更新：2026-08-14（营业时段/菜品规格已完成，酒店基础配置暂缓，待开发：加料/日志/订单/通知）*