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>
This commit is contained in:
zhougfandCursor committed 2026-05-24 14:17:47 +08:00
commit fa1b286463
241 files changed
+31188

No files matched your search

+128
View File
@@ -0,0 +1,128 @@
# 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
```