@@ -11,18 +11,11 @@
|
||||
| 理解项目分层、运行时和业务边界 | [系统架构与业务边界](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) |
|
||||
|
||||
## 文档边界
|
||||
|
||||
- `README.md`：项目定位、最短启动入口和仓库地图。
|
||||
- `docs/quickstart.md`：非破坏性的日常开发路径。
|
||||
- `docs/tenant-provisioning.md`：会创建或清理本地数据库的完整 SaaS 验收路径。
|
||||
- `docs/architecture/**`：当前代码的稳定设计与安全边界。
|
||||
- `docs/operations.md`：部署配置、后台处理、健康检查和恢复演练。
|
||||
|
||||
路线图、阶段计划、代码评审快照和历史迁移过程不放在当前实现文档中；需要保留时应进入 Issue、项目管理系统或明确标记的历史归档。
|
||||
这里只保留上手、验收、架构、安全和运维资料。路线图、横向比较、评审快照与开发过程应放在 Issue 或项目管理系统，不作为当前实现文档维护。
|
||||
|
||||
## 权威来源
|
||||
|
||||
@@ -39,4 +32,3 @@
|
||||
3. 数据库结构变更必须生成 EF Core Migration，并检查 migration script 和 pending model changes。
|
||||
4. 不在文档中保存连接密码、JWT 私钥、证书密码、Provider 密钥或平台管理员临时密码。
|
||||
5. 代码行为变化时更新对应主题，不新增内容重叠的临时说明文件。
|
||||
6. 不维护阶段路线图、旧后端接口对比、评审快照或开发过程记录。
|
||||
|
||||
@@ -1,24 +0,0 @@
|
||||
# Tiku / RuoYi 双线能力矩阵
|
||||
|
||||
状态只使用：`已实现`、`已验证`、`计划中`、`明确不移植`。`已实现`表示当前 Tiku 源码存在该能力，`已验证`表示本仓库自动化或本机真实依赖验收已经通过；它不等于生产容量结论。
|
||||
|
||||
| 能力 | Tiku 状态 | RuoYi 用途 | 维护决策 |
|
||||
| --- | --- | --- | --- |
|
||||
| Host 租户解析与租户开通 | 已验证 | 功能对照 | Tiku 主线 |
|
||||
| 平台多岗位 RBAC、菜单与路由守卫 | 已验证 | 通用后台样板 | Tiku 原生维护 |
|
||||
| OpenAPI 操作权限、风险和审批策略元数据 | 已验证 | 不移植 | Tiku 原生维护 |
|
||||
| 分级四眼审批与 Worker 执行 | 已验证 | 流程参考 | Tiku 原生维护 |
|
||||
| 类型化配置、版本发布与回滚 | 已验证 | 配置中心参考 | Tiku 原生维护 |
|
||||
| 平台站内通知与投递记录 | 已实现 | 通知中心参考 | 短信、邮件 Provider 投递计划中 |
|
||||
| 租户 360 聚合工作台 | 计划中 | 页面交互参考 | 按 Tiku 领域投影实现 |
|
||||
| 平台跨租户列表统一分页 | 计划中 | SQL 与分页参考 | 逐接口迁移为 `PagedResult<T>` |
|
||||
| 热目录输出缓存 | 已验证 | 性能对照线 | Tiku 保持租户感知缓存 |
|
||||
| 冷查询、复合索引和批量写入 | 计划中 | SQL 优化参考 | 先公平基准，再按查询补索引 |
|
||||
| 代码生成器 | 明确不移植 | 仅开发效率参考 | 不进入产品运行时 |
|
||||
| 动态数据源、Druid 管理页 | 明确不移植 | 不使用 | 保持单一受控数据访问边界 |
|
||||
| Quartz 任意任务编辑 | 明确不移植 | 不使用 | 仅实现专用 Worker 与命令 |
|
||||
| 通用业务字典 | 明确不移植 | 不使用 | 使用领域枚举和类型化配置 |
|
||||
|
||||
## 公平比较约束
|
||||
|
||||
性能结论必须使用同一台机器、相同 PostgreSQL/Redis 版本、相同租户数和业务数据量，并分别报告热目录、冷目录、认证、平台分页、批量导入和 Worker 竞争。每个场景至少执行三轮，记录 QPS、p95、p99、HTTP 状态、丢失迭代与依赖状态。未满足这些条件时，只能记录源码推断，不能记录生产容量胜负。
|
||||
@@ -1,32 +1,15 @@
|
||||
# 模块边界与所有权
|
||||
|
||||
后端保持模块化单体、统一 PostgreSQL、独立 API/Worker。目录是团队所有权边界，跨模块调用必须经过 `Tiku.Application` 合同。
|
||||
后端是共享 PostgreSQL 的模块化单体，API 与 Worker 是独立运行时。跨模块调用通过 `Tiku.Application` 契约，模块实现由 `Tiku.Infrastructure/Modules` 统一注册。
|
||||
|
||||
## 依赖方向
|
||||
|
||||
```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。
|
||||
- 业务模块通过 Application 查询/命令契约协作，不直接依赖其他模块的 Infrastructure 类型。
|
||||
- `TikuDbContext` 是统一事务入口；DbSet 按领域拆到 `Persistence/Modules`，Migration 和模型快照仍全局唯一。
|
||||
- `AddInfrastructure` 组合 Platform Core、Auth、Content、Learning、Tenant Admin、Commerce、Jobs 和 Platform 模块。
|
||||
- 后台任务处理器实现 `IBackgroundJobHandler`，在所属模块注册；Jobs 模块只负责队列、租约、调度和处理器查找。
|
||||
- 新 Service 聚合超过 800 行会被 `ArchitectureBoundaryTests` 阻止；既有超限服务不得超过记录的债务基线。
|
||||
|
||||
## API audience
|
||||
|
||||
@@ -37,4 +20,4 @@ Service 文件超过 500 行应在评审中说明原因，超过 800 行由架
|
||||
- `/api/system/*`：健康与内部诊断。
|
||||
- `/api/integrations/*`：外部系统回调。
|
||||
|
||||
旧的 platform-admin、backoffice、tenant-admin、tenant-content 和 tenant-commerce 路由不再提供兼容入口。后端、OpenAPI 客户端和两个前端必须作为一个发布单元回滚或上线。
|
||||
旧 audience 路由不提供兼容入口。路由变化必须同步更新 OpenAPI 客户端和对应前端。
|
||||
|
||||
@@ -76,7 +76,7 @@ API 不自动迁移数据库。
|
||||
| `AuthorizationCacheInvalidationWorker` | 默认 2 秒 | 重试 PostgreSQL 中待处理的 Redis 授权缓存失效事件 |
|
||||
| `CommercialBillingWorker` | 60 秒 | 生成续费应收与催缴提醒、投递启用渠道并执行已审批退款 |
|
||||
|
||||
后台任务支持 `content_import`、`content_export`、`asset_security_scan`、`tenant_export`、`statistics_aggregation`、`commerce_reconciliation` 和 `tenant_domain_recheck`。安全扫描通过 ClamAV `INSTREAM` 协议流式处理对象；未通过扫描或扫描不可用时资源访问 fail-closed。
|
||||
后台任务处理器由所属 Infrastructure 模块实现并注册，Jobs 模块按 `JobType` 调度。当前类型包括 `content_import`、`content_export`、`asset_security_scan`、`tenant_export`、`statistics_aggregation`、`commerce_reconciliation` 和 `tenant_domain_recheck`；架构测试校验处理器数量、类型和模块注册。安全扫描通过 ClamAV `INSTREAM` 流式处理对象，未通过扫描或扫描不可用时不签发资源访问地址。
|
||||
|
||||
即时任务与 `RunAfter` 延时任务统一写入 `background_jobs`。后台任务用 `FOR UPDATE SKIP LOCKED` 和五分钟租约协调；六个周期处理器使用 PostgreSQL advisory lock，允许部署多个 Worker 实例而不重复执行同一周期循环。商业续费、应收、退款和催缴投递仍以 PostgreSQL 表为权威，不引入消息代理。
|
||||
|
||||
@@ -88,32 +88,15 @@ API 不自动迁移数据库。
|
||||
- 后台任务状态、执行时间、重试和结果由 `background_jobs` 持久化。
|
||||
- PostgreSQL 不启用 RLS；租户隔离由应用和数据库多层共同保证，详见[认证、授权与租户隔离](security-and-tenancy.md)。
|
||||
|
||||
## 当前业务模块
|
||||
## 业务入口
|
||||
|
||||
### 平台端
|
||||
| Audience | 主要边界 |
|
||||
| --- | --- |
|
||||
| Platform | 租户开通与生命周期、员工/RBAC、治理审批、平台题库、SaaS 账务、运营与告警 |
|
||||
| Tenant | 成员与 DataScope、内容题库、学习运营、学生/班级、CRM、商城增长及租户 Provider 配置 |
|
||||
| Student/Public | Host 运行时配置、认证资料、学习与进度、商城权益、推荐关系和公开内容 |
|
||||
|
||||
- 租户、Owner、域名、状态、员工、角色和审计告警。租户开通在单一事务中创建 Owner、Pending 主域名、默认试用和 v1 前端配置；域名 DNS/TLS Active 后才允许平台领取一次性 Owner 激活链接。
|
||||
- 平台公共题库、分类节点、题目、导入和资源上传。
|
||||
- SaaS Feature、额度定义、套餐版本、报价、订单、支付、退款、订阅、发票和催缴。
|
||||
- 平台级 CRM、短信渠道/模板和支付应用配置。
|
||||
|
||||
### 租户端
|
||||
|
||||
- 员工、角色、权限、菜单、DataScope 和租户设置。
|
||||
- 私有题库、公共题库引用、内容目录、词汇、手册、视频、分数线、站点内容、导入导出和资源。
|
||||
- 学生、班级、CRM 跟进、监管规则、报表和审计。
|
||||
- 学生商城、订单、支付、退款、优惠券、积分、推广和分佣。
|
||||
- 租户 SaaS 目录、账务、订阅、用量、发票和 onboarding 状态。
|
||||
- 身份、短信、对象存储、支付、通知和 AI 的租户 Provider 配置边界。
|
||||
|
||||
### 学生端
|
||||
|
||||
- Host 对应的运行时品牌、导航、Feature 和登录方式 bootstrap。
|
||||
- 账号登录、个人资料、通知、签到和积分。
|
||||
- 题目目录、练习会话、作答、收藏、错题、视频播放和进度。
|
||||
- 学生商品、订单、支付、优惠券、权益和推广关系。
|
||||
|
||||
是否存在某个具体操作，应以 Controller 和 OpenAPI 为准，不能仅凭本节的模块名称推断。
|
||||
具体操作、权限元数据和 DTO 以运行时 OpenAPI 为准。
|
||||
|
||||
## 外部服务边界
|
||||
|
||||
|
||||
@@ -102,9 +102,9 @@ Redis key 使用环境前缀；配置解析会强制 `AbortOnConnectFail=false`
|
||||
|
||||
域名只有在 `AllowedCnameTargets`、DNS JSON endpoint、Gateway URL 和 API key 配置完成后，才可能从 Pending/Failed 进入 Active。仅 DNS 验证成功不代表 TLS 已就绪。
|
||||
|
||||
`TenantProvisioning:DefaultBaseOfferingCode` 必须指向 Active 基础套餐中当前有效的最新 Published 版本。Production API 启动时会查询 PostgreSQL 验证该版本存在；开通事务也会再次校验，缺失时返回 `default_offering_unavailable`，不会留下半成品租户。平台运营流程为：创建租户并抄录 CNAME/TXT → 等待域名 Active → 领取一次性激活链接 → 通过既有安全渠道交付 Owner。链接关闭后无法再次查看；需要补发时必须填写原因并撤销旧链接。
|
||||
`TenantProvisioning:DefaultBaseOfferingCode` 必须指向 Active 基础套餐的有效 Published 版本。Production 启动与租户开通事务都会校验，缺失时返回 `default_offering_unavailable`。完整流程见[空数据库到租户建站验收](tenant-provisioning.md)。
|
||||
|
||||
后台任务状态和 `RunAfter` 存在 PostgreSQL。Worker 使用 `FOR UPDATE SKIP LOCKED`、五分钟租约和有限重试处理即时、延时及失败待重试任务；周期循环使用 PostgreSQL advisory lock 防止多实例重复执行。当前六个循环分别处理域名、订阅生命周期、Feature 用量、通用任务、授权缓存失效和商业账务。商业账务会生成续费应收、提醒、外部催缴投递和已审批退款；Webhook 必须使用 HTTPS、Host allowlist、签名和私网地址拒绝。`Worker:Enabled=false` 会关闭全部循环，通常只用于测试或维护。
|
||||
后台任务状态和 `RunAfter` 存在 PostgreSQL。Worker 使用 `FOR UPDATE SKIP LOCKED`、五分钟租约和有限重试；周期循环使用 PostgreSQL advisory lock 防止多实例重复执行。通用任务由模块注册的 `IBackgroundJobHandler` 处理，Jobs 模块负责查找、租约、重试和失败补偿。六个循环处理域名、订阅、Feature 用量、通用任务、授权缓存失效和商业账务。`Worker:Enabled=false` 会关闭全部循环。
|
||||
|
||||
API 和 Worker 必须使用同一 PostgreSQL 数据库与一致的对象存储配置。迁移必须在两者启动前由 `Tiku.DbMigrator` 单独执行。
|
||||
|
||||
@@ -204,7 +204,3 @@ Readiness 为绿色不等于认证授权、跨租户隔离或后台任务恢复
|
||||
- 归档会撤销该租户授权域 Session、禁用域名并失效运行时缓存；恢复后租户为 `Suspended`，域名为 `Pending`，必须重新审核后再激活。
|
||||
- Owner 转移目标必须是已有 Active 成员，并在同一事务内同步成员角色和后台角色绑定。
|
||||
- 发布前至少演练一次导出可下载、归档阻断条件、归档、恢复和 Owner 转移。
|
||||
|
||||
## 后台任务权威边界
|
||||
|
||||
当前运行时不依赖 RabbitMQ，也没有消息 inbox/outbox 发布链路。即时、延时、重试和商业任务均以 PostgreSQL 状态为准；Redis 不保存任务或商业状态真相。回滚时不得通过恢复旧消息表绕过当前数据库状态机。
|
||||
|
||||
@@ -132,5 +132,3 @@ PostgreSQL 特有的 Migration、事务、约束和租户隔离行为必须由
|
||||
### API 启动了但后台任务不执行
|
||||
|
||||
Production 和常规 Development 都需要独立运行 `Tiku.Worker`。Development 仅额外在 API 中注册本地域名生命周期旁路，不代表 API 承载全部 Worker 循环。
|
||||
|
||||
下一步可阅读[系统架构与业务边界](architecture/overview.md)、[认证、授权与租户隔离](architecture/security-and-tenancy.md)和[配置与后台任务](operations.md)。
|
||||
|
||||
@@ -4,21 +4,11 @@
|
||||
|
||||
## 1. 准备环境
|
||||
|
||||
需要 .NET 10、Node.js 24+、npm 11+、PostgreSQL、Redis，以及 `psql`、`createdb`、`dropdb`。
|
||||
先完成[本地开发快速上手](quickstart.md)中的依赖安装。本流程额外需要 Redis、`psql`、`createdb`、`dropdb` 和租户前端仓库。
|
||||
|
||||
```bash
|
||||
dotnet --version
|
||||
node --version
|
||||
npm --version
|
||||
pg_isready -h 127.0.0.1 -p 5432
|
||||
redis-cli -h 127.0.0.1 -p 6379 ping
|
||||
```
|
||||
|
||||
首次拉取代码后安装依赖：
|
||||
|
||||
```bash
|
||||
dotnet restore TIKU-BACKEND.slnx
|
||||
npm --prefix Tiku.PlatformAdmin.Web install
|
||||
npm --prefix /path/to/tiku-saas-web install
|
||||
```
|
||||
|
||||
@@ -206,5 +196,3 @@ dropdb -h 127.0.0.1 -U <数据库用户> tiku
|
||||
```
|
||||
|
||||
该操作不可恢复，会删除本轮创建的平台账号、租户、Session、草稿和发布配置。
|
||||
|
||||
日常开发启动见[本地开发快速上手](quickstart.md)，更多配置见[配置与后台任务](operations.md)，安全边界见[认证、授权与租户隔离](architecture/security-and-tenancy.md)。
|
||||
|
||||
Reference in New Issue
Block a user