5.1 KiB
Raw Permalink Blame History

WmsLite.Api

ASP.NET Core Web API:SqlSugar + PostgreSQL + FluentMigrator,提供 WMS 主数据、库存、单据与系统字典等 REST 接口。

仓库总览见 ../README.md。

技术栈

  • .NET 10、ASP.NET Core Web API
  • SqlSugar ORM、PostgreSQL
  • FluentMigrator 数据库迁移
  • JWT Bearer 认证(Microsoft.AspNetCore.Authentication.JwtBearer)
  • BCrypt 密码哈希、Scalar OpenAPI(开发环境)

功能模块

模块 控制器 说明
认证 AuthController 登录、当前用户
主数据 Warehouse / Area / Zone / Location / Material / Container CRUD、分页
库存 Inventory / InventoryTransaction 余额、流水、库存变动
单据 InboundOrder / OutboundOrder / TransferOrder / StocktakeOrder 创建、状态流转、明细
系统 SysDictionary / SysTemplate / Health 字典、模板、健康检查

安全与租户

  • 除 Auth/login、Health 外,业务接口默认 需 JWT(FallbackPolicy = RequireAuthenticatedUser)。
  • 租户与货主从 Token Claims 解析(tenant_id、owner_code、sub),不信任请求体中的 tenantId / ownerCode。
  • 审计字段 create_by / update_by / delete_by 由 ICurrentUserContext 自动写入。
  • 登录接口与敏感字段 HTTP 日志脱敏;/api/Auth/login 不持久化请求体。

JWT Claims

Claim 说明
sub 用户 ID
tenant_id 租户
owner_code 货主
name 显示名

默认开发账号

迁移 0012_CreateSysUser 种子用户(仅开发):

  • 用户名:admin
  • 密码:admin123
  • 租户 / 货主:default / default

本地配置

1. 数据库连接串

appsettings.Development.json 中为占位密码,勿提交真实密码。任选一种方式配置:

方式 A — 本地覆盖文件(推荐)

copy appsettings.Development.local.json.example appsettings.Development.local.json
# 编辑 appsettings.Development.local.json,填写 PostgreSQL 密码

该文件已在仓库 .gitignore 中忽略。

方式 B — user-secrets

dotnet user-secrets set ConnectionStrings:PostgreSql "Host=127.0.0.1;Port=5432;Database=wmslite;Username=postgres;Password=YOUR_PASSWORD"

方式 C — 环境变量

ConnectionStrings__PostgreSql

2. JWT

Development 见 appsettings.Development.json 中 Jwt 节。生产环境请通过环境变量或 user-secrets 配置 Jwt:Key,勿使用开发密钥。

3. 迁移

启动时自动执行(Database:Migrations:Enabled = true)。主要迁移:

编号 说明
0012 sys_user 表与种子账号
0013 入库单号计数器 order_no_counter
0014 业务唯一约束(partial unique index)
0015 出库库存分配与拣货任务
0016 出库拣货任务操作字段

启动

cd WmsLite.Api
dotnet run --launch-profile http
  • 默认地址:http://localhost:9901
  • OpenAPI / Scalar:开发环境访问 /scalar/v1(Scalar 页面匿名;调业务 API 需 Bearer Token)

常用 API

POST /api/Auth/login          # 匿名,body: { "username", "password" }
GET  /api/Auth/me             # 需 Bearer
GET  /api/Health              # 匿名
POST /api/Warehouse/paged-list
POST /api/SysDictionary/map
POST /api/InboundOrder/create-header
POST /api/InboundOrder/add-line
POST /api/OutboundOrder/create-header
POST /api/OutboundOrder/add-line
POST /api/OutboundOrder/pending
POST /api/OutboundOrder/pick-task/confirm
POST /api/OutboundOrder/confirm
POST /api/OutboundOrder/cancel

单据接口约定

  • 入库、出库支持先创建 Draft 单头,再追加明细:
    • POST /api/InboundOrder/create-header
    • POST /api/InboundOrder/add-line
    • POST /api/OutboundOrder/create-header
    • POST /api/OutboundOrder/add-line
  • 出库物料行的 unit 可不传,服务端会按物料主数据单位写入;若客户端传入单位,必须与物料主数据一致。
  • 出库转待拣会按仓库、库区、物料和可选指定库位分配库存并生成拣货任务。
  • POST /api/OutboundOrder/pick-task/confirm 用于确认单个拣货任务,记录拣货人、拣货时间、已拣数量和异常原因。
  • POST /api/OutboundOrder/cancel 仅允许取消待处理出库单,会释放 PendingOutboundQty 并取消未出库任务。

未带 Token 访问业务接口返回 HTTP 401(JSON:{ "success": false, "code": "401", ... })。

项目结构

WmsLite.Api/
├── Controllers/          # API 控制器(业务继承 WmsLiteControllerBase)
├── Services/             # 业务逻辑、事务(ITransactionRunner)
├── Repositories/         # 数据访问(BaseRepository 审计戳)
├── Infrastructure/       # JWT、SqlSugar、迁移、HTTP 日志、异常中间件
├── Database/migrations/  # FluentMigrator 迁移脚本
├── Dtos/                 # 请求/响应 DTO
└── Models/               # 实体

构建

dotnet build
dotnet run --launch-profile http