# oms 表结构与接口设计文档 ---------------------------------------------------------------------------------------- ## OMS 系统说明 OMS（Order Management System，订单管理系统）作为独立服务运行和admin权限管理服务合并，面向跨境物流/仓储业务场景，提供**订单**、**渠道**、**操作**、**客户**四大核心模块，支撑从客户注册、充值、下单、定价、支付到货物入库出库的全流程管理。 ### 核心模块 | 模块 | 说明 | | --- | --- | | **订单** | 订单全生命周期管理，包括创建、预报、支付、发货、跟踪等 | | **渠道** | 销售产品与物流渠道的配置、定价及买价/卖价计算 | | **操作** | 入库、出库、打印等仓储操作 | | **客户** | 客户注册、认证、账户余额、额度及权限管理 | ---------------------------------------------------------------------------------------- ### 1.2 表结构设计公共规范 #### 表的字段命名规范 | 规范 | 说明 | 示例 | | --- | --- | --- | | 驼峰命名 | 字段名开头大写+单词驼峰 | `ServiceProviderId` | | 单数名词 | 表名用单数，表示实体 | `customer` 而非 `customers` | | 业务前缀 | 表名按业务模块加前缀 | `t_order`、`t_customer` | #### 必备字段（所有表） | 字段名 | 字段类型 | 说明 | | --- | --- | --- | | Id | BIGINT | 主键，自增，步长 1 | | IsDeleted | TINYINT | 软删除：0-否，1-是，默认 0 | | CreateUserId | INT | 创建人 | | CreateTime | DATETIME | 创建时间 | | UpdateUserId | INT | 更新人 | | UpdateTime | DATETIME | 更新时间 | #### 字段命名规范 | 规范 | 说明 | 示例 | | --- | --- | --- | | 布尔字段 | 用 `IsXxx` 或 `HasXxx` | `IsDeleted`、`IsActive` | | 外键字段 | `关联表名Id` 或 `XxxId` | `CustomerId`、`WarehouseId` | | 时间字段 | `XxxTime` 或 `XxxAt` | `CreateTime`、`PayTime` | | 禁用保留字 | 不用 desc、range、match 等 | 用 `Description` 替代 `Desc` | #### 数据类型规范 | 类型 | 说明 | | --- | --- | | 主键 | BIGINT，单表自增 | | 金额/重量 | DECIMAL，禁止 float/double | | 字符串 | varchar 长度 ≤ 5000，超出用 TEXT | | 枚举 | 小数据量用 TINYINT，可读性要求高用 VARCHAR | | 状态标志 | TINYINT | ### 1.3 接口设计公共规范 | 规范 | 说明 | | --- | --- | | 操作审计必填 | 任何新增、编辑、删除操作，必须记录操作者与操作时间 | | 新增接口 | 创建成功后需落库 `CreateUserId`、`CreateTime` | | 编辑接口 | 更新成功后需落库 `UpdateUserId`、`UpdateTime` | | 删除接口 | 逻辑删除时需落库 `UpdateUserId`、`UpdateTime`，并更新 `IsDeleted=1` | > 审计字段中的操作者信息优先从当前登录会话获取，不允许由前端直接信任覆盖。 ---------------------------------------------------------------------------------------- ## 需求迭代目录（按日期管理） > 迭代编号建议使用 `YYYYMMDD-序号`，按日期倒序维护；不同功能迭代可使用 `-01`、`-02` 递增。 | 迭代日期 | 迭代编号 | 迭代功能 | 变更模块 | 备注 | | --- | --- | --- | --- | --- | | 2026-04-27 | 20260427-01 | 客户的账号密码接入登录接口/rbac/auth/login。入参增加一个类型，0（用户）/1（客户）,客户的角色编码读取`t_customer`上的`Role`字段来划分菜单权限，默认使用编码`Customer` | 客户模块 | 已完成 | | 2026-04-27 | 20260427-02 | 任何新增、编辑、删除操作，必须通过authorization来记录操作者与操作时间 | 全局 | 已完成 | | 2026-04-27 | 20260427-03 | 文档版本差异汇总（20260427 vs 2026040802） | 全文档 | 已完成结构与内容差异归档，见下方“差异摘要” | ### 20260427-03 差异明细（按表结构与接口） > 对比范围：`oms表结构与接口设计20260427.md` vs `oms表结构与接口设计2026040802.md` #### 一、表结构差异 **新增表（4）** - `t_country` - `t_dict` - `t_notice` - `t_notice_read` **更新表（0）** - 无（按表名维度无同名结构替换；本次以新增为主） **删除表（0）** - 无 #### 二、接口差异 **新增接口（22）** - `GET /system/country/list`（国家列表） - `GET /system/dict/list`（字典列表） - `GET /system/notice/list`（通知列表） - `POST /channel/service-channel/group/create`（新增服务商） - `POST /channel/service-channel/group/delete`（删除服务商） - `POST /channel/service-channel/group/update`（编辑服务商） - `POST /order/parcel/batch-create`（批量创建小包） - `POST /system/dict/create`（新增字典） - `POST /system/dict/delete`（删除字典） - `POST /system/dict/update`（更新字典） - `POST /system/notice/create`（新增通知） - `POST /system/notice/delete`（删除通知） - `POST /system/notice/read-confirm`（确认已读） - `POST /system/notice/update`（编辑通知） **更新接口（8）** 分区的接口命名更新了，可忽略，因为已经完成了变更了，知道这个事情就行。 ---现在接口命名 - `POST /channel/kpi-area/create`（创建分区） - `POST /channel/kpi-area/delete`（删除分区） - `POST /channel/kpi-area/info/add`（新增分区明细） - `POST /channel/kpi-area/info/delete`（删除分区明细） - `POST /channel/kpi-area/info/list`（分区明细列表） - `POST /channel/kpi-area/info/update`（修改分区明细） - `POST /channel/kpi-area/list`（分区列表） - `POST /channel/kpi-area/update`（修改分区） ---原来接口命名 - `POST Track/ForewarningService/KpiArea/AddAreaInfo`（新增分区明细） - `POST Track/ForewarningService/KpiArea/CreateKpiArea`（创建分区） - `POST Track/ForewarningService/KpiArea/DeleteKpiArea`（删除分区） - `POST Track/ForewarningService/KpiArea/DeleteKpiAreaInfo`（删除分区明细） - `POST Track/ForewarningService/KpiArea/GetKpiAreaInfos`（分区明细列表） - `POST Track/ForewarningService/KpiArea/GetKpiAreas`（分区列表） - `POST Track/ForewarningService/KpiArea/ModifyKpiArea`（修改分区） - `POST Track/ForewarningService/KpiArea/ModifyKpiAreaInfo`（修改分区明细） **删除接口（10）** - `POST /channel/sales-product/config/save`（保存产品配置） - `POST /channel/service-channel/config/save`（保存渠道配置） ---------------------------------------------------------------------------------------- ## 二、订单模块 ### 1.1 核心需求说明 - **我的订单**：支持订单全流程管理，包括分页查询、详情查看、支付、预报、拦截/取消拦截、删除、打印、导出；订单状态覆盖草稿→已预报→已收货→待支付→待发货→运输中→派送成功/失败等全生命周期。 - **我要查价**：根据目的国、运输方式、重量尺寸、货物类型等条件查价，返回可选渠道及费用明细。 - **我要下单**：支持下载下单模板、上传 Excel 批量下单、查看任务进度与详情；模板分为标准模板与自定义模板。 ### 1.2 表结构设计 > **命名约定**：表名按业务模块加 t_ 前缀；字段名驼峰命名（开头大写+单词驼峰）。 #### 订单表 `t_order` | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | ServiceNo | VARCHAR | 64 | - | 是 | 运单号 | | ClientNo | VARCHAR | 64 | - | 否 | 客户单号 | | TrackNo | VARCHAR | 64 | - | 否 | 跟踪号 | | ProductCode | VARCHAR | 128 | - | 否 | 产品code | | ChannelCode | VARCHAR | 128 | - | 否 | 渠道code | | ConsigneeCountry | VARCHAR | 8 | - | 否 | 国家二字码 | | CargoAttribute | VARCHAR | 32 | - | 否 | 货物属性：general-普货，electronics-3c&带电，sensitive-敏感货 | | OrderStatus | VARCHAR | 32 | - | 是 | 订单状态 | | WarehouseId | BIGINT | - | 外键 | 否 | 仓库ID | | CustomerId | BIGINT | - | 外键 | 否 | 客户ID | | SenderId | BIGINT | - | 外键 | 否 | 发件人ID → t_order_sender | | RecipientId | BIGINT | - | 外键 | 否 | 收件人ID → t_order_recipient | | DeclarationId | BIGINT | - | 外键 | 否 | 申报信息ID → t_order_declaration | | ReceiveTime | DATETIME | - | - | 否 | 收货时间 | | ShipTime | DATETIME | - | - | 否 | 发货时间 | | PayTime | DATETIME | - | - | 否 | 支付时间 | | SignTime | DATETIME | - | - | 否 | 签收时间 | | IsCod | TINYINT | - | - | 否 | 是否COD：0-否，1-是 | | CodCurrency | VARCHAR | 16 | - | 否 | COD币种 | | CodSum | DECIMAL | 18,4 | - | 否 | COD金额 | | IsIntercept | TINYINT | - | - | 否 | 是否拦截：0-否，1-是 | | IsRemote | TINYINT | - | - | 否 | 是否偏远：0-否，1-是 | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | **OrderStatus 枚举**：draft, predeclared, received, pendingPayment, pendingShip, pendingOnline, shipping, deliverySuccess, deliveryFailed, problematic, deleted, claimed **CargoAttribute 枚举**：general-普货，electronics-3c&带电，sensitive-敏感货 #### 下单模板表 `t_order_template` | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | Name | VARCHAR | 64 | - | 是 | 模板名称 | | Type | VARCHAR | 16 | - | 是 | standard/custom | | TemplateKey | VARCHAR | 64 | - | 否 | 模板标识 | | CustomerId | BIGINT | - | 外键 | 否 | 客户ID(自定义模板) | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | #### 下单任务表 `t_order_task` | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | TaskName | VARCHAR | 128 | - | 是 | 任务名称 | | Quantity | INT | - | - | 否 | 数量 | | Status | VARCHAR | 16 | - | 是 | 处理中/已完成/待处理 | | TemplateId | BIGINT | - | 外键 | 否 | 模板ID | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | | CustomerId | BIGINT | - | 外键 | 否 | 客户ID | #### 订单发件人表 `t_order_sender` | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | OrderId | BIGINT | - | 外键 | 是 | 订单ID | | SenderName | VARCHAR | 50 | - | 否 | 姓名 | | Company | VARCHAR | 255 | - | 否 | 公司 | | Country | INT | - | - | 否 | 国家 | | Province | VARCHAR | 50 | - | 否 | 州省 | | City | VARCHAR | 50 | - | 否 | 城市 | | ZipCode | VARCHAR | 50 | - | 否 | 邮编 | | StreetAddress1 | VARCHAR | 500 | - | 否 | 地址1 | | StreetAddress2 | VARCHAR | 500 | - | 否 | 地址2 | | StreetAddress3 | VARCHAR | 500 | - | 否 | 地址3 | | HouseNumber | VARCHAR | 50 | - | 否 | 门牌号 | | Phone | VARCHAR | 50 | - | 否 | 手机 | | TelePhone | VARCHAR | 50 | - | 否 | 电话 | | Email | VARCHAR | 60 | - | 否 | 邮箱 | | IsDefault | TINYINT | - | - | 否 | 是否默认：0-否，1-是 | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | #### 订单收件人表 `t_order_recipient` | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | OrderId | BIGINT | - | 外键 | 是 | 订单ID | | RecipientsName | VARCHAR | 30 | - | 否 | 收件人名称 | | CompanyName | VARCHAR | 60 | - | 否 | 收件人公司名称 | | Country | INT | - | - | 否 | 国家 | | Phone | VARCHAR | 20 | - | 否 | 收件人手机 | | TelePhone | VARCHAR | 20 | - | 否 | 收件人电话 | | ZipCode | VARCHAR | 15 | - | 否 | 收件人邮编 | | Province | VARCHAR | 25 | - | 否 | 收件人省/州 | | City | VARCHAR | 25 | - | 否 | 收件人城市 | | StreetNumber | VARCHAR | 20 | - | 否 | 收件人门牌号 | | StreetAddress1 | VARCHAR | 255 | - | 否 | 收件人地址1 | | StreetAddress2 | VARCHAR | 255 | - | 否 | 收件人地址2 | | StreetAddress3 | VARCHAR | 255 | - | 否 | 收件人地址3 | | Email | VARCHAR | 60 | - | 否 | 收件人邮箱 | | TaxType | INT | - | - | 否 | 税号类型 | | TaxNo | VARCHAR | 35 | - | 否 | 税号 | | CertificateType | INT | - | - | 否 | 证件类型 | | CertificateNo | VARCHAR | 30 | - | 否 | 证件号码 | | Eori | VARCHAR | 255 | - | 否 | EORI | | Vat | VARCHAR | 255 | - | 否 | Vat | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | #### 订单申报信息表 `t_order_declaration` | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | OrderId | BIGINT | - | 外键 | 是 | 订单ID | | CnName | VARCHAR | 500 | - | 否 | 品名--中 | | EnName | VARCHAR | 500 | - | 否 | 品名--英 | | Sku | VARCHAR | 255 | - | 否 | SKU | | Unit | VARCHAR | 5 | - | 否 | 单位 | | UnitPrice | DECIMAL | 10,2 | - | 否 | 单价 | | UnitWeight | DECIMAL | 11,3 | - | 否 | 单重 | | Quantity | INT | - | - | 否 | 数量 | | Amount | DECIMAL | 11,2 | - | 否 | 总金额 | | Weight | DECIMAL | 11,3 | - | 否 | 总重量 | | HsCode | VARCHAR | 50 | - | 否 | HsCode | | SkuImage | VARCHAR | 255 | - | 否 | 图片 | | Category | VARCHAR | 20 | - | 否 | 类别 | | Brand | VARCHAR | 50 | - | 否 | 品牌 | | BrandType | VARCHAR | 50 | - | 否 | 品牌类型 | | IsMagnetic | BIT | - | - | 否 | 是否带磁带电 | | Distribution | VARCHAR | 255 | - | 否 | 配货信息 | | Material | VARCHAR | 50 | - | 否 | 材质 | | EnMaterial | VARCHAR | 64 | - | 否 | 英文材质 | | Purpose | VARCHAR | 50 | - | 否 | 用途 | | Attributes | VARCHAR | 50 | - | 否 | 属性 | | OriginCountry | VARCHAR | 50 | - | 否 | 原产国 | | SalesLink | VARCHAR | 255 | - | 否 | 销售链接 | | Model | VARCHAR | 64 | - | 否 | 型号 | | Specifications | VARCHAR | 50 | - | 否 | 规格 | | Comment | VARCHAR | 500 | - | 否 | 备注 | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | #### 订单件重尺表 `t_order_weight` | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | OrderId | BIGINT | - | 外键 | 是 | 订单ID | | Type | VARCHAR | 16 | - | 是 | 类型：forecast/receive/ship/downstream | | Length | DECIMAL | 10,2 | - | 否 | 长(cm) | | Width | DECIMAL | 10,2 | - | 否 | 宽(cm) | | Height | DECIMAL | 10,2 | - | 否 | 高(cm) | | ActualWeight | DECIMAL | 10,3 | - | 否 | 实重(kg) | | VolumetricWeight | DECIMAL | 10,3 | - | 否 | 体积重(kg) | | ChargeableWeight | DECIMAL | 10,3 | - | 否 | 计费重(kg) | | Cubic | DECIMAL | 12,6 | - | 否 | 立方(m³) | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | **Type 枚举**：forecast(预报)、receive(收货)、ship(发货)、downstream(下游) #### 订单费用表 `t_order_fee`（子表，关联 t_order） | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | OrderId | BIGINT | - | 外键 | 是 | 订单ID | | Type | VARCHAR | 16 | - | 是 | 类型：receivable(应收)/payable(应付) | | CostItem | VARCHAR | 64 | - | 是 | 费用项 | | Amount | DECIMAL | 18,4 | - | 是 | 金额 | | Currency | VARCHAR | 16 | - | 是 | 币种：RMB/USD/EUR | | DownstreamProvider | VARCHAR | 128 | - | 否 | 下游服务商 | | PriceNo | VARCHAR | 64 | - | 否 | 价格编号 | | PriceEffectiveTime | DATETIME | - | - | 否 | 价格编号生效时间 | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | **Type 枚举**：receivable(应收)、payable(应付) ### 1.3 核心接口设计 #### 我的订单 | 接口名称 | 请求方式 | 请求路径 | 说明 | | --- | --- | --- | --- | | 分页查询订单列表 | POST | /order/list | 支持 status、keyword、createTimeStart/End 筛选 | | 订单详情 | GET | /order/detail | 根据订单ID获取详情 | | 支付 | POST | /order/pay | 订单支付 | | 预报 | POST | /order/pre-declare | 订单预报 | | 拦截 | POST | /order/intercept | 订单拦截 | | 取消拦截 | POST | /order/cancel-intercept | 取消订单拦截 | | 删除 | POST | /order/delete | 删除订单 | | 打印 | POST | /order/print | 打印订单 | | 导出 | POST | /order/export | 导出订单 | ##### 分页查询订单列表（POST /order/list） ###### 1 接口请求示例 **请求 /order/list**（POST，分页参数放 Body） ```json { "page": 1, // 页码，从1开始 "pageSize": 20, // 每页条数 "status": "all|draft|predeclared|received|...", // 订单状态筛选 "keyword": "", // 关键词（运单号/客户单号/跟踪号） "createTimeStart": "", // 创建时间起 "createTimeEnd": "" // 创建时间止 } ``` **响应**（用于 order/myOrders 列表及订单详情抽屉，字段与 parcel/create 对应，创建时传啥返回啥 + weightList） ```json { "code": 0, "msg": "success", "data": { "items": [ { "id": 1, "clientNo": "CUST...", "trackNo": "TRK...", "serviceNo": "LP...", "productCode": "US_AIR", "channelCode": "CH001", "cargoAttribute": "general", "warehouseId": 1, "warehouse": "深圳仓", "customerId": 1, "isCod": false, "codCurrency": "", "codSum": "", "orderStatus": "待支付", "status": "pendingPayment", "receiveTime": "", "shipTime": "", "payTime": "", "signTime": "", "isIntercept": false, "isRemote": false, "createTime": "2024-01-01 12:00:00", "createBy": "", "updateTime": "", "updateBy": "", "sender": { "senderName": "发件人", "company": "示例公司", "phone": "13800138000", "telePhone": "", "email": "sender@example.com", "countryCode": 0, "province": "广东省", "city": "深圳市", "zipCode": "518000", "streetAddress1": "示例地址1", "streetAddress2": "", "streetAddress3": "", "houseNumber": "" }, "receiver": { "recipientsName": "收件人1", "companyName": "", "phone": "13800138000", "telePhone": "", "email": "", "countryCode": 0, "province": "California", "city": "Los Angeles", "streetNumber": "", "streetAddress1": "123 Main St", "streetAddress2": "", "streetAddress3": "", "zipCode": "90001", "taxType": 0, "taxNo": "", "certificateType": 0, "certificateNo": "", "eori": "", "vat": "" }, "items": [ { "cnName": "示例商品", "enName": "Sample Product", "sku": "SKU001", "unit": "件", "unitPrice": 10, "unitWeight": 0.5, "quantity": 1, "amount": 10, "weight": 0.5, "hsCode": "1234567890", "skuImage": "", "category": "普货", "brand": "示例品牌", "brandType": "自有", "isMagnetic": false, "distribution": "", "material": "塑料", "enMaterial": "Plastic", "purpose": "日用", "attributes": "", "originCountry": "中国", "salesLink": "", "model": "", "specifications": "", "comment": "" } ], "weightList": [ { "type": "forecast", "length": "20", "width": "15", "height": "10", "actualWeight": "2.50", "volumetricWeight": "2.00", "chargeableWeight": "2.50", "cubic": "0.003" } ] } ], "total": 100 } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。 ####### 校验与异常 - 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。 ##### 订单详情（GET /order/detail） ###### 1 接口请求示例 **请求 /order/detail**（GET，Query 参数） ``` ?id=1 ``` **响应** ```json { "code": 0, "msg": "success", "data": { "id": 1, "clientNo": "CUST...", "trackNo": "TRK...", "serviceNo": "LP...", "productCode": "US_AIR", "channelCode": "CH001", "cargoAttribute": "general", "warehouseId": 1, "warehouse": "深圳仓", "customerId": 1, "sender": {}, "receiver": {}, "items": [], "weightList": [] } } ``` > data 结构与 list 单条 item 一致，含 sender、receiver、items、weightList。 ###### 2 接口业务逻辑 ####### 核心流程 - 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。 ####### 校验与异常 - 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。 ##### 支付（POST /order/pay） ###### 1 接口请求示例 **请求 /order/pay**（POST） ```json { "id": 1, "requestId": "" } ``` > requestId 幂等，可选。 **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。 ####### 校验与异常 - 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。 ##### 预报（POST /order/pre-declare） ###### 1 接口请求示例 **请求 /order/pre-declare**（POST） ```json { "id": 1, "requestId": "" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。 ####### 校验与异常 - 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。 ##### 拦截（POST /order/intercept） ###### 1 接口请求示例 **请求 /order/intercept**（POST） ```json { "id": 1, "requestId": "" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。 ####### 校验与异常 - 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。 ##### 取消拦截（POST /order/cancel-intercept） ###### 1 接口请求示例 **请求 /order/cancel-intercept**（POST） ```json { "id": 1, "requestId": "" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。 ####### 校验与异常 - 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。 ##### 删除（POST /order/delete） ###### 1 接口请求示例 **请求 /order/delete**（POST） ```json { "id": 1, "requestId": "" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。 ####### 校验与异常 - 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。 ##### 打印（POST /order/print） ###### 1 接口请求示例 **请求 /order/print**（POST） ```json { "id": 1, "requestId": "" } ``` **响应** ```json { "code": 0, "msg": "success", "data": { "printUrl": "" } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。 ####### 校验与异常 - 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。 ##### 导出（POST /order/export） ###### 1 接口请求示例 **请求 /order/export**（POST） ```json { "status": "all|draft|...", "keyword": "", "createTimeStart": "", "createTimeEnd": "" } ``` **响应** ```json { "code": 0, "msg": "success", "data": { "downloadUrl": "", "expireAt": "" } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。 ####### 校验与异常 - 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。 #### 我要查价 | 接口名称 | 请求方式 | 请求路径 | 说明 | | --- | --- | --- | --- | | 查价 | POST | /order/price-check | 根据目的国、重量尺寸等查价 | ##### 查价（POST /order/price-check） ###### 1 接口请求示例 **请求 /order/price-check**（POST） ```json { "destinationCountry": "US", // 目的国二字码 "shippingMethod": "", // 运输方式 "cargoWeight": "2", // 货物重量(kg) "length": "20", // 长(cm) "width": "15", // 宽(cm) "height": "10", // 高(cm) "cargoType": "普货", // 货物类型 "destinationProvince": "", // 目的省州 "postalCode": "" // 邮编 } ``` **响应** ```json { "code": 0, "msg": "success", "data": { "items": [ { "id": 1, "shippingMethod": "美国空运专线(普货)", "warehouse": "一代深圳仓", "deliveryTime": "3-7", "volumetricWeight": "2", "chargeableWeight": "2", "costFormula": "(62*2) +5+7", "freight": "62", "otherFees": "5", "totalCost": "136", "maxDeliveryDays": 7, "totalCostNum": 136 } ] } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。 ####### 校验与异常 - 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。 #### 我要下单 | 接口名称 | 请求方式 | 请求路径 | 说明 | | --- | --- | --- | --- | | 模板列表 | GET | /order/template/list | 获取下单模板列表 | | 下载模板 | GET | /order/template/download | 下载 Excel 模板 | | 上传下单 | POST | /order/upload | multipart/form-data，file + templateId | | 任务进度列表 | GET | /order/task/list | 批量下单任务列表 | | 任务详情 | GET | /order/task/detail | 任务详情 | | 创建小包 | POST | /order/parcel/create | 创建小包订单 | | 批量创建小包 | POST | /order/parcel/batch-create | 批量创建小包订单 | ##### 创建小包（POST /order/parcel/create） ###### 1 接口请求示例 **请求 /order/parcel/create**（POST） > 字段与 t_order、t_order_sender、t_order_recipient、t_order_declaration、t_order_weight 表对应，采用 camelCase。 ```json { "clientNo": "string", // 客户单号 t_order.ClientNo "trackNo": "string", // 跟踪号 t_order.TrackNo "serviceNo": "string", // 运单号 t_order.ServiceNo "productCode": "string", // 产品代码 t_order.ProductCode "channelCode": "string", // 渠道代码 t_order.ChannelCode "cargoAttribute": "string", // 货物属性 t_order.CargoAttribute：general-普货，electronics-3c&带电，sensitive-敏感货 "warehouseId": 0, // 仓库ID t_order.WarehouseId "customerId": 0, // 客户ID t_order.CustomerId "length": 3, // 长(cm) t_order_weight.Length "width": 3, // 宽(cm) t_order_weight.Width "height": 3, // 高(cm) t_order_weight.Height "actualWeight": 3, // 实重(kg) t_order_weight.ActualWeight "volumetricWeight": 3, // 体积重(kg) t_order_weight.VolumetricWeight "chargeableWeight": 3, // 计费重(kg) t_order_weight.ChargeableWeight "cubic": 0, // 立方(m³) t_order_weight.Cubic "isCod": false, // 是否COD "codCurrency": "string", // COD币种 "codSum": "string", // COD金额 "declaredCurrency": "string", // 申报币种 "declaredSum": "string", // 申报金额 "quantity": "string", // 包裹数量 "receiver": { // 收件人 t_order_recipient "recipientsName": "string", // 收件人名称 "companyName": "string", // 收件人公司名称 "phone": "string", // 收件人手机 "telePhone": "string", // 收件人电话 "email": "string", // 收件人邮箱 "countryCode": 0, // 国家 "province": "string", // 收件人省/州 "city": "string", // 收件人城市 "streetNumber": "string", // 收件人门牌号 "streetAddress1": "string", // 收件人地址1 "streetAddress2": "string", // 收件人地址2 "streetAddress3": "string", // 收件人地址3 "zipCode": "string", // 收件人邮编 "taxType": 0, // 税号类型 "taxNo": "string", // 税号 "certificateType": 0, // 证件类型 "certificateNo": "string", // 证件号码 "eori": "string", // EORI "vat": "string" // Vat }, "sender": { // 发件人 t_order_sender "senderName": "string", // 发件人姓名 "company": "string", // 发件人公司 "phone": "string", // 发件人手机 "telePhone": "string", // 发件人电话 "email": "string", // 发件人邮箱 "countryCode": 0, // 国家 "province": "string", // 州省 "city": "string", // 城市 "zipCode": "string", // 邮编 "streetAddress1": "string", // 地址1 "streetAddress2": "string", // 地址2 "streetAddress3": "string", // 地址3 "houseNumber": "string" // 门牌号 }, "items": [ // 申报明细 t_order_declaration { "cnName": "string", // 品名-中 "enName": "string", // 品名-英 "sku": "string", // SKU "unit": "string", // 单位 "unitPrice": 0, // 单价 "unitWeight": 0, // 单重 "quantity": 0, // 数量 "amount": 0, // 总金额 "weight": 0, // 总重量 "imHsCode": "string", // 进口HsCode "exHsCode": "string", // 出口HsCode "skuImage": "string", // 图片 "category": "string", // 类别 "brand": "string", // 品牌 "brandType": "string", // 品牌类型 "isMagnetic": false, // 是否带磁带电 "distribution": "string", // 配货信息 "material": "string", // 材质 "enMaterial": "string", // 英文材质 "purpose": "string", // 用途 "attributes": "string", // 属性 "originCountry": "string", // 原产国 "salesLink": "string", // 销售链接 "model": "string", // 型号 "specifications": "string", // 规格 "comment": "string" // 备注 } ] } ``` **响应** ```json { "code": 0, "msg": "success", "data": { "clientNo": "", "serviceNo": "", "trackNo": "", "labelUrl": "" } } ``` > 幂等时可选传 requestId。 ###### 2 接口业务逻辑 ####### 核心流程 - 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。 ####### 校验与异常 - 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。 ##### 批量创建小包（POST /order/parcel/batch-create） ###### 1 接口请求示例 **请求 /order/parcel/batch-create**（POST） > 批量请求体为数组，数组内每一项与 `/order/parcel/create` 的单票请求结构完全一致。 ```json [ { "clientNo": "string", // 客户单号 t_order.ClientNo "trackNo": "string", // 跟踪号 t_order.TrackNo "serviceNo": "string", // 运单号 t_order.ServiceNo "productCode": "string", // 产品代码 t_order.ProductCode "channelCode": "string", // 渠道代码 t_order.ChannelCode "cargoAttribute": "string", // 货物属性 t_order.CargoAttribute：general-普货，electronics-3c&带电，sensitive-敏感货 "warehouseId": 0, // 仓库ID t_order.WarehouseId "customerId": 0, // 客户ID t_order.CustomerId "length": 3, // 长(cm) t_order_weight.Length "width": 3, // 宽(cm) t_order_weight.Width "height": 3, // 高(cm) t_order_weight.Height "actualWeight": 3, // 实重(kg) t_order_weight.ActualWeight "volumetricWeight": 3, // 体积重(kg) t_order_weight.VolumetricWeight "chargeableWeight": 3, // 计费重(kg) t_order_weight.ChargeableWeight "cubic": 0, // 立方(m³) t_order_weight.Cubic "isCod": false, // 是否COD "codCurrency": "string", // COD币种 "codSum": "string", // COD金额 "declaredCurrency": "string", // 申报币种 "declaredSum": "string", // 申报金额 "quantity": "string", // 包裹数量 "receiver": { // 收件人 t_order_recipient "recipientsName": "string", // 收件人名称 "companyName": "string", // 收件人公司名称 "phone": "string", // 收件人手机 "telePhone": "string", // 收件人电话 "email": "string", // 收件人邮箱 "countryCode": 0, // 国家 "province": "string", // 收件人省/州 "city": "string", // 收件人城市 "streetNumber": "string", // 收件人门牌号 "streetAddress1": "string", // 收件人地址1 "streetAddress2": "string", // 收件人地址2 "streetAddress3": "string", // 收件人地址3 "zipCode": "string", // 收件人邮编 "taxType": 0, // 税号类型 "taxNo": "string", // 税号 "certificateType": 0, // 证件类型 "certificateNo": "string", // 证件号码 "eori": "string", // EORI "vat": "string" // Vat }, "sender": { // 发件人 t_order_sender "senderName": "string", // 发件人姓名 "company": "string", // 发件人公司 "phone": "string", // 发件人手机 "telePhone": "string", // 发件人电话 "email": "string", // 发件人邮箱 "countryCode": 0, // 国家 "province": "string", // 州省 "city": "string", // 城市 "zipCode": "string", // 邮编 "streetAddress1": "string", // 地址1 "streetAddress2": "string", // 地址2 "streetAddress3": "string", // 地址3 "houseNumber": "string" // 门牌号 }, "items": [ // 申报明细 t_order_declaration { "cnName": "string", // 品名-中 "enName": "string", // 品名-英 "sku": "string", // SKU "unit": "string", // 单位 "unitPrice": 0, // 单价 "unitWeight": 0, // 单重 "quantity": 0, // 数量 "amount": 0, // 总金额 "weight": 0, // 总重量 "imHsCode": "string", // 进口HsCode "exHsCode": "string", // 出口HsCode "skuImage": "string", // 图片 "category": "string", // 类别 "brand": "string", // 品牌 "brandType": "string", // 品牌类型 "isMagnetic": false, // 是否带磁带电 "distribution": "string", // 配货信息 "material": "string", // 材质 "enMaterial": "string", // 英文材质 "purpose": "string", // 用途 "attributes": "string", // 属性 "originCountry": "string", // 原产国 "salesLink": "string", // 销售链接 "model": "string", // 型号 "specifications": "string", // 规格 "comment": "string" // 备注 } ] } ] ``` **响应** ```json { "code": 0, "msg": "success", } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 接收批量订单数据并逐条按单票创建规则执行，下发统一批次任务号并返回逐条处理结果。 ####### 校验与异常 - 校验请求数组非空、单次数量上限与单条必填字段；部分失败时返回明细错误信息。 ##### 模板列表（GET /order/template/list） ###### 1 接口请求示例 **请求 /order/template/list**（GET，Query 参数） ``` ?page=1&pageSize=20&type=standard|custom&keyword= ``` **响应** ```json { "code": 0, "msg": "success", "data": { "items": [ { "id": 1, "name": "标准模板", "type": "standard", "templateKey": "standard_v1", "customerId": 0, "createTime": "2024-01-01 12:00:00", "updateTime": "2024-01-01 12:00:00" } ], "total": 10 } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。 ####### 校验与异常 - 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。 ##### 下载模板（GET /order/template/download） ###### 1 接口请求示例 **请求 /order/template/download**（GET，Query 参数） ``` ?templateId=1 ``` **响应** > 直接返回 Excel 文件流，Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet ###### 2 接口业务逻辑 ####### 核心流程 - 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。 ####### 校验与异常 - 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。 ##### 上传下单（POST /order/upload） ###### 1 接口请求示例 **请求 /order/upload**（POST，multipart/form-data） | 字段 | 类型 | 说明 | | --- | --- | --- | | file | File | Excel 文件 | | templateId | number | 模板ID | **响应** ```json { "code": 0, "msg": "success", "data": { "taskId": 1 } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。 ####### 校验与异常 - 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。 ##### 任务进度列表（GET /order/task/list） ###### 1 接口请求示例 **请求 /order/task/list**（GET，Query 参数） ``` ?page=1&pageSize=20&status=&keyword= ``` **响应** ```json { "code": 0, "msg": "success", "data": { "items": [ { "id": 1, "taskName": "批量下单_20240101", "quantity": 100, "status": "处理中", "templateId": 1, "createTime": "2024-01-01 12:00:00", "updateTime": "2024-01-01 12:00:00" } ], "total": 10 } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。 ####### 校验与异常 - 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。 ##### 任务详情（GET /order/task/detail） ###### 1 接口请求示例 **请求 /order/task/detail**（GET，Query 参数） ``` ?taskId=1 ``` **响应** ```json { "code": 0, "msg": "success", "data": { "id": 1, "taskName": "批量下单_20240101", "quantity": 100, "successCount": 80, "failCount": 20, "status": "已完成", "templateId": 1, "createTime": "2024-01-01 12:00:00", "updateTime": "2024-01-01 12:00:00", "failList": [] } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。 ####### 校验与异常 - 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。 ## 三、渠道模块 ### 2.1 核心需求说明 - **销售产品**：管理对外销售的产品（专线/快递/邮政），配置时效、黑名单区、偏远分区、价格分区、计重规则、计重进位等；支持价格配置。 - **产品配置**：产品基础信息（编码、名称、分组、时效、面单、黑名单区、偏远分区、价格分区、计重规则、计重进位等）。 - **产品卖价**：为每个产品配置多条价格项（运费、保险费、燃油附加费等）；每条价格项通过弹窗配置： - **基础信息**：费用项、费用单位、币种、收费时机、收费条件、计费因素（因素+因素值，如货物类型、分区、重量、仓库、客户等）。 - **价格表**：根据计费因素动态生成价格表，支持分区/货物类型/重量等组合、计算公式（总价/单价/续单价）、计算值、客户组。 - **排货规则**：选择排货方案（成本最低/时效最快/综合最优），配置服务商列表（服务商名称、服务渠道、权重、指定客户）。 - **发布记录**：价格与规则的发布历史，支持查看版本内容、回滚到指定版本。 - **服务渠道**：管理下游服务渠道（支持渠道组+渠道层级），配置预报单号类型、时效、买价等。 - **渠道配置**：渠道基础信息（渠道代码、名称、时效、预报配置、描述、预报前脚本等）。 - **渠道买价**：为每个渠道配置多条买价项（运费、保险费、燃油附加费等）；每条买价项通过弹窗配置： - **基础信息**：费用项、费用单位、币种、收费时机、收费条件、计费因素（因素+因素值）。 - **价格表**：根据计费因素动态生成价格表，支持分区/货物类型/重量等组合、计算公式、计算值、客户组。 - **发布记录**：买价与规则的发布历史，支持查看版本内容、回滚到指定版本。 - **黑名单区/偏远分区/价格分区**：共用 KpiArea 表，仅通过 `AreaType` 区分；支持分区及明细（国家/省/市/邮编区间）的增删改查。 - **计重规则/计重进位**：配置计费重量规则与进位方式，明细结构与分区类似。 - **自动触发**：配置下单/入库/出库时的自动拦截、警告、问题件等触发规则。 - **标签设计**：保存 vg-print 导出的标签模板 JSON，支持尾程/客户/入库/出库/sku 等类型。 ### 2.2 表结构设计 #### 销售产品表 `t_sales_product` | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | ProductCode | VARCHAR | 64 | - | 是 | 产品编码 | | ProductName | VARCHAR | 128 | - | 是 | 产品名称 | | ProductGroup | VARCHAR | 32 | - | 否 | 分组(专线/快递/邮政) | | MinTimeliness | INT | - | - | 否 | 最小时效(天) | | MaxTimeliness | INT | - | - | 否 | 最大时效(天) | | CustomerWaybill | VARCHAR | 32 | - | 否 | 系统面单/客户面单 | | BlacklistAreaId | BIGINT | - | 外键 | 否 | 黑名单区ID | | RemoteAreaId | BIGINT | - | 外键 | 否 | 偏远分区ID | | PriceAreaId | BIGINT | - | 外键 | 否 | 价格分区ID（`t_kpi_area`，`AreaType=price`） | | WeightRuleId | BIGINT | - | 外键 | 否 | 计重规则ID | | WeightRoundingId | BIGINT | - | 外键 | 否 | 计重进位ID | | ProductDescription | TEXT | - | - | 否 | 产品描述 | | PreStorageScript | TEXT | - | - | 否 | 入库前脚本 | | IsActive | TINYINT | - | - | 是 | 是否启用 | | Scheme | VARCHAR | 32 | - | 是 | 排货方案：costLowest/timeFastest/overallBest | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | #### 产品卖价表 `t_sales_product_price`（子表，关联 t_sales_product） > 产品卖价主表，每个产品可配置多条价格项（运费、保险费、燃油附加费等）。 | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | SalesProductId | BIGINT | - | 外键 | 是 | 销售产品ID | | SerialNumber | INT | - | - | 是 | 序号 | | Status | TINYINT | - | - | 是 | 状态：0-禁用，1-启用 | | PriceName | VARCHAR | 64 | - | 是 | 价格名称（如运费、保险费） | | CostItem | VARCHAR | 64 | - | 是 | 费用项 | | CostUnit | VARCHAR | 16 | - | 是 | 费用单位：kg/票/件 | | Currency | VARCHAR | 16 | - | 是 | 币种：RMB/USD/EUR | | ChargingTime | VARCHAR | 32 | - | 否 | 收费时机：预报/出库/签收 | | ChargingCondition | VARCHAR | 64 | - | 否 | 收费条件 | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | #### 产品卖价-计费因素表 `t_sales_product_price_factor`（子表，关联 t_sales_product_price） > 弹窗「基础信息」中的计费因素配置，支持货物类型、分区、重量、仓库、客户等。 | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | PriceId | BIGINT | - | 外键 | 是 | 产品卖价ID | | SerialNumber | INT | - | - | 是 | 序号（决定因素排序） | | Factor | VARCHAR | 64 | - | 是 | 因素：货物类型/分区/重量/仓库/客户 | | FactorValues | JSON | - | - | 否 | 因素值数组，如 ["普货","敏感货"] | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | #### 产品卖价-价格表明细表 `t_sales_product_price_detail`（子表，关联 t_sales_product_price） > 弹窗「价格表」中的价格明细，表头由计费因素动态生成，存储各组合的价格值。 | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | PriceId | BIGINT | - | 外键 | 是 | 产品卖价ID | | FactorValuesJson | JSON | - | - | 否 | 非客户因素组合，如 {"分区":"欧洲","货物类型":"普货","重量":"0-0.5"} | | CalculationFormula | VARCHAR | 32 | - | 是 | 计算公式：总价/单价/续单价 | | CalculatedValue | DECIMAL | 18,4 | - | 否 | 计算值 | | CustomerGroupValues | JSON | - | - | 否 | 客户组对应价格，如 {"客户组1":10,"客户组2":12} | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | #### 排货规则-服务商表 `t_sales_product_allocation_provider`（子表，关联 t_sales_product_allocation_rule） > 服务商列表：服务商名称、服务渠道、权重、指定客户。 | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | SalesProductId | BIGINT | - | 外键 | 是 | 销售产品ID | | SerialNumber | INT | - | - | 是 | 序号 | | ProviderName | VARCHAR | 128 | - | 是 | 服务商名称 | | ServiceChannelId | BIGINT | - | 外键 | 否 | 服务渠道ID | | Weight | INT | - | - | 是 | 权重（评分用） | | CustomerIds | JSON | - | - | 否 | 指定客户ID数组，空表示全部 | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | **Scheme 枚举**：costLowest(成本最低)、timeFastest(时效最快)、overallBest(综合最优) #### 发布记录表 `t_sales_product_publish_record`（子表，关联 t_sales_product） > 价格与规则的发布历史，支持查看版本内容、回滚。 | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | SalesProductId | BIGINT | - | 外键 | 是 | 销售产品ID | | Version | VARCHAR | 32 | - | 是 | 版本号，如 20231227112339 | | OperatorType | VARCHAR | 16 | - | 是 | 操作类型：price(价格)/rules(规则) | | Status | VARCHAR | 16 | - | 是 | 状态：生效/回滚/无效 | | PublishUser | VARCHAR | 64 | - | 是 | 发布人 | | PublishTime | DATETIME | - | - | 是 | 发布时间 | | Description | VARCHAR | 512 | - | 否 | 版本备注 | | Content | JSON | - | - | 否 | 发布内容（价格或规则配置的JSON快照） | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | #### 服务渠道组表 `t_service_channel_group`（可选，用于渠道分组） | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | Name | VARCHAR | 128 | - | 是 | 渠道组名称 | | AppId | BIGINT | - | - | 否 | 应用ID（页面新增/编辑服务商时保存） | | ApiServiceProviderId | BIGINT | - | - | 否 | API服务商ID（页面新增/编辑服务商时保存） | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | #### 服务渠道表 `t_service_channel` | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | GroupId | BIGINT | - | 外键 | 否 | 渠道组ID（可选） | | ChannelCode | VARCHAR | 64 | - | 是 | 渠道编码 | | ChannelName | VARCHAR | 128 | - | 是 | 渠道名称 | | MinTime | INT | - | - | 否 | 最小时效(天) | | MaxTime | INT | - | - | 否 | 最大时效(天) | | ForecastType | VARCHAR | 32 | - | 否 | 预报单号类型(customer/waybill/tracking) | | ForecastCode | VARCHAR | 128 | - | 否 | 预报单号 | | Description | TEXT | - | - | 否 | 描述 | | PreScript | TEXT | - | - | 否 | 入库前脚本 | | IsActive | TINYINT | - | - | 是 | 是否启用 | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | #### 渠道买价表 `t_service_channel_price`（子表，关联 t_service_channel） > 渠道买价主表，每个渠道可配置多条买价项（运费、保险费、燃油附加费等）。 | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | ServiceChannelId | BIGINT | - | 外键 | 是 | 服务渠道ID | | SerialNumber | INT | - | - | 是 | 序号 | | Status | TINYINT | - | - | 是 | 状态：0-禁用，1-启用 | | PriceName | VARCHAR | 64 | - | 是 | 价格名称 | | CostItem | VARCHAR | 64 | - | 是 | 费用项 | | CostUnit | VARCHAR | 16 | - | 是 | 费用单位：kg/票/件 | | Currency | VARCHAR | 16 | - | 是 | 币种：RMB/USD/EUR | | ChargingTime | VARCHAR | 32 | - | 否 | 收费时机：预报/出库/签收 | | ChargingCondition | VARCHAR | 64 | - | 否 | 收费条件 | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | #### 渠道买价-计费因素表 `t_service_channel_price_factor`（子表，关联 t_service_channel_price） > 弹窗「基础信息」中的计费因素配置。 | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | PriceId | BIGINT | - | 外键 | 是 | 渠道买价ID | | SerialNumber | INT | - | - | 是 | 序号 | | Factor | VARCHAR | 64 | - | 是 | 因素：货物类型/分区/重量/仓库/客户 | | FactorValues | JSON | - | - | 否 | 因素值数组 | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | #### 渠道买价-价格表明细表 `t_service_channel_price_detail`（子表，关联 t_service_channel_price） > 弹窗「价格表」中的价格明细。 | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | PriceId | BIGINT | - | 外键 | 是 | 渠道买价ID | | FactorValuesJson | JSON | - | - | 否 | 非客户因素组合 | | CalculationFormula | VARCHAR | 32 | - | 是 | 计算公式：总价/单价/续单价 | | CalculatedValue | DECIMAL | 18,4 | - | 否 | 计算值 | | CustomerGroupValues | JSON | - | - | 否 | 客户组对应价格 | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | #### 服务渠道发布记录表 `t_service_channel_publish_record`（子表，关联 t_service_channel） > 买价与规则的发布历史。 | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | ServiceChannelId | BIGINT | - | 外键 | 是 | 服务渠道ID | | Version | VARCHAR | 32 | - | 是 | 版本号 | | OperatorType | VARCHAR | 16 | - | 是 | 操作类型：price(价格)/rules(规则) | | Status | VARCHAR | 16 | - | 是 | 状态：生效/回滚/无效 | | PublishUser | VARCHAR | 64 | - | 是 | 发布人 | | PublishTime | DATETIME | - | - | 是 | 发布时间 | | Description | VARCHAR | 512 | - | 否 | 版本备注 | | Content | JSON | - | - | 否 | 发布内容JSON快照 | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | #### 分区表（黑名单区/偏远分区/价格分区共用）`t_kpi_area` > 三类分区共用本表，仅通过 `AreaType` 区分业务含义。 | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | AreaType | VARCHAR | 32 | - | 是 | 类型: blacklist/remote/price | | Name | VARCHAR | 128 | - | 是 | 分区名称 | | SystemName | VARCHAR | 128 | - | 否 | 系统名称 | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | **AreaType 枚举**：blacklist(黑名单区)、remote(偏远分区)、price(价格分区) #### 分区明细表 `t_kpi_area_info` | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | AreaId | BIGINT | - | 外键 | 是 | 分区ID | | CountryCode | VARCHAR | 8 | - | 否 | 国家二字码 | | CountryName | VARCHAR | 64 | - | 否 | 国家名称 | | Province | VARCHAR | 128 | - | 否 | 省份 | | City | VARCHAR | 128 | - | 否 | 城市 | | LeftPostcode | VARCHAR | 32 | - | 否 | 左侧邮编 | | RightPostcode | VARCHAR | 32 | - | 否 | 右侧邮编 | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | #### 计重规则表 `t_weight_rule` | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | Name | VARCHAR | 128 | - | 是 | 规则名称 | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | #### 计重规则明细表 `t_weight_rule_info`（子表，关联 t_weight_rule） > 计重规则子页面，配置客户组对应的计费规则（条件表达式、计费重取值、材积系数）。 | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | RuleId | BIGINT | - | 外键 | 是 | 计重规则ID | | Client | VARCHAR | 128 | - | 是 | 客户/客户组（如：公共、客户组1、客户组2） | | Condition | VARCHAR | 256 | - | 是 | 条件表达式（如：gw>vw） | | BillableWeight | VARCHAR | 64 | - | 是 | 计费重取值（如：vw、gw） | | VolumetricFactor | VARCHAR | 32 | - | 是 | 材积系数（如：6000） | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | #### 计重进位表 `t_weight_rounding` | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | Name | VARCHAR | 128 | - | 是 | 进位名称 | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | #### 计重进位明细表 `t_weight_rounding_info`（子表，关联 t_weight_rounding） > 计重进位子页面，配置重量区间的进位值（起始值、结束值、公共/客户组进位值）。 | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | RoundingId | BIGINT | - | 外键 | 是 | 计重进位ID | | StartValue | DECIMAL | 18,4 | - | 是 | 起始值(kg) | | EndValue | DECIMAL | 18,4 | - | 是 | 结束值(kg) | | Public | VARCHAR | 32 | - | 否 | 公共进位值 | | CustomerGroup1 | VARCHAR | 32 | - | 否 | 客户组1进位值 | | CustomerGroup2 | VARCHAR | 32 | - | 否 | 客户组2进位值 | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | #### 自动触发表 `t_auto_trigger` | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | Status | TINYINT | - | - | 是 | 是否启用 | | Operation | VARCHAR | 32 | - | 否 | 操作: 拦截/警告/问题件 | | TriggerTiming | VARCHAR | 32 | - | 否 | 触发时机: 下单/入库/出库 | | TriggerCondition | TEXT | - | - | 否 | 触发条件 | | PromptMessage | VARCHAR | 512 | - | 否 | 提示信息 | | Notifier | VARCHAR | 128 | - | 否 | 通知人 | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | #### 标签模板表 `t_label_template` | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | Name | VARCHAR | 128 | - | 是 | 模板名称 | | TemplateJson | JSON | - | - | 否 | vg-print 模板 JSON | | TemplateType | VARCHAR | 32 | - | 否 | 尾程/客户/入库/出库/sku | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | ### 2.3 核心接口设计 #### 销售产品 | 接口名称 | 请求方式 | 请求路径 | 说明 | | --- | --- | --- | --- | | 产品列表 | GET | /channel/sales-product/list | 产品列表 | | 产品详情 | GET | /channel/sales-product/detail | 产品详情 | | 新增产品 | POST | /channel/sales-product/create | 新增产品 | | 更新产品 | POST | /channel/sales-product/update | 更新产品（包含产品配置 tab 保存） | | 删除产品 | POST | /channel/sales-product/delete | 删除产品 | ##### 产品列表（GET /channel/sales-product/list） ###### 1 接口请求示例 **请求 /channel/sales-product/list**（GET，Query 参数） ``` ?page=1&pageSize=20&productGroup=专线&keyword=&isActive=1 ``` **响应** ```json { "code": 0, "msg": "success", "data": { "items": [ { "id": 1, "productCode": "US-AIR-P", "productName": "美国空运专线(普货)", "productGroup": "专线", "minTimeliness": 3, "maxTimeliness": 7, "customerWaybill": "系统面单", "blacklistAreaId": 1, "remoteAreaId": 2, "priceAreaId": 3, "weightRuleId": 1, "weightRoundingId": 1, "productDescription": "美国空运普货专线", "isActive": 1, "scheme": "costLowest", "createTime": "2024-01-01 12:00:00", "updateTime": "2024-01-01 12:00:00" } ], "total": 10 } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 接收分页与筛选参数后构建查询条件（productGroup、keyword、isActive）。 ####### 校验与异常 - 按分页参数查询销售产品列表，返回 `items` 与 `total`。 ##### 产品详情（GET /channel/sales-product/detail） ###### 1 接口请求示例 **请求 /channel/sales-product/detail**（GET，Query 参数） ``` ?id=1 ``` **响应** ```json { "code": 0, "msg": "success", "data": { "id": 1, "productCode": "US-AIR-P", "productName": "美国空运专线(普货)", "productGroup": "专线", "minTimeliness": 3, "maxTimeliness": 7, "customerWaybill": "系统面单", "blacklistAreaId": 1, "remoteAreaId": 2, "priceAreaId": 3, "weightRuleId": 1, "weightRoundingId": 1, "productDescription": "美国空运普货专线", "preStorageScript": "", "isActive": 1, "scheme": "costLowest", "createTime": "2024-01-01 12:00:00", "createBy": "admin", "updateTime": "2024-01-01 12:00:00", "updateBy": "admin" } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据 `id` 查询产品主数据及扩展配置，组装详情对象返回。 ####### 校验与异常 - 若产品不存在或不可访问，返回业务错误码。 ##### 新增产品（POST /channel/sales-product/create） ###### 1 接口请求示例 **请求 /channel/sales-product/create**（POST） ```json { "productCode": "US-AIR-P", "productName": "美国空运专线(普货)", "productGroup": "专线", "minTimeliness": 3, "maxTimeliness": 7, "customerWaybill": "系统面单", "blacklistAreaId": 1, "remoteAreaId": 2, "priceAreaId": 3, "weightRuleId": 1, "weightRoundingId": 1, "productDescription": "美国空运普货专线", "preStorageScript": "", "isActive": 1, "scheme": "costLowest" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 校验产品编码唯一性与必填字段后新增产品记录。 ####### 校验与异常 - 初始化产品配置与默认状态，写入审计字段。 ##### 更新产品（POST /channel/sales-product/update） ###### 1 接口请求示例 **请求 /channel/sales-product/update**（POST） ```json { "id": 1, "productCode": "US-AIR-P", "productName": "美国空运专线(普货)", "productGroup": "专线", "minTimeliness": 3, "maxTimeliness": 7, "customerWaybill": "系统面单", "blacklistAreaId": 1, "remoteAreaId": 2, "priceAreaId": 3, "weightRuleId": 1, "weightRoundingId": 1, "productDescription": "美国空运普货专线", "preStorageScript": "", "isActive": 1, "scheme": "costLowest" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据 `id` 校验产品存在性后更新可变字段（包含产品配置 tab 的保存内容）。 ####### 校验与异常 - 记录操作人和更新时间，并触发配置缓存刷新。 ##### 删除产品（POST /channel/sales-product/delete） ###### 1 接口请求示例 **请求 /channel/sales-product/delete**（POST） ```json { "id": 1 } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 校验产品是否可删除（无有效关联配置/任务）后执行逻辑删除。 ####### 校验与异常 - 更新删除标识及审计字段，避免物理删除带来的历史数据丢失。 #### 产品卖价（子表接口） | 接口名称 | 请求方式 | 请求路径 | 说明 | | --- | --- | --- | --- | | 价格项列表 | GET | /channel/sales-product/price/list | 按产品ID获取价格项列表 | | 新增价格项 | POST | /channel/sales-product/price/create | 新增价格项（含基础信息+计费因素+价格表） | | 更新价格项 | POST | /channel/sales-product/price/update | 更新价格项 | | 删除价格项 | POST | /channel/sales-product/price/delete | 删除价格项 | | 切换价格项状态 | POST | /channel/sales-product/price/toggleStatus | 启用/禁用价格项 | | 保存价格配置 | POST | /channel/sales-product/price/save | 批量保存产品卖价（保存并可选发布） | ##### 价格项列表（GET /channel/sales-product/price/list） ###### 1 接口请求示例 **请求 /channel/sales-product/price/list**（GET，Query 参数） ``` ?salesProductId=1 ``` **响应** ```json { "code": 0, "msg": "success", "data": { "items": [ { "id": 1, "salesProductId": 1, "serialNumber": 1, "status": 1, "priceName": "运费", "costItem": "freight", "costUnit": "kg", "currency": "RMB", "chargingTime": "出库", "chargingCondition": "", "factors": [ { "id": 1, "priceId": 1, "serialNumber": 1, "factor": "货物类型", "factorValues": ["普货", "敏感货"] } ], "details": [ { "id": 1, "priceId": 1, "factorValuesJson": {"分区": "欧洲", "货物类型": "普货", "重量": "0-0.5"}, "calculationFormula": "单价", "calculatedValue": 62, "customerGroupValues": {"客户组1": 60, "客户组2": 65} } ], "version": "20260425143000", "publishTime": "2026-04-25 14:30:00", "createTime": "2024-01-01 12:00:00", "updateTime": "2024-01-01 12:00:00" } ] } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按 `salesProductId` 查询价格项主表，并聚合返回计费因素与价格明细子数据。 - 结果按 `serialNumber` 升序组织，便于前端按配置顺序渲染。 ####### 校验与异常 - 校验 `salesProductId` 必填且产品存在；不存在时返回业务错误。 - 仅返回未删除记录，查询异常返回统一错误码。 ##### 新增价格项（POST /channel/sales-product/price/create） ###### 1 接口请求示例 **请求 /channel/sales-product/price/create**（POST） ```json { "salesProductId": 1, "serialNumber": 1, "status": 1, "priceName": "运费", "costItem": "freight", "costUnit": "kg", "currency": "RMB", "chargingTime": "出库", "chargingCondition": "", "factors": [ { "serialNumber": 1, "factor": "货物类型", "factorValues": ["普货", "敏感货"] }, { "serialNumber": 2, "factor": "分区", "factorValues": ["欧洲", "美国"] } ], "details": [ { "factorValuesJson": {"分区": "欧洲", "货物类型": "普货", "重量": "0-0.5"}, "calculationFormula": "单价", "calculatedValue": 62, "customerGroupValues": {"客户组1": 60, "客户组2": 65} } ] } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 新增价格项主记录，并写入对应 `factors` 与 `details` 子记录。 - 同步写入审计字段，保持主从数据一致性。 ####### 校验与异常 - 校验 `salesProductId`、`priceName`、`costItem`、`costUnit` 等必填字段。 - 校验同产品下 `serialNumber` 不冲突；冲突时返回业务错误。 ##### 更新价格项（POST /channel/sales-product/price/update） ###### 1 接口请求示例 **请求 /channel/sales-product/price/update**（POST） ```json { "id": 1, "salesProductId": 1, "serialNumber": 1, "status": 1, "priceName": "运费", "costItem": "freight", "costUnit": "kg", "currency": "RMB", "chargingTime": "出库", "chargingCondition": "", "factors": [], "details": [] } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按 `id` 更新价格项主数据，并按最新请求重建/同步因素与明细子数据。 - 保留版本追溯能力，更新后可参与后续发布流程。 ####### 校验与异常 - 校验 `id` 存在且归属 `salesProductId`。 - 校验更新后配置合法（计算公式、阶梯区间、客户组取值等），不合法时返回业务错误。 ##### 删除价格项（POST /channel/sales-product/price/delete） ###### 1 接口请求示例 **请求 /channel/sales-product/price/delete**（POST） ```json { "id": 1 } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按价格项 `id` 执行逻辑删除，并处理关联子表数据的可见性。 ####### 校验与异常 - 校验 `id` 存在且允许删除（如未处于不可删状态）。 - 删除失败返回统一业务错误码。 ##### 切换价格项状态（POST /channel/sales-product/price/toggleStatus） ###### 1 接口请求示例 **请求 /channel/sales-product/price/toggleStatus**（POST） ```json { "id": 1, "status": 0 } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按 `id` 更新价格项启用状态（`status`），并刷新相关缓存。 ####### 校验与异常 - 校验 `status` 仅允许合法枚举值（启用/禁用）。 - 校验 `id` 存在，不存在时返回业务错误。 ##### 保存价格配置（POST /channel/sales-product/price/save） ###### 1 接口请求示例 **请求 /channel/sales-product/price/save**（POST） ```json { "salesProductId": 1, "publish": false, "prices": [ { "id": 1, "serialNumber": 1, "status": 1, "priceName": "运费", "costItem": "freight", "costUnit": "kg", "currency": "RMB", "chargingTime": "出库", "chargingCondition": "", "factors": [], "details": [] } ] } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 批量保存 `prices`，按是否存在 `id` 自动分流新增/更新，并同步子项数据。 - 当 `publish=true` 时，保存完成后触发发布流程并生成版本记录。 ####### 校验与异常 - 校验 `salesProductId`、`prices` 必填且数据结构合法。 - 批量保存过程中任一子项失败则整体回滚，返回统一错误信息。 #### 排货规则（子表接口） | 接口名称 | 请求方式 | 请求路径 | 说明 | | --- | --- | --- | --- | | 获取排货规则 | GET | /channel/sales-product/allocation/get | 按产品ID获取排货方案及服务商列表 | | 保存排货规则 | POST | /channel/sales-product/allocation/save | 保存排货方案及服务商（保存并可选发布） | ##### 获取排货规则（GET /channel/sales-product/allocation/get） ###### 1 接口请求示例 **请求 /channel/sales-product/allocation/get**（GET，Query 参数） ``` ?salesProductId=1 ``` **响应** ```json { "code": 0, "msg": "success", "data": { "salesProductId": 1, "scheme": "costLowest", "providers": [ { "id": 1, "salesProductId": 1, "serialNumber": 1, "providerName": "一代物流", "serviceChannelId": 10, "serviceChannelName": "DHL美国专线", "weight": 100, "customerIds": [1, 2], "createTime": "2024-01-01 12:00:00", "updateTime": "2024-01-01 12:00:00" } ] } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据 `salesProductId` 查询排货方案与服务商列表并按顺序返回。 ####### 校验与异常 - 校验 `salesProductId` 必填且产品存在；不存在时返回业务错误。 ##### 保存排货规则（POST /channel/sales-product/allocation/save） ###### 1 接口请求示例 **请求 /channel/sales-product/allocation/save**（POST） ```json { "salesProductId": 1, "publish": false, "scheme": "costLowest", "providers": [ { "id": 0, "serialNumber": 1, "providerName": "一代物流", "serviceChannelId": 10, "weight": 100, "customerIds": [1, 2] } ] } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 保存排货策略与服务商配置，按 `id` 判定新增或更新。 - 当 `publish=true` 时触发规则发布并生成版本记录。 ####### 校验与异常 - 校验 `salesProductId`、`scheme` 与 `providers` 合法性。 - 保存失败回滚事务并返回统一错误信息。 #### 发布记录（子表接口） | 接口名称 | 请求方式 | 请求路径 | 说明 | | --- | --- | --- | --- | | 价格发布记录列表 | GET | /channel/sales-product/publish/price/list | 按产品ID获取价格发布历史 | | 规则发布记录列表 | GET | /channel/sales-product/publish/rules/list | 按产品ID获取规则发布历史 | | 发布 | POST | /channel/sales-product/publish | 发布当前配置（价格或规则） | | 回滚到版本 | POST | /channel/sales-product/publish/rollback | 回滚到指定版本 | ##### 价格发布记录列表（GET /channel/sales-product/publish/price/list） ###### 1 接口请求示例 **请求 /channel/sales-product/publish/price/list**（GET，Query 参数） ``` ?salesProductId=1&page=1&pageSize=20 ``` **响应** ```json { "code": 0, "msg": "success", "data": { "items": [ { "id": 1, "salesProductId": 1, "version": "20231227112339", "operatorType": "price", "status": "生效", "publishUser": "admin", "publishTime": "2023-12-27 11:23:39", "description": "价格调整", "content": {}, "createTime": "2023-12-27 11:23:39" } ], "total": 5 } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按产品ID分页查询价格类发布历史，返回版本与发布人信息。 ####### 校验与异常 - 校验 `salesProductId` 与分页参数合法性，异常时返回统一错误码。 ##### 规则发布记录列表（GET /channel/sales-product/publish/rules/list） ###### 1 接口请求示例 **请求 /channel/sales-product/publish/rules/list**（GET，Query 参数） ``` ?salesProductId=1&page=1&pageSize=20 ``` **响应** ```json { "code": 0, "msg": "success", "data": { "items": [ { "id": 2, "salesProductId": 1, "version": "20231228103000", "operatorType": "rules", "status": "生效", "publishUser": "admin", "publishTime": "2023-12-28 10:30:00", "description": "规则调整", "content": {}, "createTime": "2023-12-28 10:30:00" } ], "total": 3 } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按产品ID分页查询规则类发布历史，`operatorType` 固定为 `rules`。 ####### 校验与异常 - 校验 `salesProductId` 与分页参数合法性，异常时返回统一错误码。 ##### 发布（POST /channel/sales-product/publish） ###### 1 接口请求示例 **请求 /channel/sales-product/publish**（POST） ```json { "salesProductId": 1, "operatorType": "price", "description": "价格调整" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 将当前配置发布为新版本并写入发布记录。 ####### 校验与异常 - 校验 `salesProductId`、`operatorType` 必填且可发布。 ##### 回滚到版本（POST /channel/sales-product/publish/rollback） ###### 1 接口请求示例 **请求 /channel/sales-product/publish/rollback**（POST） ```json { "salesProductId": 1, "recordId": 1, "operatorType": "price" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 将配置回滚到指定发布版本并生成回滚记录。 ####### 校验与异常 - 校验 `recordId` 版本存在且与产品、类型一致，不一致时返回业务错误。 #### 服务渠道 | 接口名称 | 请求方式 | 请求路径 | 说明 | | --- | --- | --- | --- | | 渠道列表 | GET | /channel/service-channel/list | 渠道列表（含渠道组层级） | | 渠道详情 | GET | /channel/service-channel/detail | 渠道详情 | | 新增渠道 | POST | /channel/service-channel/create | 新增渠道 | | 更新渠道 | POST | /channel/service-channel/update | 更新渠道（包含渠道配置 tab 保存） | | 删除渠道 | POST | /channel/service-channel/delete | 删除渠道 | | 新增服务商 | POST | /channel/service-channel/group/create | 新增服务商分组（写入 `t_service_channel_group`，保存应用ID与API服务商ID） | | 编辑服务商 | POST | /channel/service-channel/group/update | 编辑服务商分组（更新名称/应用ID/API服务商ID） | | 删除服务商 | POST | /channel/service-channel/group/delete | 删除服务商分组（若分组下存在渠道需禁止删除） | ##### 渠道列表（GET /channel/service-channel/list） ###### 1 接口请求示例 **请求 /channel/service-channel/list**（GET，Query 参数） ``` ?page=1&pageSize=20&groupId=&keyword=&isActive=1 ``` **响应** ```json { "code": 0, "msg": "success", "data": { "items": [ { "id": 1, "groupId": 1, "groupName": "DHL渠道组", "channelCode": "DHL-US", "channelName": "DHL美国专线", "minTime": 3, "maxTime": 7, "forecastType": "waybill", "forecastCode": "", "description": "DHL美国专线渠道", "isActive": 1, "createTime": "2024-01-01 12:00:00", "updateTime": "2024-01-01 12:00:00" } ], "total": 10 } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按分页与筛选条件查询渠道列表，返回渠道及所属分组信息。 ####### 校验与异常 - 校验分页参数合法性，异常时返回统一错误码。 ##### 渠道详情（GET /channel/service-channel/detail） ###### 1 接口请求示例 **请求 /channel/service-channel/detail**（GET，Query 参数） ``` ?id=1 ``` **响应** ```json { "code": 0, "msg": "success", "data": { "id": 1, "groupId": 1, "groupName": "DHL渠道组", "channelCode": "DHL-US", "channelName": "DHL美国专线", "minTime": 3, "maxTime": 7, "forecastType": "waybill", "forecastCode": "", "description": "DHL美国专线渠道", "preScript": "", "isActive": 1, "createTime": "2024-01-01 12:00:00", "createBy": "admin", "updateTime": "2024-01-01 12:00:00", "updateBy": "admin" } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据渠道 `id` 查询渠道详情与配置信息。 ####### 校验与异常 - 校验 `id` 必填且存在，不存在时返回业务错误。 ##### 新增渠道（POST /channel/service-channel/create） ###### 1 接口请求示例 **请求 /channel/service-channel/create**（POST） ```json { "groupId": 1, "channelCode": "DHL-US", "channelName": "DHL美国专线", "minTime": 3, "maxTime": 7, "forecastType": "waybill", "forecastCode": "", "description": "DHL美国专线渠道", "preScript": "", "isActive": 1 } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 新增渠道基础配置并写入审计字段。 ####### 校验与异常 - 校验 `groupId`、`channelCode`、`channelName` 等必填字段，编码冲突时返回业务错误。 ##### 新增服务商（POST /channel/service-channel/group/create） ###### 1 接口请求示例 **请求 /channel/service-channel/group/create**（POST） ```json { "name": "DHL服务商", "appId": 1, "apiServiceProviderId": 12 } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 在 `t_service_channel_group` 新增服务商分组并写入应用ID与API服务商ID。 ####### 校验与异常 - 校验 `name`、`appId`、`apiServiceProviderId` 必填且有效。 ##### 编辑服务商（POST /channel/service-channel/group/update） ###### 1 接口请求示例 **请求 /channel/service-channel/group/update**（POST） ```json { "id": 1, "name": "DHL服务商(更新)", "appId": 1, "apiServiceProviderId": 12 } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据分组 `id` 更新服务商名称、应用ID与API服务商ID。 ####### 校验与异常 - 校验 `id` 存在且可编辑，不存在时返回业务错误。 ##### 删除服务商（POST /channel/service-channel/group/delete） ###### 1 接口请求示例 **请求 /channel/service-channel/group/delete**（POST） ```json { "id": 1 } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据分组 `id` 执行逻辑删除。 ####### 校验与异常 - 若分组下存在渠道则禁止删除并返回业务错误。 ##### 更新渠道（POST /channel/service-channel/update） ###### 1 接口请求示例 **请求 /channel/service-channel/update**（POST） ```json { "id": 1, "groupId": 1, "channelCode": "DHL-US", "channelName": "DHL美国专线", "minTime": 3, "maxTime": 7, "forecastType": "waybill", "forecastCode": "", "description": "DHL美国专线渠道", "preScript": "", "isActive": 1 } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据 `id` 更新渠道基础信息与渠道配置 tab 数据。 ####### 校验与异常 - 校验 `id` 存在及字段合法性，更新失败返回业务错误。 ##### 删除渠道（POST /channel/service-channel/delete） ###### 1 接口请求示例 **请求 /channel/service-channel/delete**（POST） ```json { "id": 1 } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 校验渠道是否可删除后执行逻辑删除并保留历史审计信息。 ####### 校验与异常 - 存在关联配置或不可删除状态时返回业务错误。 #### 渠道买价（子表接口） | 接口名称 | 请求方式 | 请求路径 | 说明 | | --- | --- | --- | --- | | 买价项列表 | GET | /channel/service-channel/price/list | 按渠道ID获取买价项列表 | | 新增买价项 | POST | /channel/service-channel/price/create | 新增买价项（含基础信息+计费因素+价格表） | | 更新买价项 | POST | /channel/service-channel/price/update | 更新买价项 | | 删除买价项 | POST | /channel/service-channel/price/delete | 删除买价项 | | 切换买价项状态 | POST | /channel/service-channel/price/toggleStatus | 启用/禁用买价项 | | 保存买价配置 | POST | /channel/service-channel/price/save | 批量保存渠道买价（保存并可选发布） | ##### 买价项列表（GET /channel/service-channel/price/list） ###### 1 接口请求示例 **请求 /channel/service-channel/price/list**（GET，Query 参数） ``` ?serviceChannelId=1 ``` **响应** ```json { "code": 0, "msg": "success", "data": { "items": [ { "id": 1, "serviceChannelId": 1, "serialNumber": 1, "status": 1, "priceName": "运费", "costItem": "freight", "costUnit": "kg", "currency": "RMB", "chargingTime": "出库", "chargingCondition": "", "factors": [], "details": [], "createTime": "2024-01-01 12:00:00", "updateTime": "2024-01-01 12:00:00" } ] } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按 `serviceChannelId` 查询买价项及其因素、明细子项。 ####### 校验与异常 - 校验 `serviceChannelId` 必填且渠道存在；异常返回统一错误码。 ##### 新增买价项（POST /channel/service-channel/price/create） ###### 1 接口请求示例 **请求 /channel/service-channel/price/create**（POST） ```json { "serviceChannelId": 1, "serialNumber": 1, "status": 1, "priceName": "运费", "costItem": "freight", "costUnit": "kg", "currency": "RMB", "chargingTime": "出库", "chargingCondition": "", "factors": [ { "serialNumber": 1, "factor": "货物类型", "factorValues": ["普货", "敏感货"] } ], "details": [ { "factorValuesJson": {"分区": "欧洲", "货物类型": "普货", "重量": "0-0.5"}, "calculationFormula": "单价", "calculatedValue": 45, "customerGroupValues": {} } ] } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 新增买价主记录并写入因素、明细子表。 ####### 校验与异常 - 校验必填参数与序号冲突规则，校验失败返回业务错误。 ##### 更新买价项（POST /channel/service-channel/price/update） ###### 1 接口请求示例 **请求 /channel/service-channel/price/update**（POST） ```json { "id": 1, "serviceChannelId": 1, "serialNumber": 1, "status": 1, "priceName": "运费", "costItem": "freight", "costUnit": "kg", "currency": "RMB", "chargingTime": "出库", "chargingCondition": "", "factors": [], "details": [] } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按 `id` 更新买价主数据并同步子项明细。 ####### 校验与异常 - 校验 `id` 存在且归属渠道一致，校验失败返回业务错误。 ##### 删除买价项（POST /channel/service-channel/price/delete） ###### 1 接口请求示例 **请求 /channel/service-channel/price/delete**（POST） ```json { "id": 1 } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据 `id` 逻辑删除买价项并处理关联子项可见性。 ####### 校验与异常 - 校验 `id` 存在且允许删除。 ##### 切换买价项状态（POST /channel/service-channel/price/toggleStatus） ###### 1 接口请求示例 **请求 /channel/service-channel/price/toggleStatus**（POST） ```json { "id": 1, "status": 0 } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按 `id` 更新买价项启用状态并刷新缓存。 ####### 校验与异常 - 校验 `status` 枚举与 `id` 存在性，不合法时返回业务错误。 ##### 保存买价配置（POST /channel/service-channel/price/save） ###### 1 接口请求示例 **请求 /channel/service-channel/price/save**（POST） ```json { "serviceChannelId": 1, "publish": false, "prices": [ { "id": 1, "serialNumber": 1, "status": 1, "priceName": "运费", "costItem": "freight", "costUnit": "kg", "currency": "RMB", "chargingTime": "出库", "chargingCondition": "", "factors": [], "details": [] } ] } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 批量保存买价配置，按 `id` 区分新增/更新；`publish=true` 时触发发布。 ####### 校验与异常 - 校验 `serviceChannelId`、`prices` 合法；任一子项失败则事务回滚。 #### 服务渠道发布记录（子表接口） | 接口名称 | 请求方式 | 请求路径 | 说明 | | --- | --- | --- | --- | | 价格发布记录列表 | GET | /channel/service-channel/publish/price/list | 按渠道ID获取买价发布历史 | | 规则发布记录列表 | GET | /channel/service-channel/publish/rules/list | 按渠道ID获取规则发布历史 | | 发布 | POST | /channel/service-channel/publish | 发布当前配置（买价或规则） | | 回滚到版本 | POST | /channel/service-channel/publish/rollback | 回滚到指定版本 | ##### 价格发布记录列表（GET /channel/service-channel/publish/price/list） ###### 1 接口请求示例 **请求 /channel/service-channel/publish/price/list**（GET，Query 参数） ``` ?serviceChannelId=1&page=1&pageSize=20 ``` **响应** ```json { "code": 0, "msg": "success", "data": { "items": [ { "id": 1, "serviceChannelId": 1, "version": "20231227112339", "operatorType": "price", "status": "生效", "publishUser": "admin", "publishTime": "2023-12-27 11:23:39", "description": "买价调整", "content": {}, "createTime": "2023-12-27 11:23:39" } ], "total": 5 } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按渠道ID分页查询买价发布记录并返回版本信息。 ####### 校验与异常 - 校验 `serviceChannelId` 与分页参数合法性。 ##### 规则发布记录列表（GET /channel/service-channel/publish/rules/list） ###### 1 接口请求示例 **请求 /channel/service-channel/publish/rules/list**（GET，Query 参数） ``` ?serviceChannelId=1&page=1&pageSize=20 ``` **响应** ```json { "code": 0, "msg": "success", "data": { "items": [ { "id": 2, "serviceChannelId": 1, "version": "20231228103000", "operatorType": "rules", "status": "生效", "publishUser": "admin", "publishTime": "2023-12-28 10:30:00", "description": "规则调整", "content": {}, "createTime": "2023-12-28 10:30:00" } ], "total": 3 } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按渠道ID分页查询规则发布记录，`operatorType` 固定为 `rules`。 ####### 校验与异常 - 校验 `serviceChannelId` 与分页参数合法性。 ##### 发布（POST /channel/service-channel/publish） ###### 1 接口请求示例 **请求 /channel/service-channel/publish**（POST） ```json { "serviceChannelId": 1, "operatorType": "price", "description": "买价调整" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 发布当前渠道配置并生成新的发布版本记录。 ####### 校验与异常 - 校验 `serviceChannelId`、`operatorType` 必填且可发布。 ##### 回滚到版本（POST /channel/service-channel/publish/rollback） ###### 1 接口请求示例 **请求 /channel/service-channel/publish/rollback**（POST） ```json { "serviceChannelId": 1, "recordId": 1, "operatorType": "price" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 回滚到指定版本并生成回滚操作记录。 ####### 校验与异常 - 校验 `recordId` 与渠道、类型匹配关系，异常时返回业务错误。 #### 黑名单区 / 偏远分区 / 价格分区（共用 KpiArea） > 共用 `/channel/kpi-area/*` 接口，仅通过请求/响应中的 `areaType`（对应表字段 `AreaType`）区分分区类型。 | 类型 | areaType | | --- | --- | | 黑名单区 | blacklist | | 偏远分区 | remote | | 价格分区 | price | | 接口名称 | 请求方式 | 请求路径 | 说明 | | --- | --- | --- | --- | | 创建分区 | POST | /channel/kpi-area/create | 创建分区 | | 修改分区 | POST | /channel/kpi-area/update | 修改分区 | | 删除分区 | POST | /channel/kpi-area/delete | 删除分区 | | 分区列表 | POST | /channel/kpi-area/list | 分区列表 | | 新增分区明细 | POST | /channel/kpi-area/info/add | 新增分区明细 | | 修改分区明细 | POST | /channel/kpi-area/info/update | 修改分区明细 | | 删除分区明细 | POST | /channel/kpi-area/info/delete | 删除分区明细 | | 分区明细列表 | POST | /channel/kpi-area/info/list | 分区明细列表 | ##### 创建分区（POST /channel/kpi-area/create） ###### 1 接口请求示例 **请求 /channel/kpi-area/create**（POST） ```json { "areaType": "blacklist", "name": "黑名单区1", "systemName": "系统黑名单" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据 `areaType` 创建分区主记录。 ####### 校验与异常 - 校验 `areaType`、`name` 必填且合法。 ##### 修改分区（POST /channel/kpi-area/update） ###### 1 接口请求示例 **请求 /channel/kpi-area/update**（POST） ```json { "id": 1, "areaType": "blacklist", "name": "黑名单区1", "systemName": "系统黑名单" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据 `id` 更新分区名称与系统名称。 ####### 校验与异常 - 校验 `id` 存在且与 `areaType` 匹配。 ##### 删除分区（POST /channel/kpi-area/delete） ###### 1 接口请求示例 **请求 /channel/kpi-area/delete**（POST） ```json { "id": 1 } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据 `id` 执行分区逻辑删除。 ####### 校验与异常 - 分区存在明细时按业务规则拦截或级联处理。 ##### 分区列表（POST /channel/kpi-area/list） ###### 1 接口请求示例 **请求 /channel/kpi-area/list**（POST） ```json { "areaType": "blacklist", "page": 1, "pageSize": 20 } ``` **响应** ```json { "code": 0, "msg": "success", "data": { "items": [ { "id": 1, "areaType": "blacklist", "name": "黑名单区1", "systemName": "系统黑名单", "createTime": "2024-01-01 12:00:00", "updateTime": "2024-01-01 12:00:00" } ], "total": 5 } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按 `areaType` 分页查询分区列表。 ####### 校验与异常 - 校验分页参数与 `areaType` 合法性。 ##### 新增分区明细（POST /channel/kpi-area/info/add） ###### 1 接口请求示例 **请求 /channel/kpi-area/info/add**（POST） ```json { "areaId": 1, "countryCode": "US", "countryName": "美国", "province": "加州", "city": "洛杉矶", "leftPostcode": "90001", "rightPostcode": "90099" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 向指定分区新增明细记录（国家/省市/邮编区间）。 ####### 校验与异常 - 校验 `areaId` 存在且区间数据合法。 ##### 修改分区明细（POST /channel/kpi-area/info/update） ###### 1 接口请求示例 **请求 /channel/kpi-area/info/update**（POST） ```json { "id": 1, "areaId": 1, "countryCode": "US", "countryName": "美国", "province": "加州", "city": "洛杉矶", "leftPostcode": "90001", "rightPostcode": "90099" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据明细 `id` 更新分区明细字段。 ####### 校验与异常 - 校验 `id` 存在，更新内容合法。 ##### 删除分区明细（POST /channel/kpi-area/info/delete） ###### 1 接口请求示例 **请求 /channel/kpi-area/info/delete**（POST） ```json { "id": 1 } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据明细 `id` 执行逻辑删除。 ####### 校验与异常 - 校验 `id` 存在，不存在时返回业务错误。 ##### 分区明细列表（POST /channel/kpi-area/info/list） ###### 1 接口请求示例 **请求 /channel/kpi-area/info/list**（POST） ```json { "areaId": 1, "page": 1, "pageSize": 20 } ``` **响应** ```json { "code": 0, "msg": "success", "data": { "items": [ { "id": 1, "areaId": 1, "countryCode": "US", "countryName": "美国", "province": "加州", "city": "洛杉矶", "leftPostcode": "90001", "rightPostcode": "90099", "createTime": "2024-01-01 12:00:00", "updateTime": "2024-01-01 12:00:00" } ], "total": 10 } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按 `areaId` 分页查询分区明细列表。 ####### 校验与异常 - 校验 `areaId` 与分页参数合法性。 #### 计重规则 / 计重进位 | 接口名称 | 请求方式 | 请求路径 | 说明 | | --- | --- | --- | --- | | 规则列表 | POST | /channel/weight-rule/list | 规则列表 | | 创建规则 | POST | /channel/weight-rule/create | 创建规则 | | 更新规则 | POST | /channel/weight-rule/update | 更新规则 | | 删除规则 | POST | /channel/weight-rule/delete | 删除规则 | | 规则明细列表 | POST | /channel/weight-rule/info/list | 规则明细列表 | | 新增明细 | POST | /channel/weight-rule/info/add | 新增明细 | | 更新明细 | POST | /channel/weight-rule/info/update | 更新明细 | | 删除明细 | POST | /channel/weight-rule/info/delete | 删除明细 | | 进位列表 | POST | /channel/weight-rounding/list | 进位列表 | | 创建进位 | POST | /channel/weight-rounding/create | 创建进位 | | 更新进位 | POST | /channel/weight-rounding/update | 更新进位 | | 删除进位 | POST | /channel/weight-rounding/delete | 删除进位 | | 进位明细列表 | POST | /channel/weight-rounding/info/list | 进位明细列表 | | 新增进位明细 | POST | /channel/weight-rounding/info/add | 新增进位明细 | | 更新进位明细 | POST | /channel/weight-rounding/info/update | 更新进位明细 | | 删除进位明细 | POST | /channel/weight-rounding/info/delete | 删除进位明细 | ##### 规则列表（POST /channel/weight-rule/list） ###### 1 接口请求示例 **请求 /channel/weight-rule/list**（POST） ```json { "page": 1, "pageSize": 20 } ``` **响应** ```json { "code": 0, "msg": "success", "data": { "items": [{ "id": 1, "name": "标准计重规则" }], "total": 5 } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 分页查询计重规则主表。 ####### 校验与异常 - 校验分页参数合法性。 ##### 创建规则（POST /channel/weight-rule/create） ###### 1 接口请求示例 **请求 /channel/weight-rule/create**（POST） ```json { "name": "标准计重规则" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 新增计重规则并写入审计信息。 ####### 校验与异常 - 校验 `name` 必填且不重复。 ##### 更新规则（POST /channel/weight-rule/update） ###### 1 接口请求示例 **请求 /channel/weight-rule/update**（POST） ```json { "id": 1, "name": "标准计重规则" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据 `id` 更新规则信息。 ####### 校验与异常 - 校验 `id` 存在。 ##### 删除规则（POST /channel/weight-rule/delete） ###### 1 接口请求示例 **请求 /channel/weight-rule/delete**（POST） ```json { "id": 1 } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 对规则执行逻辑删除。 ####### 校验与异常 - 校验是否存在关联明细。 ##### 规则明细列表（POST /channel/weight-rule/info/list） ###### 1 接口请求示例 **请求 /channel/weight-rule/info/list**（POST） ```json { "ruleId": 1, "page": 1, "pageSize": 20 } ``` **响应** ```json { "code": 0, "msg": "success", "data": { "items": [{ "id": 1, "ruleId": 1, "client": "公共" }], "total": 3 } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按 `ruleId` 分页查询规则明细。 ####### 校验与异常 - 校验 `ruleId` 必填且有效。 ##### 新增明细（POST /channel/weight-rule/info/add） ###### 1 接口请求示例 **请求 /channel/weight-rule/info/add**（POST） ```json { "ruleId": 1, "client": "公共", "condition": "gw>vw", "billableWeight": "vw", "volumetricFactor": "6000" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 新增规则明细。 ####### 校验与异常 - 校验 `ruleId` 与字段合法性。 ##### 更新明细（POST /channel/weight-rule/info/update） ###### 1 接口请求示例 **请求 /channel/weight-rule/info/update**（POST） ```json { "id": 1, "ruleId": 1, "client": "公共", "condition": "gw>vw", "billableWeight": "vw", "volumetricFactor": "6000" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据 `id` 更新规则明细。 ####### 校验与异常 - 校验 `id` 存在且归属正确。 ##### 删除明细（POST /channel/weight-rule/info/delete） ###### 1 接口请求示例 **请求 /channel/weight-rule/info/delete**（POST） ```json { "id": 1 } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 删除规则明细（逻辑删除）。 ####### 校验与异常 - 校验 `id` 存在。 ##### 进位列表（POST /channel/weight-rounding/list） ###### 1 接口请求示例 **请求 /channel/weight-rounding/list**（POST） ```json { "page": 1, "pageSize": 20 } ``` **响应** ```json { "code": 0, "msg": "success", "data": { "items": [{ "id": 1, "name": "标准进位" }], "total": 5 } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 分页查询计重进位主表。 ####### 校验与异常 - 校验分页参数。 ##### 创建进位（POST /channel/weight-rounding/create） ###### 1 接口请求示例 **请求 /channel/weight-rounding/create**（POST） ```json { "name": "标准进位" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 新增进位规则。 ####### 校验与异常 - 校验 `name` 必填。 ##### 更新进位（POST /channel/weight-rounding/update） ###### 1 接口请求示例 **请求 /channel/weight-rounding/update**（POST） ```json { "id": 1, "name": "标准进位" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据 `id` 更新进位规则。 ####### 校验与异常 - 校验 `id` 存在。 ##### 删除进位（POST /channel/weight-rounding/delete） ###### 1 接口请求示例 **请求 /channel/weight-rounding/delete**（POST） ```json { "id": 1 } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 逻辑删除进位规则。 ####### 校验与异常 - 校验是否可删除。 ##### 进位明细列表（POST /channel/weight-rounding/info/list） ###### 1 接口请求示例 **请求 /channel/weight-rounding/info/list**（POST） ```json { "roundingId": 1, "page": 1, "pageSize": 20 } ``` **响应** ```json { "code": 0, "msg": "success", "data": { "items": [{ "id": 1, "roundingId": 1, "startValue": 0, "endValue": 1 }], "total": 5 } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按 `roundingId` 分页查询进位明细。 ####### 校验与异常 - 校验 `roundingId` 存在。 ##### 新增进位明细（POST /channel/weight-rounding/info/add） ###### 1 接口请求示例 **请求 /channel/weight-rounding/info/add**（POST） ```json { "roundingId": 1, "startValue": 0, "endValue": 1, "public": "0.5", "customerGroup1": "0.5", "customerGroup2": "0.25" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 新增进位明细。 ####### 校验与异常 - 校验区间与分组字段合法性。 ##### 更新进位明细（POST /channel/weight-rounding/info/update） ###### 1 接口请求示例 **请求 /channel/weight-rounding/info/update**（POST） ```json { "id": 1, "roundingId": 1, "startValue": 0, "endValue": 1, "public": "0.5", "customerGroup1": "0.5", "customerGroup2": "0.25" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据 `id` 更新进位明细。 ####### 校验与异常 - 校验 `id` 存在且归属正确。 ##### 删除进位明细（POST /channel/weight-rounding/info/delete） ###### 1 接口请求示例 **请求 /channel/weight-rounding/info/delete**（POST） ```json { "id": 1 } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 删除进位明细（逻辑删除）。 ####### 校验与异常 - 校验 `id` 存在。 #### 自动触发 | 接口名称 | 请求方式 | 请求路径 | 说明 | | --- | --- | --- | --- | | 列表 | GET | /channel/auto-trigger/list | 列表 | | 新增 | POST | /channel/auto-trigger/create | 新增 | | 更新 | POST | /channel/auto-trigger/update | 更新 | | 删除 | POST | /channel/auto-trigger/delete | 删除 | | 切换启用状态 | POST | /channel/auto-trigger/toggleStatus | 切换启用状态 | ##### 列表（GET /channel/auto-trigger/list） ###### 1 接口请求示例 **请求 /channel/auto-trigger/list**（GET，Query 参数） ``` ?page=1&pageSize=20&operation=&triggerTiming= ``` **响应** ```json { "code": 0, "msg": "success", "data": { "items": [{ "id": 1, "operation": "拦截", "triggerTiming": "下单" }], "total": 5 } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 分页查询自动触发规则列表。 ####### 校验与异常 - 校验分页与筛选参数合法。 ##### 新增（POST /channel/auto-trigger/create） ###### 1 接口请求示例 **请求 /channel/auto-trigger/create**（POST） ```json { "status": 1, "operation": "拦截", "triggerTiming": "下单", "triggerCondition": "weight>30", "promptMessage": "重量超过30kg，请确认", "notifier": "admin@example.com" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 新增自动触发规则。 ####### 校验与异常 - 校验关键字段必填。 ##### 更新（POST /channel/auto-trigger/update） ###### 1 接口请求示例 **请求 /channel/auto-trigger/update**（POST） ```json { "id": 1, "status": 1, "operation": "拦截", "triggerTiming": "下单", "triggerCondition": "weight>30", "promptMessage": "重量超过30kg，请确认", "notifier": "admin@example.com" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据 `id` 更新自动触发规则。 ####### 校验与异常 - 校验 `id` 存在且可编辑。 ##### 删除（POST /channel/auto-trigger/delete） ###### 1 接口请求示例 **请求 /channel/auto-trigger/delete**（POST） ```json { "id": 1 } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 逻辑删除自动触发规则。 ####### 校验与异常 - 校验 `id` 存在且可删除。 ##### 切换启用状态（POST /channel/auto-trigger/toggleStatus） ###### 1 接口请求示例 **请求 /channel/auto-trigger/toggleStatus**（POST） ```json { "id": 1, "status": 0 } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按 `id` 切换规则启用状态。 ####### 校验与异常 - 校验 `status` 枚举合法性。 #### 标签设计 | 接口名称 | 请求方式 | 请求路径 | 说明 | | --- | --- | --- | --- | | 保存标签模板 | POST | /channel/label-template/save | 保存标签模板 | ###### 1 接口请求示例 **请求 /channel/label-template/save**（POST） ```json { "id": 0, "name": "尾程标签模板1", "templateType": "lastMile", "templateJson": {} } ``` > 参数说明：`id` 模板ID，0为新增；`templateType` 类型：lastMile(尾程)/customer(客户)/inbound(入库)/outbound(出库)/sku；`templateJson` vg-print 导出的模板 JSON。 **响应** ```json { "code": 0, "msg": "success", "data": { "id": 1, "name": "尾程标签模板1", "templateType": "lastMile", "templateJson": {}, "createTime": "2024-01-01 12:00:00", "updateTime": "2024-01-01 12:00:00" } } ``` ---------------------------------------------------------------------------------------- ---------------------------------------------------------------------------------------- ###### 2 接口业务逻辑 ####### 核心流程 - 按本节接口定义执行业务处理流程，完成参数解析、数据查询/写入与结果返回。 ####### 校验与异常 - 对必填参数、状态流转与数据存在性进行校验；异常场景返回统一错误码与错误信息。 ## 四、操作模块 ### 3.1 核心需求说明 - **入库扫描**：扫描运单号完成入库，记录实重、尺寸、销售产品、目的国、仓库、操作人、操作时间；支持查看最近入库记录。 - **出库扫描**：扫描运单号完成出库，记录仓库、操作人、操作时间；支持查看最近出库记录。 - **标签打印**：按运单号/客户单号/跟踪号/其他单号选择标签模板打印；记录打印结果与操作人。 ### 3.2 表结构设计 #### 入库记录表 `t_inbound_record` | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | WaybillNo | VARCHAR | 64 | - | 是 | 运单号 | | Weight | DECIMAL | 10,2 | - | 否 | 实重(kg) | | Length | DECIMAL | 10,2 | - | 否 | 长(cm) | | Width | DECIMAL | 10,2 | - | 否 | 宽(cm) | | Height | DECIMAL | 10,2 | - | 否 | 高(cm) | | SalesProductId | BIGINT | - | 外键 | 否 | 销售产品ID | | DestinationCountry | VARCHAR | 8 | - | 否 | 目的国 | | WarehouseId | BIGINT | - | 外键 | 否 | 仓库ID | | OperateTime | DATETIME | - | - | 是 | 操作时间 | | OperatorId | BIGINT | - | 外键 | 否 | 操作人ID | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | #### 出库记录表 `t_outbound_record` | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | WaybillNo | VARCHAR | 64 | - | 是 | 运单号 | | WarehouseId | BIGINT | - | 外键 | 否 | 仓库ID | | OperateTime | DATETIME | - | - | 是 | 操作时间 | | OperatorId | BIGINT | - | 外键 | 否 | 操作人ID | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | #### 标签打印记录表 `t_label_print_record` | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | WaybillNo | VARCHAR | 64 | - | 是 | 运单号 | | CustomerOrderNo | VARCHAR | 64 | - | 否 | 客户单号 | | TrackingNo | VARCHAR | 64 | - | 否 | 跟踪号 | | OtherNumber | VARCHAR | 64 | - | 否 | 其他单号 | | LabelTemplateId | BIGINT | - | 外键 | 否 | 标签模板ID | | PrintSuccess | TINYINT | - | - | 是 | 是否打印成功 | | PrintTime | DATETIME | - | - | 是 | 打印时间 | | OperatorId | BIGINT | - | 外键 | 否 | 操作人ID | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | ### 3.3 核心接口设计 #### 入库扫描 | 接口名称 | 请求方式 | 请求路径 | 说明 | | --- | --- | --- | --- | | 入库 | POST | /operation/inbound/create | 入库 | | 最近入库记录 | GET | /operation/inbound/recent-list | 最近入库记录 | ##### 入库（POST /operation/inbound/create） ###### 1 接口请求示例 **请求 /operation/inbound/create**（POST） ```json { "waybillNo": "LP1234567890", "weight": 2.5, "length": 20, "width": 15, "height": 10, "salesProductId": 1, "destinationCountry": "US", "warehouseId": 1 } ``` > 参数说明：`waybillNo` 运单号；`weight` 实重(kg)；`length/width/height` 长宽高(cm)；`salesProductId` 销售产品ID；`destinationCountry` 目的国二字码；`warehouseId` 仓库ID。操作时间、操作人由服务端从当前会话获取。 **响应** ```json { "code": 0, "msg": "success", "data": { "id": 1, "waybillNo": "LP1234567890", "weight": 2.5, "length": 20, "width": 15, "height": 10, "salesProductId": 1, "destinationCountry": "US", "warehouseId": 1, "operateTime": "2024-01-01 12:00:00", "operatorId": 1, "createTime": "2024-01-01 12:00:00" } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。 ####### 校验与异常 - 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。 ##### 最近入库记录（GET /operation/inbound/recent-list） ###### 1 接口请求示例 **请求 /operation/inbound/recent-list**（GET，Query 参数） ``` ?limit=20&warehouseId= ``` **响应** ```json { "code": 0, "msg": "success", "data": { "items": [ { "id": 1, "waybillNo": "LP1234567890", "weight": 2.5, "length": 20, "width": 15, "height": 10, "salesProductId": 1, "salesProductName": "美国空运专线(普货)", "destinationCountry": "US", "warehouseId": 1, "warehouseName": "深圳仓", "operateTime": "2024-01-01 12:00:00", "operatorId": 1, "operatorName": "张三", "createTime": "2024-01-01 12:00:00" } ] } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。 ####### 校验与异常 - 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。 #### 出库扫描 | 接口名称 | 请求方式 | 请求路径 | 说明 | | --- | --- | --- | --- | | 出库 | POST | /operation/outbound/create | 出库 | | 最近出库记录 | GET | /operation/outbound/recent-list | 最近出库记录 | ##### 出库（POST /operation/outbound/create） ###### 1 接口请求示例 **请求 /operation/outbound/create**（POST） ```json { "waybillNo": "LP1234567890", "warehouseId": 1 } ``` > 参数说明：`waybillNo` 运单号；`warehouseId` 仓库ID（可选，不传则从订单或默认仓库获取）。操作时间、操作人由服务端从当前会话获取。 **响应** ```json { "code": 0, "msg": "success", "data": { "id": 1, "waybillNo": "LP1234567890", "warehouseId": 1, "operateTime": "2024-01-01 12:00:00", "operatorId": 1, "createTime": "2024-01-01 12:00:00" } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。 ####### 校验与异常 - 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。 ##### 最近出库记录（GET /operation/outbound/recent-list） ###### 1 接口请求示例 **请求 /operation/outbound/recent-list**（GET，Query 参数） ``` ?limit=20&warehouseId= ``` **响应** ```json { "code": 0, "msg": "success", "data": { "items": [ { "id": 1, "waybillNo": "LP1234567890", "warehouseId": 1, "warehouseName": "深圳仓", "operateTime": "2024-01-01 12:00:00", "operatorId": 1, "operatorName": "张三", "createTime": "2024-01-01 12:00:00" } ] } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。 ####### 校验与异常 - 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。 #### 标签打印 | 接口名称 | 请求方式 | 请求路径 | 说明 | | --- | --- | --- | --- | | 打印标签 | POST | /operation/print-label/print | 打印标签 | | 最近打印记录 | GET | /operation/print-label/recent-list | 最近打印记录 | | 标签模板列表 | GET | /operation/print-label/template-list | 标签模板列表 | ##### 打印标签（POST /operation/print-label/print） ###### 1 接口请求示例 **请求 /operation/print-label/print**（POST） ```json { "number": "LP1234567890", "numberType": "waybill", "labelTemplateId": 1 } ``` > 参数说明：`number` 运单号/客户单号/跟踪号/其他单号；`numberType` 单号类型：waybill(运单号)/customerOrder(客户单号)/tracking(跟踪号)/other(其他单号)；`labelTemplateId` 标签模板ID，可选，不传则按 templateType 取默认模板。也可传 `templateType`：lastMile(尾程)/customer(客户)/inbound(入库)/outbound(出库)/sku。 **响应** ```json { "code": 0, "msg": "success", "data": { "id": 1, "waybillNo": "LP1234567890", "customerOrderNo": "", "trackingNo": "", "otherNumber": "", "labelTemplateId": 1, "labelTemplateName": "尾程标签模板1", "printSuccess": 1, "printTime": "2024-01-01 12:00:00", "operatorId": 1, "createTime": "2024-01-01 12:00:00" } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。 ####### 校验与异常 - 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。 ##### 最近打印记录（GET /operation/print-label/recent-list） ###### 1 接口请求示例 **请求 /operation/print-label/recent-list**（GET，Query 参数） ``` ?limit=20&labelTemplateId= ``` **响应** ```json { "code": 0, "msg": "success", "data": { "items": [ { "id": 1, "waybillNo": "LP1234567890", "customerOrderNo": "CUST001", "trackingNo": "TRK001", "otherNumber": "", "labelTemplateId": 1, "labelTemplateName": "尾程标签模板1", "printSuccess": 1, "printTime": "2024-01-01 12:00:00", "operatorId": 1, "operatorName": "张三", "createTime": "2024-01-01 12:00:00" } ] } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。 ####### 校验与异常 - 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。 ##### 标签模板列表（GET /operation/print-label/template-list） ###### 1 接口请求示例 **请求 /operation/print-label/template-list**（GET，Query 参数） ``` ?templateType=lastMile ``` > 参数说明：`templateType` 可选，筛选模板类型：lastMile/customer/inbound/outbound/sku。不传则返回全部可用模板。 **响应** ```json { "code": 0, "msg": "success", "data": { "items": [ { "id": 1, "name": "尾程标签模板1", "templateType": "lastMile", "templateJson": {}, "createTime": "2024-01-01 12:00:00", "updateTime": "2024-01-01 12:00:00" } ] } } ``` ---------------------------------------------------------------------------------------- ---------------------------------------------------------------------------------------- ###### 2 接口业务逻辑 ####### 核心流程 - 按接口定义执行业务流程，完成参数解析、数据处理与结果返回。 ####### 校验与异常 - 对必填参数、状态与数据存在性进行校验，异常场景返回统一错误码与错误信息。 ## 五、客户模块 ### 4.1 核心需求说明 - **客户管理**：客户信息的增删改查，支持客户编号、手机、邮箱、余额、额度、状态等管理；支持重置密码；已有 customer API。 - **子账号**：主客户可创建子账号，子账号共享主客户余额与额度，独立登录与权限。 ### 4.2 表结构设计 #### 客户表 `t_customer` > 已有 customer API，表结构参考 CustomerDto。 | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | CustomerCode | VARCHAR | 32 | - | 是 | 客户编号，规则：前缀w+年份+序号（如W2501） | | CustomerName | VARCHAR | 128 | - | 是 | 客户名称 | | WechatAvatar | VARCHAR | 255 | - | 否 | 微信头像URL | | WechatNickname | VARCHAR | 64 | - | 否 | 微信昵称 | | Email | VARCHAR | 64 | - | 否 | 邮箱，唯一，用于登录/找回密码 | | Phone | VARCHAR | 16 | - | 是 | 手机号，唯一，用于登录/验证 | | Balance | DECIMAL | 18,2 | - | 是 | 账户余额，默认0 | | TotalQuota | DECIMAL | 18,2 | - | 是 | 总额度，默认0 | | UsedQuota | DECIMAL | 18,2 | - | 是 | 已用额度，默认0 | | Status | TINYINT | - | - | 是 | 状态：0-禁用，1-正常，2-冻结 | | Remark | VARCHAR | 512 | - | 否 | 备注信息 | | CreateUserId | INT | - | - | 是 | 创建人（系统/管理员账号） | | CreateTime | DATETIME | - | - | 是 | 创建时间，默认当前时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | | Salesman | VARCHAR | 32 | - | 否 | 所属销售员账号 | | CustomerService | VARCHAR | 32 | - | 否 | 所属客服账号 | | CustomerGroup | TINYINT | - | - | 否 | 客户分组：0-普通客户，1-VIP1，2-VIP2，3-VIP3，4-VIP4，5-VIP5 | | Role | VARCHAR | 64 | - | 否 | 角色，用于菜单权限 | | LastLoginIp | VARCHAR | 64 | - | 否 | 最后在线IP | | LastLoginTime | DATETIME | - | - | 否 | 最后在线时间 | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | WechatOpenid | VARCHAR | 64 | - | 否 | 微信OpenID，唯一，关联微信账号 | | Password | VARCHAR | 64 | - | 是 | 密码（MD5加密存储） | **CustomerGroup 枚举**：0-普通客户、1-VIP1、2-VIP2、3-VIP3、4-VIP4、5-VIP5 #### 子账号表 `t_customer_sub_account` | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | MainCustomerId | BIGINT | - | 外键（t_customer.Id） | 是 | 主客户ID | | SubAccountCode | VARCHAR | 32 | - | 是 | 子账号编号，规则：主客户编号+"_"+序号 | | SubWechatAvatar | VARCHAR | 255 | - | 否 | 子账号微信头像 | | SubWechatNickname | VARCHAR | 64 | - | 否 | 子账号微信昵称 | | SubPhone | VARCHAR | 16 | - | 是 | 子账号手机号，唯一 | | SubEmail | VARCHAR | 64 | - | 否 | 子账号邮箱 | | SubPassword | VARCHAR | 64 | - | 是 | 子账号密码（MD5加密） | | SubStatus | TINYINT | - | - | 是 | 子账号状态：0-禁用，1-正常 | | CreateUserId | INT | - | - | 是 | 创建人（主客户/管理员） | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是 | ### 4.3 核心接口设计 | 接口名称 | 请求方式 | 请求路径 | 说明 | | --- | --- | --- | --- | | 客户列表 | GET | /customer/list | 客户列表 | | 客户详情 | GET | /customer/get | 客户详情 | | 创建客户 | POST | /customer/create | 创建客户 | | 更新客户 | POST | /customer/update | 更新客户 | | 删除客户 | POST | /customer/delete | 删除客户 | | 重置密码 | POST | /customer/reset-password | 重置密码 | > 个人中心可复用 `/customer/get`，传入当前登录客户 ID。 ##### 客户列表（GET /customer/list） ###### 1 接口请求示例 **请求 /customer/list**（GET，Query 参数） ``` ?page=1&pageSize=20&keyword=&status=1&customerGroup=&salesman=&customerService= ``` **响应** ```json { "code": 0, "msg": "success", "data": { "items": [ { "id": 1, "customerCode": "W2501", "wechatAvatar": "", "wechatNickname": "", "email": "customer@example.com", "phone": "13800138000", "balance": 1000.00, "totalQuota": 5000.00, "usedQuota": 500.00, "status": 1, "remark": "", "salesman": "sales1", "customerService": "cs1", "customerGroup": 1, "lastLoginIp": "192.168.1.1", "lastLoginTime": "2024-01-01 12:00:00", "createTime": "2024-01-01 12:00:00", "updateTime": "2024-01-01 12:00:00" } ], "total": 50 } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据筛选参数分页查询客户列表，返回客户基础信息、状态与余额额度信息。 ####### 校验与异常 - 校验分页参数合法性；当筛选条件无匹配数据时返回空列表与 total=0。 ##### 客户详情（GET /customer/get） ###### 1 接口请求示例 **请求 /customer/get**（GET，Query 参数） ``` ?id=1 ``` **响应** ```json { "code": 0, "msg": "success", "data": { "id": 1, "customerCode": "W2501", "wechatAvatar": "", "wechatNickname": "", "email": "customer@example.com", "phone": "13800138000", "balance": 1000.00, "totalQuota": 5000.00, "usedQuota": 500.00, "status": 1, "remark": "", "salesman": "sales1", "customerService": "cs1", "customerGroup": 1, "lastLoginIp": "192.168.1.1", "lastLoginTime": "2024-01-01 12:00:00", "createTime": "2024-01-01 12:00:00", "createBy": "admin", "updateTime": "2024-01-01 12:00:00", "updateBy": "admin" } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按客户 ID 查询客户详情，返回完整客户资料与审计字段。 ####### 校验与异常 - 校验 `id` 必填且存在；不存在时返回业务错误码。 ##### 创建客户（POST /customer/create） ###### 1 接口请求示例 **请求 /customer/create**（POST） ```json { "customerCode": "W2501", "customerName": "张三客户", "wechatAvatar": "https://cdn.example.com/avatar/w2501.png", "wechatNickname": "张三", "phone": "13800138000", "email": "customer@example.com", "password": "123456", "balance": 1000.00, "totalQuota": 5000.00, "usedQuota": 500.00, "status": 1, "role": "customer", "remark": "", "salesman": "sales1", "customerService": "cs1", "customerGroup": 1 } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 新增客户账号并写入客户基础资料（客户编号/名称、微信信息、联系方式）、余额额度、角色与业务归属信息。 ####### 校验与异常 - 校验手机号/邮箱唯一性与必填字段，冲突时返回业务错误。 ##### 更新客户（POST /customer/update） ###### 1 接口请求示例 **请求 /customer/update**（POST） ```json { "id": 1, "customerCode": "W2501", "customerName": "张三客户", "wechatAvatar": "https://cdn.example.com/avatar/w2501.png", "wechatNickname": "张三", "phone": "13800138000", "email": "customer@example.com", "balance": 1000.00, "totalQuota": 5000.00, "usedQuota": 500.00, "status": 1, "role": "customer", "remark": "", "salesman": "sales1", "customerService": "cs1", "customerGroup": 1 } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据客户 ID 更新客户资料（编号/名称、微信信息、联系方式）、余额额度、状态、角色与业务归属字段。 ####### 校验与异常 - 校验 `id` 存在与可更新状态；非法状态流转时返回业务错误。 ##### 删除客户（POST /customer/delete） ###### 1 接口请求示例 **请求 /customer/delete**（POST） ```json { "id": 1 } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按客户 ID 执行逻辑删除，保留历史审计数据。 ####### 校验与异常 - 校验 `id` 存在且可删除；存在关联数据限制时返回业务错误。 ##### 重置密码（POST /customer/reset-password） ###### 1 接口请求示例 **请求 /customer/reset-password**（POST） ```json { "id": 1, "newPassword": "123456" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据客户 ID 重置登录密码并更新密码变更时间。 ####### 校验与异常 - 校验 `id` 与 `newPassword` 合法性，不满足密码策略时返回业务错误。 ---------------------------------------------------------------------------------------- ---------------------------------------------------------------------------------------- ## 六、充值管理 ### 5.1 核心需求说明 - **充值流程**：客户提交充值金额 → 选择支付方式（微信/支付宝）→ 上传充值截图 → 提交审核 → 管理员审核（通过/驳回）→ 审核通过后更新客户余额。 - **充值记录**：完整留存充值全流程信息，支持查询、导出；充值状态包含：待审核、审核通过、审核驳回。 ### 5.2 表结构设计 #### 充值记录表 `t_recharge_record` | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | CustomerId | BIGINT | - | 外键（t_customer.Id） | 是 | 客户ID（主账号/子账号关联主账号ID） | | SerialNumber | VARCHAR | 64 | - | 是 | 流水号，规则：RECHARGE+日期+随机6位数字 | | RechargeTime | DATETIME | - | - | 是 | 充值提交时间，默认当前时间 | | PayType | TINYINT | - | - | 是 | 支付方式：1-微信，2-支付宝 | | RechargeAmount | DECIMAL | 18,2 | - | 是 | 充值金额，≥0.01 | | RechargeScreenshot | VARCHAR | 255 | - | 否 | 充值截图URL（存储文件服务器地址） | | RechargeStatus | TINYINT | - | - | 是 | 充值状态：0-待审核，1-审核通过，2-审核驳回 | | Remark | VARCHAR | 512 | - | 否 | 备注（客户/审核人填写） | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | | AuditTime | DATETIME | - | - | 否 | 审核时间 | | AuditBy | VARCHAR | 32 | - | 否 | 审核人（管理员账号） | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | ### 5.3 核心接口设计 | 接口名称 | 请求方式 | 请求路径 | 请求参数 | 响应参数 | 接口说明 | | --- | --- | --- | --- | --- | --- | | 提交充值申请 | POST | /recharge/recharge/submit | customerId, payType, rechargeAmount, screenshotUrl, remark | code, msg, data.serialNumber | 生成流水号，保存充值记录，状态为待审核 | | 审核充值申请 | POST | /recharge/recharge-record/approve 或 reject | id, auditStatus, auditBy, remark | code, msg | 审核通过则更新客户余额，更新审核时间、状态、审核人 | | 查询充值记录 | GET | /recharge/recharge-record/list | customerId, serialNumber, startTime, endTime, status | list, total | 多条件分页查询充值记录 | | 导出充值记录 | GET | /recharge/export | customerId, startTime, endTime | 文件流 | 导出充值记录为Excel文件 | ##### 提交充值申请（POST /recharge/recharge/submit） ###### 1 接口请求示例 **请求 /recharge/recharge/submit**（POST） ```json { "customerId": 1, "rechargeAmount": 500, "payType": 1, "rechargeScreenshot": "https://example.com/upload/screenshot.jpg", "remark": "充值500元" } ``` > 参数说明：`customerId` 客户ID（客户端提交时可不传，取当前登录客户）；`rechargeAmount` 充值金额，≥0.01；`payType` 支付方式：1-微信，2-支付宝；`rechargeScreenshot` 充值截图URL；`remark` 备注。 **响应** ```json { "code": 0, "msg": "success", "data": { "id": 1, "serialNumber": "RECHARGE2024010100123456", "customerId": 1, "rechargeAmount": 500.00, "payType": 1, "rechargeScreenshot": "https://example.com/upload/screenshot.jpg", "rechargeStatus": 0, "remark": "充值500元", "rechargeTime": "2024-01-01 12:00:00", "createTime": "2024-01-01 12:00:00" } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 创建充值记录并生成流水号，初始状态为待审核。 ####### 校验与异常 - 校验金额、支付方式与截图信息合法性，不合法时返回业务错误。 ##### 审核充值申请-通过（POST /recharge/recharge-record/approve） ###### 1 接口请求示例 **请求 /recharge/recharge-record/approve**（POST） ```json { "id": 1, "remark": "审核通过" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 审核通过后更新充值状态与审核信息，并增加客户余额。 ####### 校验与异常 - 校验记录状态必须为待审核；重复审核或状态冲突时返回业务错误。 ##### 审核充值申请-驳回（POST /recharge/recharge-record/reject） ###### 1 接口请求示例 **请求 /recharge/recharge-record/reject**（POST） ```json { "id": 1, "remark": "截图不清晰，请重新上传" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 审核驳回后更新充值状态与审核备注，不变更客户余额。 ####### 校验与异常 - 校验记录状态与审核权限，非法操作时返回业务错误。 ##### 查询充值记录（GET /recharge/recharge-record/list） ###### 1 接口请求示例 **请求 /recharge/recharge-record/list**（GET，Query 参数） ``` ?page=1&pageSize=20&customerId=1&serialNumber=&rechargeStatus=0&startTime=2024-01-01&endTime=2024-01-31 ``` **响应** ```json { "code": 0, "msg": "success", "data": { "items": [ { "id": 1, "customerId": 1, "customerCode": "W2501", "customerPhone": "13800138000", "serialNumber": "RECHARGE2024010100123456", "rechargeTime": "2024-01-01 12:00:00", "payType": 1, "payTypeName": "微信", "rechargeAmount": 500.00, "rechargeScreenshot": "https://example.com/upload/screenshot.jpg", "rechargeStatus": 0, "rechargeStatusName": "待审核", "remark": "充值500元", "auditTime": null, "auditBy": null, "createTime": "2024-01-01 12:00:00", "updateTime": "2024-01-01 12:00:00" } ], "total": 20 } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按客户、流水号、状态和时间区间进行分页查询，返回记录列表与总数。 ####### 校验与异常 - 校验时间区间与分页参数合法性，查询异常时返回统一错误码。 ##### 导出充值记录（GET /recharge/export） ###### 1 接口请求示例 **请求 /recharge/export**（GET，Query 参数） ``` ?customerId=1&startTime=2024-01-01&endTime=2024-01-31 ``` **响应** > 返回 Excel 文件流，Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet ###### 2 接口业务逻辑 ####### 核心流程 - 根据筛选条件导出充值记录为 Excel 文件流。 ####### 校验与异常 - 校验导出条件与数据权限，导出失败时返回统一错误信息。 ---------------------------------------------------------------------------------------- ---------------------------------------------------------------------------------------- ## 七、系统模块 ### 6.1 核心需求说明 - **仓库地址**：管理仓库收货地址信息，包括主仓/中转仓/退货仓/其他类型；支持收件人、联系电话、收货地址、客服电话、客服微信及二维码等配置。 - **国家管理**：维护国家基础资料（中文名称、英文名称、二字代码），供渠道分区、下单地址等模块复用。 - **字典管理**：维护系统字典项，支持按字典类型分组管理字典编码、名称和排序，供下拉选项、状态映射等场景统一复用。 ### 6.2 表结构设计 #### 国家表 `t_country` | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | ChineseName | VARCHAR | 128 | - | 是 | 中文名称 | | EnglishName | VARCHAR | 128 | - | 是 | 英文名称 | | CountryCode | VARCHAR | 2 | - | 是 | 国家二字代码（ISO 3166-1 alpha-2） | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | #### 字典表 `t_dict` | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | DictType | VARCHAR | 64 | - | 是 | 字典类型（如 notice_type、warehouse_type） | | DictSort | INT | - | - | 是 | 字典排序，值越小越靠前 | | DictCode | VARCHAR | 64 | - | 是 | 字典编码（同类型下唯一） | | DictName | VARCHAR | 128 | - | 是 | 字典名称 | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | #### 公告通知表 `t_notice` | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | NoticeType | VARCHAR | 16 | - | 是 | 通知类型：notice-公告，message-站内信 | | Title | VARCHAR | 200 | - | 是 | 标题 | | Content | TEXT | - | - | 是 | 内容 | | IsPopup | TINYINT | - | - | 是 | 是否弹窗：0-否，1-是 | | ReceiverType | VARCHAR | 16 | - | 是 | 接收对象：user-用户，customer-客户 | | ReceiverIds | JSON | - | - | 是 | 接收人 ID 列表 | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | #### 通知已读明细表 `t_notice_read` | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | NoticeId | BIGINT | - | 外键（关联 `t_notice.Id`） | 是 | 通知 ID | | ReceiverType | VARCHAR | 16 | - | 是 | 接收对象：user-用户，customer-客户 | | ReceiverId | BIGINT | - | - | 是 | 已读主体 ID（用户 ID/客户 ID） | | ReadTime | DATETIME | - | - | 是 | 已读时间 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | #### 仓库地址表 `t_warehouse_address` | 字段名 | 字段类型 | 长度 | 主键/外键 | 非空 | 说明 | | --- | --- | --- | --- | --- | --- | | Id | BIGINT | - | 主键 | 是 | 自增唯一标识 | | WarehouseName | VARCHAR | 128 | - | 是 | 仓库名称 | | WarehouseType | VARCHAR | 32 | - | 是 | main/transit/return/other | | Recipient | VARCHAR | 64 | - | 否 | 收件人 | | ContactPhone | VARCHAR | 32 | - | 否 | 联系电话 | | ShippingAddress | TEXT | - | - | 否 | 收货地址 | | ServicePhone | VARCHAR | 32 | - | 否 | 客服电话 | | ServiceWechat | VARCHAR | 64 | - | 否 | 客服微信 | | ServiceWechatFiles | JSON | - | - | 否 | 微信二维码图片 | | IsDeleted | TINYINT | - | - | 是 | 是否删除：0-否，1-是，默认0 | | CreateUserId | INT | - | - | 是 | 创建人 | | CreateTime | DATETIME | - | - | 是 | 创建时间 | | UpdateUserId | INT | - | - | 否 | 更新人 | | UpdateTime | DATETIME | - | - | 否 | 更新时间 | ### 6.3 核心接口设计 | 接口名称 | 请求方式 | 请求路径 | 说明 | | --- | --- | --- | --- | | 国家列表 | GET | /system/country/list | 查询国家列表 | | 字典列表 | GET | /system/dict/list | 按类型分页查询字典 | | 新增字典 | POST | /system/dict/create | 新增字典项 | | 更新字典 | POST | /system/dict/update | 更新字典项 | | 删除字典 | POST | /system/dict/delete | 删除字典项 | | 仓库列表 | GET | /system/warehouse/list | 仓库列表 | | 仓库详情 | GET | /system/warehouse/detail | 仓库详情 | | 新增仓库 | POST | /system/warehouse/create | 新增 | | 更新仓库 | POST | /system/warehouse/update | 更新 | | 删除仓库 | POST | /system/warehouse/delete | 删除 | | 通知列表 | GET | /system/notice/list | 分页查询通知 | | 新增通知 | POST | /system/notice/create | 新增公告/站内信 | | 编辑通知 | POST | /system/notice/update | 编辑公告/站内信 | | 删除通知 | POST | /system/notice/delete | 删除公告/站内信 | | 确认已读 | POST | /system/notice/read-confirm | 当前用户/客户确认已读 | ##### 国家列表（GET /system/country/list） ###### 1 接口请求示例 **请求 /system/country/list**（GET） > 无请求参数，返回全部国家字段。 **响应** ```json { "code": 0, "msg": "success", "data": [ { "id": 1, "chineseName": "中国", "englishName": "China", "countryCode": "CN" }, { "id": 2, "chineseName": "美国", "englishName": "United States", "countryCode": "US" } ] } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 查询 `t_country` 全量有效数据，按 `countryCode` 或 `englishName` 排序返回。 ####### 校验与异常 - 仅返回未删除记录；无数据时返回空数组。 ##### 字典列表（GET /system/dict/list） ###### 1 接口请求示例 **请求 /system/dict/list**（GET，Query 参数） ``` ?page=1&pageSize=20&dictType=warehouse_type&keyword=主仓 ``` **响应** ```json { "code": 0, "msg": "success", "data": { "items": [ { "id": 1, "dictType": "warehouse_type", "dictSort": 1, "dictCode": "main", "dictName": "主仓", "createTime": "2026-04-27 10:00:00", "updateTime": "2026-04-27 10:00:00" } ], "total": 1 } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按 `dictType`、关键词分页查询 `t_dict`，按 `dictSort` 升序、`id` 降序返回。 ####### 校验与异常 - 校验分页参数合法性；仅返回未删除记录，查询异常时返回统一错误码。 ##### 新增字典（POST /system/dict/create） ###### 1 接口请求示例 **请求 /system/dict/create**（POST） ```json { "dictType": "warehouse_type", "dictSort": 1, "dictCode": "main", "dictName": "主仓" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 新增字典项并写入创建审计信息。 ####### 校验与异常 - 校验 `dictType`、`dictSort`、`dictCode`、`dictName` 必填及格式合法性。 - 校验同一 `dictType` 下 `dictCode` 唯一，重复时返回业务错误。 ##### 更新字典（POST /system/dict/update） ###### 1 接口请求示例 **请求 /system/dict/update**（POST） ```json { "id": 1, "dictType": "warehouse_type", "dictSort": 2, "dictCode": "transit", "dictName": "中转仓" } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据字典 ID 更新字典类型、排序、编码、名称及审计信息。 ####### 校验与异常 - 校验 `id` 存在且未删除，更新字段合法。 - 若更新后 `dictType + dictCode` 与其他记录冲突，返回业务错误。 ##### 删除字典（POST /system/dict/delete） ###### 1 接口请求示例 **请求 /system/dict/delete**（POST） ```json { "id": 1 } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据字典 ID 执行逻辑删除并保留历史审计信息。 ####### 校验与异常 - 校验 `id` 存在与删除前置条件，不存在或已删除时返回业务错误。 ##### 仓库列表（GET /system/warehouse/list） ###### 1 接口请求示例 **请求 /system/warehouse/list**（GET，Query 参数） ``` ?page=1&pageSize=20&warehouseType=main&keyword= ``` **响应** ```json { "code": 0, "msg": "success", "data": { "items": [ { "id": 1, "warehouseName": "深圳主仓", "warehouseType": "main", "warehouseTypeName": "主仓", "recipient": "张三", "contactPhone": "0755-12345678", "shippingAddress": "广东省深圳市南山区xxx路xxx号", "servicePhone": "400-xxx-xxxx", "serviceWechat": "itfx_service", "serviceWechatFiles": ["https://example.com/qrcode1.jpg"], "createTime": "2024-01-01 12:00:00", "updateTime": "2024-01-01 12:00:00" } ], "total": 5 } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按仓库类型与关键词分页查询仓库地址信息列表。 ####### 校验与异常 - 校验分页参数与筛选条件合法性，异常时返回统一错误码。 ##### 仓库详情（GET /system/warehouse/detail） ###### 1 接口请求示例 **请求 /system/warehouse/detail**（GET，Query 参数） ``` ?id=1 ``` **响应** ```json { "code": 0, "msg": "success", "data": { "id": 1, "warehouseName": "深圳主仓", "warehouseType": "main", "recipient": "张三", "contactPhone": "0755-12345678", "shippingAddress": "广东省深圳市南山区xxx路xxx号", "servicePhone": "400-xxx-xxxx", "serviceWechat": "itfx_service", "serviceWechatFiles": ["https://example.com/qrcode1.jpg"], "createTime": "2024-01-01 12:00:00", "createBy": "admin", "updateTime": "2024-01-01 12:00:00", "updateBy": "admin" } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据仓库 ID 查询仓库详情，返回完整地址与客服信息。 ####### 校验与异常 - 校验 `id` 必填且存在，不存在时返回业务错误。 ##### 新增仓库（POST /system/warehouse/create） ###### 1 接口请求示例 **请求 /system/warehouse/create**（POST） ```json { "warehouseName": "深圳主仓", "warehouseType": "main", "recipient": "张三", "contactPhone": "0755-12345678", "shippingAddress": "广东省深圳市南山区xxx路xxx号", "servicePhone": "400-xxx-xxxx", "serviceWechat": "itfx_service", "serviceWechatFiles": ["https://example.com/qrcode1.jpg"] } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 新增仓库地址配置并写入创建审计信息。 ####### 校验与异常 - 校验仓库名称、类型及地址字段完整性，不合法时返回业务错误。 ##### 更新仓库（POST /system/warehouse/update） ###### 1 接口请求示例 **请求 /system/warehouse/update**（POST） ```json { "id": 1, "warehouseName": "深圳主仓", "warehouseType": "main", "recipient": "张三", "contactPhone": "0755-12345678", "shippingAddress": "广东省深圳市南山区xxx路xxx号", "servicePhone": "400-xxx-xxxx", "serviceWechat": "itfx_service", "serviceWechatFiles": ["https://example.com/qrcode1.jpg"] } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据仓库 ID 更新仓库基础信息与联系方式。 ####### 校验与异常 - 校验 `id` 存在与更新字段合法性，更新失败时返回业务错误。 ##### 删除仓库（POST /system/warehouse/delete） ###### 1 接口请求示例 **请求 /system/warehouse/delete**（POST） ```json { "id": 1 } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据仓库 ID 执行逻辑删除并保留历史记录。 ####### 校验与异常 - 校验 `id` 存在与删除前置条件，冲突时返回业务错误。 ##### 通知列表（GET /system/notice/list） ###### 1 接口请求示例 **请求 /system/notice/list**（GET，Query 参数） ``` ?page=1&pageSize=20¬iceType=notice&receiverType=user&keyword=活动 ``` **响应** ```json { "code": 0, "msg": "success", "data": { "items": [ { "id": 101, "noticeType": "notice", "noticeTypeName": "公告", "title": "五一放假通知", "content": "仓库 5 月 1 日-5 月 3 日暂停收货。", "isPopup": 1, "receiverType": "user", "receiverTypeName": "用户", "receiverIds": [1001, 1002, 1003], "readCount": 2, "receiverCount": 3, "createTime": "2026-04-25 12:00:00", "updateTime": "2026-04-25 12:00:00" } ], "total": 1 } } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 按通知类型、接收对象、关键词分页查询 `t_notice`。 - 已读数通过聚合 `t_notice_read`（按 `NoticeId` + `ReceiverId` 去重）计算，接收人总数按 `receiverIds` 统计。 ####### 校验与异常 - 校验分页参数合法性，仅返回未删除记录；异常时返回统一错误码。 ##### 新增通知（POST /system/notice/create） ###### 1 接口请求示例 **请求 /system/notice/create**（POST） ```json { "noticeType": "notice", "title": "五一放假通知", "content": "仓库 5 月 1 日-5 月 3 日暂停收货。", "isPopup": 1, "receiverType": "user", "receiverIds": [1001, 1002, 1003] } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 新增公告/站内信并写入接收对象与接收人列表。 ####### 校验与异常 - 校验 `noticeType`、`title`、`content`、`isPopup`、`receiverType`、`receiverIds` 必填及枚举合法性。 - `receiverIds` 为空或包含无效用户/客户时返回业务错误。 ##### 编辑通知（POST /system/notice/update） ###### 1 接口请求示例 **请求 /system/notice/update**（POST） ```json { "id": 101, "noticeType": "message", "title": "账单补充说明", "content": "请于本周内完成 4 月账单核对。", "isPopup": 0, "receiverType": "customer", "receiverIds": [2001, 2002] } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据通知 ID 更新通知主体内容与接收范围。 - 如接收人发生变化，清理 `t_notice_read` 中不在新接收范围内的已读明细。 ####### 校验与异常 - 校验 `id` 存在且未删除，更新字段合法。 - 已发布通知可编辑但必须保留至少 1 个接收人。 ##### 删除通知（POST /system/notice/delete） ###### 1 接口请求示例 **请求 /system/notice/delete**（POST） ```json { "id": 101 } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 根据通知 ID 执行逻辑删除，保留历史审计信息。 ####### 校验与异常 - 校验 `id` 必填且存在，不存在或已删除时返回业务错误。 ##### 确认已读（POST /system/notice/read-confirm） ###### 1 接口请求示例 **请求 /system/notice/read-confirm**（POST） ```json { "id": 101 } ``` **响应** ```json { "code": 0, "msg": "success", "data": null } ``` ###### 2 接口业务逻辑 ####### 核心流程 - 当前登录用户/客户调用后，在 `t_notice_read` 中按 `NoticeId + ReceiverType + ReceiverId` 幂等写入已读记录，并记录 `readTime`。 ####### 校验与异常 - 校验通知存在且未删除。 - 校验当前主体在通知接收范围内，不在范围内时返回无权限错误。 ---------------------------------------------------------------------------------------- ---------------------------------------------------------------------------------------- ## 附录 ### 附录一：接口路径规范（kebab-case 汇总） | 模块 | 路径前缀 | 示例 | | --- | --- | --- | | 订单 | /order/ | list, detail, pay, pre-declare, cancel-intercept, delete, price-check | | 渠道-销售产品 | /channel/sales-product/ | list, detail, create, update, delete, price/list, allocation/get | | 渠道-服务渠道 | /channel/service-channel/ | list, detail, create, update, delete, group/create, group/update, group/delete, price/list | | 渠道-计重 | /channel/weight-rule/, weight-rounding/ | list, create, update, delete, info/list | | 渠道-自动触发 | /channel/auto-trigger/ | list, create, update, delete, toggle-status | | 渠道-分区（KpiArea） | /channel/kpi-area/ | create, update, delete, list, info/add, info/update, info/delete, info/list | | 渠道-标签 | /channel/label-template/save | | | 操作 | /operation/ | inbound/create, inbound/recent-list, outbound/create, print-label/print | | 客户 | /customer/ | list, get, create, update, delete, reset-password | | 充值 | /recharge/ | recharge/submit, recharge-record/list, approve, reject | | 系统 | /system/ | country/list, warehouse/list, warehouse/detail, warehouse/create, warehouse/update, warehouse/delete, notice/list, notice/create, notice/update, notice/delete, notice/read-confirm | ### 附录二：分区类型说明（黑名单/偏远/价格） | 页面 | areaType | 说明 | | --- | --- | --- | | 黑名单区 | blacklist | 黑名单分区 | | 偏远分区 | remote | 偏远分区 | | 价格分区 | price | 用于计价/价格表关联的分区 | 调用 KpiArea 接口时，通过 `areaType` 区分不同业务分区，无需新建表或接口。 ### 附录三：状态码与枚举 #### 订单状态 | status | 中文 | | --- | --- | | draft | 草稿 | | predeclared | 已预报 | | received | 已收货 | | pendingPayment | 待支付 | | pendingShip | 待发货 | | pendingOnline | 待上网 | | shipping | 运输中 | | deliverySuccess | 派送成功 | | deliveryFailed | 派送失败 | | problematic | 问题件 | | deleted | 已删除 | | claimed | 已理赔 | #### 充值状态 | payStatus | 中文 | | --- | --- | | 0 | 待审核 | | 1 | 成功 | | 2 | 失败 | #### 仓库类型 | warehouseType | 中文 | | --- | --- | | main | 主仓 | | transit | 中转仓 | | return | 退货仓 | | other | 其他 | #### 通知类型 | noticeType | 中文 | | --- | --- | | notice | 公告 | | message | 站内信 | #### 接收对象类型 | receiverType | 中文 | | --- | --- | | user | 用户 | | customer | 客户 | #### 客户分组（客户表） | customerGroup | 中文 | | --- | --- | | 0 | 普通客户 | | 1 | VIP1 | | 2 | VIP2 | | 3 | VIP3 | | 4 | VIP4 | | 5 | VIP5 | ---------------------------------------------------------------------------------------- *文档版本：v1.0 | 最后更新：2025-03-04*