系统概要设计文档

1. 项目概述

1.1 项目背景

BSG-WM 是一款面向仓库管理的综合性解决方案，旨在实现仓库入库、出库流程的数字化管理，并与 NetSuite ERP 系统进行无缝对接，提升企业仓储运营效率。

1.2 项目组成

组成部分	技术栈	部署方式	职责说明
后端服务	Java 25 + Spring Boot 4.0.5	容器化部署	核心业务逻辑、数据处理、NetSuite集成
前端PC管理平台	Vue 3 + TypeScript + Element Plus	静态资源部署	仓库管理后台、数据分析、日志查询
安卓APP	Android Native	APK分发	移动端扫码入库/出库操作

1.3 核心业务目标

业务目标	描述
序列号管理	实现商品序列号的全生命周期追踪（入库→在库→出库）
入库管理	采购订单转化为入库单，记录入库明细
出库管理	销售订单转化为出库单，完成发货操作
扫码操作	通过移动端APP扫描序列号完成出入库确认
NetSuite集成	与NetSuite ERP系统实时同步业务数据
日志审计	完整记录所有操作日志，支持追溯审计

2. 技术架构

2.1 系统架构图

┌─────────────────────────────────────────────────────────────────────┐
│                        外部系统层                                    │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────────┐  │
│  │  NetSuite    │    │  安卓APP     │    │   PC管理平台         │  │
│  │   ERP系统    │    │ (扫码操作)   │    │  (后台管理)          │  │
│  └──────┬───────┘    └──────┬───────┘    └──────────┬───────────┘  │
└─────────┼───────────────────┼────────────────────────┼──────────────┘
│                   │                       │
▼                   ▼                       ▼
┌─────────────────────────────────────────────────────────────────────┐
│                        API网关层                                     │
│              ┌─────────────────────────────────────┐                │
│              │         Spring Security + JWT       │                │
│              │         TokenAuthenticationFilter   │                │
│              └─────────────────────────────────────┘                │
└────────────────────────────┬────────────────────────────────────────┘
│
┌────────────────────────────▼────────────────────────────────────────┐
│                        业务服务层                                     │
│  ┌──────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────────┐ │
│  │ Auth     │ │ NetSuite     │ │ ItemSn       │ │   LogService   │ │
│  │ Service  │ │   Service    │ │   Service    │ │   (审计日志)   │ │
│  └──────────┘ └──────────────┘ └──────────────┘ └────────────────┘ │
└────────────────────────────┬────────────────────────────────────────┘
│
┌────────────────────────────▼────────────────────────────────────────┐
│                        数据访问层                                     │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐           │
│  │   JPA       │    │   Redis      │    │   JDBC       │           │
│  │ Repository  │    │   Cache      │    │   Template   │           │
│  └──────┬───────┘    └──────┬───────┘    └──────┬───────┘           │
└─────────┼───────────────────┼───────────────────┼──────────────────┘
│                   │                   │
▼                   ▼                   ▼
┌─────────────────────────────────────────────────────────────────────┐
│                        数据存储层                                     │
│        ┌──────────────────┐           ┌──────────────────┐          │
│        │    MySQL         │           │     Redis        │          │
│        │ (业务数据/日志)   │           │ (缓存/Token)     │          │
│        └──────────────────┘           └──────────────────┘          │
└─────────────────────────────────────────────────────────────────────┘

2.2 技术选型

分类	技术	版本	选型理由
语言	Java	25	LTS版本，性能稳定，支持虚拟线程
框架	Spring Boot	4.0.5	社区成熟，生态完善，便于快速构建RESTful服务
数据库	MySQL	8.0+	开源稳定，事务支持完善，适合企业级应用
缓存	Redis	7.0+	高性能缓存，支持分布式锁和数据持久化
ORM	Spring Data JPA	3.2.x	简化数据访问层开发，支持自动生成SQL
安全	Spring Security	6.2.x	成熟的安全框架，支持JWT认证
API文档	SpringDoc OpenAPI	3.0.x	自动生成API文档，便于前后端协作
监控	OpenTelemetry	2.21.x	分布式追踪、指标监控一体化方案

3. 核心业务实体

3.1 实体关系图

User ──────────────────────────────────────────────────────────┐
│                                                             │
│  1:N                                                        │
▼                                                             ▼
ItemSn ◄────────── ItemSnScanLog ─────────── ItemSnImportLog
│                     │
│                     ▼
│            ┌─────────────────────┐
│            │                     │
│            ▼                     ▼
│    ItemReceiptLog        ItemFulfillmentLog
│            │                     │
│            └─────────┬───────────┘
│                      │
│                      ▼
│            ItemFulfillmentShipStatusLog

3.2 核心实体定义

ItemSn（序列号实体）

字段名	类型	说明	约束
id	Long	主键	自增
itemSn	String	序列号	唯一，非空
itemId	String	商品ID	关联NetSuite
itemName	String	商品名称	-
itemStatus	String	状态(receipt/fulfill/inactive)	枚举
warehouseLocationId	String	仓库位置ID	-
purchaseOrderId	String	采购订单ID	-
itemReceiptId	String	入库单ID	-
salesOrderId	String	销售订单ID	-
itemFulfillmentId	String	出库单ID	-
containerNo	String	集装箱号	-
palletSn	String	托盘号	-

User（用户实体）

字段名	类型	说明	约束
id	Long	主键	自增
username	String	用户名	唯一，非空
password	String	密码（加密存储）	非空
nickname	String	昵称	-
avatar	String	头像URL	-
valid	Boolean	是否有效	默认true

ItemSnScanLog（扫描日志）

字段名	类型	说明	约束
id	Long	主键	自增
itemSn	String	扫描的序列号	非空
scanRelated	String	关联类型(IR/IF)	枚举
relatedFrId	String	关联单据ID	-
userId	Long	操作人ID	非空
username	String	操作人姓名	-
submitResult	String	提交结果(success/fail)	-
failReason	String	失败原因	-

4. 核心业务流程

4.1 入库流程

流程说明：

仓库人员使用安卓APP扫描商品序列号
系统验证序列号有效性并关联入库单
更新序列号状态为"已入库"(receipt)
同步数据至NetSuite系统
记录操作日志供审计追溯

4.2 出库流程

流程说明：

仓库人员使用安卓APP扫描待出库商品
系统验证序列号状态必须为"已入库"状态
更新序列号状态为"已出库"(fulfill)
同步数据至NetSuite系统

4.3 NetSuite单据转换流程

5. API接口设计

5.1 认证接口

API路径	HTTP方法	Controller	功能描述
/api/auth/login	POST	AuthController	用户登录
/api/auth/refresh	POST	AuthController	刷新Token
/api/auth/logout	POST	AuthController	用户登出

5.2 序列号管理接口

API路径	HTTP方法	Controller	功能描述
/api/item-sn	GET	ItemSnController	分页查询序列号列表
/api/item-sn/id	GET	ItemSnController	查询单个序列号详情
/api/item-sn	POST	ItemSnController	新增序列号
/api/item-sn/id	PUT	ItemSnController	更新序列号信息
/api/item-sn/id	DELETE	ItemSnController	删除序列号
/api/item-sn/import	POST	ItemSnController	批量导入序列号

5.3 NetSuite集成接口

API路径	HTTP方法	Controller	功能描述
/api/netsuite/record	POST	NetSuiteController	调用NetSuite REST API记录数据
/api/netsuite/query	POST	NetSuiteController	调用NetSuite SuiteQL查询
/api/netsuite/token	GET	NetSuiteController	获取NetSuite OAuth2 Token
/api/netsuite/image/upload	POST	NetSuiteController	上传图片至NetSuite
/api/netsuite/image/attach	POST	NetSuiteController	图片附加到记录

5.4 日志查询接口

API路径	HTTP方法	Controller	功能描述
/api/log/item-receipt	GET	ItemReceiptLogController	查询入库日志
/api/log/item-fulfillment	GET	ItemFulfillmentLogController	查询出库日志
/api/log/item-sn-scan	GET	ItemSnScanLogController	查询扫描日志
/api/log/login	GET	LoginLogController	查询登录日志

6. 数据库设计

6.1 核心表结构

item_sn 表（序列号表）

CREATE TABLE wm.item_sn
(
    id                      BIGINT AUTO_INCREMENT PRIMARY KEY,
    item_sn                 VARCHAR(100) NOT NULL UNIQUE,
    item_id                 VARCHAR(50),
    item_name               VARCHAR(200),
    item_status             VARCHAR(20) DEFAULT 'inactive',
    warehouse_location_id   VARCHAR(50),
    warehouse_location_name VARCHAR(200),
    purchase_order_id       VARCHAR(50),
    purchase_order_no       VARCHAR(50),
    item_receipt_id         VARCHAR(50),
    item_receipt_no         VARCHAR(50),
    sales_order_id          VARCHAR(50),
    sales_order_no          VARCHAR(50),
    item_fulfillment_id     VARCHAR(50),
    item_fulfillment_no     VARCHAR(50),
    data_file_id            VARCHAR(50),
    container_no            VARCHAR(50),
    pallet_sn               VARCHAR(50),
    create_time             DATETIME    DEFAULT CURRENT_TIMESTAMP,
    update_time             DATETIME    DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    valid                   BOOLEAN     DEFAULT TRUE,
    version                 BIGINT      DEFAULT 0
);

CREATE INDEX idx_item_sn_status ON wm.item_sn (item_status);
CREATE INDEX idx_item_sn_item_id ON wm.item_sn (item_id);

item_sn_scan_log 表（扫描日志表）

CREATE TABLE wm.item_sn_scan_log
(
    id               BIGINT AUTO_INCREMENT PRIMARY KEY,
    item_id          VARCHAR(50),
    item_sn          VARCHAR(100) NOT NULL,
    item_name        VARCHAR(200),
    scan_related     VARCHAR(20)  NOT NULL,
    related_fr_id    VARCHAR(50),
    related_fr_no    VARCHAR(50),
    related_order_id VARCHAR(50),
    related_order_no VARCHAR(50),
    container_no     VARCHAR(50),
    pallet_sn        VARCHAR(50),
    user_id          BIGINT       NOT NULL,
    username         VARCHAR(100),
    trace_id         VARCHAR(64),
    submit_result    VARCHAR(20),
    fail_reason      TEXT,
    create_time      DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE INDEX idx_scan_log_item_sn ON wm.item_sn_scan_log (item_sn);
CREATE INDEX idx_scan_log_user ON wm.item_sn_scan_log (user_id);
CREATE INDEX idx_scan_log_time ON wm.item_sn_scan_log (create_time);

user 表（用户表）

CREATE TABLE wm.user
(
    id          BIGINT AUTO_INCREMENT PRIMARY KEY,
    username    VARCHAR(100) NOT NULL UNIQUE,
    password    VARCHAR(255) NOT NULL,
    nickname    VARCHAR(100),
    avatar      VARCHAR(500),
    create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
    update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    valid       BOOLEAN  DEFAULT TRUE,
    version     BIGINT   DEFAULT 0
);

7. 安全设计

7.1 认证机制

组件	职责	说明
JWT Token	身份凭证	用户登录成功后颁发，有效期内免登录
TokenAuthenticationFilter	过滤器	拦截请求，验证Token有效性
Redis	Token存储	存储活跃Token，支持登出失效

7.2 NetSuite集成安全

安全措施	说明
OAuth 2.0	使用JWT Bearer Token方式认证
证书加密	私钥存储于配置文件，运行时加载
Token缓存	获取的OAuth2 Token缓存至Redis，有效期59分钟
请求签名	每次请求携带签名信息防止篡改

7.3 数据安全

安全措施	说明
密码加密	使用BCrypt算法加密存储
参数校验	使用Bean Validation进行输入校验
SQL注入防护	使用JPA参数化查询
XSS防护	前端自动转义，后端进行内容过滤

8. 部署与集成

8.1 依赖服务

服务	版本	用途
MySQL	8.0+	主数据库，存储业务数据
Redis	7.0+	缓存、Token存储、分布式锁
NetSuite	-	ERP系统集成

8.2 配置说明

数据库连接配置（application.yaml）

spring:
  datasource:
    url: jdbc:mysql://mysql:3306/wm?useUnicode=true&characterEncoding=UTF-8&serverTimezone=UTC
    username: ${MYSQL_USERNAME:root}
    password: ${MYSQL_PASSWORD:}
  data:
    redis:
      host: ${REDIS_HOST:redis}
      port: ${REDIS_PORT:6379}

NetSuite配置（application.yaml）

app:
  netsuite:
    oauth2:
      client-id: ${NETSUITE_OAUTH2_CLIENT_ID}
      cert-id: ${NETSUITE_OAUTH2_CERT_ID}
      account-id: ${NETSUITE_OAUTH2_ACCOUNT_ID}
      private-key-path: /conf/netsuite/oauth2/private.pem
      scope: restlets,rest_webservices,suite_analytics
    script:
      restlet-uri: https://xxx.app.netsuite.com/app/site/hosting/restlet.nl?
      image-upload: script=xxx&deploy=1
      image-attach: script=xxx&deploy=1

8.3 Docker部署

后端服务已包含Dockerfile，支持容器化部署：

FROM openjdk:25-jdk-slim
WORKDIR /app
COPY target/server-0.0.1.jar app.jar
EXPOSE 8080
ENTRYPOINT ["java", "-jar", "app.jar"]

9. 监控与日志

9.1 监控体系

监控维度	实现方式	说明
健康检查	Spring Actuator	/actuator/health
指标监控	Micrometer + OpenTelemetry	自定义指标采集
分布式追踪	OpenTelemetry	请求链路追踪
日志采集	Logback + OpenTelemetry Appender	结构化日志输出

9.2 日志分级

级别	用途	输出位置
DEBUG	开发调试信息	仅开发环境
INFO	业务操作日志	控制台+文件
WARN	警告信息	控制台+文件
ERROR	错误异常信息	控制台+文件+告警

10. 代码结构

10.1 后端目录结构

server/src/main/java/run/ice/bsg/wm/server/
├── api/                    # API接口定义
├── config/                 # 配置类
├── constant/               # 常量定义
├── controller/             # REST控制器
├── entity/                 # JPA实体类
├── enums/                  # 枚举类型
├── error/                  # 异常处理
├── filter/                 # 过滤器
├── handler/                # 异常处理器
├── helper/                 # 辅助工具类
├── interceptor/            # 拦截器
├── model/                  # 请求/响应模型
├── repository/             # 数据访问层
├── service/                # 业务服务层
├── util/                   # 通用工具类
└── ServerApplication.java  # 启动类

10.2 前端目录结构

admin/src/
├── api/                    # API接口封装
├── components/             # 公共组件
├── config/                 # 配置文件
├── directives/             # 自定义指令
├── layout/                 # 布局组件
├── router/                 # 路由配置
├── store/                  # 状态管理
├── utils/                  # 工具函数
├── views/                  # 页面视图
├── App.vue                 # 根组件
└── main.ts                 # 入口文件

11. 关键业务枚举

11.1 ActionType（操作类型）

枚举值	说明
purchaseorder_transform_itemreceipt	采购订单转入库单
customrecord_scanning_data	扫描数据提交
salesorder_transform_itemfulfillment	销售订单转出库单
patch_itemfulfillment_shipstatus	更新出库单发货状态

11.2 ItemStatus（序列号状态）

枚举值	说明
inactive	未激活
receipt	已入库
fulfill	已出库

11.3 ScanRelated（扫描关联类型）

枚举值	说明
IR	关联入库单(ItemReceipt)
IF	关联出库单(ItemFulfillment)

12. 扩展规划

12.1 可扩展功能

功能模块	描述	优先级
库存盘点	支持定期盘点和差异处理	高
库存预警	库存低于阈值时自动提醒	中
报表分析	出入库统计、库存周转率分析	中
移动端增强	支持离线操作、条码打印	低

12.2 性能优化方向

优化项	说明
读写分离	数据库主从复制，查询走从库
缓存策略	热点数据多级缓存
异步处理	日志记录等非核心操作异步化
批量操作	支持批量导入导出

文档版本: v1.0
创建日期: 2026-06-04
适用项目: BSG-WM 仓库管理系统

1. 项目概述​

1.1 项目背景​

1.2 项目组成​

1.3 核心业务目标​

2. 技术架构​

2.1 系统架构图​

2.2 技术选型​

3. 核心业务实体​

3.1 实体关系图​

3.2 核心实体定义​

4. 核心业务流程​

4.1 入库流程​

4.2 出库流程​

4.3 NetSuite单据转换流程​

5. API接口设计​

5.1 认证接口​

5.2 序列号管理接口​

5.3 NetSuite集成接口​

5.4 日志查询接口​

6. 数据库设计​

6.1 核心表结构​

7. 安全设计​

7.1 认证机制​

7.2 NetSuite集成安全​

7.3 数据安全​

8. 部署与集成​

8.1 依赖服务​

8.2 配置说明​

8.3 Docker部署​

9. 监控与日志​

9.1 监控体系​

9.2 日志分级​

10. 代码结构​

10.1 后端目录结构​

10.2 前端目录结构​

11. 关键业务枚举​

11.1 ActionType（操作类型）​

11.2 ItemStatus（序列号状态）​

11.3 ScanRelated（扫描关联类型）​

12. 扩展规划​

12.1 可扩展功能​

12.2 性能优化方向​