TIKU Backend

TIKU Backend 是题库 SaaS 的 ASP.NET Core 模块化单体，使用 EF Core 管理 PostgreSQL 数据，由同一个 API 进程提供平台端、租户端和学生端接口并处理后台任务。

当前技术栈

• .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（安全频控、Feature 缓存和生产输出缓存）
• PostgreSQL 后台任务队列、租约和重试
• Serilog + OpenTelemetry
• xUnit 单元测试和真实 PostgreSQL 集成测试

解决方案结构

Tiku.Api              HTTP API、中间件、认证授权、OpenAPI/Scalar 和 Hosted Service
Tiku.Application      用例契约、应用服务接口和安全上下文
Tiku.Domain           领域实体、枚举和值对象
Tiku.Infrastructure   EF Core、PostgreSQL、认证、后台任务和外部服务实现
Tiku.DbMigrator       数据库迁移、内置目录 seed 和平台管理员引导
Tiku.UnitTests        单元测试
Tiku.IntegrationTests API、授权、EF 模型、迁移和真实 PostgreSQL 测试

依赖方向固定为：Domain <- Application <- Infrastructure。Api 是唯一运行时组合根，DbMigrator 是部署时迁移入口；第三方 SDK、数据库访问和密钥处理只放在 Infrastructure。

快速启动

需要 .NET 10 SDK 和 PostgreSQL。Development 默认连接本机 tiku 数据库，也可以通过 DATABASE_URL 覆盖。

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 首次运行的终端输出。完整步骤见本地开发与运行。

默认开发入口：

• 平台管理端：首次在 Tiku.PlatformAdmin.Web 执行 npm install；之后启动 Tiku.Api 时会在 Development 自动启动前端，访问 http://localhost:5173
• 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；Production 缺少 Redis 时 API 会拒绝启动。
• 租户由可信 Host 解析；平台 Host 上只有允许的路径可通过 x-tenant-code 或 tenantCode 指定租户。
• 租户数据由 EF Query Filter、写入拦截器、租户限定外键/唯一索引和 PostgreSQL guard 共同隔离。
• 普通请求默认要求认证；匿名接口必须显式声明 [AllowAnonymous]。
• API 只在 Development 映射 OpenAPI 和 Scalar，不应把文档端点作为生产依赖。

常用验证

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。

文档

当前文档统一从文档总览进入：

• 系统架构与业务边界
• 认证、授权与租户隔离
• 配置与后台任务
• 本地开发与运行

接口、DTO、请求参数和响应模型以运行时 OpenAPI/Scalar 为准；文档不再维护手写接口清单或迁移过程记录。