WMSlite/WmsLite.Api
..
2026-06-01 23:30:36 +08:00
2026-06-01 23:30:36 +08:00
2026-06-01 23:30:36 +08:00
2026-06-01 23:30:36 +08:00
2026-06-01 23:30:36 +08:00
2026-06-01 23:30:36 +08:00

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)

启动

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

未带 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