forge_admin/code-copilot/changes/hotel-reconciliation/tasks.md

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

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

---

前置条件

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

---

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 明细
• 约束: 遵循编码规范（@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）