test

Prompt

第一版目标 基础功能 能实现， 发货申请 # 订单构成 ReadOrder 在当前系统中，`Order`（订单）实体的结构高度模块化，旨在兼容**实物订单 (physical)** 和 **票券订单 (ticket)** 两种业务形态。 一个典型的订单包含以下核心元素，按逻辑功能分类如下： ### 1. 基础标识与元数据 (System Metadata) - `order_number`：系统生成的唯一订单号（如 `TK2026...`）。 - `tenant_id`：所属租户ID，用于数据隔离。 - `order_type`：核心类型定义（`physical` 或 `ticket`），决定后续逻辑走向。 - `created_by` / `user_email` / `user_name`：下单用户信息与快捷信息（用于展示）。 ### 2. 状态管理 (Lifecycle States) - **物理订单状态**：使用 `order_status`（如 `pending_purchase`、`in_warehouse` 等）。 - **票券订单状态**：使用 `ticket_status`（如 `pending_confirmation`、`in_warehouse`、`shipped` 等）。 - **支付状态**：`payment_status`（unpaid, paid 等）及相关的流水号（`alipay_trade_no` 等）。 - **存档状态**：`is_archived`，用于过滤历史订单。 ### 3. 票券/商品详情 (Business Data) - **商品核心**：`product_name`（或 `performance_name`）、`quantity`、`weight_g`（用于运费计算）。 - **票券专用 (ticket_data)**：这是票券订单的核心嵌套字段，包含： - 演出信息、演出时间、座位类型、座位数量。 - 购买渠道 (`sales_method`)、销售时间区间、配送方式。 - **存储与运输**：`arrival_photo_url`（入库图片）、`tracking_number`（物流单号）。 ### 4. 财务与费用模型 (Financials) 这是系统中最复杂的部分，涵盖了从预付到结算的逻辑： - **预付金相关**：`prepayment_amount`（预付金额）、`prepayment_currency`（币种）、`prepayment_rate_jpy_cny`（汇率）。 - **尾款结算**：`order_balance_due_jpy`（剩余未付货款）、`order_balance_surcharge_jpy`（加值费/手续费）、`order_balance_settled`（是否已结清）。 - **增值服务**：`selected_addons`（增值服务项列表）、`item_size_extra_fee`（尺寸超标附加费）、`rewarehouse_fee_jpy`（再入库费用）。 - **其他费用**：`service_fee_amount`（服务费）、`shipping_fee_amount`（运费）。 ### 5. 交互与作业控制 (Operations) - **消息流 (`messages`)**：包含系统通知、用户交流及管理员备注的数组，结构为 `{role, content, timestamp, from}`。 - **作业备注**：`user_note`（用户下单备注）、`admin_note`（内部备注）、`admin_packing_note`（仓库捆包备注）。 - **拼邮控制**：`consolidation_requested`（是否已申请拼邮）、`consolidation_pool_id`（关联的拼邮池 ID）。 - **仓储控制**：`storage_days_overdue`（超期天数）、`storage_fee_currency`（仓储费币种）。 ### 6. 其它辅助元素 - **标签系统**：`online_store_tag`（在线商店标签，用于自动分类）及对应的颜色。 - **合规/申报**：`customs_declaration`（海关申报信息，用于直邮/国际转运）。 - **拆单信息**：`split_sections`（拆单记录，用于处理一个订单拆成多个包裹的情况）。 --- **核心总结**： 订单实体是一个**设置驱动 (Settings-driven)** 的对象。它不仅记录了“买了什么”，更记录了“钱是怎么算出来的（预付/尾款/手续费）”以及“物流状态流转的关键证据（实拍图/物流单号/拼邮池关联）”。 如果你需要查看具体的某个字段定义，可以参考实体文件 `entities/Order.json`（如果在定义文件中存在）。 # 订单状态 ### 状态机流程概览 订单生命周期大致遵循以下路径： 1. **初始化/提交** (`pending_confirmation`): 用户提交订单，此时为“后付款待确认”。 2. **支付阶段** (`payment_pending` -> `awaiting_payment_confirmation` -> `paid`/`pending_purchase`): - 用户支付后进入待确认状态。 - 确认支付后，变为“已付款/待下单”。 3. **采购与仓库** (`purchased` -> `in_warehouse`): - 管理员操作后变为“已下单”。 - 仓库入库后变为“已入库”。 4. **发货前夕** (`notified_shipment` -> `shipping_fee_pending`/`ready_to_ship`): - 用户发起出货通知，变为“待出货”。 - 计算运费后，用户支付运费，变为“已付运费/待发货”。 5. **尾程物流** (`shipped` -> `delivered`): - 发货后变为“已发出”。 - 确认收货后变为“已收货”。 此外还有： - **异常/特殊状态**: `in_storage`（暂存中）、`cancelled`（已取消）。 - **中转逻辑**: `transit_shipped`（中转地发货）。 ### 关键业务逻辑 - **角色差异**: 相同状态在管理员和用户侧显示不同的标签和颜色（例如 `paid` 状态，管理员看到的是“待下单”，用户看到的是“已付款”）。 - **批量操作**: 控制器中的 `getBulkActions` 定义了管理员如何通过状态触发一键变更（如：从“待下单”直接标记为“已下单”；从“已入库”变为“待发货”等）。 - **权限与活跃度**: `ACTIVE_STATUSES` 定义了哪些状态属于“非终结”状态（正在进行中），用于控制列表筛选和全局看板的数据逻辑。 # 拼邮申请运费计算 用户拼邮的付款额计算逻辑由 `lib/shippingFeeCalc.js` 中的 `calcFeeBreakdownPerUser` 函数核心驱动。计算过程会将费用分为**个人承担部分**和**平摊部分**： ### 1. 个人承担费用 (Personal Fees) 这些费用直接计入特定用户的总额： - **货款尾款**：未付货款差额（货款总额 - 已预付）及相关的尾款加值（如果有加值比例）。 - **特殊处理费**：物品尺寸追加费、再入库处理费。 - **个人捆包费**：管理员手动设定的个人追加作业费（支持补正，可为负数）。 - **增值服务费**：该用户在所有订单中选择的增值服务费用（去重计算）。 - **特定场景费**：如果是拼邮且未选择“平摊手续费”，则中转地手续费按用户单独计算。 - **中转运输费**：具体的中转运输方式费用。 ### 2. 平摊费用 (Shared Fees) 如果是拼邮模式，以下费用会根据**用户订单重量占比**平摊： - **国际运费**：管理员填写的实际运费总额。 - **外箱费用**：外箱单价总计。 - **捆包作业服务费**：管理员填写的捆包作业全局总额。 - **中转手续费**：如果选择了平摊模式 (`transitHandlingFeeSplit=true`)，则中转地手续费也会加入此池。 **平摊计算公式**： `该用户承担金额 = (用户个人订单总重量 / 拼邮总重量) * 共享费用基数` ### 3. 总额结算 `总金额 (JPY) = 个人承担部分总和 + (如果是拼邮 ? 平摊部分 : 直接费用)` **关键点**： - **基础单位**：所有计算最终均换算为 **JPY**。 - **数据隔离**：函数接收 `pool` 对象和 `orders` 数组，通过 `user_email` 对订单进行分组计算，确保费用按用户独立拆分。 - **灵活性**：通过 `packingFeesPerUser` 预留了管理员对特定用户进行费用修正（增加或减免）的口子。 这种机制保证了拼邮费用的颗粒度精确到每个用户，同时兼顾了物流运营中的固定费用摊销。如果您需要查看具体的运费拆分报表，可以查看 ShippingPool 详情中的费用明细部分。 # 订单流程 订单从“下单”到“发货申请”之间的流程，本质上是一个**从商品采购、仓储入库到用户主动触发物流需求**的准备过程。 以下是这一阶段的业务流程概览： ### 1. 采购与入库阶段 (Procurement & In-Warehouse) - **下单确认**：用户完成支付后，订单进入 `paid` 或 `pending_purchase` 状态。 - **平台代购**：管理员在后台通过 `purchased` 状态标记商品已完成外部平台（如日本电商）的购买。 - **物流接收**：商品到达平台指定的日本仓库。 - **入库上架**： - 仓库人员执行入库操作，上传“入库实拍图”（`arrival_photo_url`）。 - 状态变更为 `in_warehouse`。 - **关键点**：此时订单具备了“可发货”的前置条件（即：商品已在库，且有实重信息）。 ### 2. 暂存或待发货阶段 (Storage or Ready-to-Ship) 在商品入库后，用户进入了“发货准备期”： - **暂存 (Storage Mode)**：如果用户希望凑单，订单会停留在 `in_warehouse` 状态或进入 `in_storage` 状态（由仓储策略决定）。 - **增值服务决策**：用户可以在这一阶段查看订单明细，选择是否添加增值服务（如：加固包装、移除外箱、商品清点等）。 ### 3. 发货申请触发 (Requesting Shipment) 这是从订单到发货申请的“临界点”： - **用户动作**：用户在“我的订单”界面选中已入库的订单，点击“申请发货”。 - **物流方案选择**： - **选择发货方式**：用户选择心仪的国际物流渠道（如 EMS、海运等）。 - **拼邮池匹配**：系统检查该用户是否有现存的拼邮池，或根据租户设置自动创建一个新的拼邮池 (`ShippingPool`)。 - **地址锁定**：用户确认最终收货地址。系统会将该地址写入 `ShippingPool`，作为后续面单打印和运费计算的基准。 ### 4. 申请状态流转 (State Transition) - **数据归集**：一旦申请提交，订单从 `in_warehouse` 状态流转为 `notified_shipment`（待出货/已通知出货）。 - **锁定操作**：订单被“锁定”到对应的 `ShippingPool` 中，不再允许随意拆单或修改关键属性（如商品信息），进入后台管理员的处理队列。 --- ### 该阶段的系统控制点： - **费用预估**：在用户提交发货申请时，系统根据当前订单的入库重量（`weight_g`）提供运费预估，但最终金额需等待管理员完成捆包后确认。 - **数据同步**：此时 `PhysicalOrderController` 的数据逻辑会自动将该订单从“入库订单列表”转移到“待发货/拼邮订单看板”，确保管理效率。 - **合规性检查**：系统会在用户申请发货前，自动检查是否有未结算的货款尾款，确保“钱货匹配”。 简而言之，这个阶段完成的任务是：**完成从“零散的海外采购”到“归集整合的物流货包”的形态转变**，为后续的拼邮平摊计算和国际物流调度打下基础。 # 发货申请流程 从“用户提交发货申请”到“最终发货”的业务全流程，主要由**发货申请发起、拼邮池管理、仓储处理、运费结算、以及最终物流发货**五个核心环节组成。 以下是该业务逻辑的整体概括： ### 1. 发货申请发起 (Consolidation Request) - **触发点**：用户在“我的订单”中，针对已入库（`in_warehouse`）的实物订单发起发货申请。 - **拼邮逻辑选择**： - **直发模式**：订单单独发货，直接进入“待发货”状态。 - **拼邮模式**：将订单加入一个 `ShippingPool`（拼邮池）。系统会根据 `consolidation_type`（直发/中转）以及用户指定的拼邮池规则进行匹配。 - **地址确认**：用户选择或填写最终配送地址，系统锁定该地址用于后续运费计算。 ### 2. 拼邮池管理 (Shipping Pool Orchestration) - **状态锁定**：订单加入拼邮池后，状态变为 `notified_shipment`（待出货）。 - **归集与审核**：管理员在后台的“发货池管理”界面查看当前拼邮池状态，监控重量、合并订单内容、审核地址合规性。 - **中转处理**：如果是中转拼邮，订单会被归集到指定的中转中心，并记录中转地的接收确认信息。 ### 3. 仓储处理与捆包 (Packing & Warehousing) - **捆包作业**：仓库人员根据发货池进行物理装箱（`box_template`），此过程产生“捆包作业费”。 - **数据更新**：管理员更新 `final_weight_g`（最终重量，包含外箱）和 `packing_image_urls`（捆包实拍图），这些数据直接影响最终运费计算。 - **外箱费用**：根据选择的外箱规格，系统自动累计对应的外箱费用。 ### 4. 运费结算 (Fee Settlement) - **费用自动核算**：管理员在后台更新实际的“国际运费”总额后，系统调用 `shippingFeeCalc.js` 的计算引擎： - **平摊部分**：运费、外箱费、捆包服务费按**用户订单重量占比**进行平摊。 - **个人部分**：单独累加货款尾款、物品尺寸追加费、增值服务费等。 - **通知用户**：状态流转至 `shipping_fee_pending`（待付运费），通知用户查看并支付最终运费。 - **付款核销**：用户支付后，管理员确认收款，订单进入“待发货”状态。 ### 5. 最终物流发货 (Shipping & Delivery) - **面单录入**：管理员录入 `tracking_number`（物流单号），并上传 `label_image_urls`（面单图片）。 - **出库流转**：状态从 `ready_to_ship` 变更为 `shipped`（已发出）。 - **终端签收**：物流到达后，状态变更为 `delivered`（已收货），订单完成整个闭环。 --- ### 该流程的关键技术支撑点： - **数据隔离**：所有发货池和订单数据均受 `tenant_id` 租户隔离控制。 - **货币一致性**：全程以 **JPY** 为内部结算货币，只有支付环节才涉及汇率折算。 - **设置驱动**：捆包费率、运费计算规则（tiered/simple）、增值服务费率均通过 `ServiceFeeRule` 等设置模块配置，而非写死在代码中。 这个流程确保了拼邮业务在处理多用户、多订单合并发货时，既能保证财务上的精准平摊，又能通过自动化的状态流转实现高效的仓储与物流闭环。 # 中转地系统 订单从“下单”到“发货申请”之间的流程，本质上是一个**从商品采购、仓储入库到用户主动触发物流需求**的准备过程。 以下是这一阶段的业务流程概览： ### 1. 采购与入库阶段 (Procurement & In-Warehouse) - **下单确认**：用户完成支付后，订单进入 `paid` 或 `pending_purchase` 状态。 - **平台代购**：管理员在后台通过 `purchased` 状态标记商品已完成外部平台（如日本电商）的购买。 - **物流接收**：商品到达平台指定的日本仓库。 - **入库上架**： - 仓库人员执行入库操作，上传“入库实拍图”（`arrival_photo_url`）。 - 状态变更为 `in_warehouse`。 - **关键点**：此时订单具备了“可发货”的前置条件（即：商品已在库，且有实重信息）。 ### 2. 暂存或待发货阶段 (Storage or Ready-to-Ship) 在商品入库后，用户进入了“发货准备期”： - **暂存 (Storage Mode)**：如果用户希望凑单，订单会停留在 `in_warehouse` 状态或进入 `in_storage` 状态（由仓储策略决定）。 - **增值服务决策**：用户可以在这一阶段查看订单明细，选择是否添加增值服务（如：加固包装、移除外箱、商品清点等）。 ### 3. 发货申请触发 (Requesting Shipment) 这是从订单到发货申请的“临界点”： - **用户动作**：用户在“我的订单”界面选中已入库的订单，点击“申请发货”。 - **物流方案选择**： - **选择发货方式**：用户选择心仪的国际物流渠道（如 EMS、海运等）。 - **拼邮池匹配**：系统检查该用户是否有现存的拼邮池，或根据租户设置自动创建一个新的拼邮池 (`ShippingPool`)。 - **地址锁定**：用户确认最终收货地址。系统会将该地址写入 `ShippingPool`，作为后续面单打印和运费计算的基准。 ### 4. 申请状态流转 (State Transition) - **数据归集**：一旦申请提交，订单从 `in_warehouse` 状态流转为 `notified_shipment`（待出货/已通知出货）。 - **锁定操作**：订单被“锁定”到对应的 `ShippingPool` 中，不再允许随意拆单或修改关键属性（如商品信息），进入后台管理员的处理队列。 --- ### 该阶段的系统控制点： - **费用预估**：在用户提交发货申请时，系统根据当前订单的入库重量（`weight_g`）提供运费预估，但最终金额需等待管理员完成捆包后确认。 - **数据同步**：此时 `PhysicalOrderController` 的数据逻辑会自动将该订单从“入库订单列表”转移到“待发货/拼邮订单看板”，确保管理效率。 - **合规性检查**：系统会在用户申请发货前，自动检查是否有未结算的货款尾款，确保“钱货匹配”。 简而言之，这个阶段完成的任务是：**完成从“零散的海外采购”到“归集整合的物流货包”的形态转变**，为后续的拼邮平摊计算和国际物流调度打下基础。