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