chore: apply Spotless formatting

salary_design.md

@@ -0,0 +1,742 @@
+# 工资结算业务设计（PeiPei）
+
+## 心智模型（Mental Model）
+- 冻结期之后入池：订单完成并超过冻结期（Cooling-Off）后，进入“可结算池”（eligible pool）。
+- 结算即消费并打标：无论是手动还是周期性自动结算，都是从同一个池中“消费”订单；提交时通过条件更新把订单从“未结算→已结算”，每个订单只会被消费一次。
+- 并发先到先得：自动与手动可能并发提交，谁先成功把订单标记为已结算，谁拿到该订单；另一次提交只会结算剩余的订单，并看到差异提示。
+- 历史不回溯：新结算不会影响已结算（尤其是已发放）的工资单；已发放的结算单不可变更，只能通过后续“负向调整”处理异常。
+- 配置有快照：每张结算单保存生成时的配置快照（周期、冻结期、退款策略等）；后续修改配置不会影响历史结算。未发放的结算单可选择按“快照”或“最新配置”重算。
+- 退款有策略：
+  - 未发放：可重算并剔除该订单。
+  - 已发放：不改历史，生成负向调整，按策略“冲减下一期（OFFSET_NEXT）”或“立即回收（IMMEDIATE_RECOVER）”。
+- 边界一致性：统一 UTC 存储、按租户时区展示；统计窗口用闭开区间 [start, end) 保持口径一致。
+- 审计与幂等：订单可记录 settlement_id，明细表对 (tenant_id, order_id) 做唯一约束，保障“只结算一次、可追溯可审计”。
+
+## 设计目标
+- 清晰可追溯：店员能看到“某段时间我应得多少”，并能追溯到每一单与计算口径。
+- 灵活可控：店主既可手动结算（挑人/时间/单），也可设置自动结算计划（周期、触发时间、冻结期、是否自动发放）。
+- 可追责与可回滚：每次结算保留规则、范围、计算与调整留痕；退款/重算/冲销有明确策略闭环。
+
+## 核心概念
+- 结算周期 Pay Period：一段明确起止的统计窗口（如 2025-09-01 ~ 2025-09-07）。
+- 结算单 Settlement（工资单）：周期内“已完成且过冻结期”的订单汇总，形成“应结金额”，进入确认与发放流程。
+- 结算明细 Line Item：逐单记录（订单号、完成时间、实付、分成比例、预计收入、优惠券扣减、调整等）。
+- 冻结期 Cooling-Off：订单完成后 X 小时/天内可退款不计入工资；过期后进入“可结算池”。
+- 调整 Adjustment：正/负向校正（奖惩、税费、异常修正等），与证据与操作人绑定。
+
+## 角色与诉求
+- 店员
+  - 未结算：我有哪些单即将入池/已入池，合计多少，预计何时发放。
+  - 已结算：分周期查看应结/调整/实发金额与发放渠道/时间，下载工资条。
+  - 可解释：看到优惠券扣减、比例、退款影响与调整缘由。
+- 店主
+  - 手动结算：指定店员/分组/全部，指定时间段，预览→（可加调整）→生成结算单→发放。
+  - 自动结算：按日/周/月/自定义计划，到点生成草稿或直接发放。
+  - 异常闭环：跨期退款、重算、冲销策略；权限与审计；报表与导出。
+
+## 结算规则与口径
+- 计入范围
+  - 订单状态：已完成（orderStatus=3）。
+  - 冻结期：完成时间超过配置的冻结期（默认 24h）。
+  - 收入口径：以订单落库时的“店员预计收入 estimatedRevenue / 比例”为准（已含优惠券承担策略）。
+- 跨期退款
+  - 未结算时退款：从可结算池剔除。
+  - 已结算后退款：生成负向调整（绑定原订单），策略：
+    - OFFSET_NEXT（冲减下一期，默认）；或
+    - IMMEDIATE_RECOVER（立即冲销并回收账户余额）。
+- 舍入与门槛
+  - 金额保留 2 位、四舍五入（可配置）；最低发放门槛（如 <10 元累计至下期）。
+- 锁定与重算
+  - 结算单状态：Draft → Ready → Paid → Closed。
+  - Paid 锁定；Draft/Ready 允许重算（保留差异快照与版本号）。
+- 多租户与权限
+  - 全流程按租户隔离；店主/财务具备结算与调整权限；店员仅可见本人。
+
+## 业务流程
+- 自动结算
+  1) 到点触发计划（按配置周期/时间）；
+  2) 扫描“已完成且过冻结期且未结算”的订单，按店员聚合生成 Draft 结算单；
+  3) 若开启自动发放：直接进入 Paid，写发放流水与时间并通知；否则停留 Ready，待人工发放。
+- 手动结算
+  1) 选择时间范围/店员/分组/全员→预览“待结算订单 + 初步金额”；
+  2) 可添加正/负调整（需备注与可选证据）；
+  3) 生成结算单（Ready）→ 选择发放渠道（余额/线下）→ 发放（Paid）。
+- 订单入池
+  - 订单完成→冻结计时→过期入“未结算池”→被结算消耗→写入工资明细，并把订单标记为“已结算”与结算时间。
+- 通知
+  - 店员：生成/发放通知与工资条链接；
+  - 店主：自动结算摘要与异常（负向冲销/重算）日报。
+
+## 配置中心（租户级）
+- 周期与时间：DAILY/WEEKLY/MONTHLY/CUSTOM；触发时间点（如 03:00）；自然周/月或滚动周期。
+- 冻结期：单位小时/天；可按下单类型（指定/随机/打赏）细分（可选）。
+- 分成口径：是否使用“订单入库时的预计收入”（默认）；是否允许“按当前比例重算”（默认关闭）。
+- 优惠券承担策略：与订单侧一致；变更通过结算“统一调整”进行口径对齐。
+- 退款冲销策略：OFFSET_NEXT 或 IMMEDIATE_RECOVER；是否回收余额与方式。
+- 金额规则：舍入模式、最低发放门槛、是否预扣税/平台费与比例（可选）。
+- 自动发放：开关；发放渠道默认；失败重试与人工补发流程。
+
+---
+
+## 简易 API 设计（草案）
+
+路径均以租户隔离与鉴权为前提，店员端与店主端分权控制。
+
+### 店主侧（结算与配置）
+- 预览结算（按条件聚合）
+  - POST `/api/payroll/settlements/preview`
+  - Body：`{ startDate, endDate, scope: {type: 'ALL'|'GROUP'|'CLERK', ids:[]}, includeTypes?: ['REGULAR','RANDOM','REWARD'], coolingHours?: number }`
+  - Resp：`[{ clerkId, clerkName, orders:[{orderId,orderNo,finishTime,finalAmount,revenueRatio,estimatedRevenue,couponDeduction}], sum:{orderCount,finalAmount,estimatedRevenue} }]`
+
+- 生成结算单（可带调整）
+  - POST `/api/payroll/settlements`
+  - Body：`{ period:{startDate,endDate}, items:[{clerkId, adjustment?:{amount,reason,evidenceUrl}}], fromPreviewId?:string }`
+  - Resp：`{ settlementIds:[...], status:'READY' }`
+
+- 发放/支付结算单（单个/批量）
+  - POST `/api/payroll/settlements/{id}/pay`
+  - Body：`{ channel:'BALANCE'|'OFFLINE', payRef?:string }`
+  - Resp：`{ id,status:'PAID', paidAt, channel, payRef }`
+
+- 重算未发放结算单
+  - POST `/api/payroll/settlements/{id}/recalculate`
+  - Resp：`{ id, diff:{amountBefore,amountAfter,ordersChanged:[]}, version }`
+
+- 查询结算单列表/详情
+  - GET `/api/payroll/settlements?status=READY&clerkId=&groupId=&from=&to=&page=&size=`
+  - GET `/api/payroll/settlements/{id}`（含明细与调整、快照）
+
+- 添加/撤销调整
+  - POST `/api/payroll/adjustments`
+  - Body：`{ settlementId, clerkId, type:'PLUS'|'MINUS', amount, reason, evidenceUrl }`
+  - DELETE `/api/payroll/adjustments/{id}`
+
+- 自动结算配置
+  - GET `/api/payroll/config`
+  - PUT `/api/payroll/config`
+  - Body：`{ cycle:'DAILY'|'WEEKLY'|'MONTHLY'|'CUSTOM', triggerTime:'HH:mm', coolingHours:number, autoPay:boolean, minPayout:number, rounding:'HALF_UP'|'DOWN'|..., refundPolicy:'OFFSET_NEXT'|'IMMEDIATE_RECOVER', includeTypes?:[...] }`
+
+### 店员侧（自助查询）
+- 我的未结算汇总
+  - GET `/api/payroll/me/summary` → `{ unsettled:{orderCount,finalAmount,estimatedRevenue}, nextExpectedPayTime }`
+- 我的结算单列表/详情
+  - GET `/api/payroll/me/settlements?from=&to=&status=&page=&size=`
+  - GET `/api/payroll/me/settlements/{id}`（含订单明细、调整、发放信息）
+
+---
+
+## 表结构设计（草案）
+
+说明：系统已有表 `play_clerk_wages_info`、`play_clerk_wages_details_info` 与订单 `play_order_info`。为支持完整结算流程，建议补充或扩展字段（向后兼容）。以下为建议DDL（伪SQL，仅供参考）。
+
+### 1) 店员工资结算汇总（扩展）
+表：`play_clerk_wages_info`
+- 现有主要字段：`id, tenant_id, clerk_id, start_count_date, end_count_date, settlement_date, order_number, final_amount, estimated_revenue, order_continue_* , orders_expired_number, serial_number, version, deleted`
+- 新增建议字段：
+  - `status` varchar(16) COMMENT 'Draft|Ready|Paid|Closed'
+  - `pay_amount` decimal(10,2) DEFAULT 0.00 COMMENT '实发金额=estimated_revenue+adjustment_amount，受门槛/舍入影响'
+  - `adjustment_amount` decimal(10,2) DEFAULT 0.00 COMMENT '调整合计（可负）'
+  - `pay_channel` varchar(16) NULL COMMENT 'BALANCE|OFFLINE|...'
+  - `pay_time` datetime NULL
+  - `pay_reference_no` varchar(64) NULL COMMENT '发放流水号/凭证'
+  - `payroll_no` varchar(32) NULL COMMENT '结算单号（可读性）'
+  - `remarks` varchar(512) NULL
+  - 索引：`idx_wages_tenant_status (tenant_id,status,pay_time)`；`uniq_payroll_no (tenant_id,payroll_no)`
+
+### 2) 店员工资结算明细（扩展）
+表：`play_clerk_wages_details_info`
+- 现有字段：`id, tenant_id, wages_id, clerk_id, order_id, order_no, final_amount, estimated_revenue, end_order_time, ...`
+- 新增建议字段：
+  - `revenue_ratio` int NULL COMMENT '订单时的分成比例%'
+  - `coupon_deduction` decimal(10,2) DEFAULT 0.00 COMMENT '与店员相关的优惠扣减'
+  - `adjustment_amount` decimal(10,2) DEFAULT 0.00 COMMENT '单笔调整（如异常修正）'
+  - `first_order` varchar(1) NULL COMMENT '0/1'
+  - `place_type` varchar(1) NULL COMMENT '-1/0/1/2'
+  - 索引：`idx_details_wages (tenant_id,wages_id)`；`idx_details_order (tenant_id,order_id)`
+
+### 3) 结算调整记录（新增）
+表：`play_payroll_adjustment`
+- `id` varchar(32) PK
+- `tenant_id` varchar(32)
+- `settlement_id` varchar(32) NOT NULL
+- `clerk_id` varchar(32) NOT NULL
+- `type` varchar(8) NOT NULL COMMENT 'PLUS|MINUS'
+- `amount` decimal(10,2) NOT NULL
+- `reason` varchar(512) NULL
+- `evidence_url` varchar(512) NULL
+- `operator_id` varchar(32) NOT NULL
+- `operator_name` varchar(64) NULL
+- `created_time` datetime NOT NULL
+- 索引：`idx_adj_settlement (tenant_id,settlement_id)`
+
+### 4) 自动结算计划（新增）
+表：`play_payroll_plan`
+- `id` varchar(32) PK
+- `tenant_id` varchar(32) NOT NULL
+- `name` varchar(64) NOT NULL
+- `cycle` varchar(16) NOT NULL COMMENT 'DAILY|WEEKLY|MONTHLY|CUSTOM'
+- `trigger_time` varchar(8) NOT NULL COMMENT 'HH:mm'
+- `cooling_hours` int NOT NULL DEFAULT 24
+- `auto_pay` tinyint(1) NOT NULL DEFAULT 0
+- `min_payout` decimal(10,2) DEFAULT 0.00
+- `rounding` varchar(16) DEFAULT 'HALF_UP'
+- `refund_policy` varchar(32) DEFAULT 'OFFSET_NEXT' COMMENT 'OFFSET_NEXT|IMMEDIATE_RECOVER'
+- `include_types` varchar(64) NULL COMMENT 'REGULAR,RANDOM,REWARD'
+- `enabled` tinyint(1) NOT NULL DEFAULT 1
+- `created_time` datetime, `updated_time` datetime
+- 索引：`idx_plan_tenant_enabled (tenant_id,enabled)`
+
+### 5) 计划运行日志（新增）
+表：`play_payroll_run_log`
+- `id` varchar(32) PK
+- `tenant_id` varchar(32) NOT NULL
+- `plan_id` varchar(32) NOT NULL
+- `run_time` datetime NOT NULL
+- `status` varchar(16) NOT NULL COMMENT 'SUCCESS|PARTIAL|FAILED'
+- `generated_settlements` int DEFAULT 0
+- `paid_settlements` int DEFAULT 0
+- `message` varchar(1024) NULL
+- 索引：`idx_runlog_plan (tenant_id,plan_id,run_time)`
+
+---
+
+## 状态机（结算单）
+- Draft：生成草稿，未锁定，可重算与编辑调整。
+- Ready：待发放；可批量发放；可重算。
+- Paid：已发放并锁定；仅允许附加备注或生成负向调整进入下期冲销。
+- Closed：业务上关闭（例：被替代的版本或已归档）。
+
+迁移：Draft → Ready → Paid → Closed；Ready↔Draft（仅未发放时）。
+
+## 报表与导出
+- 维度：按店员/分组/周期，产出应结、调整、实发、订单数、退款冲销、TOP 列表与趋势。
+- 导出：结算单工资条 PDF/Excel、汇总对账单。
+
+## MVP 落地建议
+1) 先用“订单落库时的 estimatedRevenue”做口径；
+2) 实现：预览→生成结算（Ready）→发放（Balance）→订单打“已结算”标；
+3) 自动结算先不自动发放；
+4) 提供负向调整/冲销“冲减下一期”；
+5) 店员/店主端最小信息集与导出。
+
+> 备注：本文为业务与数据结构草案，开发落地需与现有表结构与代码对齐（如 MyBatis-Plus 实体、租户拦截、定时任务与权限模型）。
+
+---
+
+## 防错与冲突处理（关键业务规则）
+
+### 核心原则
+- 唯一归属与幂等：每个订单最多被一个结算单消费；“提交结算”用条件更新（order_settlement_state=0）实现天然去重。
+- 配置快照：结算单保存当时配置（周期、冻结期、退款策略…），后续改配置不影响已生成/已发放单；重算默认沿用快照，可选按新配置重算。
+- 非重叠窗口：同一店员任意时刻最多存在一个“活动（Draft/Ready）”结算窗口，避免重复覆盖。
+
+### 典型冲突与处理策略
+- 自动刚结算，紧接着手动结算：
+  - 以提交时 eligible 订单为准（未结算且过冻结期）；自动已消费的订单不会再次计入。
+  - 预览页提示“部分订单已在X结算单中结算”，提交后回显差异。
+- 自动与手动同时提交（竞态）：
+  - 不做预留锁，提交时抢占；条件更新谁先成功谁消费；另一次提交金额可能为0并提示。
+- 同店员多活动工资单：
+  - 校验并限制，同店员同租户仅允许一个 Draft/Ready；新建前需发放/关闭旧草稿；窗口不可交叠。
+- 改变结算周期（如周结→半月）：
+  - 默认“从下次触发起生效”；旧计划跑完，新计划按新周期起算；不跨期追溯。
+  - 提供“期中迁移向导”：把未结算池按新周期切割预览，一键生成 Ready 结算单。
+- 改变冻结期（24h→12h/48h）：
+  - 默认前向生效：仅影响变更后完成的订单；已完成订单按旧值判定。
+  - 可选“追溯重算向导”：列出因此新增/剔除的订单，允许一次性处理。
+- 手动窗口与自动计划重叠：
+  - 基于未结算池天然去重，但为避免碎片化，仍限制窗口交叠并提供“对齐计划边界”快捷选项。
+- 预览符合、提交时变化（跨边界/被他方消费）：
+  - 以提交为准；返回“变化提示”摘要（新增/剔除订单与金额差）。
+- 已发放后发生退款：
+  - 生成“负向调整”（绑定原订单）；策略可配置：
+    - OFFSET_NEXT：冲减下一期（可选是否即时回收余额）；
+    - IMMEDIATE_RECOVER：即时回收并通知，下一期不再重复扣减。
+- 重算策略（未发放）：
+  - 允许重算；默认沿用快照，可选应用最新配置；保留差异快照与版本号。
+- 时区/边界：
+  - 服务端统一 UTC 存储、按租户时区展示；周期用闭开区间 [start, end)。
+
+### 关键防错机制与索引
+- 订单唯一消费：
+  - 在工资明细表增加唯一索引 `uniq_tenant_order (tenant_id, order_id)`；
+  - 或在订单表增加 `settlement_id` 字段，并用 `where order_settlement_state=0` 条件更新确保幂等。
+- 活动物资单约束：
+  - 逻辑层保证同店员同租户仅一个 Draft/Ready；可在表层加入部分索引辅助查询（如 `idx_wages_tenant_status`）。
+- 配置快照字段：
+  - `plan_cycle_snapshot, trigger_time_snapshot, cooling_hours_snapshot, refund_policy_snapshot, include_types_snapshot, plan_version`。
+- 计划版本化：
+  - 变更计划→旧计划 disabled，新计划 enabled(effective_at)；定时仅拉取有效版本；运行日志写 `plan_id/version`。
+- 提交前后差异校验：
+  - 提交端使用与预览相同条件+条件更新，回显影响行数与差异；为0时提示“无可结算”。
+
+### 配置变更落地策略（默认）
+- 周期变更：从下次触发起生效；提供“期中迁移向导”。
+- 冻结期变更：默认前向生效；提供“追溯重算向导”。
+- 自动 vs 手动：以未结算池为准天然去重；限制同店员仅一个活动结算单。
+
+---
+
+## 细则
+
+### 整体心法
+- 一个订单只能被一个结算单“吃掉”。“未结算池”= 已完成 + 过冻结期 + 未结算 的订单集合。
+- 结算单保存“配置快照”，后续改配置不影响历史；未发放时可重算，默认沿用快照，也可显式用新配置。
+- 同一店员同一时间最多一个“活动结算窗口”（Draft/Ready），避免重复与碎片。
+
+### 核心对象
+- 订单（play_order_info）：`orderStatus=3` 完成；`order_settlement_state`（0/1）；`order_end_time`；`estimatedRevenue`（按比例计算的店员应得）。
+- 结算单（play_clerk_wages_info）：新增/建议字段 `status/pay_amount/adjustment_amount/pay_channel/pay_time/payroll_no` + 配置快照字段。
+- 结算明细（play_clerk_wages_details_info）：逐单记录，建议唯一索引 `(tenant_id, order_id)` 防重复。
+- 调整（play_payroll_adjustment）：正/负调整，含 `reason/evidence/operator` 审计。
+- 计划（play_payroll_plan）：自动结算的周期/时间/冻结期/自动发放，含版本与运行日志。
+
+### 冻结期理解
+- 作用：完成后短期可退款，需等待；过了冻结期才进入“未结算池”。
+- 判定：`order_end_time <= now - coolingHours`。
+- 变更：默认“前向生效”；若需追溯，走“追溯重算向导”，列出新增/剔除候选供确认。
+
+### 流程：预览 → 提交
+- 预览：查询符合条件的订单（不加锁），展示店员聚合的金额/列表。
+- 提交（幂等/抢占）：
+  1) 事务内条件更新，将订单 `settlement_state:0→1`，写 `settlement_time/settlement_id`；
+  2) 回读本次吃到的订单集合；
+  3) 插入结算明细与汇总，保存快照；
+  4) 自动发放则记账与流水；否则置 Ready；
+  5) 返回“差异摘要”（与预览的差别）。
+- 明细表唯一索引兜底，避免重复插入。
+
+### 自动 vs 手动 冲突
+- 自动吃走一部分后手动提交：手动提交按剩余 eligible 订单结算，金额自然减少，并提示“已被结算单X消费”。
+- 同时提交：谁先成功谁消费；另一次影响行数为0或金额变小，提示差异。
+
+### 活动作业窗口与非重叠
+- 同店员同租户仅一个 Draft/Ready；若支持多窗口，则窗口时间不可交叠（闭开区间 [start,end)）。
+
+### 配置快照的意义
+- 保存 `cycle/trigger_time/cooling_hours/refund_policy/include_types/plan_version`，保证历史不受新配置影响；重算默认用快照。
+
+### 周期与冻结期的改变
+- 周期：默认从“下次触发”起生效；提供“期中迁移向导”对未结算池按新周期切割并生成 Ready。
+- 冻结期：默认前向；提供“追溯重算向导”列出会新增/剔除的候选供一次性处理。
+
+### 退款处理（不同阶段）
+- 冻结期内：未入池，直接不计入。
+- 已入池未发放：允许重算，剔除该订单并更新金额。
+- 已发放：生成“负向调整”，策略二选一：
+  - OFFSET_NEXT：下一期冲减（可配置是否立即回收余额）；
+  - IMMEDIATE_RECOVER：立即回收并通知，下一期不重复扣。
+
+### 舍入与最低发放
+- 在“发放阶段”统一舍入（默认保留2位四舍五入），写入 `pay_amount`；低于门槛的留到下一期。
+
+### 时区与边界
+- 存储 UTC、展示按租户时区；周期用闭开区间 `[start, end)` 统一口径。
+
+### 审计与可追责
+- 明细唯一：`uniq_tenant_order (tenant_id, order_id)`；订单可写 `settlement_id` 追溯。
+- 计划版本化：禁用旧计划、启用新计划（effective_at）；运行日志含 `plan_id/version` 与统计。
+- 结算单/调整记录操作人与备注完整保留。
+
+### 示例时序
+- 周二 10:00 订单A完成，冻结24h；周三 10:00 可入池。
+- 周三 03:00 自动计划跑，A 未过冻结期 → 不吃到。
+- 周三 10:05 手动预览：看到 A。
+- 周三 10:06 他人触发自动提交并成功吃到 A。
+- 周三 10:07 店主手动提交：影响行数0，提示“A已被结算单#123消费”。
+
+### 实现模式（可复用）
+- 预览：`SELECT ... WHERE status=3 AND settlement_state=0 AND end_time<=:cutoff`。
+- 提交：
+  - `UPDATE ... SET settlement_state=1, settlement_time=NOW(), settlement_id=:sid WHERE ... AND settlement_state=0 AND end_time<=:cutoff AND id IN (:previewIds)`；
+  - 回读实际吃到的订单→插入明细与汇总。
+- 事务：以“单个结算单”为单位，避免大事务。
+
+### 测试清单
+- 竞态：两并发提交同批订单，断言仅一方成功（影响行数>0）。
+- 冻结边界：cutoff ±1 秒。
+- 退款路径：冻结内/外、已发放与未发放。
+- 配置变更：周期/冻结期前向与向导追溯。
+- 调整项：正负组合、累计多次，实发金额与报表一致。
+- 时区：跨日/跨周边界。
+- 幂等重试：提交阶段服务异常重试不重复消费订单。
+
+---
+
+## 配置快照（Snapshot）细则
+
+### 一、是什么（定义）
+- 配置快照 = 结算单生成时，把与计算相关的关键配置“拍个照”保存在结算单里，用于追溯与稳定重算。
+- 建议纳入快照的要素：
+  - 周期与窗口：`cycle_snapshot`（DAILY/WEEKLY/MONTHLY/CUSTOM）、该结算单统计区间 `[startDate, endDate)`；
+  - 冻结期：`cooling_hours_snapshot`；
+  - 计入范围：`include_types_snapshot`（REGULAR/RANDOM/REWARD…）、优惠券承担策略、收入口径（按订单入库比例 vs. 当前比例）；
+  - 结算规则：`rounding_snapshot`、`min_payout_snapshot`、`refund_policy_snapshot`（OFFSET_NEXT/IMMEDIATE_RECOVER）、`timezone_snapshot`；
+  - 计划版本：`plan_version`、`trigger_time_snapshot`；
+  - 资格边界时间：`eligibility_cutoff_at`（当次计算使用的“冻结边界时间点”）。
+
+### 二、为什么要有（目的）
+- 保证历史不漂移：配置改了，历史金额/明细不变，便于对账与审计。
+- 可控重算：未发放时默认用快照重算（稳定），也可显式用新配置重算（改变口径），并生成差异快照。
+- 审计留痕：能还原“当时按什么规则产生了这张结算单”。
+
+### 三、怎么保存（形态）
+- 字段式：在 `play_clerk_wages_info` 上增加若干 `*_snapshot` 字段与 `eligibility_cutoff_at`；
+- 或 JSON：`config_snapshot` JSON 一列集中存储全部配置；
+- 二者可并用（关键字段单列 + 完整 JSON 便于扩展）。
+
+### 四、如何使用（生成与重算）
+- 首次生成：
+  1) 读取当前租户配置，确定 `[startDate, endDate)`；
+  2) 计算 `eligibility_cutoff_at = now - coolingHours`（或约定的边界）；
+  3) 查询 eligible 订单：`status=3 ∧ settlement_state=0 ∧ endTime ≤ eligibility_cutoff_at`；
+  4) 生成明细与汇总，写入快照与 cutoff。
+- 重算（仅未发放）两种模式：
+  1) 沿用快照（默认）：坚持用快照中的窗口与 `eligibility_cutoff_at` 重跑，不纳入新过冻结期的订单；
+  2) 应用最新配置（需显式）：用当前配置计算新 cutoff，但仅纳入“未结算 ∧ 仍处于本结算窗口”的订单；返回“前后差异”。
+
+### 五、与新结算关系（不回溯）
+- 已发放（Paid）结算单不可变更；新生成的结算总是按“当前配置”，历史不被改写。
+
+### 六、为何快照 cutoff（eligibility_cutoff_at）很关键
+- 冻结判断依赖“当前时间”，若不快照具体时间点，重算会“随时间漂移”。
+- 快照固定 cutoff → 沿用快照重算时集合稳定；只有“应用最新配置重算”时才计算新 cutoff。
+
+### 七、例子
+- 24h 改 12h：
+  - 默认（沿用快照）：不变；
+  - 用最新重算：新 cutoff 更靠近当前，可能多纳入订单；生成差异快照并审计。
+- 周结改半月结：
+  - 历史按“周结”保留；
+  - 新计划按“半月”生成；
+  - 未发放的“周结草稿”可通过“期中迁移”用新配置重算并对齐边界（校验不交叠）。
+- 优惠券承担策略变化：
+  - 历史按老策略；
+  - 新单按新策略；
+  - 旧草稿若要改，需“应用最新配置重算”，并记录差异。
+
+### 八、API 建议
+- 结算详情返回 `generatedConfig`（快照）与 `currentConfig`（现配），以及“快照 vs 现配”的差异摘要。
+- 重算接口：`POST /api/payroll/settlements/{id}/recalculate`，Body `{ applyLatest: boolean }`，返回前后金额与订单差异、使用基线（snapshot/latest）。
+- 权限：`applyLatest=true` 需更高权限或审批通过。
+
+### 九、数据表字段映射（建议）
+- `play_clerk_wages_info`：
+  - 汇总：`status, pay_amount, adjustment_amount, pay_channel, pay_time, payroll_no`；
+  - 快照：`cycle_snapshot, cooling_hours_snapshot, refund_policy_snapshot, include_types_snapshot, rounding_snapshot, min_payout_snapshot, timezone_snapshot, plan_version, eligibility_cutoff_at` 或 `config_snapshot`；
+- `play_clerk_wages_details_info`：唯一索引 `uniq_tenant_order(tenant_id, order_id)`；
+- `play_order_info`：可选 `settlement_id` 便于追溯。
+
+### 十、一句话总结
+- “快照让当时怎么算就永远怎么算；未发放可选稳定重算或按新口径重算；已发放绝不回溯。”
+
+---
+
+## 配置存放与生效（真源）
+
+### 层次结构
+- 系统默认（只读）：application.yml 作为默认值兜底，不作为运行时真源。
+- 租户当前配置（真源）：表 `play_payroll_config` 保存“计算规则”当前有效版本。
+- 自动结算计划（真源）：表 `play_payroll_plan` 保存“调度/周期/触发/自动发放”等计划项。
+- 运行时缓存（可选）：Redis key `payroll:config:{tenantId}`、`payroll:plan:{tenantId}` 缓存 JSON，更新时失效缓存。
+
+### 表：play_payroll_config（建议）
+- 主键与公共：`id, tenant_id, version, effective_at, enabled, updated_by, updated_time`
+- 计算规则：
+  - `cooling_hours` int 默认 24
+  - `include_types` varchar(64) 例：REGULAR,RANDOM,REWARD
+  - `refund_policy` varchar(32) OFFSET_NEXT|IMMEDIATE_RECOVER
+  - `rounding` varchar(16) HALF_UP|DOWN|…
+  - `min_payout` decimal(10,2)
+  - `timezone` varchar(32)
+  - `use_order_snapshot_ratio` tinyint(1) 默认 1（按订单入库比例结算）
+- 查询规则：取“当前有效一条”（`enabled=1 AND effective_at<=NOW()` 按版本/时间取最新）。
+
+### 表：play_payroll_plan（与计算规则的职责边界）
+- 计划项：`cycle (DAILY|WEEKLY|MONTHLY|CUSTOM)`, `trigger_time (HH:mm)`, `auto_pay (0/1)`, `name`, 版本/effective_at/enabled。
+- 仅用于“何时、以何周期触发结算”，不承载“计算规则”（由 config 表负责）。
+
+### 覆盖与优先级（可选扩展）
+- 表：`play_payroll_override`
+  - 字段：`id, tenant_id, scope ('GROUP'|'CLERK'), scope_id, key, value, effective_at, enabled`
+  - 合并优先级：店员 > 组 > 租户配置 > 系统默认。
+
+### 读取顺序（伪代码）
+```
+conf = getTenantConfig(tenantId)              // play_payroll_config 当前有效
+conf = applyOverrides(conf, groupId, clerkId) // 可选：覆盖层
+plan = getTenantPlan(tenantId)                // play_payroll_plan 当前有效
+```
+
+### 配置变更落地流程
+- 改“计算规则”：在 `play_payroll_config` 写新版本（设置 `effective_at`，建议未来时刻），置 `enabled=1`；失效缓存；旧版本可保留但 `enabled=0`。
+- 改“计划/调度”：在 `play_payroll_plan` 写新版本（设置 `effective_at`、`enabled=1`），定时器仅拉“当前有效计划”。
+
+### 与快照的关系
+- 生成结算单时，把“当时的配置（config + plan 的关键项）”拍成快照写入结算单，并保存 `eligibility_cutoff_at`。
+- 未发放结算单重算：
+  - 默认沿用快照；
+  - 如选择按最新配置重算，则读取 `play_payroll_config` 当前版本（与可选覆盖），计算新 cutoff 并产出差异快照。
+- 已发放结算单不受新配置影响。
+
+---
+
+## 核心结算逻辑（Service 层伪代码 + SQL）
+
+### Java 伪代码（按店员分组结算，支持并发幂等）
+
+```java
+@Service
+public class PayrollSettlementService {
+
+  @Transactional
+  public SettlementResult settle(SettlementRequest req) {
+    // 1) 读取“当前有效配置”并合并覆盖（或使用传入的快照配置用于重算）
+    PayrollConfig current = configRepo.loadEffectiveConfig(req.getTenantId());
+    PayrollConfig baseConf = req.applyLatest() ? current : req.snapshotOr(current);
+
+    // 2) 计算结算窗口与冻结边界（cutoff）
+    LocalDate start = req.getStartDate();
+    LocalDate end   = req.getEndDate();        // [start, end)
+    Instant cutoff  = req.applyLatest()
+        ? clock.now().minus(baseConf.getCoolingHours(), HOURS)
+        : req.getEligibilityCutoffAtOr(clock.now().minus(baseConf.getCoolingHours(), HOURS));
+
+    // 3) 预查询“候选订单”（不加锁）
+    List<OrderRow> candidates = orderDao.findEligible(
+        req.getTenantId(), start.atStartOfDay(), end.atStartOfDay(), cutoff, req.getScope());
+    if (candidates.isEmpty()) return SettlementResult.empty();
+
+    // 4) 生成本次结算批次ID（用于订单回读与明细追溯）
+    String batchId = Ids.uuid();
+
+    // 5) 条件更新“抢占订单”（幂等关键点）
+    int affected = orderDao.markSettled(
+        req.getTenantId(), cutoff, batchId, candidates.stream().map(OrderRow::getId).toList());
+    if (affected == 0) {
+      return SettlementResult.nothingToDo();
+    }
+
+    // 6) 回读“本次实际吃到的订单”（防并发差异）
+    List<OrderRow> consumed = orderDao.findByBatch(req.getTenantId(), batchId);
+
+    // 7) 按店员分组，分别生成结算单头与明细
+    Map<String, List<OrderRow>> byClerk = consumed.stream().collect(groupingBy(OrderRow::getClerkId));
+    List<SettlementHeader> headers = new ArrayList<>();
+    for (Map.Entry<String, List<OrderRow>> e : byClerk.entrySet()) {
+      String clerkId = e.getKey();
+      List<OrderRow> rows = e.getValue();
+
+      // 7.1 汇总（金额、订单数、续单等可扩展）
+      BigDecimal sumFinal     = rows.stream().map(OrderRow::getFinalAmount).reduce(ZERO, BigDecimal::add);
+      BigDecimal sumEstimated = rows.stream().map(OrderRow::getEstimatedRevenue).reduce(ZERO, BigDecimal::add);
+
+      // 7.2 生成结算单号与快照
+      String wagesId = Ids.uuid();
+      SettlementHeader header = SettlementHeader.builder()
+          .id(wagesId)
+          .tenantId(req.getTenantId())
+          .clerkId(clerkId)
+          .status(Ready)
+          .startCountDate(start)
+          .endCountDate(end)
+          .settlementDate(LocalDate.now())
+          .orderNumber(rows.size())
+          .finalAmount(sumFinal)
+          .estimatedRevenue(sumEstimated)
+          .cycleSnapshot(baseConf.getCycle())
+          .coolingHoursSnapshot(baseConf.getCoolingHours())
+          .refundPolicySnapshot(baseConf.getRefundPolicy())
+          .includeTypesSnapshot(baseConf.getIncludeTypes())
+          .roundingSnapshot(baseConf.getRounding())
+          .minPayoutSnapshot(baseConf.getMinPayout())
+          .timezoneSnapshot(baseConf.getTimezone())
+          .planVersion(baseConf.getPlanVersion())
+          .eligibilityCutoffAt(cutoff)
+          .payrollNo(NoGen.next("PY"))
+          .build();
+      headers.add(header);
+
+      // 7.3 插入汇总表
+      wagesInfoRepo.insert(header);
+
+      // 7.4 批量插入明细（带唯一约束 (tenant_id, order_id) 兜底）
+      List<WagesDetail> details = rows.stream().map(r -> WagesDetail.builder()
+          .id(Ids.uuid())
+          .tenantId(req.getTenantId())
+          .wagesId(wagesId)
+          .clerkId(clerkId)
+          .orderId(r.getId())
+          .orderNo(r.getOrderNo())
+          .finalAmount(r.getFinalAmount())
+          .estimatedRevenue(r.getEstimatedRevenue())
+          .revenueRatio(r.getEstimatedRevenueRatio())
+          .couponDeduction(r.getCouponDeduction())
+          .firstOrder(r.getFirstOrder())
+          .placeType(r.getPlaceType())
+          .endOrderTime(r.getOrderEndTime())
+          .build()).toList();
+      wagesDetailRepo.batchInsertIgnore(details);
+
+      // 7.5（可选）若开启自动发放：发放到余额、写流水，更新 header.status=Paid & pay_time
+      if (req.isAutoPayEnabled()) {
+        payoutService.payToBalance(header, details);
+        wagesInfoRepo.updatePaid(header.getId(), req.getDefaultPayChannel(), clock.now(), req.getPayRef());
+      }
+    }
+
+    return SettlementResult.success(headers, consumed, affected);
+  }
+}
+```
+
+### 关键 SQL（MySQL 示例）
+
+1) 预查询“候选订单”（预览用，不加锁）
+
+```sql
+SELECT id, tenant_id, accept_by AS clerk_id, order_no,
+       final_amount, estimated_revenue, estimated_revenue_ratio,
+       coupon_deduction, first_order, place_type, order_end_time
+FROM   play_order_info
+WHERE  tenant_id = :tenantId
+  AND  order_status = '3'                 -- 已完成
+  AND  order_settlement_state = '0'       -- 未结算
+  AND  purchaser_time >= :startDate
+  AND  purchaser_time <  :endDate         -- [start, end)
+  AND  order_end_time <= :eligibilityCutoffAt
+  AND  (:clerkId IS NULL OR accept_by = :clerkId)
+  AND  (:groupId IS NULL OR group_id = :groupId)
+ORDER BY order_end_time ASC
+```
+
+2) 条件更新“抢占订单”（提交用，幂等关键）
+
+```sql
+UPDATE play_order_info
+SET    order_settlement_state = '1',
+       order_settlement_time  = NOW(),
+       settlement_id          = :batchId
+WHERE  tenant_id = :tenantId
+  AND  order_status = '3'
+  AND  order_settlement_state = '0'
+  AND  order_end_time <= :eligibilityCutoffAt
+  AND  id IN (:candidateIds)
+```
+
+3) 回读本次实际吃到的订单（用于分组、插明细）
+
+```sql
+SELECT *
+FROM   play_order_info
+WHERE  tenant_id = :tenantId
+  AND  settlement_id = :batchId
+```
+
+4) 插入结算汇总（工资单头）
+
+```sql
+INSERT INTO play_clerk_wages_info (
+  id, tenant_id, clerk_id, historical_statistics, serial_number, ranking_index,
+  start_count_date, end_count_date, settlement_date,
+  order_number, final_amount, estimated_revenue,
+  status, payroll_no, pay_amount, adjustment_amount, pay_channel, pay_time, pay_reference_no,
+  cycle_snapshot, cooling_hours_snapshot, refund_policy_snapshot, include_types_snapshot,
+  rounding_snapshot, min_payout_snapshot, timezone_snapshot, plan_version, eligibility_cutoff_at,
+  created_time
+) VALUES (
+  :id, :tenantId, :clerkId, '0', 0, NULL,
+  :startDate, :endDate, CURDATE(),
+  :orderNumber, :finalAmount, :estimatedRevenue,
+  :status, :payrollNo, 0.00, 0.00, NULL, NULL, NULL,
+  :cycleSnapshot, :coolingHoursSnapshot, :refundPolicySnapshot, :includeTypesSnapshot,
+  :roundingSnapshot, :minPayoutSnapshot, :timezoneSnapshot, :planVersion, :eligibilityCutoffAt,
+  NOW()
+)
+```
+
+5) 批量插入结算明细（唯一约束兜底）
+
+```sql
+-- 方案A：INSERT IGNORE（存在唯一冲突时忽略）
+INSERT IGNORE INTO play_clerk_wages_details_info (
+  id, tenant_id, wages_id, clerk_id, order_id, order_no,
+  final_amount, estimated_revenue, revenue_ratio, coupon_deduction,
+  end_order_time, created_time
+) VALUES
+  -- 批量 values (...), (...), ...
+
+-- 方案B：ON DUPLICATE KEY UPDATE 空更新（等效忽略）
+INSERT INTO play_clerk_wages_details_info (...columns...)
+VALUES (...values...)
+ON DUPLICATE KEY UPDATE id = id;
+```
+
+6) 索引与约束（建议）
+
+```sql
+-- 明细唯一：防止一笔订单进入两张结算单
+ALTER TABLE play_clerk_wages_details_info
+  ADD UNIQUE KEY uniq_tenant_order (tenant_id, order_id);
+
+-- 汇总检索：按状态与时间快速筛选
+CREATE INDEX idx_wages_tenant_status ON play_clerk_wages_info (tenant_id, status, settlement_date);
+```
+
+7) 事务与隔离（建议）
+- 将“条件更新 + 回读 + 插明细 + 插汇总/更新状态”置于同一事务。
+- 数据库隔离级别可用 READ COMMITTED；并发去重依赖条件更新与唯一索引，不依赖悲观锁。
+
+---
+
+## 验收要求（Acceptance Criteria）
+
+角色：店员（Clerk）、租户管理员/店主（Admin）。以下场景均在租户隔离前提下验证。
+
+### 店员视图
+- 订单完成后未过冻结期：
+  - 在“即将入池”区域看到该订单，显示预计入池倒计时（基于 coolingHours）。
+  - 未计入“未结算汇总”的数量与金额。
+- 订单过冻结期且未结算：
+  - “未结算汇总”显示订单数量、finalAmount 合计与 estimatedRevenue 合计；
+  - 订单列表展示订单号、完成时间、分成比例、优惠券扣减、预计收入。
+- 生成结算单（Ready 或 Paid）后：
+  - “我的结算单”列表出现新记录，包含周期 [startDate, endDate)、应结金额（estimatedRevenue）、调整合计、实发金额、状态（Draft/Ready/Paid/Closed）与生成时间；
+  - 进入详情可见：订单明细、调整明细、配置快照（cycle/cooling/refundPolicy…）、eligibility_cutoff_at；
+  - 若为 Paid：展示发放渠道、发放时间、流水号，并且店员余额已增加（如渠道为 Balance）。
+- 退款处理：
+  - 若订单在未发放结算单内被退款并重算：该订单从该结算单移除，金额相应减少；
+  - 若订单已在 Paid 结算单内：生成负向调整，店员在下一期结算单看到负向条目（OFFSET_NEXT），或即时回收余额（IMMEDIATE_RECOVER），并收到通知。
+- 最低发放门槛：
+  - 当本期应发小于 min_payout 时，状态显示“待累计/低于门槛”，不发放；下一期累计显示应发金额已合并。
+
+### 租户管理员视图
+- 预览结算：
+  - 选择时间窗口/范围（全员/分组/单人）后，预览页返回候选订单与按店员聚合的汇总；
+  - 并发情况下提交时如有差异，返回“差异摘要”（新增/剔除订单、金额差），并仅以实际抢占成功的订单生成结算；
+  - 预览不改变数据，提交后被消费的订单 `order_settlement_state` 置为1并写 `order_settlement_time/settlement_id`。
+- 生成结算单：
+  - 系统按店员分组生成若干结算单头与明细；
+  - 结算单头包含配置快照与 eligibility_cutoff_at；
+  - 明细插入受唯一索引 `(tenant_id, order_id)` 保护；
+  - 生成完成后可在列表中按状态/日期筛选看到新结算单。
+- 发放：
+  - 对 Ready 的结算单，可选择渠道发放（Balance/Offline）；
+  - 发放成功后结算单状态变为 Paid，记录 pay_time/pay_channel/pay_reference_no；（Balance 渠道时，对应店员余额有一笔入账流水）。
+- 自动计划：
+  - 配置 cycle/trigger_time/auto_pay 后，到点生成结算单并写运行日志（成功/部分/失败、结算单数量、错误信息）；
+  - 若 auto_pay=true，则结算单直接 Paid；否则为 Ready 待人工发放。
+- 重算：
+  - 对未发放结算单（Draft/Ready）可重算：默认沿用快照；也可选择“使用最新配置重算”，系统返回前后金额与订单差异；
+  - 已发放结算单不可重算，仅能追加备注或按退款策略产生负向调整。
+- 配置变更：
+  - 修改 `play_payroll_config`（冷却期/门槛/退款策略等）后，新的结算使用新配置；历史结算不受影响；
+  - 修改 `play_payroll_plan`（周期/触发时间/自动发放）后，从下一个触发时刻起生效；
+  - 如选择“期中迁移/追溯重算”，系统提供候选清单与确认步骤。
+- 导出与审计：
+  - 可导出结算单工资条与汇总对账单；
+  - 结算单/调整/计划运行日志具备操作者、时间、备注与配置快照，满足审计追溯。
+
+### 并发与一致性（验收要点）
+- 两个并发提交同一时间窗的结算请求：仅一个请求的条件更新返回影响行数>0，另一请求返回0或减少，且不会出现同一订单进两张结算单（由唯一索引与条件更新共同保证）。
+- 重试幂等：在网络/服务异常时重试提交，不会重复消费同一订单，也不会重复插入明细。