功能模块详细设计文档

1. 概述

本文档详细描述 BSG-WM 仓库管理系统的功能模块设计，包括前端 PC 管理平台和安卓 APP 的功能模块，以及与后端接口的对接关系。

2. 前端 PC 管理平台功能模块

2.1 功能模块总览

模块分类	模块名称	路由路径	功能描述
首页	Welcome	`/welcome`	系统首页，展示概览信息
订单管理	SN Management	`/order/item-sn`	序列号全生命周期管理
安全审计	Login Logs	`/audit/login-log`	登录日志查询
安全审计	Import SN Logs	`/audit/item-sn-import-log`	SN导入日志查询
安全审计	Upsert SN Logs	`/audit/item-sn-upsert-log`	SN更新日志查询
安全审计	Receipt Logs	`/audit/item-receipt-log`	入库日志查询
安全审计	Fulfillment Logs	`/audit/item-fulfillment-log`	出库日志查询
安全审计	Scan SN Logs	`/audit/item-sn-scan-log`	扫描日志查询
安全审计	IF Ship Status Logs	`/audit/item-fulfillment-ship-status-log`	发货状态日志查询
系统管理	User Management	`/system/user`	用户管理
系统管理	APP Configuration	`/system/app-config`	应用配置
账户设置	Account Settings	`/account-settings`	个人设置
权限管理	Page Permission	`/permission/page`	页面权限
权限管理	Button Permission	`/permission/button`	按钮权限

2.2 订单管理模块 - SN Management

功能定位：商品序列号的全生命周期管理，包括查询、新增、编辑、导入、导出等操作。

页面结构：

┌─────────────────────────────────────────────────────────────────┐
│                        搜索区域                                  │
│  [ID] [Item SN] [Item ID] [Item Name] [Item Status] ...        │
│  [Search] [Reset] [Add] [Download Template] [Import] [Export]  │
├─────────────────────────────────────────────────────────────────┤
│                        数据列表                                  │
│  ┌────┬─────────┬─────────┬────────────┬─────────────┬───────┐ │
│  │ ID │ Item SN │ Item ID │ Item Name  │ Item Status │ ...  │ │
│  ├────┼─────────┼─────────┼────────────┼─────────────┼───────┤ │
│  │ 1  │ SN001   │ ITEM01  │ Product A  │ receipt     │ ...  │ │
│  └────┴─────────┴─────────┴────────────┴─────────────┴───────┘ │
└─────────────────────────────────────────────────────────────────┘

功能列表：

功能	描述	操作方式	后端接口
条件搜索	多条件组合查询序列号	填写搜索条件后点击搜索	`POST /api/item-sn-search`
新增SN	手动新增序列号记录	点击Add按钮，填写表单	`POST /api/item-sn-upsert`
编辑SN	修改序列号信息	点击Edit按钮，修改表单	`POST /api/item-sn-upsert`
查看详情	查看序列号详细信息	点击View按钮	`POST /api/item-sn-select`
批量导入	从Excel导入SN数据	上传Excel文件	`POST /api/item-sn-import`
模板下载	下载导入模板	点击Download Template	`/template/item_sn_import.xlsx`
数据导出	导出SN数据为Excel	点击Export按钮	`POST /api/item-sn-search`

搜索条件：

字段	类型	说明
id	Long	主键ID
itemSn	String	序列号（模糊匹配）
itemId	String	商品ID
itemName	String	商品名称
itemStatus	Enum	状态（inactive/receipt/fulfill）
warehouseLocationId	String	仓库位置ID
warehouseLocationName	String	仓库位置名称
purchaseOrderNo	String	采购订单号
itemReceiptNo	String	入库单号
salesOrderNo	String	销售订单号
itemFulfillmentNo	String	出库单号
containerNo	String	集装箱号
palletSn	String	托盘号
valid	Boolean	是否有效

表格字段：

字段	说明	数据来源
id	主键ID	itemSn.id
itemSn	序列号	itemSn.itemSn
itemId	商品ID	itemSn.itemId
itemName	商品名称	itemSn.itemName
itemStatus	状态	itemSn.itemStatus
warehouseLocationId	仓库位置ID	itemSn.warehouseLocationId
warehouseLocationName	仓库位置名称	itemSn.warehouseLocationName
purchaseOrderNo	采购订单号	itemSn.purchaseOrderNo
itemReceiptNo	入库单号	itemSn.itemReceiptNo
salesOrderNo	销售订单号	itemSn.salesOrderNo
itemFulfillmentNo	出库单号	itemSn.itemFulfillmentNo
containerNo	集装箱号	itemSn.containerNo
palletSn	托盘号	itemSn.palletSn
createTime	创建时间	itemSn.createTime
updateTime	更新时间	itemSn.updateTime
operation	操作按钮	View / Edit

新增/编辑表单字段：

字段	类型	必填	说明
itemSn	String	是	序列号（编辑时不可修改）
itemId	String	否	商品ID
warehouseLocationId	String	否	仓库位置ID
purchaseOrderNo	String	否	采购订单号
salesOrderNo	String	否	销售订单号
itemReceiptNo	String	否	入库单号
itemFulfillmentNo	String	否	出库单号

2.3 安全审计模块

功能定位：记录用户登录行为，支持审计追溯。

搜索条件：

字段	类型	说明
id	Long	日志ID
userId	Long	用户ID
username	String	用户名（模糊匹配）
loginType	Enum	登录类型（password）
loginResult	Enum	登录结果（success/fail）
traceId	String	追踪ID
valid	Boolean	是否有效

表格字段：

字段	说明	数据来源
id	日志ID	loginLog.id
userId	用户ID	loginLog.userId
username	用户名	loginLog.username
loginType	登录类型	loginLog.loginType
loginResult	登录结果	loginLog.loginResult
loginIp	登录IP	loginLog.loginIp
userAgent	用户代理	loginLog.userAgent
traceId	追踪ID	loginLog.traceId
failReason	失败原因	loginLog.failReason
createTime	创建时间	loginLog.createTime

后端接口：POST /api/log/login-search

2.3.2 Import SN Logs（SN导入日志）

功能定位：记录序列号批量导入操作。

搜索条件：

字段	类型	说明
id	Long	日志ID
userId	Long	用户ID
username	String	用户名
dataFileId	String	数据文件ID
importQuantity	Integer	导入数量
successQuantity	Integer	成功数量
failQuantity	Integer	失败数量
submitResult	Enum	提交结果
valid	Boolean	是否有效

后端接口：POST /api/log/item-sn-import-log-search

2.3.3 Upsert SN Logs（SN更新日志）

功能定位：记录序列号新增/更新操作。

搜索条件：

字段	类型	说明
id	Long	日志ID
userId	Long	用户ID
username	String	用户名
itemSn	String	序列号
operationType	Enum	操作类型（insert/update）
submitResult	Enum	提交结果
valid	Boolean	是否有效

后端接口：POST /api/log/item-sn-upsert-log-search

2.3.4 Receipt Logs（入库日志）

功能定位：记录采购订单转入库单操作。

搜索条件：

字段	类型	说明
id	Long	日志ID
userId	Long	用户ID
username	String	用户名
purchaseOrderId	String	采购订单ID
purchaseOrderNo	String	采购订单号
itemReceiptId	String	入库单ID
itemReceiptNo	String	入库单号
receiptQuantity	Integer	入库数量
submitResult	Enum	提交结果
valid	Boolean	是否有效

后端接口：POST /api/log/item-receipt-log-search

2.3.5 Fulfillment Logs（出库日志）

功能定位：记录销售订单转出库单操作。

搜索条件：

字段	类型	说明
id	Long	日志ID
userId	Long	用户ID
username	String	用户名
salesOrderId	String	销售订单ID
salesOrderNo	String	销售订单号
itemFulfillmentId	String	出库单ID
itemFulfillmentNo	String	出库单号
fulfillmentQuantity	Integer	出库数量
submitResult	Enum	提交结果
valid	Boolean	是否有效

后端接口：POST /api/log/item-fulfillment-log-search

2.3.6 Scan SN Logs（扫描日志）

功能定位：记录移动端扫码操作。

搜索条件：

字段	类型	说明
id	Long	日志ID
userId	Long	用户ID
username	String	用户名
itemSn	String	序列号
scanRelated	Enum	关联类型（IR/IF）
relatedFrId	String	关联单据ID
relatedFrNo	String	关联单据号
submitResult	Enum	提交结果
valid	Boolean	是否有效

后端接口：POST /api/log/item-sn-scan-log-search

2.3.7 IF Ship Status Logs（发货状态日志）

功能定位：记录出库单发货状态变更操作。

搜索条件：

字段	类型	说明
id	Long	日志ID
userId	Long	用户ID
username	String	用户名
itemFulfillmentId	String	出库单ID
itemFulfillmentNo	String	出库单号
shipStatusId	String	发货状态ID
shipStatusName	String	发货状态名称
valid	Boolean	是否有效

后端接口：POST /api/log/item-fulfillment-ship-status-log-search

2.4 系统管理模块

2.4.1 User Management（用户管理）

功能定位：管理系统用户，包括新增、编辑、删除、重置密码、仓库权限分配。

搜索条件：

字段	类型	说明
id	Long	用户ID
username	String	用户名（模糊匹配）
nickname	String	昵称
valid	Boolean	是否有效

表格字段：

字段	说明	数据来源
id	用户ID	user.id
username	用户名	user.username
nickname	昵称	user.nickname
avatar	头像	user.avatar
createTime	创建时间	user.createTime
updateTime	更新时间	user.updateTime
valid	是否有效	user.valid
operation	操作	Edit / Warehouse / Reset Password

功能列表：

功能	描述	后端接口
新增用户	创建新用户	`POST /api/user-insert`
编辑用户	修改用户信息	`POST /api/user-update`
删除用户	删除用户	`DELETE /api/user/{id}`
重置密码	重置用户密码	`POST /api/security/reset-password`
仓库权限	分配用户仓库权限	`POST /api/warehouse/user-warehouse-upsert`

新增/编辑表单字段：

字段	类型	必填	说明
username	String	是	用户名
password	String	新增必填	密码
nickname	String	否	昵称
avatar	String	否	头像URL

仓库权限分配弹窗：

字段	类型	说明
warehouseLocationId	String	仓库位置ID
warehouseLocationName	String	仓库位置名称
valid	Boolean	是否有权限

2.4.2 APP Configuration（应用配置）

功能定位：管理系统配置参数。

表格字段：

字段	说明	数据来源
id	配置ID	appConfig.id
configKey	配置键	appConfig.configKey
configValue	配置值	appConfig.configValue
configDesc	配置描述	appConfig.configDesc
createTime	创建时间	appConfig.createTime
updateTime	更新时间	appConfig.updateTime
valid	是否有效	appConfig.valid

功能列表：

功能	描述	后端接口
查询配置	分页查询配置列表	`POST /api/app-config-search`
新增配置	创建新配置	`POST /api/app-config-upsert`
编辑配置	修改配置值	`POST /api/app-config-upsert`
删除配置	删除配置	`DELETE /api/app-config/{id}`

2.5 账户设置模块

功能定位：用户个人信息管理和密码修改。

功能列表：

功能	描述	后端接口
修改个人信息	更新昵称、头像	`POST /api/user-self-update`
修改密码	修改登录密码	`POST /api/security/change-password`

2.6 权限管理模块

功能定位：管理页面和按钮权限。

2.6.1 Page Permission（页面权限）

功能：配置角色可访问的页面。

2.6.2 Button Permission（按钮权限）

功能：配置角色可操作的按钮。

3. 安卓 APP 功能模块

3.1 功能模块总览

模块	功能	描述
登录模块	账号登录	用户登录系统
扫码入库	SN扫描	扫描序列号完成入库确认
扫码出库	SN扫描	扫描序列号完成出库确认
SN查询	序列号查询	查询序列号状态
单据查询	单据列表	查询入库单/出库单
个人中心	个人信息	查看/修改个人信息

3.2 登录模块

功能流程：

接口对接：

接口	方法	说明
`/api/auth/login`	POST	用户登录
`/api/auth/refresh`	POST	刷新Token

请求参数：

参数	类型	必填	说明
username	String	是	用户名
password	String	是	密码

响应数据：

字段	类型	说明
token	String	JWT Token
user	Object	用户信息
user.id	Long	用户ID
user.username	String	用户名
user.nickname	String	昵称

3.3 扫码入库模块

功能定位：仓库人员扫描商品序列号，完成入库确认。

功能流程：

接口对接：

接口	方法	说明
`/api/netsuite/record`	POST	提交扫描数据到NetSuite

请求参数：

参数	类型	必填	说明
uri	String	是	`/customrecord_scanning_data`
param	Object	是	扫描数据
param.custrecord_scanning_item	String	是	商品ID
param.custrecord_scanning_sn	String	是	序列号
param.custrecord_related_type	String	是	关联类型（IR）
param.custrecord_related_fr	String	是	关联单据ID
param.custrecord_scanning_cn	String	否	集装箱号
param.custrecord_scanning_pn	String	否	托盘号

3.4 扫码出库模块

功能定位：仓库人员扫描商品序列号，完成出库确认。

功能流程：

接口对接：

接口	方法	说明
`/api/netsuite/record`	POST	提交扫描数据到NetSuite

请求参数：

参数	类型	必填	说明
uri	String	是	`/customrecord_scanning_data`
param	Object	是	扫描数据
param.custrecord_scanning_item	String	是	商品ID
param.custrecord_scanning_sn	String	是	序列号
param.custrecord_related_type	String	是	关联类型（IF）
param.custrecord_related_fr	String	是	关联单据ID

3.5 SN查询模块

功能定位：查询序列号的详细信息和状态。

接口对接：

接口	方法	说明
`/api/item-sn-select`	POST	查询序列号详情

请求参数：

参数	类型	必填	说明
itemSn	String	是	序列号

响应数据：

字段	类型	说明
itemSn	String	序列号
itemId	String	商品ID
itemName	String	商品名称
itemStatus	String	状态（inactive/receipt/fulfill）
warehouseLocationId	String	仓库位置ID
warehouseLocationName	String	仓库位置名称
purchaseOrderNo	String	采购订单号
itemReceiptNo	String	入库单号
salesOrderNo	String	销售订单号
itemFulfillmentNo	String	出库单号
containerNo	String	集装箱号
palletSn	String	托盘号
createTime	String	创建时间
updateTime	String	更新时间

3.6 单据查询模块

功能定位：查询入库单和出库单列表。

接口对接：

接口	方法	说明
`/api/netsuite/query`	POST	查询NetSuite单据

查询SQL示例：

-- 查询入库单
SELECT *
FROM itemreceipt
WHERE createdfrom = '采购订单ID';

-- 查询出库单
SELECT *
FROM itemfulfillment
WHERE orderid = '销售订单ID';

4. 后端接口详细设计

4.1 认证接口

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

登录接口请求：

{
  "param": {
    "username": "string",
    "password": "string"
  }
}

登录接口响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "token": "string",
    "user": {
      "id": "number",
      "username": "string",
      "nickname": "string",
      "avatar": "string"
    }
  }
}

4.2 序列号管理接口

接口路径	HTTP方法	Controller	功能描述
`/api/item-sn-search`	POST	ItemSnController	分页查询序列号
`/api/item-sn-select`	POST	ItemSnController	查询单个序列号
`/api/item-sn-upsert`	POST	ItemSnController	新增/更新序列号
`/api/item-sn-import`	POST	ItemSnController	批量导入序列号

查询请求：

{
  "param": {
    "page": 1,
    "size": 10,
    "param": {
      "itemSn": "string",
      "itemStatus": "string"
    },
    "matches": [
      {
        "property": "itemSn",
        "mode": "contain"
      }
    ],
    "orders": [
      {
        "property": "id",
        "direction": "desc"
      }
    ]
  }
}

查询响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "list": [],
    "total": 0,
    "page": 1,
    "size": 10
  }
}

4.3 日志查询接口

接口路径	HTTP方法	Controller	功能描述
`/api/log/login-search`	POST	LoginLogController	查询登录日志
`/api/log/item-receipt-log-search`	POST	ItemReceiptLogController	查询入库日志
`/api/log/item-fulfillment-log-search`	POST	ItemFulfillmentLogController	查询出库日志
`/api/log/item-sn-scan-log-search`	POST	ItemSnScanLogController	查询扫描日志
`/api/log/item-sn-import-log-search`	POST	ItemSnImportLogController	查询导入日志
`/api/log/item-sn-upsert-log-search`	POST	ItemSnUpsertLogController	查询更新日志
`/api/log/item-fulfillment-ship-status-log-search`	POST	ItemFulfillmentShipStatusLogController	查询发货状态日志

4.4 用户管理接口

接口路径	HTTP方法	Controller	功能描述
`/api/user-search`	POST	UserController	分页查询用户
`/api/user-select`	POST	UserController	查询单个用户
`/api/user-insert`	POST	UserController	新增用户
`/api/user-update`	POST	UserController	更新用户
`/api/user-delete`	DELETE	UserController	删除用户

4.5 仓库管理接口

接口路径	HTTP方法	Controller	功能描述
`/api/warehouse/all-list`	POST	WarehouseController	查询所有仓库
`/api/warehouse/user-list`	POST	WarehouseController	查询用户仓库权限
`/api/warehouse/user-warehouse-upsert`	POST	WarehouseController	更新用户仓库权限

4.6 NetSuite集成接口

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

Record接口请求：

{
  "param": {
    "uri": "/customrecord_scanning_data",
    "param": {
      "custrecord_scanning_item": "string",
      "custrecord_scanning_sn": "string",
      "custrecord_related_type": "IR",
      "custrecord_related_fr": "string"
    }
  }
}

4.7 安全接口

接口路径	HTTP方法	Controller	功能描述
`/api/security/change-password`	POST	SecurityController	修改密码
`/api/security/reset-password`	POST	SecurityController	重置密码

4.8 文件接口

接口路径	HTTP方法	Controller	功能描述
`/api/file/upload`	POST	FileController	上传文件
`/api/file/download/{id}`	GET	FileController	下载文件

5. 接口响应通用格式

5.1 成功响应

{
  "code": 200,
  "message": "success",
  "data": {}
}

5.2 失败响应

{
  "code": 500,
  "message": "error message",
  "data": null
}

5.3 分页响应

{
  "code": 200,
  "message": "success",
  "data": {
    "list": [],
    "total": 0,
    "page": 1,
    "size": 10
  }
}

6. 数据模型映射

6.1 序列号状态映射

数据库值	显示名称	说明
`inactive`	Inactive	未激活
`receipt`	Receipt	已入库
`fulfill`	Fulfill	已出库

6.2 操作类型映射

数据库值	显示名称	说明
`purchaseorder_transform_itemreceipt`	PO转IR	采购订单转入库单
`customrecord_scanning_data`	扫描数据	提交扫描记录
`salesorder_transform_itemfulfillment`	SO转IF	销售订单转出库单
`patch_itemfulfillment_shipstatus`	更新发货状态	修改出库单状态

6.3 扫描关联类型映射

数据库值	显示名称	说明
`IR`	Item Receipt	关联入库单
`IF`	Item Fulfillment	关联出库单

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

1. 概述​

2. 前端 PC 管理平台功能模块​

2.1 功能模块总览​

2.2 订单管理模块 - SN Management​

2.3 安全审计模块​

2.3.1 Login Logs（登录日志）​

2.3.2 Import SN Logs（SN导入日志）​

2.3.3 Upsert SN Logs（SN更新日志）​

2.3.4 Receipt Logs（入库日志）​

2.3.5 Fulfillment Logs（出库日志）​

2.3.6 Scan SN Logs（扫描日志）​

2.3.7 IF Ship Status Logs（发货状态日志）​

2.4 系统管理模块​

2.4.1 User Management（用户管理）​

2.4.2 APP Configuration（应用配置）​

2.5 账户设置模块​

2.6 权限管理模块​

2.6.1 Page Permission（页面权限）​

2.6.2 Button Permission（按钮权限）​

3. 安卓 APP 功能模块​

3.1 功能模块总览​

3.2 登录模块​

3.3 扫码入库模块​

3.4 扫码出库模块​

3.5 SN查询模块​

3.6 单据查询模块​

4. 后端接口详细设计​

4.1 认证接口​

4.2 序列号管理接口​

4.3 日志查询接口​

4.4 用户管理接口​

4.5 仓库管理接口​

4.6 NetSuite集成接口​

4.7 安全接口​

4.8 文件接口​

5. 接口响应通用格式​

5.1 成功响应​

5.2 失败响应​

5.3 分页响应​

6. 数据模型映射​

6.1 序列号状态映射​

6.2 操作类型映射​

6.3 扫描关联类型映射​

1. 概述

2. 前端 PC 管理平台功能模块

2.1 功能模块总览

2.2 订单管理模块 - SN Management

2.3 安全审计模块

2.3.1 Login Logs（登录日志）

2.3.2 Import SN Logs（SN导入日志）

2.3.3 Upsert SN Logs（SN更新日志）

2.3.4 Receipt Logs（入库日志）

2.3.5 Fulfillment Logs（出库日志）

2.3.6 Scan SN Logs（扫描日志）

2.3.7 IF Ship Status Logs（发货状态日志）

2.4 系统管理模块

2.4.1 User Management（用户管理）

2.4.2 APP Configuration（应用配置）

2.5 账户设置模块

2.6 权限管理模块

2.6.1 Page Permission（页面权限）

2.6.2 Button Permission（按钮权限）

3. 安卓 APP 功能模块

3.1 功能模块总览

3.2 登录模块

3.3 扫码入库模块

3.4 扫码出库模块

3.5 SN查询模块

3.6 单据查询模块

4. 后端接口详细设计

4.1 认证接口

4.2 序列号管理接口

4.3 日志查询接口

4.4 用户管理接口

4.5 仓库管理接口

4.6 NetSuite集成接口

4.7 安全接口

4.8 文件接口

5. 接口响应通用格式

5.1 成功响应

5.2 失败响应

5.3 分页响应

6. 数据模型映射

6.1 序列号状态映射

6.2 操作类型映射

6.3 扫描关联类型映射