refactor(architecture): enforce module boundaries
This commit is contained in:
@@ -9,6 +9,7 @@
|
||||
| 首次拉取代码，启动本地开发环境 | [本地开发快速上手](quickstart.md) |
|
||||
| 从空库验收租户创建、Owner 激活和站点发布 | [空数据库到租户建站验收](tenant-provisioning.md) |
|
||||
| 理解项目分层、运行时和业务边界 | [系统架构与业务边界](architecture/overview.md) |
|
||||
| 按模块协作、拆分 Service 或调整依赖 | [模块边界与所有权](architecture/module-boundaries.md) |
|
||||
| 修改认证、权限或租户数据 | [认证、授权与租户隔离](architecture/security-and-tenancy.md) |
|
||||
| 查看 Tiku/RuoYi 双线取舍和公平基准边界 | [双线能力矩阵](architecture/dual-line-capability-matrix.md) |
|
||||
| 部署 API/Worker、配置依赖或排查任务 | [配置与后台任务](operations.md) |
|
||||
|
||||
40
docs/architecture/module-boundaries.md
Normal file
40
docs/architecture/module-boundaries.md
Normal file
@@ -0,0 +1,40 @@
|
||||
# 模块边界与所有权
|
||||
|
||||
后端保持模块化单体、统一 PostgreSQL、独立 API/Worker。目录是团队所有权边界，跨模块调用必须经过 `Tiku.Application` 合同。
|
||||
|
||||
## 依赖方向
|
||||
|
||||
```text
|
||||
Platform Core: Tenancy / Auth / Security
|
||||
Catalog -> QuestionBanks -> Content / Assets -> Learning
|
||||
Commerce -> Points / Growth
|
||||
TenantAdmin / PlatformAdmin -> Application contracts or dedicated read models
|
||||
Jobs -> queue / processor / operations + module job handlers
|
||||
```
|
||||
|
||||
- API Controller 不得引用 `Tiku.Infrastructure` 或 `TikuDbContext`。
|
||||
- 一个模块不得引用另一个模块的 Infrastructure 类型。
|
||||
- 跨模块查询使用 Application 查询合同；跨模块写入调用目标模块命令合同。
|
||||
- `TikuDbContext` 仍是统一事务入口，但 DbSet 按模块拆在 `Persistence/Modules`。
|
||||
- EF Migration 与模型快照串行合并，由 CODEOWNERS 默认负责人复核。
|
||||
|
||||
## 子模块目录
|
||||
|
||||
- TenantAdmin：Dashboard、Classes、Students、Supervision、StudentEngagement、MembersAndAccess、SiteSettings、DomainsAndEngagement。
|
||||
- Content：Questions、Vocabulary、Handbook、EducationCatalog、Scorelines、Videos、OperationContent、Imports。
|
||||
- Learning：Analytics、Answering、QuestionReview、WordLearning、PracticeSessions、Foundation。
|
||||
- Commerce：Orders、Payments、Coupons、Refunds、Reconciliation、Adjustments、Points。
|
||||
- PlatformAdmin：Dashboard、TenantProvisioning、TenantDomains、StaffAndAccess、AuditAndAlerts、Dunning、Operations。
|
||||
|
||||
Service 文件超过 500 行应在评审中说明原因，超过 800 行由架构测试阻止新增。现有聚合接口应逐步由子模块接口替代，不允许把新能力继续追加到聚合 Service。
|
||||
|
||||
## API audience
|
||||
|
||||
- `/api/platform/*`：平台控制面。
|
||||
- `/api/tenant/*`：租户管理后台。
|
||||
- `/api/student/*`：学生业务。
|
||||
- `/api/public/*`：匿名公开读取。
|
||||
- `/api/system/*`：健康与内部诊断。
|
||||
- `/api/integrations/*`：外部系统回调。
|
||||
|
||||
旧的 platform-admin、backoffice、tenant-admin、tenant-content 和 tenant-commerce 路由不再提供兼容入口。后端、OpenAPI 客户端和两个前端必须作为一个发布单元回滚或上线。
|
||||
@@ -6,8 +6,8 @@
|
||||
|
||||
API 支持两组认证接口：
|
||||
|
||||
- `/api/auth/**` 返回 access token 与 refresh token，适合 Bearer 客户端。
|
||||
- `/api/browser-auth/**` 把 token 写入 HttpOnly Cookie，适合同源浏览器客户端。
|
||||
- `/api/tenant/auth/**` 返回 access token 与 refresh token，适合 Bearer 客户端。
|
||||
- `/api/tenant/auth/browser/**` 把 token 写入 HttpOnly Cookie，适合同源浏览器客户端。
|
||||
|
||||
当前登录方式：
|
||||
|
||||
|
||||
@@ -186,11 +186,11 @@ Worker 使用 ClamAV `INSTREAM` 协议，不在本地落盘待扫描对象。启
|
||||
|
||||
## 健康检查与观测
|
||||
|
||||
- `GET /api/health`：轻量 liveness，只说明 API 进程可响应。
|
||||
- `GET /api/health/ready`：检查 PostgreSQL 和已配置 Redis；依赖未就绪时返回 503，匿名响应只包含总体状态和检查时间。
|
||||
- `GET /api/platform-admin/operations/health`：需要 `platform:operations:view`，返回 PostgreSQL、Redis、Worker heartbeat、ClamAV 和对象存储配置状态。
|
||||
- `GET /api/platform-admin/operations/workers`：查询 Worker 心跳、周期循环和 stale 状态。
|
||||
- `GET /api/platform-admin/operations/job-metrics`：查询队列状态、最老 Pending 任务与过期租约。
|
||||
- `GET /api/system/health`：轻量 liveness，只说明 API 进程可响应。
|
||||
- `GET /api/system/health/ready`：检查 PostgreSQL 和已配置 Redis；依赖未就绪时返回 503，匿名响应只包含总体状态和检查时间。
|
||||
- `GET /api/platform/operations/health`：需要 `platform:operations:view`，返回 PostgreSQL、Redis、Worker heartbeat、ClamAV 和对象存储配置状态。
|
||||
- `GET /api/platform/operations/workers`：查询 Worker 心跳、周期循环和 stale 状态。
|
||||
- `GET /api/platform/operations/job-metrics`：查询队列状态、最老 Pending 任务与过期租约。
|
||||
- 设置 `OpenTelemetry:OtlpEndpoint` 后导出 ASP.NET Core、HTTP client 和数据库观测数据。
|
||||
- Serilog 输出结构化请求日志；数据库性能拦截器记录慢查询指标。
|
||||
|
||||
|
||||
@@ -84,8 +84,8 @@ ASPNETCORE_ENVIRONMENT=Development dotnet run --project Tiku.Api --launch-profil
|
||||
- API：<http://localhost:5090>
|
||||
- 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>
|
||||
- Liveness：<http://localhost:5090/api/system/health>
|
||||
- Readiness：<http://localhost:5090/api/system/health/ready>
|
||||
|
||||
后台循环不在 API 内运行。需要处理域名、订阅、任务队列、授权缓存失效或商业账务时，另开终端启动 Worker：
|
||||
|
||||
@@ -127,7 +127,7 @@ PostgreSQL 特有的 Migration、事务、约束和租户隔离行为必须由
|
||||
|
||||
### Readiness 返回 503
|
||||
|
||||
`/api/health/ready` 会检查 PostgreSQL 和已配置的 Redis。先验证数据库连接；配置 Redis 后还需确认 Redis 可访问。匿名响应不会暴露依赖详情。
|
||||
`/api/system/health/ready` 会检查 PostgreSQL 和已配置的 Redis。先验证数据库连接；配置 Redis 后还需确认 Redis 可访问。匿名响应不会暴露依赖详情。
|
||||
|
||||
### API 启动了但后台任务不执行
|
||||
|
||||
|
||||
@@ -91,7 +91,7 @@ API 在 Development 会同时拉起平台管理端 Vite 服务：
|
||||
- API：<http://localhost:5090>
|
||||
- Scalar：<http://localhost:5090/scalar/v1>
|
||||
- OpenAPI：<http://localhost:5090/openapi/v1.json>
|
||||
- Readiness：<http://localhost:5090/api/health/ready>
|
||||
- Readiness：<http://localhost:5090/api/system/health/ready>
|
||||
|
||||
不要使用 `http://localhost:5090/platform-admin/` 作为开发入口；该路径受 API 授权保护，未登录访问返回 401。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user