151 lines
5.1 KiB
Markdown
151 lines
5.1 KiB
Markdown
# WmsLite.Api
|
||
|
||
ASP.NET Core Web API:SqlSugar + PostgreSQL + FluentMigrator,提供 WMS 主数据、库存、单据与系统字典等 REST 接口。
|
||
|
||
仓库总览见 [../README.md](../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 — 本地覆盖文件(推荐)**
|
||
|
||
```powershell
|
||
copy appsettings.Development.local.json.example appsettings.Development.local.json
|
||
# 编辑 appsettings.Development.local.json,填写 PostgreSQL 密码
|
||
```
|
||
|
||
该文件已在仓库 `.gitignore` 中忽略。
|
||
|
||
**方式 B — user-secrets**
|
||
|
||
```powershell
|
||
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 | 出库拣货任务操作字段 |
|
||
|
||
## 启动
|
||
|
||
```powershell
|
||
cd WmsLite.Api
|
||
dotnet run --launch-profile http
|
||
```
|
||
|
||
- 默认地址:**http://localhost:9901**
|
||
- OpenAPI / Scalar:开发环境访问 `/scalar/v1`(Scalar 页面匿名;调业务 API 需 Bearer Token)
|
||
|
||
## 常用 API
|
||
|
||
```http
|
||
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/ # 实体
|
||
```
|
||
|
||
## 构建
|
||
|
||
```powershell
|
||
dotnet build
|
||
dotnet run --launch-profile http
|
||
```
|