formatting and comments

2026-07-16 00:12:26 -07:00
parent edb6d2b5b4
commit 994854d104
45 changed files with 2514 additions and 628 deletions
@@ -0,0 +1,50 @@
+# Rust 后端
+
+这是多租户直播组件服务的可复用核心和唯一运行时进程。`src/main.rs` 只处理进程启动；主要行为由 library
+crate 导出。
+
+## 模块职责
+
+| 模块          | 职责                                                     |
+| ------------- | -------------------------------------------------------- |
+| `app`         | 依赖组装、迁移、事件队列、源启动与旧配置导入             |
+| `auth`        | 邀请码、TOTP、恢复码、会话、secret 加密和组件 token      |
+| `components`  | 组件定义、设置版本、订阅、projection 与 handler registry |
+| `config`      | TOML 解析、部署策略校验和旧单用户兼容字段                |
+| `credentials` | CookieCloud URL 边界与 Bilibili Cookie 提取              |
+| `db`          | PostgreSQL pool、迁移和 RLS tenant context               |
+| `domain`      | provider-independent event 与 WebSocket envelope         |
+| `http_api`    | REST/WS、会话、权限、same-origin、静态资源与安全响应头   |
+| `live`        | provider trait、Bilibili adapter 与 source supervisor    |
+| `overlay`     | 弹幕姬设置及礼物/表情目录                                |
+| `rate_limit`  | 匿名登录和 enrollment 滥用限制                           |
+| `realtime`    | source event routing 与 component-scoped fanout          |
+| `repository`  | PostgreSQL component facade 和热路径缓存同步             |
+
+## 重要不变量
+
+- handler 不能信任请求体中的 owner；owner 必须来自 session 或 source context。
+- tenant table 查询必须在 `Db::set_tenant` 后的事务中执行。
+- provider 只能输出 canonical、bounded、sanitized `LiveEvent`。
+- projection 无副作用；可靠业务动作必须使用幂等 handler。
+- token、邀请码和恢复码只存摘要，TOTP/CookieCloud Secret 只存认证加密密文。
+- EventHub 的 channel key 是 component ID，不允许增加无权限的全局 receiver。
+
+## 本地质量检查
+
+在仓库根目录执行：
+
+```bash
+cargo fmt --manifest-path apps/server-rust/Cargo.toml --check
+cargo clippy --manifest-path apps/server-rust/Cargo.toml --all-targets --no-deps -- -D warnings
+cargo test --manifest-path apps/server-rust/Cargo.toml --all-targets
+```
+
+第三方 `vendor/blivedm` 不作为本项目风格重写目标；项目只维护保留原始 JSON 所需的小补丁。
+
+更多设计说明：
+
+- [总体架构](../../docs/architecture.md)
+- [组件开发](../../docs/components/README.md)
+- [实时协议](../../docs/protocol.md)
+- [安全模型](../../docs/security.md)