Files
WMSlite/WmsLite.Api/README.md
T
zhougfandCursor fa1b286463 Add WmsLite monorepo with JWT auth, tenant context, and project READMEs.
Implement API security baseline (sys_user, JWT, audit fields, transactions,
unique constraints) and Web real login with 401 handling. Document setup
and development workflows in root, WmsLite.Api, and WmsLite.Web README files.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-05-24 14:17:47 +08:00

129 lines
4.0 KiB
Markdown
Raw 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) |
## 启动
```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
```
未带 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
```