html/docs

Fork 0

Files

T

ouyangxq 1ec28f7cfc docs: initialize documentation repository

2026-07-31 10:43:58 +08:00

69 KiB

Raw Blame History

国际货运代理 SaaS 平台 - 完整技术架构设计

版本: v1.0 | 日期: 2026-06-01 | 适用规模: 中大型多租户 SaaS 平台（支持数千商家入驻）

1. 系统整体架构

1.1 架构总览图（文字描述）

+-----------------------------------------------------------------------------+
|                              接入层 (Access Layer)                            |
|  [CDN静态资源] [WAF安全防护] [DNS域名解析] [API Gateway网关]                  |
+--------|---------------|---------------|----------------|---------------------+
|                              应用层 (Application Layer)                       |
|  +-----------------------------------------------------------------------+    |
|  |                        前端应用集群                                     |    |
|  |  [商家端Web Vue3/React] [运营后台Vue3] [移动端H5 uni-app] [开放平台]    |    |
|  +-----------------------------------------------------------------------+    |
|  +-----------------------------------------------------------------------+    |
|  |                        后端微服务集群 (11个服务)                         |    |
|  |  租户服务 | 订单/运单 | 海运费报价 | 关税管理 | 仓库作业 | 清关管理        |    |
|  |  财务结算 | 消息通知 | 数据看板   | 文件报表 | 认证服务 | API网关         |    |
|  +-----------------------------------------------------------------------+    |
+-----------------------------------------------------------------------------+
|                              中间件层 (Middleware Layer)                      |
|  [Nacos注册配置中心] [RocketMQ消息队列] [Redis缓存集群]                     |
|  [Elasticsearch搜索] [Sentinel熔断限流]                                    |
+-----------------------------------------------------------------------------+
|                              数据层 (Data Layer)                             |
|  [MySQL主从+分库分表] [MongoDB日志] [MinIO/OSS对象存储]                   |
|  [ClickHouse OLAP分析] [Redis会话缓存]                                     |
+-----------------------------------------------------------------------------+
|                              基础设施层 (Infrastructure)                     |
|  Kubernetes(K8s) + Docker | CI/CD Jenkins | Prometheus+Grafana监控 | ELK日志  |
+-----------------------------------------------------------------------------+

1.2 架构分层说明

层级	组件	核心职责
接入层	CDN / WAF / DNS / API Gateway	流量接入、DDoS防护、路由分发、负载均衡、限流熔断、统一鉴权
应用层	Vue3/React前端 + Java/Go微服务	业务逻辑处理，按领域(DDD)拆分为独立微服务
中间件层	Nacos / RocketMQ / Redis / ES / Sentinel	服务发现、配置中心、异步解耦、分布式缓存、全文检索、流量控制
数据层	MySQL / MongoDB / MinIO / ClickHouse / Redis	结构化主数据、文档日志、文件对象、OLAP分析、高速缓存
基础设施	K8s / Docker / Jenkins / Prometheus / Grafana / ELK	容器编排、持续集成部署、全链路监控告警、集中日志

1.3 多租户架构模式

采用 共享数据库 + 共享Schema + TenantId行级隔离 方案：

所有业务表均包含 tenant_id 字段
每条SQL查询自动追加 WHERE tenant_id = ? 条件（MyBatis拦截器实现）
敏感财务数据支持VIP租户独立物理库隔离
适用规模：数千租户级别，运维成本低，资源共享率高

2. 微服务拆分方案（共11个核心服务）

2.1 服务清单

#	服务名	端口	核心职责	关键依赖
1	logistics-tenant-service	8001	商家入驻审核、租户信息CRUD、套餐订阅、RBAC权限、组织架构	MySQL, Redis, OSS, MQ
2	logistics-order-service	8002	运单全生命周期、多运输方式(FCL/LCL/空运/陆运/联运)、状态机管理、费用项、物流轨迹	MySQL, Redis, MQ, ES
3	logistics-freight-service	8003	船期维护、海运费率体系(基价+附加费BAF/CAF/DDC/THC等)、询价报价流程、合约特价管理	MySQL, Redis, ES, MQ
4	logistics-customs-duty-service	8004	HS编码库(中英模糊匹配)、各国税率表(关税/VAT/消费税/反倾销税)、关税预估计算引擎、退税管理、保税政策适配	MySQL, Redis, ES(全文检索HS)
5	logistics-warehouse-service	8005	仓库/库区/货位基础数据、入库(收货预约/检验/上架)、出库(拣货策略/复核打包)、库存(实时/冻结/调整)、盘点、装箱打托	MySQL, Redis(热点库存), MQ
6	logistics-clearance-service	8006	报关单(进口/出口/转关/退运)、报关要素采集、单证管理(发票/箱单/合同/CO)、商检、海关单一窗口对接(预留)、异常处理(改单删单担保放行)	MySQL, Redis, OSS, MQ
7	logistics-finance-service	8007	应收AR/应付AP、对账单生成(月结/票票对账)、发票管理(开票/作废/红冲)、收付款核销(部分核销/预收款)、成本利润核算	MySQL, Redis, MQ(事件驱动对账)
8	logistics-notification-service	8008	站内消息、短信验证码/业务通知、邮件对账单/回执、微信钉钉推送、消息模板变量替换、投递状态追踪	MySQL, Redis, MQ(异步发送)
9	logistics-dashboard-service	8009	业务统计看板(订单量/收入/利润趋势)、运营监控大屏、客户画像(TOP客户/流失预警/RFM)、自定义报表拖拽引擎、Excel/PDF导出	ClickHouse, MySQL, Redis缓存, ES
10	logistics-file-service	8010	文件上传下载(单证/合同/资质)、在线预览(PDF/Office/图片)、版本管理、报表模板(JasperReports)、异步批量导出、图片压缩缩略图	MinIO/Aliyun-OSS, Redis
11	logistics-auth-service	8011	注册登录(密码/手机/OAuth)、JWT签发校验、多租户身份注入TenantContext、RBAC接口鉴权、SSO单点登录、操作审计	MySQL, Redis(Token黑名单)

2.2 服务间调用关系

API Gateway (Spring Cloud Gateway)
    |
    +---> Auth Service (认证鉴权 - 第一道关卡)
    |
    +---> Tenant Service (租户管理)
    |       |
    +---> File Service (文件服务 - 被所有服务调用)
    |
    +---> Order Service (运单核心)
    |       |---> Freight Service (查询费率订舱)
    |       |---> Customs Duty Service (HS编码/关税预估)
    |       |---> Warehouse Service (出入库操作)
    |       +---> Clearance Service (报关操作)
    |
    +---> Finance Service <--- Notification Service (结算通知)
    +---> Dashboard Service (聚合统计 - 只读)

2.3 通信规范

场景	方式	协议	说明
同步调用(服务间)	OpenFeign / gRPC	HTTP2 / Protocol Buffers	核心链路同步调用
异步事件	RocketMQ	AMQP	状态变更通知、对账触发、消息解耦
前后端通信	HTTP RESTful	JSON	通过API网关统一入口

3. 数据库核心表设计

3.1 ER 关系总览

tenant (租户) 1:N tenant_user (用户) -- N:M tenant_role_menu (角色权限)
     |
     | 1:N
shipment_order (运单) 1:N order_item (货物明细)
                          1:N order_container (集装箱)
                          1:N order_tracking (物流轨迹)

customs_declaration (报关单) 1:N customs_decl_item (报关商品明细)
                                1:N customs_decl_document (报关附件)

warehouse (仓库) 1:N warehouse_location (库位)

product_sku (商品SKU)
     |
     | 1:N
inventory (库存) -- 1:N inventory_transaction (库存流水)

warehouse_receipt (入库单) 1:N warehouse_receipt_item (入库明细)
warehouse_shipment (出库单) 1:N warehouse_shipment_item (出库明细)

freight_rate (海运费率) 1:N surcharge (附加费率)

finance_bill (账单) 1:N finance_bill_item (账单明细)
     |
     | 1:N
finance_settlement (结算核销记录)

hs_code (HS编码) 1:N customs_tariff (税率表)
duty_estimate (关税预估记录)

3.2 核心表 DDL

以下为所有核心业务表的完整 DDL 定义，涵盖8大模块。

(A) 商家/租户模块

-- ========================================
-- 租户主表
-- ========================================
CREATE TABLE tenant (
    id                BIGINT AUTO_INCREMENT PRIMARY KEY,
    tenant_code       VARCHAR(32) NOT NULL UNIQUE COMMENT '租户唯一编码',
    company_name      VARCHAR(200) NOT NULL COMMENT '公司名称',
    company_name_en   VARCHAR(200) DEFAULT NULL COMMENT '公司英文名',
    uniform_credit_code VARCHAR(50) DEFAULT NULL COMMENT '统一社会信用代码',
    contact_person    VARCHAR(50) DEFAULT NULL COMMENT '联系人',
    contact_phone     VARCHAR(20) DEFAULT NULL COMMENT '联系电话',
    contact_email     VARCHAR(100) DEFAULT NULL,
    address           VARCHAR(500) DEFAULT NULL,
    business_license_url VARCHAR(500) DEFAULT NULL COMMENT '营业执照URL',
    status            TINYINT NOT NULL DEFAULT 0 COMMENT '0待审核 1正常 2停用 3注销',
    tier              TINYINT NOT NULL DEFAULT 0 COMMENT '0免费 1标准 2专业 3企业',
    expire_time       DATETIME DEFAULT NULL COMMENT '套餐到期时间',
    max_users         INT NOT NULL DEFAULT 10 COMMENT '最大用户数',
    timezone          VARCHAR(32) DEFAULT 'Asia/Shanghai',
    locale            VARCHAR(16) DEFAULT 'zh_CN',
    config_json       JSON DEFAULT NULL COMMENT '扩展配置JSON',
    remark            VARCHAR(500) DEFAULT NULL,
    created_by        BIGINT DEFAULT NULL,
    created_at        DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at        DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    deleted           TINYINT NOT NULL DEFAULT 0,
    INDEX idx_tenant_code (tenant_code),
    INDEX idx_status (status),
    INDEX idx_tier (tier)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='租户主表';

-- ========================================
-- 租户用户表
-- ========================================
CREATE TABLE tenant_user (
    id              BIGINT AUTO_INCREMENT PRIMARY KEY,
    tenant_id       BIGINT NOT NULL COMMENT '归属租户ID',
    username        VARCHAR(64) NOT NULL COMMENT '登录名',
    password_hash   VARCHAR(256) NOT NULL COMMENT 'BCrypt密码哈希',
    real_name       VARCHAR(50) DEFAULT NULL,
    phone           VARCHAR(20) DEFAULT NULL,
    email           VARCHAR(100) DEFAULT NULL,
    avatar_url      VARCHAR(500) DEFAULT NULL,
    role_id         BIGINT DEFAULT NULL COMMENT '角色ID',
    dept_id         BIGINT DEFAULT NULL COMMENT '部门ID',
    status          TINYINT NOT NULL DEFAULT 1 COMMENT '0禁用 1正常',
    last_login_at   DATETIME DEFAULT NULL,
    last_login_ip   VARCHAR(45) DEFAULT NULL,
    created_at      DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at      DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    deleted         TINYINT NOT NULL DEFAULT 0,
    UNIQUE KEY uk_tenant_username (tenant_id, username),
    INDEX idx_tenant_id (tenant_id),
    INDEX idx_phone (phone)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='租户用户表';

-- RBAC角色与菜单关联表略(tenant_role, tenant_role_menu)

(B) 运单/订单模块（核心大表）

-- ========================================
-- 运单主表 (系统最核心的表)
-- ========================================
CREATE TABLE shipment_order (
    id                  BIGINT AUTO_INCREMENT PRIMARY KEY,
    tenant_id           BIGINT NOT NULL,
    order_no            VARCHAR(40) NOT NULL COMMENT '运单编号(业务单号)',
    reference_no        VARCHAR(100) DEFAULT NULL COMMENT '客户参考号',
    transport_mode      TINYINT NOT NULL COMMENT '1海运整箱 2海运拼箱 3空运 4陆运 5多式联运',
    business_type       TINYINT NOT NULL COMMENT '1进口 2出口 3内贸',

    -- 发货方信息
    shipper_name        VARCHAR(200) NOT NULL,
    shipper_address     VARCHAR(500) DEFAULT NULL,
    shipper_contact     VARCHAR(50) DEFAULT NULL,
    shipper_phone       VARCHAR(20) DEFAULT NULL,

    -- 收货方信息
    consignee_name      VARCHAR(200) NOT NULL,
    consignee_address   VARCHAR(500) DEFAULT NULL,
    consignee_contact   VARCHAR(50) DEFAULT NULL,
    consignee_phone     VARCHAR(20) DEFAULT NULL,

    -- 港口/航站
    pol                 VARCHAR(20) DEFAULT NULL COMMENT '装货港 POL',
    pod                 VARCHAR(20) DEFAULT NULL COMMENT '卸货港 POD',
    place_of_receipt    VARCHAR(20) DEFAULT NULL COMMENT '收货地',
    place_of_delivery   VARCHAR(20) DEFAULT NULL COMMENT '最终目的地',

    -- 时间节点
    etd                 DATE DEFAULT NULL COMMENT '预计出发 ETD',
    eta                 DATE DEFAULT NULL COMMENT '预计到达 ETA',
    atd                 DATE DEFAULT NULL COMMENT '实际出发 ATD',
    ata                 DATE DEFAULT NULL COMMENT '实际到达 ATA',

    -- 船舶航班信息
    vessel_name         VARCHAR(100) DEFAULT NULL COMMENT '船名/航班号',
    voyage_no           VARCHAR(30) DEFAULT NULL COMMENT '航次号',
    mbl_no              VARCHAR(50) DEFAULT NULL COMMENT '主提单号 MBL',
    hbl_no              VARCHAR(50) DEFAULT NULL COMMENT '分提单号 HBL',

    -- 货物概要
    container_count     INT DEFAULT 0 COMMENT '箱量',
    container_type      VARCHAR(20) DEFAULT NULL COMMENT '箱型 20GP/40GP/40HC等',
    gross_weight        DECIMAL(14,4) DEFAULT NULL COMMENT '总毛重KG',
    volume              DECIMAL(14,4) DEFAULT NULL COMMENT '总体积CBM',
    package_count       INT DEFAULT 0 COMMENT '总件数',

    -- 费用汇总
    total_revenue       DECIMAL(14,2) DEFAULT 0.00 COMMENT '应收总额',
    total_cost          DECIMAL(14,2) DEFAULT 0.00 COMMENT '应付总额',
    estimated_profit    DECIMAL(14,2) DEFAULT 0.00 COMMENT '预估毛利',
    currency            CHAR(3) DEFAULT 'CNY' COMMENT '币种',

    -- 状态字段
    order_status        TINYINT NOT NULL DEFAULT 0 COMMENT '0草稿 1已确认 2已订舱 3已报关 4运输中 5到港待提 6已完成 7已取消',
    payment_status      TINYINT DEFAULT 0 COMMENT '0未结清 1部分结清 2已结清',
    priority            TINYINT DEFAULT 0 COMMENT '0普通 1紧急 2加急',

    -- 人员关联
    salesman_id         BIGINT DEFAULT NULL COMMENT '销售员ID',
    operator_id         BIGINT DEFAULT NULL COMMENT '操作员ID',
    customer_id         BIGINT DEFAULT NULL COMMENT '客户档案ID',

    -- 备注
    internal_remark     VARCHAR(1000) DEFAULT NULL,
    customer_remark     VARCHAR(1000) DEFAULT NULL,
    tags                JSON DEFAULT NULL COMMENT '标签JSON数组',

    created_by          BIGINT DEFAULT NULL,
    created_at          DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at          DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    deleted             TINYINT NOT NULL DEFAULT 0,
    UNIQUE KEY uk_tenant_order (tenant_id, order_no),
    INDEX idx_status (order_status),
    INDEX idx_customer (customer_id),
    INDEX idx_etd_eta (etd, eta),
    INDEX idx_created (created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='运单主表';

-- ========================================
-- 运单货物明细表
-- ========================================
CREATE TABLE order_item (
    id              BIGINT AUTO_INCREMENT PRIMARY KEY,
    order_id        BIGINT NOT NULL,
    item_no         INT NOT NULL COMMENT '序号',
    hs_code         VARCHAR(20) DEFAULT NULL COMMENT 'HS编码',
    description_cn  VARCHAR(500) NOT NULL COMMENT '中文品名',
    description_en  VARCHAR(500) DEFAULT NULL COMMENT '英文品名',
    material        VARCHAR(100) DEFAULT NULL COMMENT '材质',
    usage           VARCHAR(200) DEFAULT NULL COMMENT '用途',
    brand_model     VARCHAR(200) DEFAULT NULL COMMENT '品牌型号',
    package_type    VARCHAR(20) DEFAULT NULL COMMENT '包装类型 CTN/PAL/SKID',
    quantity        DECIMAL(14,2) NOT NULL COMMENT '数量',
    unit            VARCHAR(10) DEFAULT 'PCS' COMMENT '单位',
    unit_price      DECIMAL(14,4) DEFAULT NULL COMMENT '单价USD',
    total_value     DECIMAL(14,2) DEFAULT NULL COMMENT '总价申报价值',
    currency        CHAR(3) DEFAULT 'USD',
    gross_weight    DECIMAL(14,4) DEFAULT NULL COMMENT '毛重KG',
    net_weight      DECIMAL(14,4) DEFAULT NULL COMMENT '净重KG',
    volume          DECIMAL(14,4) DEFAULT NULL COMMENT '体积CBM',
    marks_numbers   VARCHAR(500) DEFAULT NULL COMMENT '唛头',
    origin_country  VARCHAR(10) DEFAULT NULL COMMENT '原产国',
    remark          VARCHAR(500) DEFAULT NULL,
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at      DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_order_id (order_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='运单货物明细';

-- ========================================
-- 运单集装箱明细
-- ========================================
CREATE TABLE order_container (
    id              BIGINT AUTO_INCREMENT PRIMARY KEY,
    order_id        BIGINT NOT NULL,
    container_no    VARCHAR(20) NOT NULL COMMENT '柜号',
    container_type  VARCHAR(10) NOT NULL COMMENT '箱型',
    seal_no         VARCHAR(20) DEFAULT NULL COMMENT '封条号',
    pkg_count       INT DEFAULT 0 COMMENT '件数',
    gross_weight    DECIMAL(14,4) DEFAULT NULL COMMENT '毛重',
    volume          DECIMAL(14,4) DEFAULT NULL COMMENT '体积CBM',
    cargo_desc      VARCHAR(500) DEFAULT NULL COMMENT '货物品名描述',
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_order_id (order_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='运单集装箱明细';

-- ========================================
-- 物流轨迹表
-- ========================================
CREATE TABLE order_tracking (
    id              BIGINT AUTO_INCREMENT PRIMARY KEY,
    order_id        BIGINT NOT NULL,
    track_time      DATETIME NOT NULL COMMENT '轨迹时间',
    track_status    VARCHAR(30) NOT NULL COMMENT '状态码',
    track_desc      VARCHAR(500) NOT NULL COMMENT '轨迹描述',
    track_location  VARCHAR(100) DEFAULT NULL COMMENT '地点',
    track_source    VARCHAR(20) DEFAULT NULL COMMENT '来源 MANUAL/API/CARRIER',
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_order_id (order_id),
    INDEX idx_track_time (track_time)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='物流轨迹表';

(C) 报关单模块

-- ========================================
-- 报关单主表
-- ========================================
CREATE TABLE customs_declaration (
    id                  BIGINT AUTO_INCREMENT PRIMARY KEY,
    tenant_id           BIGINT NOT NULL,
    decl_no             VARCHAR(40) NOT NULL COMMENT '报关单号预录入号',
    order_id            BIGINT DEFAULT NULL COMMENT '关联运单',
    decl_type           TINYINT NOT NULL COMMENT '1进口 2出口 3转关 4退运',
    trade_mode          VARCHAR(10) DEFAULT NULL COMMENT '贸易方式 一般贸易/加工贸易/保税',
    tax_mode            VARCHAR(10) DEFAULT NULL COMMENT '征免性质',
    ie_port             VARCHAR(10) DEFAULT NULL COMMENT '进出境口岸',
    destination_country VARCHAR(10) DEFAULT NULL COMMENT '运抵国/运往国',
    license_no          VARCHAR(50) DEFAULT NULL COMMENT '许可证号',
    contract_no         VARCHAR(50) DEFAULT NULL COMMENT '合同协议号',
    invoice_no          VARCHAR(50) DEFAULT NULL COMMENT '发票号码',
    bill_lading_no      VARCHAR(50) DEFAULT NULL COMMENT '提运单号',

    -- 货物汇总
    total_packages      INT DEFAULT 0,
    package_type        VARCHAR(10) DEFAULT NULL COMMENT '包装种类',
    gross_weight        DECIMAL(14,4) DEFAULT NULL COMMENT '毛重KG',
    net_weight          DECIMAL(14,4) DEFAULT NULL COMMENT '净重KG',
    total_value_usd     DECIMAL(14,2) DEFAULT NULL COMMENT '总价USD',

    -- 税费
    customs_duty        DECIMAL(14,2) DEFAULT 0.00 COMMENT '关税额',
    value_added_tax     DECIMAL(14,2) DEFAULT 0.00 COMMENT '增值税额',
    consumption_tax     DECIMAL(14,2) DEFAULT 0.00 COMMENT '消费税额',
    total_tax           DECIMAL(14,2) DEFAULT 0.00 COMMENT '税费合计',

    -- 状态
    decl_status         TINYINT DEFAULT 0 COMMENT '0草稿 1待申报 2已申报 3审单通过 4布控查验 5放行 6异常',
    customs_entry_id    VARCHAR(50) DEFAULT NULL COMMENT '海关通关编号',
    decl_date           DATE DEFAULT NULL COMMENT '申报日期',
    release_date        DATE DEFAULT NULL COMMENT '放行日期',

    -- 申报单位
    declarer_company    VARCHAR(200) DEFAULT NULL,
    declarer_contact    VARCHAR(50) DEFAULT NULL COMMENT '申报员',
    remark              VARCHAR(1000) DEFAULT NULL,
    created_by          BIGINT DEFAULT NULL,
    created_at          DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at          DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    deleted             TINYINT DEFAULT 0,
    UNIQUE KEY uk_tenant_decl (tenant_id, decl_no),
    INDEX idx_order_id (order_id),
    INDEX idx_status (decl_status)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='报关单主表';

-- 报关单货物明细(customs_decl_item)和附件表(customs_decl_document)DDL略

(D) 仓库作业模块

-- ========================================
-- 仓库主表 & 库位表
-- ========================================
CREATE TABLE warehouse (
    id              BIGINT AUTO_INCREMENT PRIMARY KEY,
    tenant_id       BIGINT NOT NULL,
    warehouse_code  VARCHAR(32) NOT NULL,
    warehouse_name  VARCHAR(100) NOT NULL,
    warehouse_type  TINYINT DEFAULT 1 COMMENT '1普通仓 2保税仓 3监管仓 4冷藏仓',
    address         VARCHAR(500) DEFAULT NULL,
    area_sqm        DECIMAL(12,2) DEFAULT NULL COMMENT '面积平方米',
    status          TINYINT DEFAULT 1,
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at      DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    deleted         TINYINT DEFAULT 0,
    UNIQUE KEY uk_tenant_wh (tenant_id, warehouse_code)
);

CREATE TABLE warehouse_location (
    id              BIGINT AUTO_INCREMENT PRIMARY KEY,
    warehouse_id    BIGINT NOT NULL,
    zone_code       VARCHAR(20) DEFAULT NULL COMMENT '库区',
    shelf_code      VARCHAR(20) DEFAULT NULL COMMENT '货架',
    location_code   VARCHAR(32) NOT NULL COMMENT '库位编码唯一',
    location_type   TINYINT DEFAULT 1 COMMENT '1地面 2货架 3拣货位 4存储位',
    length_mm       INT DEFAULT NULL,
    width_mm        INT DEFAULT NULL,
    height_mm       INT DEFAULT NULL,
    max_weight_kg   DECIMAL(10,2) DEFAULT NULL COMMENT '最大承重KG',
    status          TINYINT DEFAULT 1 COMMENT '0占用 1可用 2锁定 3故障',
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
    UNIQUE KEY uk_wh_loc (warehouse_id, location_code)
);

-- ========================================
-- 商品SKU主档
-- ========================================
CREATE TABLE product_sku (
    id              BIGINT AUTO_INCREMENT PRIMARY KEY,
    tenant_id       BIGINT NOT NULL,
    sku_code        VARCHAR(64) NOT NULL,
    sku_name        VARCHAR(200) NOT NULL,
    category_id     BIGINT DEFAULT NULL,
    hs_code         VARCHAR(20) DEFAULT NULL,
    brand           VARCHAR(100) DEFAULT NULL,
    specification   VARCHAR(300) DEFAULT NULL,
    length_mm       INT DEFAULT NULL,
    width_mm        INT DEFAULT NULL,
    height_mm       INT DEFAULT NULL,
    weight_kg       DECIMAL(10,4) DEFAULT NULL,
    volume_cbm      DECIMAL(10,6) DEFAULT NULL,
    barcode         VARCHAR(64) DEFAULT NULL,
    image_url       VARCHAR(500) DEFAULT NULL,
    status          TINYINT DEFAULT 1,
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at      DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    deleted         TINYINT DEFAULT 0,
    UNIQUE KEY uk_tenant_sku (tenant_id, sku_code)
);

-- ========================================
-- 库存表 (高频读写核心表)
-- ========================================
CREATE TABLE inventory (
    id              BIGINT AUTO_INCREMENT PRIMARY KEY,
    tenant_id       BIGINT NOT NULL,
    warehouse_id    BIGINT NOT NULL,
    location_id     BIGINT NOT NULL COMMENT '库位ID',
    sku_id          BIGINT NOT NULL,
    batch_no        VARCHAR(50) DEFAULT NULL COMMENT '批次号',
    qty_available   DECIMAL(14,4) NOT NULL DEFAULT 0 COMMENT '可用数量',
    qty_frozen      DECIMAL(14,4) NOT NULL DEFAULT 0 COMMENT '冻结数量',
    qty_total       DECIMAL(14,4) NOT NULL DEFAULT 0 COMMENT '总数量',
    production_date DATE DEFAULT NULL COMMENT '生产日期',
    expiry_date     DATE DEFAULT NULL COMMENT '过期日期',
    unit_cost       DECIMAL(14,4) DEFAULT NULL COMMENT '单位成本',
    updated_at      DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY uk_inv_batch (tenant_id, warehouse_id, location_id, sku_id, batch_no),
    INDEX idx_sku (sku_id),
    INDEX idx_warehouse (warehouse_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='库存表';

-- ========================================
-- 入库单 & 出库单 (warehouse_receipt / warehouse_shipment 及其明细表 DDL略)
-- ========================================

-- ========================================
-- 库存变动流水表 (只追加不修改)
-- ========================================
CREATE TABLE inventory_transaction (
    id              BIGINT AUTO_INCREMENT PRIMARY KEY,
    tenant_id       BIGINT NOT NULL,
    inventory_id    BIGINT NOT NULL,
    tran_type       VARCHAR(20) NOT NULL COMMENT 'RECEIPT/SHIPMENT/ADJUST/FROZEN/UNFROZEN/COUNT',
    ref_no          VARCHAR(40) DEFAULT NULL COMMENT '关联单号',
    qty_before      DECIMAL(14,4) NOT NULL,
    qty_change      DECIMAL(14,4) NOT NULL COMMENT '变动数量正负',
    qty_after       DECIMAL(14,4) NOT NULL,
    cost_before     DECIMAL(14,4) DEFAULT 0,
    cost_change     DECIMAL(14,4) DEFAULT 0,
    cost_after      DECIMAL(14,4) DEFAULT 0,
    remark          VARCHAR(255) DEFAULT NULL,
    created_by      BIGINT DEFAULT NULL,
    created_at      DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_inventory_id (inventory_id),
    INDEX idx_ref_no (ref_no),
    INDEX idx_created (created_at)
);

(E) 海运费模块

-- 港口基础数据(base_port), 航线(shipping_route) DDL略

-- ========================================
-- 海运费率表 (核心定价表)
-- ========================================
CREATE TABLE freight_rate (
    id              BIGINT AUTO_INCREMENT PRIMARY KEY,
    tenant_id       BIGINT NOT NULL COMMENT '所属租户 全局价为0',
    rate_name       VARCHAR(100) NOT NULL,
    rate_type       TINYINT NOT NULL COMMENT '1合约价 2市场价 3特价',
    carrier_id      BIGINT DEFAULT NULL,
    carrier_name    VARCHAR(100) DEFAULT NULL,
    pol             VARCHAR(10) NOT NULL COMMENT '起运港',
    pod             VARCHAR(10) NOT NULL COMMENT '目的港',
    route_id        BIGINT DEFAULT NULL,
    container_type  VARCHAR(10) NOT NULL COMMENT '20GP/40GP/40HC/40NR/45HC',
    base_rate       DECIMAL(12,2) NOT NULL COMMENT '基础运价USD',
    currency        CHAR(3) DEFAULT 'USD',
    effective_from  DATE NOT NULL COMMENT '生效起始',
    effective_to    DATE DEFAULT NULL COMMENT '生效截止NULL长期',
    cut_off_day     INT DEFAULT 0 COMMENT '截关天数开船前N天',
    transit_days    INT DEFAULT NULL COMMENT '航程天',
    schedule        VARCHAR(200) DEFAULT NULL COMMENT '船期频率',
    status          TINYINT DEFAULT 1 COMMENT '0停用 1启用 2已过期',
    priority        INT DEFAULT 0 COMMENT '优先级越大越优先',
    remark          VARCHAR(500) DEFAULT NULL,
    created_by      BIGINT DEFAULT NULL,
    created_at      DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at      DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    deleted         TINYINT DEFAULT 0,
    INDEX idx_pol_pod (pol, pod),
    INDEX idx_container (container_type),
    INDEX idx_effective (effective_from, effective_to),
    INDEX idx_tenant_carrier (tenant_id, carrier_id)
) COMMENT='海运费率表';

-- ========================================
-- 附加费率表 (BAF/CAF/THC/DDC/DOC/WRS/SEAL等)
-- ========================================
CREATE TABLE surcharge (
    id              BIGINT AUTO_INCREMENT PRIMARY KEY,
    freight_rate_id BIGINT NOT NULL,
    surcharge_code  VARCHAR(20) NOT NULL COMMENT '附加费代码',
    surcharge_name  VARCHAR(50) NOT NULL,
    calc_method     TINYINT NOT NULL DEFAULT 1 COMMENT '1固定金额 2按箱 3按吨 4按运价百分比',
    amount          DECIMAL(12,4) DEFAULT 0,
    currency        CHAR(3) DEFAULT 'USD',
    effective_from  DATE NOT NULL,
    effective_to    DATE DEFAULT NULL,
    status          TINYINT DEFAULT 1,
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_freight_rate_id (freight_rate_id)
) COMMENT='附加费率表';

-- 询价报价单(freight_quote)和承运商供应商(carrier_supplier)表DDL略

(F) 关税模块

-- ========================================
-- HS编码主表 (支持全文检索)
-- ========================================
CREATE TABLE hs_code (
    id              BIGINT AUTO_INCREMENT PRIMARY KEY,
    hs_code         VARCHAR(20) NOT NULL COMMENT '如 6109.10.00',
    version_year    VARCHAR(4) DEFAULT '2026',
    description_cn  VARCHAR(500) NOT NULL COMMENT '中文名称',
    description_en  VARCHAR(500) DEFAULT NULL COMMENT '英文名称',
    unit_1          VARCHAR(20) DEFAULT NULL COMMENT '法定第一计量单位',
    unit_2          VARCHAR(20) DEFAULT NULL COMMENT '法定第二计量单位',
    elements        TEXT DEFAULT NULL COMMENT '申报要素JSON结构化',
    ciq_elements    TEXT DEFAULT NULL COMMENT 'CIQ申报要素',
    supervision_cond VARCHAR(200) DEFAULT NULL COMMENT '监管条件A入境B出境等',
    category_path   VARCHAR(200) DEFAULT NULL COMMENT '分类路径',
    import_tax_note VARCHAR(500) DEFAULT NULL,
    export_tax_note VARCHAR(500) DEFAULT NULL,
    status          TINYINT DEFAULT 1,
    created_at      DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at      DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    FULLTEXT INDEX ft_hs_desc (description_cn, description_en),
    UNIQUE KEY uk_hs_version (hs_code, version_year)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='HS编码主表';

-- ========================================
-- 关税税率表
-- ========================================
CREATE TABLE customs_tariff (
    id                      BIGINT AUTO_INCREMENT PRIMARY KEY,
    hs_code                 VARCHAR(20) NOT NULL,
    version_year            VARCHAR(4) DEFAULT '2026',
    country_code            VARCHAR(10) NOT NULL COMMENT '目标国家地区',
    country_name            VARCHAR(50) DEFAULT NULL,
    trade_type              VARCHAR(10) DEFAULT 'IMPORT' COMMENT 'IMPORT/EXPORT',
    mfn_duty_rate           DECIMAL(8,6) DEFAULT 0 COMMENT '最惠国税率',
    general_duty_rate       DECIMAL(8,6) DEFAULT 0 COMMENT '普通税率',
    preferential_duty_rate  DECIMAL(8,6) DEFAULT 0 COMMENT '协定优惠税率',
    vat_rate                DECIMAL(8,6) DEFAULT 0 COMMENT '增值税率',
    consumption_tax_rate    DECIMAL(8,6) DEFAULT 0 COMMENT '消费税税率',
    anti_dumping_duty       DECIMAL(8,6) DEFAULT 0 COMMENT '反倾销税税率',
    effective_from          DATE NOT NULL,
    effective_to            DATE DEFAULT NULL,
    policy_note             VARCHAR(500) DEFAULT NULL COMMENT 'FTA优惠安排等',
    created_at              DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at              DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_hs_country (hs_code, country_code),
    INDEX idx_country (country_code)
) COMMENT='关税税率表';

-- 关税预估记录(duty_estimate)表DDL略

(G) 财务结算模块

-- ========================================
-- 财务账单主表 (AR/AP)
-- ========================================
CREATE TABLE finance_bill (
    id                    BIGINT AUTO_INCREMENT PRIMARY KEY,
    tenant_id             BIGINT NOT NULL,
    bill_no               VARCHAR(40) NOT NULL COMMENT '账单编号',
    bill_type             TINYINT NOT NULL COMMENT '1应收AR 2应付AP',
    bill_category         VARCHAR(20) DEFAULT NULL COMMENT 'FREIGHT/CUSTOMS/WAREHOUSE/SURCHARGE/OTHER',
    order_id              BIGINT DEFAULT NULL COMMENT '关联运单',
    partner_id            BIGINT NOT NULL COMMENT '往来单位ID',
    partner_name          VARCHAR(200) DEFAULT NULL,
    partner_type          TINYINT DEFAULT 1 COMMENT '1客户 2供应商',
    subtotal              DECIMAL(14,2) DEFAULT 0.00,
    tax_amount            DECIMAL(14,2) DEFAULT 0.00,
    total_amount          DECIMAL(14,2) NOT NULL,
    currency              CHAR(3) DEFAULT 'CNY',
    exchange_rate         DECIMAL(12,6) DEFAULT 1.000000,
    cny_amount            DECIMAL(14,2) DEFAULT NULL COMMENT '折合人民币',
    billing_period_start  DATE DEFAULT NULL,
    billing_period_end    DATE DEFAULT NULL,
    due_date              DATE DEFAULT NULL COMMENT '到期日',
    bill_status           TINYINT DEFAULT 0 COMMENT '0待审核 1已确认 2部分结清 3已结清 4作废',
    paid_amount           DECIMAL(14,2) DEFAULT 0.00,
    unpaid_amount         DECIMAL(14,2) GENERATED ALWAYS AS (total_amount - paid_amount) STORED,
    invoice_no            VARCHAR(50) DEFAULT NULL,
    remark                VARCHAR(500) DEFAULT NULL,
    confirmed_by          BIGINT DEFAULT NULL,
    confirmed_at          DATETIME DEFAULT NULL,
    created_by            BIGINT DEFAULT NULL,
    created_at            DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at            DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    deleted               TINYINT DEFAULT 0,
    UNIQUE KEY uk_tenant_bill (tenant_id, bill_no),
    INDEX idx_partner (partner_id),
    INDEX idx_status (bill_status),
    INDEX idx_due_date (due_date)
) COMMENT='财务账单主表';

-- ========================================
-- 结算核销记录表
-- ========================================
CREATE TABLE finance_settlement (
    id                BIGINT AUTO_INCREMENT PRIMARY KEY,
    tenant_id         BIGINT NOT NULL,
    settlement_no     VARCHAR(40) NOT NULL,
    settlement_type   TINYINT NOT NULL COMMENT '1收款 2付款 3退款 4调整',
    bill_id           BIGINT DEFAULT NULL,
    partner_id        BIGINT NOT NULL,
    partner_name      VARCHAR(200) DEFAULT NULL,
    settlement_amount DECIMAL(14,2) NOT NULL,
    currency          CHAR(3) DEFAULT 'CNY',
    payment_method    VARCHAR(20) DEFAULT NULL COMMENT 'CASH/BANK_TRANSFER/CHECK/ALIPAY/WECHAT',
    account_name      VARCHAR(100) DEFAULT NULL,
    account_number    VARCHAR(50) DEFAULT NULL,
    bank_name         VARCHAR(100) DEFAULT NULL,
    transaction_ref   VARCHAR(50) DEFAULT NULL COMMENT '交易流水号',
    transaction_date  DATE DEFAULT NULL,
    settlement_status TINYINT DEFAULT 0 COMMENT '0待审核 1已审核 2已驳回',
    attachment_url    VARCHAR(500) DEFAULT NULL COMMENT '凭证附件',
    remark            VARCHAR(500) DEFAULT NULL,
    approved_by       BIGINT DEFAULT NULL,
    approved_at       DATETIME DEFAULT NULL,
    created_by        BIGINT DEFAULT NULL,
    created_at        DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at        DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    deleted           TINYINT DEFAULT 0,
    UNIQUE KEY uk_tenant_settle (tenant_id, settlement_no),
    INDEX idx_bill_id (bill_id)
) COMMENT='结算核销记录表';

-- 发票(finance_invoice)和账单明细(finance_bill_item)表DDL略

3.3 分库分表策略

分库: 按tenant_id取模 -> 4个数据库实例 (logistics_db_0 ~ 3)
分表:
  - shipment_order        -> 16张表 (order_id取模)
  - inventory             -> 16张表 (sku_id取模)
  - inventory_transaction -> 32张表 (时间范围+取模)
  - order_tracking         -> 16张表 (order_id取模)
  - operation_log         -> 32张表 (按月分区)
中间件: ShardingSphere-JDBC (客户端分片) 或 MyCat (代理层)

4. 核心业务流程

4.1 商家入驻流程

[提交资料] --> [资质审核] --> [套餐选择] --> [开通账号]
  |                |               |               |
  公司名称          营业执照        免费版/标准版     创建管理员
  统一社会信用码    法人身份证      专业版/企业版     初始密码绑定手机
  联系方式/地址     货运资质证明     付费/试用开通    邮件通知

状态流转:
PENDING_REVIEW(待审核)
  --> APPROVED(审核通过)
  --> REJECTED(驳回补交资料)
  --> PACKAGE_SELECTED(已选套餐)
  --> ACTIVE(已激活/可使用)
  --> SUSPENDED(欠费停用)
  --> CLOSED(注销)

4.2 一票货运完整流程（海运出口为例）-- 最核心流程

===== 阶段1: 询价 =====
客户发起询价(起运港/目的港/箱型箱量/货好日期/贸易条款)
    --> 货代内部核价(匹配费率+附加费+船期查询+利润测算)
    --> 特价申请审批(如需)
    --> 发送报价给客户(报价单/有效期/总价/交货条款)
    --> 客户确认/还价/接受

===== 阶段2: 接单 =====
客户确认下单 --> 创建正式运单(运单号生成)
    --> 补充发货人/收货人信息
    --> 录入货物明细(品名/数量/体积重量/HS Code)
    --> 约定费用(应收/应付)
    --> 指派销售员/操作员
    --> [状态: 已确认]

===== 阶段3: 订舱 =====
向船公司/一代订舱 S/O (Shipping Order)
    --> 获取: 船名/航次/截关日/截单日/开船日
    --> [状态: 已订舱]

===== 阶段4: 做柜/拖车 =====
安排拖车(SO到码头) --> 安排装箱(工厂或仓库装柜)
    --> 获取: 柜号/封条号/装柜照片
    --> 过磅 VGM (Verified Gross Mass) 重量验证
    --> EIR 设备交接单
    --> [状态: 已做柜]

===== 阶段5: 报关 =====
准备报关单证(发票/箱单/合同/委托书/申报要素)
    --> 电子申报(单一窗口/QP系统)
    --> 报关要素(HS编码/价格/产地/用途)
    --> 海关审单(通过/查验/改单)
    --> [状态: 已报关/已放行]

===== 阶段6: 装船离港 =====
装船 Loading on Vessel
    --> 获取 MBL/HBL (正本/电放)
    --> 船后发 DEPARTURE NOTICE 给客户
    --> [状态: 运输中]

===== 阶段7: 到港换单 =====
到港通知 Arrival Notice
    --> 客户换单换取 D/O (Delivery Order)
    --> 缴纳港杂费 THC
    --> 进口报关(如是进口业务)
    --> [状态: 到港待提]

===== 阶段8: 配送交付 =====
安排派送(提货/拖车/Last Mile Delivery)
    --> 签收 POD (Proof of Delivery)
    --> 回传签收单拍照留底
    --> [状态: 已完成]

===== 阶段9: 结算归档 =====
费用核对 --> 生成账单 --> 客户确认 --> 开具发票
    --> 收款核销 --> 利润核算 --> 单据归档

4.3 运单状态机定义

状态枚举:
  DRAFT(0,草稿)         --> 可编辑未提交
  CONFIRMED(1,已确认)    --> 客户确认下单
  BOOKED(2,已订舱)       --> S/O已获取
  CONTAINER_READY(3,已做柜) --> 装柜VGM完成
  CUSTOMS_CLEARED(4,已报关) --> 报关放行
  IN_TRANSIT(5,运输中)   --> 已装船在途
  ARRIVED(6,到港待提)    --> 到达目的港
  COMPLETED(7,已完成)    --> 签收交付
  CANCELLED(-1,已取消)   --> 作废

合法转换路径:
  DRAFT --> CONFIRMED | CANCELLED
  CONFIRMED --> BOOKED | CANCELLED
  BOOKED --> CONTAINER_READY | CANCELLED
  CONTAINER_READY --> CUSTOMS_CLEARED
  CUSTOMS_CLEARED --> IN_TRANSIT
  IN_TRANSIT --> ARRIVED
  ARRIVED --> COMPLETED

4.4 财务结算流程

运单产生应收/应付费用
    --> 月末/票票对账规则触发
    --> 生成 AR/AP 账单
    --> 账单审核
    --> 客户/供应商确认对账单
    --> 开具发票(电子/纸质)
    --> 收/付款(线上/线下)
    --> 收款核销(部分/全额/预收)
    --> 利润核算(收入-成本=毛利)

4.5 关税预估流程

输入: 品名关键词 + 原产地 + 目的国 + 货值 + 数量
    --> ES模糊匹配HS编码(推荐Top3)
    --> 用户选择/修正HS编码
    --> 查询目标国税率表
    --> 计算公式:
        关税 = 申报价值 x 关税税率
        增值税 = (申报价值 + 关税) x 增值税率
        消费税 = (申报价值 + 关税) / (1 - 消费税率) x 消费税率
        附加税 = 反倾销税 + 反补贴税
    --> 自动获取央行当日汇率中间价
    --> 输出: 关税预估报告(各税费明细)

5. 技术选型建议

5.1 技术选型总览

层级	技术选型	备选方案	选型理由
前端框架	Vue 3 + TypeScript + Vite	React + Next.js	国内货代行业Vue生态更成熟，学习曲线平缓
UI组件库	Element Plus	Ant Design Vue	企业级后台首选，组件丰富
移动端	uni-app (Vue3)	Flutter/Taro	一套代码多端发布(小程序/H5/App)
构建工具	Vite 5.x	Webpack	开发体验好，HMR极快
后端框架	Spring Boot 3.2 + Spring Cloud Alibaba 2023	Go (Gin/Kratos)	生态成熟，微服务体系完善，团队易招聘
ORM框架	MyBatis-Plus	JPA/Hibernate	SQL灵活可控，适合复杂业务查询
API网关	Spring Cloud Gateway	Kong / APISIX	与Spring Cloud生态无缝集成
注册/配置中心	Nacos 2.x	Consul / Eureka	阿里开源，功能全面，中文社区活跃
消息队列	RocketMQ 5.x	Kafka / RabbitMQ	事务消息支持，适合金融场景
分布式缓存	Redis 7.x Cluster	Hazelcast	数据结构丰富，性能卓越
搜索引擎	Elasticsearch 8.x	OpenSearch	HS编码全文检索、日志检索必备
关系数据库	PostgreSQL / MySQL 8.0	TiDB	成熟稳定，分库分表方案成熟
时序/OLAP	ClickHouse	Druid/Doris	报表聚合分析，查询速度极快
对象存储	MinIO (私有化) / Aliyun OSS (云端)	AWS S3	文档单证存储
文档数据库	MongoDB	-	存储非结构化日志和文件元数据
容器编排	Kubernetes 1.28+	Docker Swarm	行业标准，云原生必备
CI/CD	GitLab CI / Jenkins	GitHub Actions	流水线自动化
监控	Prometheus + Grafana	Datadog	开源标配，指标采集丰富
日志	PLFK (Loki) 或 ELK (Elasticsearch+Logstash+Kibana)	日志集中收集与分析
链路追踪	SkyWalking / Zipkin	Jaeger	分布式调用链路可视化

5.2 前端技术栈详细说明

前端项目结构:
logistics-web-admin/          (运营管理后台 - Vue3)
  src/
    api/                      (Axios接口封装)
    assets/                   (静态资源)
    components/               (公共组件)
      Table/                  (通用表格封装)
      Upload/                 (文件上传)
      FormDesigner/           (表单设计器)
    views/                    (页面视图)
      tenant/                 (商家管理)
      order/                  (运单管理)
      freight/                (海运费管理)
      customs-duty/           (关税管理)
      warehouse/              (仓库作业)
      clearance/              (清关管理)
      finance/                (财务结算)
      dashboard/              (数据看板)
      system/                 (系统设置)
    stores/                   (Pinia状态管理)
    router/                   (Vue Router)
    utils/                    (工具函数)
    layouts/                  (布局组件)

logistics-web-merchant/       (商家端 - Vue3)
  类似结构，功能子集

logistics-mobile/            (移动端H5 - uni-app/Vue3)
  pages/                     (页面)
  components/                (组件)

5.3 后端技术栈详细说明

后端工程结构(Maven多模块):
logistics-parent/            (父POM - 版本管理)
  logistics-common/          (公共模块 - 工具类/常量/异常/注解)
  logistics-gateway/         (API网关)
  logistics-auth/            (认证授权服务)
  logistics-tenant/          (租户服务)
  logistics-order/           (运单服务)
  logistics-freight/         (海运费服务)
  logistics-customs-duty/    (关税服务)
  logistics-warehouse/       (仓库服务)
  logistics-clearance/       (清关服务)
  logistics-finance/         (财务服务)
  logistics-notification/    (通知服务)
  logistics-dashboard/       (看板服务)
  logistics-file/            (文件服务)
  logistics-api/             (Feign客户端接口定义)

每个服务的内部结构:
  src/main/java/com/logistics/xxx/
    XxxApplication.java      (启动类)
    controller/               (REST控制器)
    service/                  (业务逻辑接口)
    service/impl/             (业务逻辑实现)
    mapper/                   (MyBatis Mapper接口)
    entity/                   (数据库实体)
    dto/                      (数据传输对象)
    vo/                       (视图对象)
    config/                   (配置类)
    interceptor/              (拦截器 - 如租户上下文注入)
    enums/                    (枚举)
    exception/                (自定义异常)
  src/main/resources/
    mapper/                   (MyBatis XML映射文件)
    application.yml           (配置文件)
    bootstrap.yml             (bootstrap配置)

6. API 设计概要

6.1 API 设计规范

Base URL: https://api.logistics-saas.com/v1
认证方式: Bearer Token (JWT)
请求头: Authorization: Bearer {token}
租户标识: X-Tenant-Id: {tenantId} (可选，也可从Token解析)
响应格式: 统一JSON格式

统一响应结构:
{
  "code": 200,              // 业务码 200成功 其他为错误码
  "message": "success",     // 提示信息
  "data": {},               // 业务数据
  "timestamp": 1717200000000,
  "traceId": "abc123"       // 链路追踪ID
}

分页响应:
{
  "code": 200,
  "data": {
    "list": [],
    "total": 100,
    "pageNum": 1,
    "pageSize": 20,
    "totalPages": 5
  }
}

6.2 各模块 API 清单

(A) 认证模块 /auth

方法	路径	说明
POST	/auth/login	用户登录(账号密码)
POST	/auth/login/sms	手机验证码登录
POST	/auth/register	商家注册(提交入驻申请)
POST	/auth/logout	登出(Token加入黑名单)
POST	/auth/token/refresh	刷新Token
POST	/auth/password/reset	重置密码
GET	/auth/captcha	获取图形验证码
POST	/auth/sms/code	发送短信验证码
GET	/auth/user/info	获取当前用户信息
PUT	/auth/user/password	修改密码
GET	/auth/user/menus	获取当前用户菜单权限
POST	/auth/oauth/{provider}	第三方OAuth登录(微信/钉钉)

(B) 租户/商家模块 /tenant

方法	路径	说明
GET	/tenant/profile	获取当前租户信息
PUT	/tenant/profile	更新租户信息
POST	/tenant/upload/license	上传营业执照
GET	/tenant/users	用户列表(分页)
POST	/tenant/users	新增用户
PUT	/tenant/users/{id}	编辑用户
DELETE	/tenant/users/{id}	删除用户(禁用)
PUT	/tenant/users/{id}/password	重置用户密码
PUT	/tenant/users/{id}/status	启用/禁用用户
GET	/tenant/roles	角色列表
POST	/tenant/roles	新增角色
PUT	/tenant/roles/{id}	编辑角色
DELETE	/tenant/roles/{id}	删除角色
PUT	/tenant/roles/{id}/menus	分配角色菜单权限
GET	/tenant/depts	组织架构树
POST	/tenant/depts	新增部门
PUT	/tenant/depts/{id}	编辑部门
GET	/tenant/packages	可用套餐列表
POST	/tenant/upgrade	升级/续费套餐
GET	/tenant/usage	租户用量统计
GET	/tenant/config	获取租户配置
PUT	/tenant/config	更新租户配置

(C) 运单/订单模块 /orders

方法	路径	说明
GET	/orders	运单列表(多条件筛选分页)
POST	/orders	创建运单
GET	/orders/{orderId}	运单详情(含货物明细/集装箱/费用)
PUT	/orders/{orderId}	更新运单
DELETE	/orders/{orderId}	取消运单
POST	/orders/{orderId}/submit	提交确认运单
POST	/orders/{orderId}/copy	复制运单
POST	/orders/{orderId}/items	添加货物明细
PUT	/orders/{orderId}/items/{itemId}	编辑货物明细
DELETE	/orders/{orderId}/items/{itemId}	删除货物明细
POST	/orders/{orderId}/containers	添加集装箱
PUT	/orders/{orderId}/containers/{cId}	编辑集装箱信息
DELETE	/orders/{orderId}/containers/{cId}	删除集装箱
POST	/orders/{orderId}/status/change	状态变更(驱动工作流)
GET	/orders/{orderId}/tracking	物流轨迹
POST	/orders/{orderId}/tracking	手动添加轨迹
GET	/orders/{orderId}/timeline	运单时间轴(关键节点)
GET	/orders/export	导出运单列表(Excel)
POST	/orders/batch/status	批量更新状态
GET	/orders/statistics	运单统计数据
POST	/orders/{orderId}/attach
ments	上传运单附件
GET	/orders/{orderId}/fees	运单费用列表(应收/应付)
POST	/orders/{orderId}/fees	添加费用项

(D) 海运费管理模块 /freight

方法	路径	说明
GET	/freight/rates	费率列表查询(多条件筛选)
POST	/freight/rates	新增费率
PUT	/freight/rates/{rateId}	编辑费率
DELETE	/freight/rates/{rateId}	删除/停用费率
GET	/freight/rates/{rateId}/surcharges	费率关联的附加费列表
POST	/freight/rates/{rateId}/surcharges	添加附加费
PUT	/freight/surcharges/{id}	编辑附加费
DELETE	/freight/surcharges/{id}	删除附加费
GET	/freight/quotes	询价/报价单列表
POST	/freight/quotes	创建询价单
POST	/freight/quotes/{quoteId}/quote	执行核价并生成报价
POST	/freight/quotes/{quoteId}/accept	客户接受报价
POST	/freight/quotes/{quoteId}/reject	客户拒绝报价
GET	/freight/quotes/{quoteId}/convert-to-order	将报价转为正式运单
GET	/freight/schedules	船期查询(船名航次/截关日等)
POST	/freight/schedules	维护船期信息
GET	/freight/ports	港口列表(支持模糊搜索)
GET	/freight/routes	航线列表
GET	/freight/carriers	承运商/供应商列表
POST	/freight/carriers	新增承运商
PUT	/freight/carriers/{id}	编辑承运商
GET	/freight/quick-quote	快速询价接口(输入POL/POD/箱型->返回参考价)

(E) 关税管理模块 /customs-duty

方法	路径	说明
GET	/customs-duty/hs-codes	HS编码查询(关键词模糊搜索)
GET	/customs-duty/hs-codes/{hsCode}	HS编码详情(含申报要素)
GET	/customs-duty/hs-codes/search/fulltext	HS编码全文检索(ES)
GET	/customs-duty/tariffs	税率表查询(HS+国家)
GET	/customs-duty/tariffs/{country}	某国税率总览
POST	/customs-duty/tariffs	新增/导入税率数据
POST	/customs-duty/estimate	关税预估计算
GET	/customs-duty/estimates	预估记录列表
GET	/customs-duty/estimates/{id}	预估详情报告
POST	/customs-duty/estimates/{id}/confirm	确认预估结果
GET	/customs-duty/exchange-rate	获取汇率(央行中间价)
POST	/customs-duty/policies	税率政策变更录入
GET	/customs-duty/policies/alerts	政策变更预警列表

(F) 仓库作业模块 /warehouse

方法	路径	说明
GET	/warehouse/list	仓库列表
POST	/warehouse	新增仓库
PUT	/warehouse/{whId}	编辑仓库
GET	/warehouse/{whId}/locations	库位列表
POST	/warehouse/{whId}/locations	批量新增库位
PUT	/warehouse/locations/{locId}	编辑库位状态
GET	/warehouse/skus	商品SKU列表
POST	/warehouse/skus	新增SKU
PUT	/warehouse/skus/{skuId}	编辑SKU
GET	/warehouse/inventory	库存查询(多条件)
GET	/warehouse/inventory/{invId}	库存详情(含批次)
POST	/warehouse/inventory/adjust	库存调整(盘点差异)
POST	/warehouse/inventory/freeze	冻结库存
POST	/warehouse/inventory/unfreeze	解冻库存
GET	/warehouse/receipts	入库单列表
POST	/warehouse/receipts	创建入库单
POST	/warehouse/receipts/{receiptId}/receive	执行收货操作
POST	/warehouse/receipts/{receiptId}/putaway	执行上架操作
GET	/warehouse/receipts/{receiptId}/items	入库明细
GET	/warehouse/shipments	出库单列表
POST	/warehouse/shipments	创建出库单
POST	/warehouse/shipments/{shipmentId}/pick	执行拣货
POST	/warehouse/shipments/{shipmentId}/pack	执行复核打包
POST	/warehouse/shipments/{shipmentId}/ship	确认出库
GET	/warehouse/shipments/{shipmentId}/items	出库明细
GET	/warehouse/transactions	库存变动流水
POST	/warehouse/count-sheets	创建盘点单
POST	/warehouse/count-sheets/{sheetId}/execute	执行盘点
GET	/warehouse/statistics	仓库统计(利用率/周转率等)

(G) 清关管理模块 /clearance

方法	路径	说明
GET	/clearance/declarations	报关单列表
POST	/clearance/declarations	创建报关单
GET	/clearance/declarations/{declId}	报关单详情
PUT	/clearance/declarations/{declId}	编辑报关单
DELETE	/clearance/declarations/{declId}	删除报关单
POST	/clearance/declarations/{declId}/submit	提交申报
POST	/clearance/declarations/{declId}/items	添加报关商品
PUT	/clearance/declaration-items/{itemId}	编辑报关商品
DELETE	/clearance/declaration-items/{itemId}	删除报关商品
GET	/clearance/declarations/{declId}/documents	报关附件列表
POST	/clearance/declarations/{declId}/documents	上报报关单证
DELETE	/clearance/documents/{docId}	删除附件
POST	/clearance/declarations/{declId}/sync-status	同步海关状态(对接单一窗口时)
POST	/clearance/declarations/{declId}/amend	申请改单
POST	/clearance/declarations/{declId}/cancel	申请删单
GET	/clearance/inspections	布控查验记录
POST	/clearance/inspections	录入查验结果
GET	/clearance/templates	报关单模板(常用申报要素)

(H) 财务结算模块 /finance

方法	路径	说明
GET	/finance/bills	账单列表(AR/AP)
POST	/finance/bills	创建账单
GET	/finance/bills/{billId}	账单详情(含明细)
PUT	/finance/bills/{billId}	编辑账单
POST	/finance/bills/{billId}/confirm	确认账单
POST	/finance/bills/{billId}/void	作废账单
POST	/finance/bills/{billId}/items	添加账单费用项
PUT	/finance/bill-items/{itemId}	编辑费用项
DELETE	/finance/bill-items/{itemId}	删除费用项
POST	/finance/bills/generate/auto	自动对账生成账单
POST	/finance/bills/generate/from-order	从运单生成账单
GET	/finance/settlements	结算记录列表
POST	/finance/settlements	创建结算(收/付款)
POST	/finance/settlements/{setId}/approve	审核结算
POST	/finance/settlements/{setId}/reject	驳回结算
GET	/finance/invoices	发票列表
POST	/finance/invoices	开具发票
POST	/finance/invoices/{invoiceId}/cancel	作废发票
POST	/finance/invoices/{invoiceId}/credit-note	红冲发票
GET	/finance/invoices/{invoiceId}/pdf	获取发票PDF
GET	/finance/receivables	应收汇总(按客户/账龄)
GET	/finance/payables	应付汇总(按供应商/账龄)
GET	/finance/profit-analysis	利润分析(按运单/客户/时间段)
GET	/finance/reports/trial-balance	试算平衡表
GET	/finance/reports/aging	账龄分析报表
GET	/finance/reports/revenue	收入报表

(I) 数据看板模块 /dashboard

方法	路径	说明
GET	/dashboard/overview	总览面板(今日/本周/本月核心指标)
GET	/dashboard/order-trends	订单量趋势图
GET	/dashboard/revenue-trends	收入趋势图
GET	/dashboard/profit-trends	利润趋势图
GET	/dashboard/order-status-dist	运单状态分布
GET	/dashboard/top-customers	TOP客户排行
GET	/dashboard/top-routes	热门航线排行
GET	/dashboard/port-throughput	港口吞吐量统计
GET	/dashboard/alerts	业务预警(即将到期/异常订单等)
GET	/dashboard/kpi	KPI指标卡集合
POST	/dashboard/reports/custom	自定义报表查询
GET	/dashboard/reports/{reportId}	获取报表数据
GET	/dashboard/customer-portrait	客户画像分析
GET	/dashboard/churn-prediction	流失预警

(J) 文件服务模块 /files

方法	路径	说明
POST	/files/upload	文件上传(分片/断点续传)
GET	/files/{fileId}	文件下载
GET	/files/{fileId}/preview	在线预览
GET	/files/{fileId}/info	文件信息(元数据)
DELETE	/files/{fileId}	删除文件
POST	/files/{fileId}/thumbnail	获取缩略图
GET	/files/list	文件列表(按业务对象)
POST	/files/batch-upload	批量上传
GET	/files/report-templates	报表模板列表
POST	/files/reports/generate	触发报表生成任务
GET	/files/reports/tasks/{taskId}	查询导出任务进度
GET	/files/reports/tasks/{taskId}/download	下载生成的报表

(K) 消息通知模块 /notifications

方法	路径	说明
GET	/notifications	当前用户消息列表(分页,未读优先)
GET	/notifications/{msgId}	消息详情
PUT	/notifications/{msgId}/read	标记已读
PUT	/notifications/read-all	全部标记已读
GET	/notifications/unread-count	未读消息数量
POST	/notifications/send	发送消息(管理员用)
GET	/notification-templates	消息模板列表
POST	/notification-templates	新增消息模板
PUT	/notification-templates/{tplId}	编辑模板
GET	/notification-settings	用户通知偏好设置
PUT	/notification-settings	更新通知偏好
GET	/notifications/sms/logs	短信发送记录
GET	/notifications/email/logs	邮件发送记录

7. 部署架构与运维

7.1 Kubernetes 部署拓扑

                          Internet
                             |
                     [CDN + WAF + DNS]
                             |
                    [Load Balancer / SLB]
                             |
                 +------------+-------------+
                 |     Kubernetes Cluster      |
                 |   Master Node x3 (HA)       |
                 |   Worker Node x N (弹性伸缩) |
                 +------------+-------------+
                              |
        +----------+----------+-----------+-----------+
        |          |          |           |           +
   [Gateway    [Auth Svc] [Tenant Svc] [Order Svc] ...各微服务
    Pod x3]     Pod x2]     Pod x2]     Pod x3]
        |          |          |           |
        +----------+----------+-----------+
                             |
        +--------------------+---------------------+
        |                    |                     |
   [Redis Cluster]    [MySQL Primary+Replica]  [RocketMQ Broker]
   6节点(3主3从)      1主2从(半同步)         2主2从

7.2 环境规划

环境	用途	K8s集群	数据库	配置
dev	开发环境	单节点(minikube)	MySQL单机	dev profile
test	测试环境	3节点集群	MySQL主从	test profile
staging	预发布环境	5节点集群	与生产同构(小规格)	staging profile
prod	生产环境	多AZ高可用集群	MySQL主从+分库分表	prod profile

7.3 CI/CD 流水线

代码提交(GitLab/GitHub)
    --> 触发Webhook
    --> Jenkins Pipeline:
        Stage 1: 代码检查(SonarQube静态分析 + CheckStyle)
        Stage 2: 单元测试(JUnit 5 + Mockito,覆盖率>80%)
        Stage 3: 构建镜像(Maven打包 -> Docker Build -> 推送Harbor)
        Stage 4: 部署到Test环境(kubectl apply)
        Stage 5: 集成测试(Postman/Newman API自动化测试)
        Stage 6: 人工审批(--> Staging --> Prod)
        Stage 7: 生产部署(滚动更新 RollingUpdate,灰度发布)
        Stage 8: 部后验证(Smoke Test + 性能基线对比)

镜像版本策略: {服务名}:{分支名}-{build号}-{commit短hash}
例: logistics-order:develop-20260601-a1b2c3d

7.4 监控告警体系

监控层次:
  L1 基础设施: K8s节点CPU/内存/磁盘/网络(Kubelet Metrics + node-exporter)
  L2 中间件: Redis/MQ/MySQL/ES 各项健康指标(Prometheus Exporter)
  L3 应用层: JVM GC/线程池/QPS/RT/Error Rate(Micrometer + Spring Boot Actuator)
  L4 业务层: 运单量/注册数/支付成功率(自定义Business Metrics)
  L5 日志: 全链路日志集中收集(PLFK/Loki)

告警通道:
  - P0紧急: 电话 + 短信 + 钉钉/企微 + 邮件 (服务不可用/数据丢失风险)
  - P1严重: 钉钉/企微 + 短信 + 邮件 (RT>P99阈值/错误率>5%)
  - P2一般: 钉钉/企微 + 邮件 (资源使用率>80%/队列积压)
  - P3提醒: 邮件 (证书即将到期/磁盘空间预警)

关键Dashboard:
  - 服务全局大盘(所有服务健康状态一览)
  - API性能大盘(QPS/RT/P99/错误率趋势)
  - 数据库性能大盘(慢SQL/连接数/主从延迟)
  - 业务运营大盘(实时订单/收入/活跃用户)

8. 安全设计

8.1 安全架构层次

L7 应用层安全:
  - JWT Token认证(RS256非对称签名, Access Token 30min + Refresh Token 7天)
  - RBAC权限模型(角色-菜单-按钮三级粒度)
  - 接口鉴权(Spring Security + 自定义注解 @RequiresPermissions)
  - SQL注入防护(MyBatis参数化查询 #{} 禁止 ${})
  - XSS防护(前端转义 + 后端输入过滤 + CSP头)
  - CSRF防护(Token机制 + SameSite Cookie)
  - 敏感数据脱敏(手机号/身份证/银行卡号中间掩码)

L4 传输层安全:
  - HTTPS全站加密(TLS 1.3)
  - 证书管理(Let's Encrypt 或企业CA)
  - API网关限流(令牌桶算法, 按租户+IP维度)
  - WAF防火墙规则(SQL注入/XSS/CC攻击/恶意爬虫拦截)

L3 网络层安全:
  - VPC网络隔离(不同环境独立VPC)
  - 安全组规则(最小开放端口原则)
  - K8s NetworkPolicy(服务间访问控制)
  - 内网服务不暴露公网(仅通过内网LB通信)

L2 数据安全:
  - 敏感字段AES-256加密存储(密码/证件号/银行账号)
  - 数据库连接加密(SSL/TLS)
  - Redis访问密码认证 + ACL
  - 定期数据库备份(每日全量 + 实时Binlog增量)
  - 备份异地容灾(跨可用区/跨地域)

L1 审计合规:
  - 全操作日志记录(operation_log表)
  - 敏感操作二次验证(删除/大额付款需短信/OTP确认)
  - 数据导出审批流程(大批量数据下载需审批)
  - 租户数据隔离校验(每条SQL强制追加tenant_id)
  - GDPR/个人信息保护合规(数据可删除/可导出)

8.2 多租户安全措施

1. 租户上下文自动注入:
   - 通过Gateway过滤器或Feign拦截器
   - 从JWT中解析tenant_id
   - 注入ThreadLocal TenantContext
   - MyBatis拦截器自动追加 WHERE tenant_id = ?

2. 跨租户数据防越权:
   - 所有查询强制带tenant_id条件
   - 更新/删除操作校验数据归属
   - 接口返回数据做租户归属校验

3. 租户间资源隔离(可选增强):
   - VIP租户独立Schema或独立Database
   - 敏感财务数据物理隔离
   - 大租户独享计算资源(命名空间配额限制)

9. 非功能性需求

9.1 性能指标

指标	目标值	说明
API平均响应时间	< 200ms (P50)	一般接口
API响应时间P99	< 1000ms	99分位
并发用户数	支持 5000+ 在线	数千商家同时使用
QPS	核心接口 > 5000 QPS	峰值承载能力
页面加载时间	< 2s (首屏)	前端渲染完成
文件上传	支持断点续传, 单文件最大 200MB	单证/图片上传
批量导出	10万行以内 Excel < 30秒	异步生成 + 下载通知

9.2 可用性指标

指标	目标值	措施
系统可用性	>= 99.9% (年宕机 < 8.76小时)	多AZ部署, 服务自愈, 故障转移
RTO (恢复时间目标)	< 30分钟	灾备切换, 快速回滚
RPO (恢复点目标)	< 5分钟	实时Binlog备份
计划内维护	不影响业务(滚动升级)	零停机部署
数据可靠性	99.999999% (11个9)	多副本存储 + 跨机架

9.3 可扩展性

水平扩展能力:
  - 无状态应用服务: K8s HPA自动扩缩容(基于CPU/内存/QPS指标)
  - 数据库读写分离: 1主N从, 读请求路由到从库
  - 分库分表: ShardingSphere, 按租户ID分库, 按业务ID分表
  - 缓存层: Redis Cluster, 动态增加节点
  - 消息队列: RocketMQ Broker动态扩展
  - ES集群: 增加Data Node和Client Node
  - 对象存储: MinIO分布式模式, 动态添加Disk

垂直扩展预留:
  - 微服务可按功能进一步拆分(如仓库服务拆为入库/出库/盘点子服务)
  - 国际化多语言支持(i18n框架)
  - 多币种/多税率体系扩展

9.4 数据容量规划（初期~3年）

数据类型	初期(1年内)	1年后	3年后	存储方案
租户数据	~1000家	~3000家	~8000家	MySQL (分库)
运单数据	~10万票	~80万票	~300万票	MySQL (16分表)
货物明细	~50万行	~400万行	~1500万行	MySQL (分表)
报关单	~8万份	~60万份	~200万份	MySQL (分表)
库存记录	~20万条	~150万条	~500万条	MySQL + Redis热数据
库存流水	~100万条	~800万条	~3000万条	MySQL (32分表)
物流轨迹	~50万条	~400万条	~1500万条	MySQL (分表) + ES
财务账单	~15万张	~120万张	~400万张	MySQL
操作日志	~500万条	~4000万条	~1.5亿条	MongoDB / ClickHouse
文件存储	~500GB	~3TB	~10TB	MinIO/OSS
HS编码数据	~12万条	~15万条	~18万条	MySQL + ES全文索引

9.5 合规与审计

- 数据留存策略: 核心业务数据永久保存, 日志数据保留180天可配置
- 操作留痕: 所有关键操作记录操作人/时间/IP/变更前后值
- 数据导出审计: 大批量数据导出需要审批并记录
- 密码策略: 最少8位, 必须包含大小写字母+数字+特殊字符, 90天过期
- 会话管理: 空闲30分钟自动登出, 单设备登录互踢(可选)
- IP白名单: 可选功能, 限制租户只能从指定IP访问
- 版本管理: 数据库DDL变更必须走Flyway/Liquibase版本化管理

附录：项目实施路线建议

Phase 1 - MVP原型（第1-2个月）

搭建基础框架：Spring Cloud Alibaba + Vue3 脚手架
实现核心模块：租户管理 + 运单CRUD + 基础海运费查询
数据库初始化脚本 + 种子数据
基础认证与RBAC

Phase 2 - 核心业务闭环（第3-4个月）

完整运单生命周期（接单 -> 完成）
海运费报价完整流程（询价 -> 核价 -> 报价）
仓库基础作业（入库 + 出库 + 库存）
基础财务（应收应付 + 账单）

Phase 3 - 专业功能（第5-6个月）

清关管理（报关单 + 单证）
关税管理（HS编码 + 税率 + 预估引擎）
数据看板（统计图表 + 导出）
消息通知（站内信 + 短信 + 邮件）

Phase 4 - 运营优化（第7-8个月）

高级BI分析（自定义报表 + 客户画像）
开放平台（API对外开放）
移动端适配（小程序 + App）
性能优化 + 压力测试

文档结束

本架构设计文档涵盖国际货运代理 SaaS 平台的完整技术方案，包括：

5层系统架构（接入/应用/中间件/数据/基础设施）

11个微服务的职责边界与调用关系

30+ 张核心数据库表的完整 DDL（覆盖商家/运单/报关/仓库/海运费/关税/财务 8大领域）

5个核心业务流程（入驻 / 一票货全程 / 结算 / 关税预估 / 状态机）

完整技术选型（前后端 / 中间件 / 数据库 / DevOps）

150+ 个 RESTful API 接口（覆盖全部 11 个业务模块）

部署/K8s/监控/安全/非功能性需求全套方案

4阶段实施路线图

69 KiB Raw Blame History Unescape Escape

国际货运代理 SaaS 平台 - 完整技术架构设计

1. 系统整体架构

1.1 架构总览图（文字描述）

1.2 架构分层说明

1.3 多租户架构模式

2. 微服务拆分方案（共11个核心服务）

2.1 服务清单

2.2 服务间调用关系

2.3 通信规范

3. 数据库核心表设计

3.1 ER 关系总览

3.2 核心表 DDL

(A) 商家/租户模块

(B) 运单/订单模块（核心大表）

(C) 报关单模块

(D) 仓库作业模块

(E) 海运费模块

(F) 关税模块

(G) 财务结算模块

3.3 分库分表策略

4. 核心业务流程

4.1 商家入驻流程

4.2 一票货运完整流程（海运出口为例）-- 最核心流程

4.3 运单状态机定义

4.4 财务结算流程

4.5 关税预估流程

5. 技术选型建议

5.1 技术选型总览

5.2 前端技术栈详细说明

5.3 后端技术栈详细说明

6. API 设计概要

6.1 API 设计规范

6.2 各模块 API 清单

(A) 认证模块 /auth

(B) 租户/商家模块 /tenant

(C) 运单/订单模块 /orders

(D) 海运费管理模块 /freight

(E) 关税管理模块 /customs-duty

(F) 仓库作业模块 /warehouse

(G) 清关管理模块 /clearance

(H) 财务结算模块 /finance

(I) 数据看板模块 /dashboard

(J) 文件服务模块 /files

(K) 消息通知模块 /notifications

7. 部署架构与运维

7.1 Kubernetes 部署拓扑

7.2 环境规划

7.3 CI/CD 流水线

7.4 监控告警体系

8. 安全设计

8.1 安全架构层次

8.2 多租户安全措施

9. 非功能性需求

9.1 性能指标

9.2 可用性指标

9.3 可扩展性

9.4 数据容量规划（初期~3年）

9.5 合规与审计

附录：项目实施路线建议

Phase 1 - MVP原型（第1-2个月）

Phase 2 - 核心业务闭环（第3-4个月）

Phase 3 - 专业功能（第5-6个月）

Phase 4 - 运营优化（第7-8个月）

69 KiB

Raw Blame History