# InsightReply 系统架构 (Architecture Overview)

> 本文档描述 InsightReply 的整体技术架构、各组件职责与数据流。

---

## 一、架构全景图

```
┌─────────────────────────────────────────────────────────────────┐
│                      用户浏览器 (Chrome / Edge)                   │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │              X (Twitter) 页面                            │    │
│  │  ┌──────────────┐    ┌──────────────────────────────┐   │    │
│  │  │ Content       │    │ InsightReply Sidebar         │   │    │
│  │  │ Script        │───▶│ (Shadow DOM 隔离)            │   │    │
│  │  │ - DOM 感知     │    │ - 策略选择                    │   │    │
│  │  │ - 按钮注入     │    │ - 评论展示                    │   │    │
│  │  │ - 数据提取     │    │ - 一键复制                    │   │    │
│  │  └──────────────┘    └──────────┬───────────────────┘   │    │
│  └───────────────────────────────────┼─────────────────────┘    │
│                                      │ chrome.runtime           │
│  ┌───────────────────────────────────┼─────────────────────┐    │
│  │          Background Service Worker                       │    │
│  │          - 消息中转                                       │    │
│  │          - JWT Token 管理                                │    │
│  │          - API 请求代理                                   │    │
│  └───────────────────────────────────┼─────────────────────┘    │
└──────────────────────────────────────┼──────────────────────────┘
                                       │ HTTPS
                                       ▼
┌──────────────────────────────────────────────────────────────────┐
│                    Nginx / Caddy (TLS 终结)                       │
└──────────────────────────────────────┬───────────────────────────┘
                                       │
                                       ▼
┌──────────────────────────────────────────────────────────────────┐
│                   Go 后端服务 (Docker Container)                  │
│                                                                  │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────┐    │
│  │ Handler  │─▶│ Service  │─▶│Repository│─▶│ PostgreSQL   │    │
│  │ (HTTP)   │  │ (BizLogic│  │ (GORM)   │  │ (Tailscale)  │    │
│  └──────────┘  └────┬─────┘  └──────────┘  └──────────────┘    │
│                     │                                            │
│                     ▼                                            │
│            ┌──────────────┐                                      │
│            │ LLM Gateway  │──▶ OpenAI / Claude / DeepSeek       │
│            │ (Timeout +   │                                      │
│            │  Breaker +   │                                      │
│            │  Retry)      │                                      │
│            └──────────────┘                                      │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ Radar Scheduler (定时任务)                                │   │
│  │ - Asynq (Redis Queue)                                    │   │
│  │ - Nitter Scraper                                         │   │
│  │ - 热度计算引擎                                            │   │
│  └──────────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────────┘
```

---

## 二、分层架构 (Clean Architecture)

```
cmd/server/main.go          ← 入口：配置加载、依赖注入、路由注册
│
├── internal/handler/       ← 表现层：HTTP 请求解析 → 调用 Service → 返回 JSON
│   ├── ai_handler.go
│   ├── user_handler.go
│   └── common.go           ← 统一 Response 工具函数
│
├── internal/service/       ← 业务层：核心逻辑（LLM 调用、热度计算、权限校验）
│   ├── ai_service.go
│   └── user_service.go
│
├── internal/repository/    ← 数据层：封装所有 SQL / GORM 操作
│   └── user_repository.go
│
├── internal/model/         ← 数据模型：Go struct 定义
│   └── user.go
│
├── config/                 ← 配置读取（环境变量 → 结构体）
├── pkg/                    ← 跨模块共享工具包
└── prompts/                ← Prompt 模板文件 (规划中)
```

**调用链规则**：`Handler → Service → Repository`，严禁跨层调用。

---

## 三、数据流

### 3.1 核心链路：用户生成评论

```mermaid
sequenceDiagram
    participant U as 用户 (X 页面)
    participant CS as Content Script
    participant BG as Background SW
    participant API as Go 后端
    participant LLM as OpenAI

    U->>CS: 点击 Insight 按钮
    CS->>CS: 提取推文 DOM 数据
    CS->>BG: chrome.runtime.sendMessage
    BG->>API: POST /ai/generate (带 JWT)
    API->>API: 验证 Token + Rate Limit
    API->>LLM: ChatCompletion (含 Prompt)
    LLM-->>API: 生成结果
    API-->>BG: JSON 响应 (10 条候选)
    BG-->>CS: sendResponse
    CS->>U: Sidebar 展示评论
    U->>U: 选择 → 一键复制 → 粘贴发布
```

### 3.2 雷达链路：后台监控推文 *(规划中)*

```mermaid
sequenceDiagram
    participant SCH as Scheduler
    participant Q as Asynq (Redis)
    participant SC as Scraper Worker
    participant NIT as Nitter 实例
    participant DB as PostgreSQL

    SCH->>Q: 定时投放抓取任务
    Q->>SC: 消费任务
    SC->>SC: Jitter 延迟 (1-5s)
    SC->>NIT: HTTP GET (指纹轮换)
    alt 正常响应
        NIT-->>SC: HTML
        SC->>SC: goquery 解析
        SC->>DB: Batch UPSERT tweets
        SC->>DB: 计算 heat_score
    else 429/503
        SC->>SC: 触发 Circuit Breaker
        SC->>Q: 指数退避后重新入队
    end
```

---

## 四、部署架构

```
                    Internet
                       │
              ┌────────┴────────┐
              │  Nginx / Caddy  │ ← TLS + 反代 → :8080
              └────────┬────────┘
                       │
    ┌──────────────────┼──────────────────┐
    │          Oracle ARM VPS              │
    │          144.24.60.0                 │
    │                                      │
    │  ┌────────────────────────────┐      │
    │  │ Docker                     │      │
    │  │  ├── insight-reply-server  │      │
    │  │  └── (未来: redis)         │      │
    │  └────────────────────────────┘      │
    │                                      │
    └──────────────────┼──────────────────┘
                       │ Tailscale VPN
                       ▼
              ┌────────────────┐
              │  PostgreSQL    │
              │  100.64.0.5    │
              └────────────────┘
```

---

## 五、技术栈一览

| 层级 | 技术 | 版本 |
|------|------|------|
| **前端插件** | Vue 3 + Composition API | 3.5 |
| **样式** | Tailwind CSS | v4 |
| **打包** | Vite + CRXJS | 7.x |
| **后端** | Go (chi router) | 1.24 |
| **ORM** | GORM + pgx | 1.31 |
| **数据库** | PostgreSQL | 15+ |
| **LLM** | OpenAI (go-openai) | GPT-4o Mini |
| **任务队列** *(规划)* | Asynq (Redis) | - |
| **容器** | Docker + Docker Compose | 24.x |
| **CI/CD** | Gitea Actions | - |
| **VPN** | Tailscale | - |