forked from xiongyuxing/tiku-backend.net
90 lines
3.9 KiB
Markdown
90 lines
3.9 KiB
Markdown
# TIKU Backend
|
||
|
||
TIKU Backend 是题库 SaaS 的 ASP.NET Core 后端，使用 EF Core 管理 PostgreSQL 数据，提供平台端、租户端和学生端 API，并由独立 Worker 处理后台任务。
|
||
|
||
|
||
|
||
## 当前技术栈
|
||
|
||
- .NET 10 / ASP.NET Core Controller API
|
||
- Entity Framework Core 10 + Npgsql 10 + PostgreSQL
|
||
- ASP.NET Core Identity + RSA JWT + 数据库存储的 Session
|
||
- Scalar + OpenAPI（仅 Development 暴露）
|
||
- Redis（分布式安全频控和生产输出缓存）
|
||
- MassTransit 8 + RabbitMQ 4 + EF Core Outbox
|
||
- Serilog + OpenTelemetry
|
||
- xUnit 单元测试和真实 PostgreSQL 集成测试
|
||
|
||
## 解决方案结构
|
||
|
||
```text
|
||
Tiku.Api HTTP API、中间件、认证授权、OpenAPI/Scalar、静态管理端
|
||
Tiku.Application 用例契约、应用服务接口和安全上下文
|
||
Tiku.Domain 领域实体、枚举和值对象
|
||
Tiku.Infrastructure EF Core、PostgreSQL、认证、消息和外部服务实现
|
||
Tiku.Contracts API 与 Worker 之间的版本化消息契约
|
||
Tiku.DbMigrator 数据库迁移、内置目录 seed 和平台管理员引导
|
||
Tiku.Worker 域名、订阅、用量和后台任务处理
|
||
Tiku.UnitTests 单元测试
|
||
Tiku.IntegrationTests API、授权、EF 模型、迁移和真实 PostgreSQL 测试
|
||
```
|
||
|
||
依赖方向固定为：`Domain <- Application <- Infrastructure`。`Api`、`Worker` 和 `DbMigrator` 是组合根；第三方 SDK、数据库访问和密钥处理只放在 Infrastructure。
|
||
|
||
## 快速启动
|
||
|
||
需要 .NET 10 SDK 和 PostgreSQL。Development 默认连接本机 `tiku` 数据库，也可以通过 `DATABASE_URL` 覆盖。
|
||
|
||
```bash
|
||
createdb -h 127.0.0.1 -U "$(whoami)" tiku
|
||
dotnet restore TIKU-BACKEND.slnx
|
||
dotnet build TIKU-BACKEND.slnx --no-restore
|
||
ASPNETCORE_ENVIRONMENT=Development dotnet run --project Tiku.DbMigrator
|
||
dotnet run --project Tiku.Api
|
||
```
|
||
|
||
Development 首次迁移会创建平台管理员 `admin@tiku.local`，随机临时密码只在 DbMigrator 首次运行的终端输出。完整步骤见[本地开发与运行](docs/quickstart.md)。
|
||
|
||
默认开发入口：
|
||
|
||
- 平台管理端：<http://localhost:5090/platform-admin/>
|
||
- Scalar：<http://localhost:5090/scalar/v1>
|
||
- OpenAPI：<http://localhost:5090/openapi/v1.json>
|
||
- Liveness：<http://localhost:5090/api/health>
|
||
- Readiness：<http://localhost:5090/api/health/ready>
|
||
|
||
## 运行时边界
|
||
|
||
- API 不自动执行数据库迁移；部署和本地初始化都使用 `Tiku.DbMigrator`。
|
||
- Development 可不配置 Redis 和 RabbitMQ；Production 缺少任一依赖时 API 与 Worker 会拒绝启动。
|
||
- 租户由可信 Host 解析；平台 Host 上只有允许的路径可通过 `x-tenant-code` 或 `tenantCode` 指定租户。
|
||
- 租户数据由 EF Query Filter、写入拦截器、租户限定外键/唯一索引和 PostgreSQL guard 共同隔离。
|
||
- 普通请求默认要求认证；匿名接口必须显式声明 `[AllowAnonymous]`。
|
||
- API 只在 Development 映射 OpenAPI 和 Scalar，不应把文档端点作为生产依赖。
|
||
|
||
## 常用验证
|
||
|
||
```bash
|
||
dotnet build TIKU-BACKEND.slnx --no-restore
|
||
dotnet test TIKU-BACKEND.slnx --no-build
|
||
dotnet format TIKU-BACKEND.slnx --verify-no-changes --no-restore
|
||
dotnet ef migrations has-pending-model-changes \
|
||
--project Tiku.Infrastructure \
|
||
--startup-project Tiku.DbMigrator \
|
||
--no-build
|
||
git diff --check
|
||
```
|
||
|
||
PostgreSQL 特有的迁移、事务、约束和跨租户不变量必须由 `Tiku.IntegrationTests` 在真实 PostgreSQL 上验证，不能只依赖 EF InMemory。
|
||
|
||
## 文档
|
||
|
||
当前文档统一从[文档总览](docs/README.md)进入：
|
||
|
||
- [系统架构与业务边界](docs/architecture/overview.md)
|
||
- [认证、授权与租户隔离](docs/architecture/security-and-tenancy.md)
|
||
- [配置与后台任务](docs/operations.md)
|
||
- [本地开发与运行](docs/quickstart.md)
|
||
|
||
接口、DTO、请求参数和响应模型以运行时 OpenAPI/Scalar 为准；文档不再维护手写接口清单或迁移过程记录。
|