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