# Luxx 数据库设计文档

## 1. 数据库概述

- **类型**: SQLite
- **ORM**: SQLAlchemy 2.0
- **连接字符串**: `sqlite:///./chat.db`

## 2. ER 关系图

```mermaid
erDiagram
    USER {
        int id PK
        string username UK
        string email UK
        string password_hash
        string role
        int permission_level
        string workspace_path
        bool is_active
        datetime created_at
    }

    LLM_PROVIDER {
        int id PK
        int user_id FK
        string name
        string provider_type
        string base_url
        string api_key
        string default_model
        int max_tokens
        bool is_default
        bool enabled
        datetime created_at
    }

    PROJECT {
        string id PK
        int user_id FK
        string name
        string description
        datetime created_at
    }

    CONVERSATION {
        string id PK
        int user_id FK
        int provider_id FK
        string title
        string model
        text system_prompt
        float temperature
        bool thinking_enabled
        datetime created_at
    }

    MESSAGE {
        string id PK
        string conversation_id FK
        string role
        text content
        int token_count
        string usage
        datetime created_at
    }

    AGENT {
        string id PK
        string name
        string role
        string avatar
        text system_prompt
        int provider_id FK
        string model
        string tools
        bool is_active
        int priority
        bool auto_response
        bool mention_trigger
        float temperature
        int max_tokens
    }

    CHAT_ROOM {
        string id PK
        string name
        string description
        int owner_id FK
        bool is_active
        datetime created_at
    }

    CHAT_ROOM_AGENT {
        string id PK
        string chat_room_id FK
        string agent_id FK
        bool is_active
        datetime joined_at
    }

    CHAT_ROOM_MESSAGE {
        string id PK
        string room_id FK
        string sender_type
        string sender_id
        string sender_name
        text content
        string mentions
        string parent_id
        int token_count
        datetime created_at
    }

    USER ||--o{ LLM_PROVIDER : has
    USER ||--o{ PROJECT : owns
    USER ||--o{ CONVERSATION : creates
    USER ||--o{ CHAT_ROOM : owns
    USER ||--o{ AGENT : creates
    LLM_PROVIDER ||--o{ CONVERSATION : powers
    LLM_PROVIDER ||--o{ AGENT : configures
    CONVERSATION ||--o{ MESSAGE : contains
    CHAT_ROOM ||--o{ CHAT_ROOM_MESSAGE : contains
    CHAT_ROOM ||--o{ CHAT_ROOM_AGENT : has
    AGENT ||--o{ CHAT_ROOM_AGENT : joins
```

## 3. 表设计

### users 用户表

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | INTEGER | PK | 用户 ID |
| username | VARCHAR(50) | UNIQUE, NOT NULL | 用户名 |
| email | VARCHAR(120) | UNIQUE | 邮箱 |
| password_hash | VARCHAR(255) | - | 密码哈希 |
| role | VARCHAR(20) | DEFAULT 'user' | 角色 |
| permission_level | INTEGER | DEFAULT 1 | 权限等级 |
| workspace_path | VARCHAR(500) | - | 工作空间路径 |
| is_active | BOOLEAN | DEFAULT 1 | 是否激活 |
| created_at | DATETIME | - | 创建时间 |

**权限等级:** 1=READ_ONLY, 2=WRITE, 3=EXECUTE, 4=ADMIN

### llm_providers LLM 提供商表

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | INTEGER | PK | 提供商 ID |
| user_id | INTEGER | FK(users.id) | 所属用户 |
| name | VARCHAR(100) | NOT NULL | 提供商名称 |
| provider_type | VARCHAR(50) | NOT NULL | 类型 |
| base_url | VARCHAR(500) | NOT NULL | API 地址 |
| api_key | VARCHAR(500) | NOT NULL | API 密钥 |
| default_model | VARCHAR(100) | NOT NULL | 默认模型 |
| max_tokens | INTEGER | DEFAULT 8192 | 最大 token |
| is_default | BOOLEAN | DEFAULT 0 | 是否默认 |
| enabled | BOOLEAN | DEFAULT 1 | 是否启用 |

### projects 项目表

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | VARCHAR(64) | PK | 项目 ID |
| user_id | INTEGER | FK(users.id) | 所属用户 |
| name | VARCHAR(255) | NOT NULL | 项目名称 |
| description | TEXT | - | 描述 |
| created_at | DATETIME | - | 创建时间 |

### conversations 会话表

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | VARCHAR(64) | PK | 会话 ID |
| user_id | INTEGER | FK(users.id) | 所属用户 |
| provider_id | INTEGER | FK(llm_providers.id) | LLM 提供商 |
| title | VARCHAR(255) | NOT NULL | 会话标题 |
| model | VARCHAR(64) | NOT NULL | 模型名称 |
| system_prompt | TEXT | NOT NULL | 系统提示词 |
| temperature | FLOAT | DEFAULT 0.7 | 温度参数 |
| max_tokens | INTEGER | DEFAULT 2000 | 最大 token |
| thinking_enabled | BOOLEAN | DEFAULT 0 | 思维链开关 |

### messages 消息表

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | VARCHAR(64) | PK | 消息 ID |
| conversation_id | VARCHAR(64) | FK(conversations.id) | 所属会话 |
| role | VARCHAR(16) | NOT NULL | user/assistant/system/tool |
| content | TEXT | NOT NULL | JSON 格式内容 |
| token_count | INTEGER | DEFAULT 0 | Token 数 |
| usage | TEXT | - | Token 使用统计 |
| created_at | DATETIME | - | 创建时间 |

**content 格式:** `{"text": "...", "steps": [...]}`

### agents Agent 表

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | VARCHAR(64) | PK | Agent ID |
| name | VARCHAR(50) | NOT NULL | 名称 |
| role | VARCHAR(50) | NOT NULL | 角色类型 |
| avatar | VARCHAR(500) | - | 头像 URL |
| system_prompt | TEXT | NOT NULL | 系统提示词 |
| provider_id | INTEGER | FK(llm_providers.id) | LLM 提供商 |
| model | VARCHAR(100) | - | 模型 |
| tools | TEXT | - | 工具列表(JSON 数组) |
| is_active | BOOLEAN | DEFAULT 1 | 是否启用 |
| priority | INTEGER | DEFAULT 5 | 优先级 |
| auto_response | BOOLEAN | DEFAULT 1 | 自动响应 |
| mention_trigger | BOOLEAN | DEFAULT 0 | @ 触发 |
| temperature | FLOAT | DEFAULT 0.7 | 温度 |
| max_tokens | INTEGER | DEFAULT 2048 | 最大 token |

### chat_rooms 聊天室表

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | VARCHAR(64) | PK | 聊天室 ID |
| name | VARCHAR(100) | NOT NULL | 聊天室名称 |
| description | TEXT | - | 描述 |
| owner_id | INTEGER | FK(users.id) | 所有者 |
| is_active | BOOLEAN | DEFAULT 1 | 是否启用 |
| created_at | DATETIME | - | 创建时间 |

### chat_room_agents 聊天室成员表

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | VARCHAR(64) | PK | 关联 ID |
| chat_room_id | VARCHAR(64) | FK(chat_rooms.id) | 聊天室 ID |
| agent_id | VARCHAR(64) | FK(agents.id) | Agent ID |
| is_active | BOOLEAN | DEFAULT 1 | 是否启用 |
| joined_at | DATETIME | - | 加入时间 |

### chat_room_messages 聊天室消息表

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| id | VARCHAR(64) | PK | 消息 ID |
| room_id | VARCHAR(64) | FK(chat_rooms.id) | 聊天室 ID |
| sender_type | VARCHAR(16) | NOT NULL | user/agent/system |
| sender_id | VARCHAR(64) | NOT NULL | 发送者 ID |
| sender_name | VARCHAR(50) | NOT NULL | 发送者名称 |
| content | TEXT | NOT NULL | 消息内容 |
| mentions | TEXT | - | @ 提及列表(JSON) |
| parent_id | VARCHAR(64) | - | 回复的消息 ID |
| token_count | INTEGER | DEFAULT 0 | Token 数 |
| created_at | DATETIME | - | 创建时间 |

## 4. 流程图

### 消息流

```mermaid
sequenceDiagram
    participant U as 用户
    participant WS as WebSocket
    participant R as ChatRoomService
    participant A as Agent
    participant LLM as LLM

    U->>WS: 发送消息
    WS->>R: dispatch
    R->>A: 触发 Agent
    A->>LLM: stream_call
    LLM-->>A: SSE 流
    A-->>WS: process_step
    WS-->>U: 实时推送
```

### Agent 调度

```mermaid
flowchart TD
    A[用户消息] --> B{有 @ 提及?}

    B -->|是| C[触发指定 Agent]
    B -->|否| D[触发 auto_response Agent]

    C --> E[并行调用]
    D --> E
    E --> F[流式响应]
    F --> G[聚合结果]
    G --> H[WebSocket 推送]
```

## 5. 索引

```mermaid
flowchart LR
    subgraph indexes[推荐索引]
        I1[users.username UNIQUE]
        I2[users.email UNIQUE]
        I3[conversations.user_id]
        I4[messages.conversation_id]
        I5[chat_rooms.owner_id]
        I6[chat_room_messages.room_id]
    end
```

## 6. 迁移

```python
from luxx.core.database import init_db
init_db()  # 创建所有表
```