diff --git a/业务快速索引.md b/业务快速索引.md index 062c94a..a473cf2 100644 --- a/业务快速索引.md +++ b/业务快速索引.md @@ -22,7 +22,8 @@ | 库位、托盘、占位、释放 | 国内称重整票块归 Warehouse；海外实物托盘资源归 Warehouse Overseas；业务任务归 Lastleg | 业务路由查“称重确认”或“海外仓库与通用资料”；用国内/海外和业务阶段继续限定 | | 拖车、派车、提柜、还柜 | 国内订舱拖车与目的港码头车队是不同业务；海外配送排车另属 Lastleg | 国内 `apps/admin-web/src/modules/trucking/`；目的港 `apps/admin-web/src/modules/container-loading/api/terminalDrayages.ts`；配送查“海外出库、排车” | | 报关资料、退税资料、完成文件 | 平台整柜操作与客户订单上传先按终端区分 | Admin `apps/admin-web/src/modules/container-loading/components/ContainerCustomsPanel.vue`；Client `apps/client-web/src/modules/first-leg/components/CustomsDocumentsDialog.vue` | -| 异常、退回、退仓、回访 | 派送异常退回与库存退货业务不可混用 | 派送查 `apps/admin-web/src/modules/overseas-warehouse/pages/ExceptionOrdersView.vue`；库存业务先查 Lastleg 最近指引 | +| 退货、退货预报、退货换标、退货签收、退货合箱 | 客户退货预报及签收库存，区别于派送异常退回 | Client `apps/client-web/src/modules/overseas-warehouse/views/ReturnOrdersView.vue`；Admin `apps/admin-web/src/modules/overseas-warehouse/pages/ReturnInventoryManagementView.vue`；Lastleg `returnreceipt/`，见下表“退货预报、签收、库存与合箱” | +| 异常、退回、退仓、回访 | 派送异常退回与库存退货业务不可混用 | 派送查 `apps/admin-web/src/modules/overseas-warehouse/pages/ExceptionOrdersView.vue`；退货预报/库存查 Lastleg `returnreceipt/` | ## 定位步骤与反馈 @@ -35,6 +36,8 @@ ## 业务快速路由表 +退货预报、签收、库存与合箱：Client `modules/overseas-warehouse/views/ReturnOrdersView.vue`、`ReturnInventoryView.vue`；Admin `modules/overseas-warehouse/pages/ReturnInventoryManagementView.vue`；Backend `lastleg-service/returnreceipt/`，详细接口与状态见 `baiyue-firstleg/lastleg-service/AGENTS.md` 的退货入口，OpenAPI 为 `overseas-business-v1.yaml`。客户预报 → PDA 后端签收 → 退货箱/SKU 库存 → 同客户合箱 → `delivery/` 退货出库；设备端是否承载签收/合箱须查实际注册，不按后台接口推断。派送异常退回仍归 `exceptionorder/`。 + 本表只路由到范围依据和首个代码入口；Admin/Client 路径从对应应用的 `src/` 起算，国内 PDA 路径从 `apps/pda-uniapp/` 起算，海外 PDA 路径从 `apps/pda-overseas-uniapp/src/` 起算，Backend 路径从 `baiyue-firstleg/` 起算。进入目标后继续读最近的 `AGENTS.md`，不要把根表当作模块细节清单。 | 业务 | 范围依据 | 首个代码入口 | diff --git a/海外仓业务/README.md b/海外仓业务/README.md index f8a3a77..13b7ca7 100644 --- a/海外仓业务/README.md +++ b/海外仓业务/README.md @@ -18,7 +18,7 @@ | 海外仓 | 尾程订单、入库单、换标单、托盘管理、库存管理；箱号管理与产品库当前暂不进入海外仓业务正式入口；Admin 入口 `../../apps/admin-web/src/modules/overseas-warehouse/` | 原型 `../悦/货代SAAS平台后台/prototype-src/modules/03-overseas-warehouse.html`；Backend `../../baiyue-firstleg/lastleg-service/`、`../../baiyue-firstleg/warehouse-overseas-service/`，经 `gateway-overseas/` | | 海外仓排车与智能预排 | 平台查看排车列表/详情，按入仓计划或已收托盘创建预排，并完成编辑、取消、拣货、出库、发车和转派送 | Admin `../../apps/admin-web/src/modules/overseas-warehouse/pages/DispatchesView.vue`、`api/dispatches.ts`；Backend `../../baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/` | | 海外仓客户自助服务 | 客户工作台正式开放贴标申请、仓储转运、货物废弃和退货换标；所有查询和写入只使用登录态客户范围 | Client `../../apps/client-web/src/modules/overseas-warehouse/routes.ts`、`views/WarehouseServiceView.vue`、`api/warehouseServices.ts`；Backend `../../baiyue-firstleg/lastleg-service/` 的 `relabel/`、`transfer/`、`discard/`，经 `gateway-overseas/` | -| 海外仓 PDA 柜号签收与入仓 | 独立应用 `../../apps/pda-overseas-uniapp/`；当前真实前端只开放拆柜收货，完成柜号认领、三类照片、FBA 按 SKU 箱数/OVERSEAS 逐箱实收与全柜完成 | 前端 `src/api/inbound.js`、`receiving-adapter.js`、`pages/operation/operation.vue`；Backend `../../baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/inboundplan/pda/controller/ReceivingContainerController.java`、`ReceivingContainerService.java`，经 `gateway-overseas/` | +| 海外仓 PDA 柜号签收与退货入库 | 独立应用 `../../apps/pda-overseas-uniapp/`；拆柜收货完成柜号认领、三类照片、按目的类型实收与全柜完成；退货入库支持扫描退货单号或 SKU 候选并按本包实收生成退货箱和计费批次，签收后可按同客户退货单合箱 | 拆柜前端 `src/api/inbound.js`、`receiving-adapter.js`、`pages/operation/operation.vue`；退货前端 `src/api/return-receipt.js`、`src/api/return-packing.js`、`pages/return-receipt/return-receipt.vue`、`pages/return-packing/return-packing.vue`；Backend 分别为 `inboundplan/pda/` 与 `returnreceipt/controller/PdaReturnReceiptController.java`、`PdaReturnInventoryController.java`，经 `gateway-overseas/` | | 海外仓 PDA 库内、托盘、换标与查询 | Lastleg 提供盘点、同仓整托移库、托盘组拆换绑、换标和库存/库位/托盘查询能力；当前终端入口按工作台能力开关启用，未进入 PDA 的操作由 Admin/Client 正式页面承载 | Backend `../../baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/pda/stocktake/`、`pda/move/`、`pda/warehouse/`、`palletops/`、`relabel/pda/`；契约 `src/main/resources/openapi/overseas-pda-operations-v1.yaml` | | 海外仓出库与派送 | 排车编辑/取消、PDA 排车拣货、出库任务、发车门禁、转派送、客户派送单和派送完成 | Admin `../../apps/admin-web/src/modules/overseas-warehouse/`；Overseas PDA `../../apps/pda-overseas-uniapp/src/pages/dispatch/`、`src/pages/outbound/`；Backend `../../baiyue-firstleg/lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/`、`delivery/` | | 异常退回与客户回访 | 异常建档、派送退回入仓、派送状态、签收/回访附件和客户回访 | Admin `ExceptionOrdersView.vue`、`CustomerVisitsView.vue`；Backend `exceptionorder/`、`customervisit/` | diff --git a/财务管理/README.md b/财务管理/README.md index 075cbc0..4f90743 100644 --- a/财务管理/README.md +++ b/财务管理/README.md @@ -4,9 +4,9 @@ ## 当前确认：一件代发客户资金账户（2026-09-05） -当前对话已将资金账户作为一件代发的前置节点重新纳入范围，并覆盖本文后续历史章节中“钱包不做”的旧结论。首批固定为 CNY。账户分别保存实际余额、冻结金额、授信额度、已用授信和冻结授信；`总可用余额 = 实际余额 + 授信额度 - 已用授信 - 冻结金额`，`可用授信 = 授信额度 - 已用授信 - 冻结授信`。扣款及业务冻结先使用未冻结的实际资金，再使用授信；充值先归还已用授信，剩余金额增加实际余额。 +当前对话已将资金账户作为一件代发的前置节点重新纳入范围，并覆盖本文后续历史章节中“钱包不做”的旧结论。首批固定为 CNY。平台设置授信时必须同时设置晚于今天的到期日，最远日期不设上限；到期日当天仍有效。有效期内消费先扣实际可用资金，不足部分累计为已用授信；次日授信失效时，已用授信自动并入实际余额并允许形成负数，负数实际余额会阻止客户提交新订单。充值先归还已用授信或负余额，剩余金额才形成正数资金。 -客户选择固定或自定义金额，查看后台配置的微信/支付宝静态收款码，付款后上传 JPG/PNG 截图形成待审核申请。平台在客户账户明细顶部审核或驳回，也可手工充值、扣款和设置客户授信额度；每次变动写不可变账户流水。新账户授信额度读取 `baiyue.finance.wallet.default-credit-limit`，默认 `0.00`，平台设置的客户额度随后独立持久化。Finance 还提供仅服务令牌可访问、按业务类型和业务单号幂等的冻结、结算和释放接口，供一件代发等模块接入。审核、账户更新、流水、冻结记录和幂等结果在 Finance 单事务内完成，文件内容仍归 File 服务。接口契约见 [客户资金账户 OpenAPI](openapi/finance-wallet-v1.yaml)。 +客户选择固定或自定义金额，查看后台配置的微信/支付宝静态收款码，付款后上传 JPG/PNG 截图形成待审核申请。平台在客户账户明细顶部审核或驳回，也可手工充值、扣款和设置客户限时授信；每次变动写不可变账户流水。新账户默认授信为 `0.00`，只有平台明确设置额度与有效期后才启用。Finance 还提供仅服务令牌可访问、按业务类型和业务单号幂等的冻结、结算和释放接口，供一件代发等模块接入。审核、账户更新、流水、冻结记录和幂等结果在 Finance 单事务内完成，文件内容仍归 File 服务。接口契约见 [客户资金账户 OpenAPI](openapi/finance-wallet-v1.yaml)。 > 盘点日期：2026-09-09 > 当前状态：费用入池 P0 与对账结算 P1 已完成测试环境部署及真实 HTTP 全链验收；最终报告为 `baiyue-firstleg/reports/admin-test-env-acceptance-20260909103401.json`，1518/1518 通过。领导页面人工截图仍按独立验收规则执行 diff --git a/财务管理/openapi/finance-wallet-v1.yaml b/财务管理/openapi/finance-wallet-v1.yaml index 01e4cbf..d0cf3d6 100644 --- a/财务管理/openapi/finance-wallet-v1.yaml +++ b/财务管理/openapi/finance-wallet-v1.yaml @@ -3,9 +3,9 @@ info: title: 客户资金账户、授信与充值 API version: 1.1.0 description: | - CNY 资金账户支持静态收款码、付款截图申请、平台审核、手工充扣、授信额度及业务冻结/结算/释放。 - 总可用余额 = 实际余额 + 授信额度 - 已用授信 - 冻结金额；业务扣款先使用未冻结的实际资金，再使用授信。 - 充值先归还已用授信，剩余部分增加实际余额。新账户授信额度由 + CNY 资金账户支持静态收款码、付款截图申请、平台审核、手工充扣、限时授信及业务冻结/结算/释放。 + 授信到期日当天仍有效，次日不再计入可用余额。消费直接扣减实际余额并允许形成负数；实际余额为负时禁止提交新订单。 + 充值直接增加实际余额。新账户授信额度由 `baiyue.finance.wallet.default-credit-limit` 初始化，默认 `0.00`，平台可按客户调整。 paths: /api/client/finance/v1/account: @@ -203,16 +203,18 @@ components: data: { $ref: '#/components/schemas/WalletAccount' } WalletAccount: type: object - required: [currencyCode, actualBalance, frozenBalance, availableBalance, creditLimit, creditUsed, creditFrozen, availableCredit, version] + required: [currencyCode, actualBalance, frozenBalance, availableBalance, creditLimit, creditUsed, creditFrozen, availableCredit, creditActive, version] properties: currencyCode: { type: string, enum: [CNY] } - actualBalance: { type: number, format: decimal, minimum: 0 } + actualBalance: { type: number, format: decimal, description: 实际余额；授信到期后已用额度并入此余额，可为负数 } frozenBalance: { type: number, format: decimal, minimum: 0, description: 实际资金冻结与授信冻结合计 } - availableBalance: { type: number, format: decimal, minimum: 0, description: 实际可用资金与可用授信合计 } + availableBalance: { type: number, format: decimal, description: 当前可用余额，可在授信失效后为负数 } creditLimit: { type: number, format: decimal, minimum: 0 } creditUsed: { type: number, format: decimal, minimum: 0 } creditFrozen: { type: number, format: decimal, minimum: 0 } availableCredit: { type: number, format: decimal, minimum: 0 } + creditExpiresOn: { type: string, format: date, nullable: true, description: 授信到期日，当天仍有效 } + creditActive: { type: boolean, description: 授信当前是否有效 } version: { type: integer, minimum: 0 } updatedAt: { type: string, format: date-time, nullable: true } RechargeReviewRequest: @@ -235,9 +237,10 @@ components: expectedAccountVersion: { type: integer, minimum: 0 } CreditLimitRequest: type: object - required: [creditLimit, expectedAccountVersion] + required: [creditLimit, creditExpiresOn, expectedAccountVersion] properties: creditLimit: { type: number, format: decimal, minimum: 0 } + creditExpiresOn: { type: string, format: date, description: 必须晚于服务端当前日期，不限制最远日期 } remark: { type: string, maxLength: 500 } expectedAccountVersion: { type: integer, minimum: 0 } WalletFreezeRequest: