# 报工跨日期工时归属拆分设计 ## 背景 现有报工记录使用 `report_date` 作为单一报工日期。这个字段被报工记录、管理员审核、经理看板、导出、对账小账本、设备/模具使用统计等模块复用。 当员工夜里或凌晨跨日期工作时，单一 `report_date` 无法准确表达工时归属。例如： - `00:10` 上班，`11:00` 下班 - `00:10-06:00` 是前一天夜班尾段 - `06:00-08:00` 是作息空白区间，但按新规则应算加班 - `08:00-11:00` 是当天白班 如果整条报工强行归前一天或当天，都会造成一部分工时、数量、工资统计不合理。 ## 目标 实现一条原始报工记录可以按工时归属拆分到多个日期。 核心原则： - 原始报工记录仍然只保留一条，不拆成多条审核记录。 - 管理员审核、作废、更改、水印、员工记录仍围绕原始报工记录。 - 经理看板、导出、对账小账本、设备/模具统计、概览等统计类模块按拆分后的归属明细汇总。 - 跨日期时，成品数量、不良数量、报废数量、换料次数、参考工资等涉及统计的字段按有效工时比例拆分。 - 作息空白区间统一算加班，但不直接改变原始 `report_date`。 ## 非目标 - 不把一条原始报工拆成多条 `ProductionReport`。 - 不开放管理员手工编辑 `report_date`。 - 不批量回改历史记录的原始 `report_date`。 - 不改变员工扫码上班、换模具、下班提交的主流程。 ## 术语 - 原始报工：员工提交或系统自动提交后形成的一条 `ProductionReport`。 - 工序明细：一条报工下的产品工序明细。 - 归属明细：按日期和班种拆出来的统计明细。 - 有效工时：扣除符合规则的吃饭时间后，用于统计、工资和数量分摊的工时。 - 空白区间：不属于白班、夜班、原加班区间的作息时间，例如默认 `06:00-08:00`、`17:20-18:00`。 ## 推荐方案 采用“一条原始报工 + 多条归属明细”的方案。 ### 原始记录 `ProductionReport` 继续保存员工真实提交的完整记录： - 考勤点 - 员工 - 上班时间 - 下班时间 - 报工明细 - 审核状态 - 作废状态 - 更改状态 - 原始 `report_date` 原始 `report_date` 仍用于报工记录卡片的基础展示，但统计类模块不再只依赖它。 ### 归属明细 新增一张后端表，例如 `production_report_allocations`。 建议字段： - `id` - `report_id` - `report_item_id` - `attendance_point_name` - `employee_phone` - `allocation_date` - `day_minutes` - `overtime_minutes` - `night_minutes` - `effective_minutes` - `good_qty` - `defect_qty` - `scrap_qty` - `changeover_count` - `reference_wage` - `created_at` - `updated_at` 如果后续设备/模具统计需要直接按设备或模具拆分，可以再补： - `device_no` - `mold_name` - `product_name` - `process_name` - `stamping_method` 第一版建议保留到 `report_item_id` 级别，设备/模具统计可以根据现有工序明细和设备段关联计算，避免一次性改表过重。 ## 拆分规则 ### 班种区间 按报工所属考勤点的作息配置计算： - 白班：`day_start` 到 `day_end` - 原加班：`overtime_start` 到 `overtime_end` - 夜班：`night_start` 到 `night_end` - 午饭、晚饭：继续使用当前吃饭扣除规则 夜班跨天时，例如 `20:00-06:00`，按当前系统已有跨天区间逻辑处理。 ### 空白区间 一天中不属于白班、原加班、夜班的时间，统一计入加班。 默认作息下： - `06:00-08:00` 算加班 - `17:20-18:00` 算加班 空白区间只影响工时分布，不单独改变原始 `report_date`。 ### 日期归属 归属明细按时间片所在的自然日期和夜班归属拆分。 默认作息 `20:00-06:00` 下： - `20:00-24:00` 夜班归属当天 - `00:00-06:00` 夜班归属前一天 - `06:00` 之后的空白加班、白班、加班归属当天 例子：`2026-07-25 00:10` 到 `2026-07-25 11:00` - `2026-07-24`：夜班 `350` 分钟 - `2026-07-25`：加班 `120` 分钟，白班 `180` 分钟 ### 数量和金额分摊 每个工序明细先计算总有效分钟，再按日期归属比例拆分。 公式： ```text 归属比例 = 某归属日有效分钟 / 当前工序明细总有效分钟 归属数量 = 原始数量 * 归属比例 归属工资 = 原始参考工资 * 归属比例 ``` 适用字段： - 成品数量 - 不良数量 - 报废数量 - 换料次数 - 参考工资 ### 小数处理 后端内部保留两位小数。 导出和页面展示可以使用两位小数，避免比例拆分后出现不合理的整数强行取整。 如果未来现场要求成品必须整数，可以另开一个“整数分摊余数归属规则”，本次不引入。 ## 数据流 ### 员工提交报工 1. 员工扫码、填写报工并提交。 2. 后端创建一条 `ProductionReport` 和对应 `ProductionReportItem`。 3. 后端计算原始记录指标。 4. 后端生成或刷新归属明细。 5. 返回原始报工卡片。 ### 系统自动提交 1. 自动提交服务创建原始报工。 2. 原始结束时间为系统自动提交时间。 3. 后端计算原始记录指标。 4. 后端生成或刷新归属明细。 ### 管理员审核或更改 管理员调整以下内容时，需要重算归属明细： - 上班时间 - 下班时间 - 换模具时间 - 产品工序 - 设备 - 成品数量 - 不良数量 - 报废数量 - 换料次数 - 工序单价 - 作废/撤销作废 保存流程： 1. 校验管理员权限和编辑窗口。 2. 保存原始记录修改。 3. 重算原始记录指标。 4. 删除旧归属明细。 5. 生成新归属明细。 6. 设置更改水印。 作废记录不参与统计。作废时可以保留归属明细，但统计查询必须过滤；也可以删除归属明细。第一版建议保留并在统计查询中过滤，方便撤销作废后立即恢复统计。 ## 模块影响 ### 员工报工记录 仍显示一条原始记录。 可在明细里补充展示工时归属，例如： ```text 工时归属：2026-07-24 夜班 5小时50分；2026-07-25 加班 2小时、白班 3小时 ``` 第一版只在管理员和经理侧展示归属摘要，员工侧报工记录保留现状。 ### 管理员审核页 仍按原始记录审核。 管理员改时间或数量后，页面返回重算后的原始指标和归属摘要。 审核页可以展示归属摘要，帮助管理员知道这条记录会被拆到哪些日期。 ### 经理报工看板 看板按归属明细汇总，不再只按 `ProductionReport.report_date` 汇总。 筛选日期查的是 `allocation_date`。 同人、同考勤点、同项目、同产品、同工序、同冲压方式的聚合，应基于归属明细汇总。 ### 经理看板导出 第一张明细 sheet 按归属明细导出。 建议保留两个日期字段： - 原始报工日期 - 统计归属日期 这样经理既能追溯原始记录，也能看到工资和工时实际归属。 参考工资、工序单价、工种、备注等现有导出字段继续保留。 工资汇总 sheet 按归属明细汇总。 ### 对账小账本 已报工成品数量使用归属明细统计。 最后一道工序判断仍按产品清单数字工序大小确定。 月份归属改为 `allocation_date` 所在月份。 ### 设备/模具使用统计 默认统计审核通过且未作废记录。 时间筛选按归属明细日期。 普通设备/模具： - 时长按归属明细有效分钟汇总 - 报工次数按原始报工 ID 去重 建议第一版： - 时长按归属明细汇总 - 报工次数按原始报工 ID 去重 清洗设备： - 清洗数量按归属明细数量汇总 - 报工次数按原始报工 ID 去重 ### 概览 涉及今日、历史待审核、已通过等指标时： - 审核状态类数量仍按原始报工记录。 - 工时、数量、工资类指标按归属明细。 ## 错误处理 - 如果归属明细生成失败，原始报工保存应回滚，避免原始记录和统计数据不一致。 - 如果旧数据没有归属明细，统计查询应提供兼容兜底：用原始记录实时计算或用迁移脚本补齐。 - 如果有效分钟为 `0`，数量和工资不做比例拆分，统一归到原始 `report_date`，同时记录日志，避免除零。 - 如果作息配置缺失，使用当前默认作息。 ## 历史数据处理 历史原始 `report_date` 不批量回改。 但为了让统计类模块切换到新口径，建议提供一次性迁移脚本： 1. 扫描审核通过且未作废的历史报工。 2. 根据记录当时的上下班时间、工序明细、考勤点作息生成归属明细。 3. 不修改原始 `report_date`。 4. 迁移后输出处理数量、跳过数量、异常记录 ID。 如果担心历史作息被后续修改导致还原不准，第一版接受使用当前考勤点作息生成历史归属明细。后续如要严格追溯，需要在报工时快照作息配置。 ## 测试用例 核心用例： - `2026-07-25 00:10` 到 `2026-07-25 11:00` - `2026-07-24` 夜班 `350` 分钟 - `2026-07-25` 加班 `120` 分钟，白班 `180` 分钟 - `2026-07-25 05:59` 到 `2026-07-25 11:00` - `2026-07-24` 夜班 `1` 分钟 - `2026-07-25` 加班 `120` 分钟，白班 `180` 分钟 - `2026-07-24 20:00` 到 `2026-07-25 06:30` - `2026-07-24` 夜班 `600` 分钟 - `2026-07-25` 加班 `30` 分钟 - `2026-07-25 06:00` 到 `2026-07-25 08:00` - `2026-07-25` 加班 `120` 分钟 - `2026-07-25 17:20` 到 `2026-07-25 18:00` - `2026-07-25` 加班 `40` 分钟 - 覆盖吃饭扣除和 5 分钟缓冲规则。 - 覆盖管理员修改上下班时间后归属明细重算。 - 覆盖管理员修改换模具时间后归属明细重算。 - 覆盖作废记录从统计中排除。 - 覆盖撤销作废后统计恢复。 ## 实施顺序建议 1. 后端新增归属计算服务和单元测试。 2. 新增归属明细表和迁移脚本。 3. 报工提交、自动提交、管理员审核保存后写入归属明细。 4. 经理看板和导出切换到归属明细。 5. 对账小账本、设备/模具统计、概览按风险顺序切换。 6. 前端增加归属摘要展示。 7. 跑迁移脚本补齐历史归属明细。 ## 已固定技术口径 当前方案已按以下业务口径固定： - 涉及拆分的字段都按工时比例拆。 - 空白作息区间算加班。 - 空白作息区间不影响原始 `report_date`。 - 原始报工记录不拆。 - 报工次数统计按原始报工 ID 去重，不因一条报工拆到多个日期而重复计数。