dashboard-nanobot/design/database.md

# Dashboard Nanobot 数据库设计文档（当前实现）

数据库默认使用 SQLite：`data/nanobot_dashboard.db`。

## 1. ERD

```mermaid
erDiagram
    BOTINSTANCE ||--o{ BOTMESSAGE : "messages"
    NANOBOTIMAGE ||--o{ BOTINSTANCE : "referenced by"

    BOTINSTANCE {
        string id PK
        string name
        string workspace_dir UK
        string docker_status
        string image_tag
        string current_state
        text last_action
        datetime created_at
        datetime updated_at
    }

    BOTMESSAGE {
        int id PK
        string bot_id FK
        string role
        text text
        text media_json
        datetime created_at
    }

    NANOBOTIMAGE {
        string tag PK
        string image_id
        string version
        string status
        string source_dir
        datetime created_at
    }
```

## 2. 设计原则

- 数据库只保留运行索引和历史消息。
- Bot 参数（模型、渠道、资源配额、5 个 MD 文件）统一持久化在：
  - `.nanobot/config.json`
  - `.nanobot/workspace/*.md`
  - `.nanobot/env.json`
- `channelroute` 已废弃，不再使用数据库存储渠道。

## 3. 表说明

### 3.1 `botinstance`

仅存基础索引与运行态：

- 标识与展示：`id`、`name`
- 容器与镜像：`docker_status`、`image_tag`
- 运行状态：`current_state`、`last_action`
- 路径与时间：`workspace_dir`、`created_at`、`updated_at`

### 3.2 `botmessage`

Dashboard 渠道对话历史（用于会话回放）：

- `role`: `user | assistant`
- `text`: 文本内容
- `media_json`: 附件相对路径 JSON

### 3.3 `nanobotimage`

基础镜像登记表（手动注册）：

- `tag`: 如 `nanobot-base:v0.1.4`
- `status`: `READY | UNKNOWN | ERROR`
- `source_dir`: 来源标识（通常 `manual`）

## 4. 迁移策略

服务启动时：

1. `SQLModel.metadata.create_all(engine)`
2. 清理废弃表：`DROP TABLE IF EXISTS channelroute`
3. 对 `botinstance` 做列对齐，删除历史遗留配置列（保留当前最小字段集）