From 4751e738b1d7b6cc18cd3f81a38faaa53cb46639 Mon Sep 17 00:00:00 2001 From: xiong Date: Mon, 3 Aug 2026 13:41:03 +0800 Subject: [PATCH] =?UTF-8?q?=E6=B8=85=E7=90=86=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 1 + docs/README.md | 10 +----- .../dual-line-capability-matrix.md | 24 -------------- docs/architecture/module-boundaries.md | 31 ++++------------- docs/architecture/overview.md | 33 +++++-------------- docs/operations.md | 8 ++--- docs/quickstart.md | 2 -- docs/tenant-provisioning.md | 14 +------- 8 files changed, 20 insertions(+), 103 deletions(-) delete mode 100644 docs/architecture/dual-line-capability-matrix.md diff --git a/README.md b/README.md index 101726c..f901abc 100644 --- a/README.md +++ b/README.md @@ -84,6 +84,7 @@ PostgreSQL 特有的迁移、事务、约束和跨租户不变量必须由 `Tiku 当前文档统一从[文档总览](docs/README.md)进入： - [系统架构与业务边界](docs/architecture/overview.md) +- [模块边界与所有权](docs/architecture/module-boundaries.md) - [认证、授权与租户隔离](docs/architecture/security-and-tenancy.md) - [配置与后台任务](docs/operations.md) - [本地开发快速上手](docs/quickstart.md) diff --git a/docs/README.md b/docs/README.md index 6eea606..385238c 100644 --- a/docs/README.md +++ b/docs/README.md @@ -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. 不维护阶段路线图、旧后端接口对比、评审快照或开发过程记录。 diff --git a/docs/architecture/dual-line-capability-matrix.md b/docs/architecture/dual-line-capability-matrix.md deleted file mode 100644 index 7bb0d36..0000000 --- a/docs/architecture/dual-line-capability-matrix.md +++ /dev/null @@ -1,24 +0,0 @@ -# Tiku / RuoYi 双线能力矩阵 - -状态只使用：`已实现`、`已验证`、`计划中`、`明确不移植`。`已实现`表示当前 Tiku 源码存在该能力，`已验证`表示本仓库自动化或本机真实依赖验收已经通过；它不等于生产容量结论。 - -| 能力 | Tiku 状态 | RuoYi 用途 | 维护决策 | -| --- | --- | --- | --- | -| Host 租户解析与租户开通 | 已验证 | 功能对照 | Tiku 主线 | -| 平台多岗位 RBAC、菜单与路由守卫 | 已验证 | 通用后台样板 | Tiku 原生维护 | -| OpenAPI 操作权限、风险和审批策略元数据 | 已验证 | 不移植 | Tiku 原生维护 | -| 分级四眼审批与 Worker 执行 | 已验证 | 流程参考 | Tiku 原生维护 | -| 类型化配置、版本发布与回滚 | 已验证 | 配置中心参考 | Tiku 原生维护 | -| 平台站内通知与投递记录 | 已实现 | 通知中心参考 | 短信、邮件 Provider 投递计划中 | -| 租户 360 聚合工作台 | 计划中 | 页面交互参考 | 按 Tiku 领域投影实现 | -| 平台跨租户列表统一分页 | 计划中 | SQL 与分页参考 | 逐接口迁移为 `PagedResult` | -| 热目录输出缓存 | 已验证 | 性能对照线 | Tiku 保持租户感知缓存 | -| 冷查询、复合索引和批量写入 | 计划中 | SQL 优化参考 | 先公平基准，再按查询补索引 | -| 代码生成器 | 明确不移植 | 仅开发效率参考 | 不进入产品运行时 | -| 动态数据源、Druid 管理页 | 明确不移植 | 不使用 | 保持单一受控数据访问边界 | -| Quartz 任意任务编辑 | 明确不移植 | 不使用 | 仅实现专用 Worker 与命令 | -| 通用业务字典 | 明确不移植 | 不使用 | 使用领域枚举和类型化配置 | - -## 公平比较约束 - -性能结论必须使用同一台机器、相同 PostgreSQL/Redis 版本、相同租户数和业务数据量，并分别报告热目录、冷目录、认证、平台分页、批量导入和 Worker 竞争。每个场景至少执行三轮，记录 QPS、p95、p99、HTTP 状态、丢失迭代与依赖状态。未满足这些条件时，只能记录源码推断，不能记录生产容量胜负。 diff --git a/docs/architecture/module-boundaries.md b/docs/architecture/module-boundaries.md index 576a4e6..485cb65 100644 --- a/docs/architecture/module-boundaries.md +++ b/docs/architecture/module-boundaries.md @@ -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 客户端和对应前端。 diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index 8a6f4ec..e3445d1 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -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 为准。 ## 外部服务边界 diff --git a/docs/operations.md b/docs/operations.md index 02c0620..3584291 100644 --- a/docs/operations.md +++ b/docs/operations.md @@ -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 不保存任务或商业状态真相。回滚时不得通过恢复旧消息表绕过当前数据库状态机。 diff --git a/docs/quickstart.md b/docs/quickstart.md index 5966bec..da423df 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -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)。 diff --git a/docs/tenant-provisioning.md b/docs/tenant-provisioning.md index 7fa02d5..ded6f39 100644 --- a/docs/tenant-provisioning.md +++ b/docs/tenant-provisioning.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)。