报告

报告是现场工作人员记录已完成工作的凭证。工作人员完成安装、维修或检查后，提交报告，记录工作内容、所用材料、施工地点及照片或备注。提交报告会自动生成库存消耗交易并纳入付款计算——无需额外填写纸质文件。

报告结构

报告页面展示现场执行记录，包含消耗情况和状态

核心字段：

• 名称 — 报告标题或摘要
• 描述 — 详细备注、观察结果及遇到的问题
• 提交人 — 提交报告的用户
• 报告日期 — 工作执行时间
• 工单 — 可选的父级工单关联
• 几何对象 — 工作执行位置（点、线或多边形）

工作记录：

• 已完成工作 — 已消耗资源及已完成任务的列表
• 消耗来源 — 哪些库存项已耗尽（触发交易）

媒体：

• 照片 — 施工前后的对比图像及遇到的问题
• 附件 — 文件、图表、认证文件

已完成工作结构

"已完成工作"列表中的每条记录对应一种类型的工作：

示例： 工作人员报告安装了 45 米 Cat6 电缆、8 个接线盒以及 3.5 小时电工工时，全部关联至同一任务。

临时报告（无正式任务）

每条已完成工作记录中的任务字段为可选项——支持计划外工作：

使用场景：

• 紧急维修（设备故障、事故处理）
• 客户服务呼叫（非计划现场访问）
• 其他工作中发现的维护需求
• 探索性工作（勘察、评估）

示例：

报告："紧急光纤维修 - 风暴损坏"
已完成工作：[
  { resource: "Fiber Cable", volume: 20, uom: "meters" }
  // 无关联任务 - 这是计划外的紧急工作
]
消耗来源：[
  { stockItemId: truck_fiber_id, resource: "Fiber Cable", volume: 20, uom: "meters" }
]

即使没有正式的任务分配，系统仍会创建消耗交易、追踪材料成本并计算付款。

消耗来源（自动交易）

"消耗来源"列表在报告提交时触发自动库存扣减：

工作流程：

1. 工作人员提交含消耗来源条目的报告
2. 系统验证每个库存项的可用量
3. 自动创建消耗交易
4. 交易与本报告关联
5. 库存项余量减少
6. 若库存不足 → 拒绝报告，或提示工作人员进行部分消耗

示例：

消耗来源：[
  { stockItemId: johns_truck_cable, resource: "Cat6 Cable", volume: 45, uom: "meters" },
  { stockItemId: johns_truck_boxes, resource: "Junction Boxes", volume: 8, uom: "units" }
]

结果：
  - 创建了 2 笔消耗交易
  - 约翰的卡车库存减少 45 米电缆和 8 个接线盒
  - 交易与本报告关联
  - 付款计算拥有可靠的消耗数据

优势：

• 库存始终准确（未记录消耗量不得提交工单）
• 交易审计追踪自动生成
• 防止"虚耗"（提交报告时库存未变动）
• 按实际用料付款

报告验证

报告提交时，系统进行以下验证：

库存可用性：

• 检查每条消耗来源条目
• 若某库存项余量不足 → 可选方案：
  1. 拒绝整个报告（显示错误信息）
  2. 提示部分消耗（减少报告数量）
  3. 允许负余额（带警告提示——需后续调整交易）

工作量与消耗量匹配：

• 若消耗来源与已完成工作量不符则发出警告
• 示例：报告完成 50 米电缆施工，实际仅消耗 30 米
• 不阻止提交（工作人员可能使用了个人材料）
• 标记为需验证审核

几何验证：

• 点必须具有有效坐标
• 线必须至少包含 2 个点
• 多边形必须闭合（起始点 = 终点）
• 作业位置必须在任务几何范围的合理距离内（可配置）

创建报告

所需权限： reportsCreate 管理员权限（或自助报告权限）

工作流程：

1. 导航至【履约】→【报告】
2. 点击"添加报告"
3. 填写基本信息（名称、描述、日期）
4. 关联工单（可选——用于进度跟踪）
5. 添加已完成工作条目：
   • 选择资源
   • 输入完成量
   • 关联任务（可选）
6. 添加消耗来源条目：
   • 选择库存项（通常为工作人员的个人站点）
   • 选择资源
   • 输入消耗量
7. 设置几何对象（工作执行位置）
8. 上传照片/附件
9. 提交 → 交易自动生成

从工单快速创建报告： 在工单详情视图中打开预填表单：

• 工单、分配对象、可用任务自动填充
• 基于资源目标提供建议消耗量
• 工作人员调整实际值后提交

移动端创建报告： 简化的移动界面：

• 相机集成，用于拍摄照片
• GPS 自动捕获地理位置
• 语音转文字，用于描述输入
• 最小化必填字段

报告对进度的贡献

报告会更新任务和工单的进度：

任务进度：

• 汇总该任务所有报告的已完成工作量
• 除以任务资源需求量
• 每项资源上限为 100%

工单进度：

• 汇总本工单所有报告的已完成工作量
• 除以工单资源目标值
• 每项资源上限为 100%
• 计算所有目标的平均值

超额交付： 工作人员可报告超出分配量的工作：

• 有助于推进任务进度（加速任务完成）
• 工单进度上限为 100%（工作人员超额完成目标）
• 验证环节审核超额交付内容（核查准确性）

报告详情视图

显示信息：

• 基本信息（名称、描述、日期、上报人）
• 工单关联（如适用）
• 已完成工作列表及任务引用
• 消耗来源列表及库存项链接
• 消耗交易记录（自动生成）
• 照片及附件
• 地图上的几何对象
• 验证结果（如已执行质量控制）

可用操作：

• 编辑报告（验证前）
• 上传额外照片
• 添加评论/备注
• 请求验证
• 查看消耗交易记录
• 打印报告（PDF 导出）

付款计算

报告驱动付款工作流：

劳务付款：

已完成工作：
  - 电工：3.5 小时
  
付款金额 = 3.5 小时 × 小时费率

材料成本：

消耗来源：
  - Cat6 电缆：45 米 × $2/米 = $90
  - 接线盒：8 个 × $15/个 = $120
  
总材料成本 = $210

总工作成本：

人工 + 材料 = 支付给工人的报酬 + 材料成本 = 总成本

交易审计追踪提供可靠的材料成本（无法虚报消耗量——与实际库存消耗挂钩）。

报告列表中的验证徽章

验证现已直接在报告页面以交通灯徽章的形式呈现——您无需再导航至独立的 /fulfillment/validations 页面来查看或创建验证。每条报告行包含：

• 独立列中的聚合验证徽章，显示最严重的状态及数量（例如 FAILED · 3）。悬停可查看各状态明细。
• 展开报告后显示的按状态分组徽章行，每条验证对应一个徽章。

点击任意徽章可打开 ValidationEditModal —— 一个全屏覆盖层，无需离开报告即可查看、编辑或创建验证。模态框中的提交按钮会将报告和验证的编辑原子性地一同提交。

详见验证完整说明。

筛选报告

预置筛选器：

• 由我提交 — 您提交的报告
• 待验证 — 没有任何验证的报告（灰色徽章）
• 近期 — 过去 7 天内的报告

验证状态筛选： 报告列表支持验证状态筛选，选项如下：

• all — 所有报告（默认）
• none — 没有任何验证的报告
• any — 至少有一条验证的报告
• failed — 至少有一条失败验证的报告
• revision — 至少有一条 needs-revision 验证的报告
• passed — 所有验证均通过的报告

自定义筛选：

• 日期范围
• 由特定用户提交
• 工单
• 任务引用

最佳实践

准确的消耗报告：

• 报告实际使用的材料（非估算值）
• 使用个人站点中的库存项（证明材料来源）
• 记录超额消耗（说明为何需要更多材料）

及时提交：

• 当日完成工作，当日提交报告
• GPS 定位与时间戳确保责任可追溯
• 记忆新鲜 = 细节更准确

照片记录：

• 施工前照片（现场状况）
• 施工中照片（工程进行中）
• 施工后照片（安装完成）
• 问题照片（损坏、障碍物、非标准状况）

详细说明：

• 记录任何偏离任务要求的情况
• 记录超额/不足消耗的原因
• 记录问题以备将来参考（如门锁关闭、许可证缺失、天气状况）

尽可能关联任务：

• 便于追踪任务进度
• 支持空间分析（工作集中区域）
• 优化未来任务估算

响应验证结果：

• 及时审查验证结果
• 如有疑问，提供说明
• 在后续报告中修正错误
• 从质量反馈中汲取经验

报告不可变性

软删除： 报告可标记为已删除但保留在数据库中：

• 保留交易记录（消耗交易仍存在）
• 维持付款审计追踪
• 可配置保留期限（应用设置）
• 需 viewDeleted 管理员权限查看已删除报告

编辑限制： 验证完成后：

• 报告转为只读状态
• 修改需创建新报告并附备注
• 保持质量控制完整性
• 版本历史记录追踪所有验证前的变更

审计追踪：

• 每份报告的编辑均有日志（编辑者、时间、修改内容）
• 消耗交易不可编辑（不可篡改）
• 付款计算可追溯至原始报告数据