模块划分

Sentinel 后端采用模块化设计，每个模块负责特定的业务领域。

模块概览

apps/api/src/
├── analysis/          # 分析任务模块
├── auth/              # 认证授权模块
├── health/            # 健康检查模块
├── integrations/      # 第三方集成模块
├── projects/          # 项目管理模块
├── repositories/      # 仓库管理模块
├── requests/          # LLM 请求记录模块
├── session_artifacts/ # 会话产物模块
├── sessions/          # Agent 会话模块
├── sse/              # Server-Sent Events 模块
├── tool_calls/       # 工具调用记录模块
├── users/            # 用户管理模块
└── webhooks/         # Webhook 处理模块

核心模块详解

1. Auth 模块

职责: 用户认证和授权

主要功能:

用户登录/注册
JWT Token 生成和验证
GitHub OAuth 集成
密码重置流程
用户信息管理

关键文件:

auth/
├── routes.rs         # 认证相关路由
├── repository.rs     # 用户数据访问
├── github.rs         # GitHub OAuth 客户端
└── mod.rs           # 模块导出

数据库表:

users - 用户基本信息
password_reset_tokens - 密码重置令牌

API 端点:

POST /api/v1/auth/login
POST /api/v1/auth/register
POST /api/v1/auth/logout
GET /api/v1/me

2. Projects 模块

职责: 项目生命周期管理

主要功能:

创建/更新/删除项目
项目列表查询
Slug 唯一性管理
项目归属验证

关键文件:

projects/
├── routes.rs         # 项目路由
├── repository.rs     # 项目数据访问
├── model.rs         # 请求/响应模型
└── mod.rs

数据库表:

projects - 项目信息

API 端点:

POST /api/v1/projects
GET /api/v1/projects
GET /api/v1/projects/{id}
PATCH /api/v1/projects/{id}
DELETE /api/v1/projects/{id}

3. Repositories 模块

职责: 代码仓库管理

主要功能:

GitHub 仓库导入
仓库设置管理
自动审查配置
仓库列表查询

关键文件:

repositories/
├── routes.rs         # 仓库路由
├── repository.rs     # 仓库数据访问
└── mod.rs

数据库表:

repositories - 仓库信息

配置字段:

enabled - 是否启用
review_on_push - Push 时自动审查
review_on_pull_request - PR 时自动审查

API 端点:

POST /api/v1/projects/{id}/repositories/imports/github
GET /api/v1/projects/{id}/repositories
GET /api/v1/repositories/{id}
PATCH /api/v1/repositories/{id}

4. Analysis 模块

职责: 代码分析任务管理

主要功能:

创建分析任务
任务状态管理
分析结果查询
任务取消和重运行

关键文件:

analysis/
├── routes.rs         # 分析路由
├── repository.rs     # 分析数据访问
├── model.rs         # 分析模型
└── mod.rs

数据库表:

analyses - 分析任务信息

任务类型:

security_review - 安全审查
code_review - 代码审查
full_analysis - 全面分析

任务状态:

submitted → pending → running → completed
                            ↘ failed
                            ↘ cancelled

API 端点:

POST /api/v1/analysis
GET /api/v1/analysis
GET /api/v1/analysis/{id}
POST /api/v1/analysis/{id}/rerun
DELETE /api/v1/analysis/{id}
GET /api/v1/analysis/{id}/findings
GET /api/v1/analysis/{id}/requests
GET /api/v1/analysis/{id}/tool-calls

5. Integrations 模块

职责: 第三方服务集成

主要功能:

GitHub App 安装管理
GitHub API 同步
远程仓库列表
权限验证

关键文件:

integrations/
├── routes.rs         # 集成路由
├── repository.rs     # 集成数据访问
├── github_client.rs  # GitHub API 客户端
└── mod.rs

数据库表:

github_installations - GitHub App 安装记录

API 端点:

GET /api/v1/integrations/github/install-url
GET /api/v1/integrations/github/callback
GET /api/v1/integrations/github/installations
POST /api/v1/integrations/github/installations/{id}/sync
GET /api/v1/integrations/github/installations/{id}/repositories
GET /api/v1/integrations/github/installations/{id}/remote-repositories

6. Sessions 模块

职责: Agent 执行会话管理

主要功能:

会话生命周期管理
会话状态跟踪
会话产物关联

关键文件:

sessions/
├── routes.rs         # 会话路由
├── repository.rs     # 会话数据访问
└── mod.rs

数据库表:

sessions - Agent 会话记录

会话状态:

pending - 等待中
running - 执行中
completed - 已完成
failed - 失败
cancelled - 已取消

7. Requests 模块

职责: LLM API 请求记录

主要功能:

记录 Claude API 请求
Token 使用统计
缓存命中率追踪

关键文件:

requests/
├── routes.rs         # 请求路由
├── repository.rs     # 请求数据访问
└── mod.rs

数据库表:

requests - LLM 请求记录

记录字段:

model - 使用的模型
input_tokens - 输入 Token 数
output_tokens - 输出 Token 数
cached_input_tokens - 缓存命中 Token 数

8. Tool Calls 模块

职责: Agent 工具调用记录

主要功能:

记录工具调用历史
工具执行状态追踪
输入输出记录

关键文件:

tool_calls/
├── routes.rs         # 工具调用路由
├── repository.rs     # 工具调用数据访问
└── mod.rs

数据库表:

tool_calls - 工具调用记录

工具类型 (示例):

read_file - 读取文件
write_file - 写入文件
execute_command - 执行命令
search_code - 搜索代码

9. SSE 模块

职责: 实时事件推送

主要功能:

分析任务实时状态推送
会话事件流
连接管理

关键文件:

sse/
├── routes.rs         # SSE 路由
└── mod.rs

事件类型:

status_changed - 状态变更
progress_updated - 进度更新
finding_added - 新增发现
session_started - 会话开始
session_completed - 会话完成

连接端点:

GET /api/v1/sse/analysis/{id}
GET /api/v1/sse/session/{id}

10. Webhooks 模块

职责: 外部事件处理

主要功能:

GitHub Webhook 接收
事件签名验证
自动触发分析

关键文件:

webhooks/
├── routes.rs         # Webhook 路由
└── mod.rs

处理的 GitHub 事件:

push - 代码推送
pull_request - PR 事件
installation - App 安装
installation_repositories - 仓库权限变更

API 端点:

POST /api/v1/webhooks/github

11. Session Artifacts 模块

职责: 会话产物存储

主要功能:

存储分析报告
存储代码快照
产物查询和下载

关键文件:

session_artifacts/
├── routes.rs         # 产物路由
├── repository.rs     # 产物数据访问
└── mod.rs

存储位置:

Object Store (S3/R2)

产物类型:

review_report - 审查报告
code_snapshot - 代码快照
diff_analysis - Diff 分析

12. Users 模块

职责: 用户信息管理

主要功能:

用户资料查询
用户列表（管理员）
用户状态管理

关键文件:

users/
├── routes.rs         # 用户路由
├── repository.rs     # 用户数据访问
└── mod.rs

用户角色:

user - 普通用户
admin - 管理员
system - 系统账户

用户状态:

active - 活跃
suspended - 暂停
deleted - 已删除

13. Health 模块

职责: 系统健康检查

主要功能:

数据库连接检查
服务状态检查

API 端点:

GET /health

模块依赖关系

┌─────────────┐
│   Health    │ (独立)
└─────────────┘

┌─────────────┐
│    Auth     │ ←──┐
└─────────────┘    │
       │           │
       ↓           │
┌─────────────┐    │
│   Users     │    │
└─────────────┘    │
                   │
┌─────────────┐    │
│  Projects   │ ←──┤
└─────────────┘    │
       │           │
       ↓           │
┌─────────────┐    │
│Repositories │ ←──┤
└─────────────┘    │
       │           │
       ↓           │
┌─────────────┐    │
│  Analysis   │ ←──┘
└─────────────┘
       │
       ├──→ ┌─────────────┐
       │    │  Sessions   │
       │    └─────────────┘
       │           │
       ├──→ ┌─────────────┐
       │    │  Requests   │
       │    └─────────────┘
       │           │
       ├──→ ┌─────────────┐
       │    │ Tool Calls  │
       │    └─────────────┘
       │           │
       └──→ ┌─────────────┐
            │Session      │
            │Artifacts    │
            └─────────────┘

┌─────────────┐
│Integrations │ (独立)
└─────────────┘

┌─────────────┐
│  Webhooks   │ (独立)
└─────────────┘

┌─────────────┐
│     SSE     │ (独立)
└─────────────┘

模块间通信

1. 直接依赖

Analysis 依赖 Repositories
Repositories 依赖 Projects
Projects 依赖 Users

2. 数据关联

Sessions 关联 Analysis
Requests 关联 Sessions
Tool Calls 关联 Requests

3. 事件驱动

Webhooks 触发 Analysis
Analysis 推送 SSE 事件

模块设计模式

标准模块结构

每个模块遵循统一的结构：

rust

// mod.rs
mod repository;
mod routes;

pub use repository::*;
pub use routes::router;

// routes.rs
use axum::Router;

pub fn router() -> Router<AppState> {
    Router::new()
        .route("/path", get(handler))
        // ...
}

// repository.rs
pub struct XxxRepository {
    db: Pool<Postgres>,
}

impl XxxRepository {
    pub fn new(db: Pool<Postgres>) -> Self {
        Self { db }
    }
    
    pub async fn find_by_id(&self, id: Uuid) -> Result<Option<Record>> {
        // SQLx query
    }
}

错误处理模式

每个模块定义自己的 AppError：

rust

struct AppError {
    status: StatusCode,
    message: String,
}

impl AppError {
    fn not_found(msg: impl Into<String>) -> Self { /* ... */ }
    fn bad_request(msg: impl Into<String>) -> Self { /* ... */ }
    fn db(error: impl Display) -> Self { /* ... */ }
}

impl IntoResponse for AppError {
    fn into_response(self) -> Response {
        (self.status, Json(json!({ "error": self.message }))).into_response()
    }
}

模块划分 ​

模块概览 ​

核心模块详解 ​

1. Auth 模块 ​

2. Projects 模块 ​

3. Repositories 模块 ​

4. Analysis 模块 ​

5. Integrations 模块 ​

6. Sessions 模块 ​

7. Requests 模块 ​

8. Tool Calls 模块 ​

9. SSE 模块 ​

10. Webhooks 模块 ​

11. Session Artifacts 模块 ​

12. Users 模块 ​

13. Health 模块 ​

模块依赖关系 ​

模块间通信 ​

1. 直接依赖 ​

2. 数据关联 ​

3. 事件驱动 ​

模块设计模式 ​

标准模块结构 ​

错误处理模式 ​

下一步阅读 ​

模块划分

模块概览

核心模块详解

1. Auth 模块

2. Projects 模块

3. Repositories 模块

4. Analysis 模块

5. Integrations 模块

6. Sessions 模块

7. Requests 模块

8. Tool Calls 模块

9. SSE 模块

10. Webhooks 模块

11. Session Artifacts 模块

12. Users 模块

13. Health 模块

模块依赖关系

模块间通信

1. 直接依赖

2. 数据关联

3. 事件驱动

模块设计模式

标准模块结构

错误处理模式

下一步阅读