交易

每笔交易都会为库存的每次移动、消耗、收货和调整生成不可篡改的审计记录。交易数据不可编辑或删除——更正操作将生成新的调整交易记录。

交易类型

交易流程：

收据转移消耗调整领取 ↓ ↓ ↓ ↓ ↓ 新库存 → 站点A → 站点B → 作业消耗库存手动修正任务资源拣货 (采购) (QR拣货) (报告提交) (循环盘点) (扫描任务二维码) ```

交易列表 交易页面显示所有库存移动的审计追踪记录

收货新库存抵达站点（采购、现场退回）。

字段：- toSite - 目标站点- resource - 到货商品- toVolume - 收货后新库存项目余额- uom - 计量单位

**示例：**100米电缆抵达仓库 类型："收货" 目的地：中央仓库资源：Cat6电缆库存量：600米（原为500米，现为600米）

转移库存：在不同站点间移动（仓库→工人，工人→现场站点）。

字段： - fromSite - 源位置 - toSite - 目标位置 - resource - 转移对象 - fromVolume - 转移后源方余额 - toVolume - 转移后目标方余额 - pickupCode - 扫描的JWT（若为基于二维码的转移）

scannerUserId - 扫描二维码者 - scanMethod - "self"（工人）或"staff"（仓库人员） - scanLocation - 扫描发生的GPS坐标

示例： 工人通过扫描二维码领取10米电缆 类型："转移" 起始仓库：中央仓库目标仓库：John个人库存资源：Cat6电缆起始数量：590米（仓库库存从600米减少）目标库存量：10米（约翰新增库存项）提货码："eyJhbGc..."（JWT）扫描用户ID：john_id扫描方式："自助"扫描位置：{ 纬度：40.7128, 经度：-74.0060 }

消耗现场作业消耗库存（提交报告时自动生成）。

字段：- fromSite - 消耗材料的来源（通常为工人的个人仓库）- resource - 消耗的资源类型- fromVolume - 消耗后的剩余库存- reportId - 工作报告链接（用于支付结算）

示例： 工人使用8米电缆完成任务type: "consumption"fromSite: John's Personal Inventoryresource: Cat6 CablefromVolume: 2m (从10米减少)reportId: report_abc123

库存水平的手动调整（循环盘点、损坏、损失）。

字段：- 库存项ID - 调整的库存项- 资源 - 调整对象- 起始数量 - 原始余额- 目标数量 - 新余额- 原因 - 必须填写说明（例如"实物盘点修正"、"运输损坏"）

示例： 循环盘点发现差异type: "adjustment"stockItemId: stock_xyzresource: Cat6 CablefromVolume: 2m (记录余额)toVolume: 0m (实际实物盘点量)reason: "2026-02-10 循环盘点 - 滚动尾数废弃"

领取交易记录以下信息：领取的资源、数量、来源站点、扫描人员（实际领取人），以及关联回任务和该任务中具体资源行的链接（context: { taskId, taskResourceIdx }）。领取与转移的区别在于：转移是站点间通用的库存移动；领取是带有任务上下文的转移——它将库存扣减直接与特定计划工作项挂钩。该上下文链接使您可以通过汇总领取交易来查询"已为任务X收集了多少该资源"，而无需在任务本身存储累计总量。

领取二维码为一次性使用（重复扫描将被拒绝并返回冲突错误）。代码可单独作废（通过 return 交易归还库存）或重新生成（签发新代码，原代码失效）。

交易字段

所有类型共有的字段：- type - 收据、转账、消费、调整- resource - 资源定义引用- uom - 计量单位- createdAt - 时间戳（自动生成）- createdBy - 发起用户（自动捕获）- properties - 用于自定义数据的灵活JSON字段

类型特定字段：- fromSite / toSite - 移动起点与终点- fromVolume / toVolume - 余额变动量- reportId - 工作报告链接（消耗记录）- pickupCode - 扫描的JWT（受保护转账）

scannerUserId - 扫描者身份（转账）- scanMethod - 自助扫描 vs 人工协助 - scanLocation - 扫描时GPS定位 - reason - 操作说明（调整项）

事务不可变性

不可编辑：- 交易为只写模式- 不支持更新或删除操作- 确保审计轨迹完整性

**更正操作说明：**1. 切勿尝试编辑错误交易2. 创建新的调整交易3. 附上详细说明更正原因4. 两笔交易均保留在历史记录中

示例更正流程：```第1天：收据显示100个单位已到货 → 创建交易：toVolume = 100

第2天：发现实际仅收到95件货物 → 创建调整：原数量=100，调整后数量=95 → 原因："收货数量错误 - 该批次仅含95件货物"

结果：两笔交易均在审计追踪中可见

自动交易创建

报告提交流程当工人提交包含`consumedFrom`字段的报告时：1. 系统验证每个库存项的可用量2. 原子性地为每项资源创建消耗交易3. 通过`reportId`将交易关联至报告4. 减少库存项的数量5. 若库存不足 → 拒绝报告或提示部分消耗

优势：- 库存始终准确（无需担心遗漏消耗记录）- 报表与交易同时提交（原子性）- 支付计算基于可靠数据

通过二维码取件扫描当工作人员扫描任务取件二维码时：1. 验证JWT签名及有效期2. 确认扫描者为授权接收方或具备`canFacilitatePickups`权限3. 核查源站库存可用性4. 自动创建转运交易5. 记录扫描者身份、操作方式及GPS定位

优势：- 无需人工录入交易- GPS定位验证实际到场- 审计轨迹显示转账授权人

通过扫描二维码进行手动交易录入

对于运抵现场时物品尚未贴有二维码的货物，现场工作人员可使用集成二维码扫描功能的手动交易单，通过资源二维码的实体参考手册快速完成库存接收。

创建实体资源参考书

管理员设置（仅需一次）：

导航至 管理 → 资源二维码 (/admin/resource-qr-codes)
根据需要按资源类型筛选（材料、人工、设备）3. 搜索需包含的具体资源4. 点击打印生成可打印的二维码表格5. 使用标准信纸/A4纸打印6. 覆膜后装订成参考手册7. 将手册放置于收货区或仓库工作站

**二维码格式：**每个二维码包含JSON数据：json { "type": "resource", "id": "resource_id_123", "name": "Cat6 Cable", "defaultUom": "m", "resourceType": "material"}

移动收货工作流

现场工作人员流程：

打开手动交易表单 - 导航至库存 → 交易 - 点击“添加手动交易”按钮 - 需具备 canFacilitatePickups 权限
启用批处理模式（可选但推荐） - 切换表单顶部的“批处理模式”开关 - 允许在最终提交前扫描并录入多个物品 - 当货件包含5件以上不同物品时可节省时间
扫描资源二维码 - 点击资源名称字段旁的扫描按钮（📷图标） - 移动设备相机自动开启 - 将镜头对准参考书中的二维码 - 二维码数据自动填充：资源名称、资源ID、默认计量单位
输入数量详情- 数量字段：输入收货数量（例如"50"）- 计量单位字段：从二维码预填，如有需要可调整（例如"m"代表米）- 地点：拖放目标地点或使用当前位置
添加到批次（若启用批处理模式） - 点击"添加到批次"按钮 - 该物品将显示在下方批次列表中 - 表单清空以供添加下一项 - 对货运中的每项物品重复步骤3-5
提交交易 - 单笔模式：点击“提交”（生成一笔交易） - 批量模式：点击“提交批量（N项）”（原子性生成N笔交易） - 成功通知显示接受的项目数量 - 若有项目失败，系统报告失败数量但不回滚其他交易

批次处理示例：货物抵达，包含5种不同物料：1. 扫描"Cat6网线"二维码 → 输入50米 → 加入批次2. 扫描"1英寸导管"二维码 → 输入20件 → 加入批次3. 扫描"接线盒"二维码 → 输入15件 → 加入批次4. 扫描"扎带"二维码 → 输入500件 → 加入批次5. 扫描"接地线"二维码 → 输入15件 → 加入批次 3. 扫描"接线盒"二维码 → 输入15个单位 → 加入批次4. 扫描"扎带"二维码 → 输入500个单位 → 加入批次5. 扫描"接地线"二维码 → 输入100米 → 加入批次6. 提交批次（5项）→ 即时生成5个库存项 + 5笔收货交易

未知资源的处理

若货件包含未在参考书中列出的物品：

手动输入资源名称 - 在资源名称字段中输入名称（无需扫描二维码） - 系统将按名称搜索现有资源 - 若未找到 → 自动放置于**"暂存/待处理"**资源中
暂存/预备工作流 - 交易属性包含 originalResourceName（您输入的内容） - 警告提示："资源未找到。已放入暂存/预备区" - 创建带有暂存/预备资源的库存项 - 后续：办公室人员分配至正确资源（参见下文"分配预备库存"）
自动分拣的优势 - 现场人员无需等待办公室审批 - 库存实物即时接收并追踪 - 资源分类异步完成 - 紧急发货无阻塞延迟

批处理模式功能

明细表：- 提交前显示所有已扫描项目- 显示：资源名称、数量、计量单位- 通过X按钮移除单个项目- 清晰呈现即将提交的内容

提交机制：- 原子批量处理（尽可能采用全有或全无模式）- 单项处理失败时报告异常但不阻塞其他项- 成功计数："5笔交易创建成功"- 部分失败处理："2项处理失败"

移动端优化：- 大尺寸触控友好型扫描按钮- 带手电筒开关的相机访问功能- 支持PWA缓存的离线运行- 批量自动保存至本地存储（页面刷新后仍保留）

分配分阶段库存

现场工作人员将未知资源纳入暂存/中转区后：

导航至库存项目 - 按"站点：暂存/预备"筛选（若已实施） - 查找具有isHoldingResource: true的项目
开放分配弹窗 - 在库存商品上点击"分配暂存库存"按钮 - 显示：当前数量、现场人员输入的原始名称
选择合适资源 - 选项A： 从资源表中拖拽现有资源 - 选项B： 切换"创建新资源"并输入详细信息 - 输入分配原因（例如："已确认是Cat6A线缆，而非Cat6"）
提交分配 - 原子性更新： - 库存项资源字段（持有 → 实际资源） - 创建包含分配原因的调整事务 - 在事务属性中保留 originalResourceName

优势：- 现场验收永不阻塞- 办公室分类保留审计轨迹- 过渡期间库存不会"消失"- 原始现场工作人员笔记得以保留

查看交易记录

全局事务日志：- 导航至库存 → 事务- 按类型、日期范围、站点、资源筛选- 导出用于对账或合规性核查

库存项目历史：- 导航至特定库存项目- "交易历史"显示所有影响该项目的变动- 追溯来源（物料来自何处，流向何方）

消耗报告：- 进入工作报告- "材料使用"部分关联消耗交易记录- 核对库存中实际消耗的物料

站点活动：- 访问站点- "最近交易"显示收据、转账、消费记录- 监控仓库吞吐量

常规盘点：- 每周：核对调整项（应属罕见）- 每月：对主要库存商品进行循环盘点- 每季度：执行全仓库盘点

利用GPS优化转运：- 通过scanLocation核查受保护库存- 检测异常情况（仓库100公里外扫描）- 地理围栏验证防止远程共享二维码

监控交易量：- 高调整率 = 流程问题- 低消耗配高提货量 = 囤积或盗窃- 收据/消耗不匹配 = 需求预测问题

交易权限

创建交易：- transactionsCreate - 可创建收据、调整项- 自动创建的交易（来自报告、二维码扫描）无需权限- 站点特定权限可限制在哪些站点创建收据

查看交易记录：- 所有用户均可查看自身库存项目的交易记录- 角色权限限制可隐藏特定资源/站点的交易记录- viewDeleted权限允许查看软删除的交易记录（若已实现）

无删除权限：- 任何人都无法删除交易记录- 确保审计轨迹完整性- 仅数据库管理员可删除（仅限紧急运维情况）

交易