151 lines
5.1 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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
```