# 任务拆分 — 酒店-餐厅对账功能

> 拆分顺序：数据库 → 实体/VO/DTO → Mapper/XML → Service → Controller → 前端 API → 前端页面
> 每个任务 = 可独立提交的原子变更

---

## 前置条件

- [x] 确认多租户方案：方案一（受控跨租户），对账单归酒店租户
- [x] 确认对账周期：按月
- [x] 确认退款订单处理：系统提供排除能力
- [x] 确认餐厅端载体：方案 A（同后台不同角色）
- [x] 确认对账单编号规则：DZ-YYYYMM-NNN
- [x] 确认不需要线上签字
- [x] 确认双方均需导出 Excel
- [x] 确认不需要按餐厅维度拆分

---

## Task 1: Flyway 迁移脚本 — 建表 + 字典 + 菜单 + 导出配置

- **目标**: 创建对账单主表、明细表、字典数据、菜单权限、Excel 导出配置
- **涉及文件**:
    - `forge-server/db/migration/V1.0.143__add_hotel_reconciliation_module.sql` — **新建**
- **内容**:
    1. `CREATE TABLE IF NOT EXISTS hotel_reconciliation`（主表，含逻辑删除 del_flag）
    2. `CREATE TABLE IF NOT EXISTS hotel_reconciliation_item`（明细表）
    3. 字典类型 `hotel_reconciliation_status`（0=待确认/1=已确认/2=已结算）
    4. 一级菜单「对账管理」（与「餐厅管理」同级，sort=12）
    5. 子菜单「对账单」（酒店端）+ 按钮权限（query/generate/exclude/settle/export/submit）
    6. 子菜单「对账单（餐厅）」+ 按钮权限（partner:query/confirm/export）
    7. Excel 导出配置 `hotel_reconciliation_export` + 列配置
- **约束**: 全部 `NOT EXISTS` 防重复，`tenant_id = 1`

---

## Task 2: Entity + DTO + VO

- **目标**: 创建对账单实体、明细实体、生成 DTO、VO
- **涉及文件**（均在 `reconciliation/` 子包下）:
    - `domain/HotelReconciliation.java` — **新建**，extends TenantEntity，含 @TableLogic
    - `domain/HotelReconciliationItem.java` — **新建**，extends TenantEntity
    - `dto/ReconciliationGenerateDTO.java` — **新建**（yearMonth 字段）
    - `vo/HotelReconciliationVO.java` — **新建**，纯 @Data POJO
    - `vo/ReconciliationDetailVO.java` — **新建**，含主表信息 + List<HotelReconciliationItemVO> 明细
- **约束**: 遵循编码规范（@Data + @EqualsAndHashCode(callSuper=true) + @TableName + @Serial + Javadoc 注释）

---

## Task 3: Mapper 接口 + XML

- **目标**: 创建 Mapper 接口和 XML，实现核心查询 SQL
- **涉及文件**:
    - `mapper/HotelReconciliationMapper.java` — **新建**
    - `mapper/HotelReconciliationItemMapper.java` — **新建**
    - `resources/mapper/business/hotel/reconciliation/HotelReconciliationMapper.xml` — **新建**
    - `resources/mapper/business/hotel/reconciliation/HotelReconciliationItemMapper.xml` — **新建**
- **核心 SQL**:
    - `selectPage`：对账单分页查询（支持 status 筛选）
    - `selectPartnerPage`：餐厅端分页（仅 status IN (1,2)）
    - `selectMaxNo`：查当月最大编号（生成编号用）
    - `selectOrdersByMonth`：查指定月份已完成订单（生成对账单数据源）
    - `selectDetailByReconciliationId`：按对账单 ID 查明细列表
    - `selectExportList`：导出查询（供 Excel 导出配置调用）

---

## Task 4: Service 接口 + 实现

- **目标**: 实现核心业务逻辑
- **涉及文件**:
    - `service/HotelReconciliationService.java` — **新建**
    - `service/impl/HotelReconciliationServiceImpl.java` — **新建**
- **核心方法**:
    - `IPage<HotelReconciliationVO> reconciliationPage(PageQuery, HotelReconciliation query)` — 酒店端分页
    - `IPage<HotelReconciliationVO> partnerPage(PageQuery, HotelReconciliation query)` — 餐厅端分页（跨租户）
    - `ReconciliationDetailVO detail(Long id)` — 详情
    - `ReconciliationDetailVO partnerDetail(Long id)` — 餐厅端详情（跨租户）
    - `void generate(ReconciliationGenerateDTO dto)` — 生成对账单
    - `void excludeItem(Long itemId, String reason)` — 排除/恢复明细
    - `void submit(Long id)` — 提交给餐厅（待确认→已确认的前置步骤，或直接改为可确认）
    - `void confirm(Long id)` — 餐厅确认（跨租户）
    - `void settle(Long id, String remark)` — 标记已结算
    - `List<HotelReconciliationVO> queryExportList(Map<String, Object> params)` — 导出查询

---

## Task 5: Controller（酒店端 + 餐厅端）

- **目标**: 创建 REST 接口
- **涉及文件**:
    - `controller/HotelReconciliationController.java` — **新建**，基路径 `/hotel/reconciliation`
    - `controller/HotelReconciliationPartnerController.java` — **新建**，基路径 `/hotel/reconciliation/partner`
- **酒店端接口**:
    - `GET /page` — 分页列表
    - `GET /detail` — 详情
    - `POST /generate` — 生成对账单
    - `POST /excludeItem` — 排除/恢复
    - `POST /submit` — 提交给餐厅
    - `POST /settle` — 标记结算
    - `GET /export` — 导出
- **餐厅端接口**:
    - `GET /page` — 分页列表（跨租户，仅已确认+已结算）
    - `GET /detail` — 详情（跨租户）
    - `POST /confirm` — 确认（跨租户）
    - `GET /export` — 导出（跨租户）
- **约束**: @Autowired 字段注入、@OperationLog、@SaCheckPermission、实体类接收查询参数、方法名路径风格

---

## Task 6: 前端 API 接口定义

- **目标**: 在 hotel.js 中追加对账相关 API 函数
- **涉及文件**:
    - `forge-admin-ui/src/api/hotel.js` — 修改
- **新增函数**:
    - `getReconciliationPage(params)` — 酒店端分页
    - `getReconciliationDetail(id)` — 酒店端详情
    - `generateReconciliation(data)` — 生成对账单
    - `excludeReconciliationItem(itemId, reason)` — 排除明细
    - `submitReconciliation(id)` — 提交
    - `settleReconciliation(id, remark)` — 标记结算
    - `exportReconciliation(params)` — 导出
    - `getPartnerReconciliationPage(params)` — 餐厅端分页
    - `getPartnerReconciliationDetail(id)` — 餐厅端详情
    - `confirmReconciliation(id)` — 餐厅确认
    - `exportPartnerReconciliation(params)` — 餐厅端导出

---

## Task 7: 前端酒店端页面 reconciliation.vue

- **目标**: 酒店端对账单管理页面
- **涉及文件**:
    - `forge-admin-ui/src/views/hotel/reconciliation.vue` — **新建**
- **功能**:
    - AiCrudPage 列表（hide-add / hide-batch-delete / hide-selection）
    - 工具栏：生成对账单按钮（弹窗选月份）
    - 搜索：状态筛选（DictSelect hotel_reconciliation_status）
    - 表格列：编号、周期、订单数、总额、排除数/额、应付、状态（DictTag）、操作
    - 操作列：详情 / 排除管理（待确认）/ 提交（待确认）/ 标记结算（已确认）/ 导出
    - 详情弹窗：汇总信息 + 明细 NDataTable（排除订单灰显）
    - 排除弹窗：排除原因输入
    - 结算弹窗：结算备注输入

---

## Task 8: 前端餐厅端页面 reconciliationPartner.vue

- **目标**: 餐厅端对账单查看页面
- **涉及文件**:
    - `forge-admin-ui/src/views/hotel/reconciliationPartner.vue` — **新建**
- **功能**:
    - AiCrudPage 列表（只读，hide-add / hide-batch-delete / hide-selection）
    - 搜索：状态筛选（仅已确认+已结算）
    - 表格列：同酒店端（去掉排除管理）
    - 操作列：详情 / 确认（已确认状态）/ 导出
    - 详情弹窗：同酒店端（排除订单灰显标注）

---

## Task 9: 构建验证

- **目标**: 确保后端编译通过 + 前端 lint 通过
- **步骤**:
    1. `mvn compile -pl forge-business/forge-hotel -am -DskipTests`
    2. `pnpm.cmd lint:fix`（forge-admin-ui）