dashboard-nanobot/design/database.md

# Dashboard Nanobot 数据库设计文档

数据库默认使用 PostgreSQL（推荐使用 psycopg3 驱动）。

## 1. ERD

```mermaid
erDiagram
    bot_instance ||--o{ bot_message : "messages"
    bot_instance ||--o{ bot_request_usage : "usage"
    bot_instance ||--o{ bot_activity_event : "events"
    bot_image ||--o{ bot_instance : "referenced by"

    bot_instance {
        string id PK
        string name
        boolean enabled
        string access_password
        string workspace_dir UK
        string docker_status
        string current_state
        string last_action
        string image_tag
        datetime created_at
        datetime updated_at
    }

    bot_message {
        int id PK
        string bot_id FK
        string role
        text text
        text media_json
        string feedback
        datetime feedback_at
        datetime created_at
    }

    bot_image {
        string tag PK
        string image_id
        string version
        string status
        string source_dir
        datetime created_at
    }

    bot_request_usage {
        int id PK
        string bot_id FK
        string request_id
        string channel
        string status
        string provider
        string model
        int input_tokens
        int output_tokens
        int total_tokens
        datetime started_at
        datetime completed_at
        datetime created_at
    }

    bot_activity_event {
        int id PK
        string bot_id FK
        string request_id
        string event_type
        string channel
        string detail
        text metadata_json
        datetime created_at
    }

    sys_setting {
        string key PK
        string name
        string category
        string description
        string value_type
        text value_json
        boolean is_public
        int sort_order
        datetime created_at
        datetime updated_at
    }
```

## 2. 设计原则

- 数据库保留运行索引、历史消息、用量统计与运维事件。
- Bot 核心配置（渠道、资源配额、5 个 MD 文件）统一持久化在文件系统：
  - `.nanobot/config.json`
  - `.nanobot/workspace/*.md`
  - `.nanobot/env.json`

## 3. 表说明

### 3.1 `bot_instance`
存储 Bot 基础索引与运行态。

### 3.2 `bot_message`
Dashboard 渠道对话历史（用于会话回放与反馈）。

### 3.3 `bot_image`
基础镜像登记表。

### 3.4 `bot_request_usage`
模型调用用量详细记录。

### 3.5 `bot_activity_event`
运维事件记录（如容器启动/停止、指令提交、系统告警等）。

### 3.6 `sys_setting`
平台全局参数设置。

## 4. 初始化与迁移策略

数据库初始化改为离线显式执行：

1. `scripts/sql/create-tables.sql` 负责创建业务表和索引。
2. `scripts/sql/init-data.sql` 负责初始化 `sys_setting` 和默认 `skill_market_item` 数据。
3. `scripts/init-full-db.sh` 在完整部署场景下会按顺序执行 PostgreSQL 引导 SQL、建表 SQL、初始化数据 SQL。
4. 后端启动时（`backend/core/database.py`）只校验必需表和核心 `sys_setting` 是否已经存在；若缺失则直接中止启动，不再做运行时迁移或结构修复。