# ///
# DATABASE.md
# 描述：WXAuto Center 数据库设计文档
# 作者：AI Generated
# 创建日期：2026-04-05
# 更新日期：2026-04-06
# ///

# WXAuto Center 数据库设计文档

## 概述

本系统使用 PostgreSQL 数据库，通过 SQLAlchemy ORM 进行数据访问。数据库包含以下表：

| 表名 | 说明 |
|------|------|
| `nodes` | 节点配置表 |
| `webhook_urls` | Webhook URL 表 |
| `logs` | 日志表 |
| `plugin_configs` | 插件配置表 |

## ER 图

```
┌─────────────────┐     ┌─────────────────┐
│     nodes       │     │ webhook_urls    │
├─────────────────┤     ├─────────────────┤
│ node_id (PK)    │     │ id (PK)         │
│ name            │     │ name            │
│ api_url         │     │ url             │
│ api_key         │     │ format          │
│ enabled         │     │ enabled         │
│ description     │     │ event_types     │
│ group           │     │ created_at      │
│ status          │     │ updated_at      │
│ wechat_status   │     └─────────────────┘
│ is_healthy      │
│ health_message  │
│ created_at      │
│ updated_at      │
└─────────────────┘

┌─────────────────┐     ┌─────────────────┐
│     logs        │     │ plugin_configs  │
├─────────────────┤     ├─────────────────┤
│ id (PK)         │     │ id (PK)         │
│ timestamp       │     │ plugin_name     │
│ level           │     │ config_json     │
│ source          │     │ enabled         │
│ message         │     │ created_at      │
└─────────────────┘     │ updated_at      │
                        └─────────────────┘
```

---

## 表结构详解

### 1. nodes - 节点配置表

存储所有微信节点的信息。

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `node_id` | VARCHAR(50) | **PK** | 节点唯一标识 |
| `name` | VARCHAR(100) | NOT NULL | 节点显示名称 |
| `api_url` | VARCHAR(255) | NOT NULL | 节点 API 地址 |
| `api_key` | VARCHAR(255) | NOT NULL | 节点 API 密钥 |
| `enabled` | BOOLEAN | DEFAULT true | 是否启用 |
| `description` | TEXT | DEFAULT '' | 节点描述 |
| `group` | VARCHAR(50) | DEFAULT 'default' | 节点分组 |
| `status` | VARCHAR(20) | DEFAULT 'inactive' | API 状态 |
| `wechat_status` | VARCHAR(20) | DEFAULT 'online' | 微信状态 |
| `is_healthy` | BOOLEAN | DEFAULT false | 健康检查状态 |
| `health_message` | VARCHAR(255) | DEFAULT '' | 健康检查消息 |
| `created_at` | TIMESTAMP | DEFAULT now | 创建时间 |
| `updated_at` | TIMESTAMP | DEFAULT now | 更新时间 |

**状态值说明：**

| status 值 | 说明 |
|------------|------|
| `active` | API 正常响应 |
| `inactive` | API 未响应 |
| `error` | API 返回错误 |

| wechat_status 值 | 说明 |
|------------------|------|
| `online` | 微信已登录 |
| `offline` | 微信未登录 |

**SQL：**
```sql
CREATE TABLE nodes (
    node_id VARCHAR(50) PRIMARY KEY,
    name VARCHAR(100) NOT NULL,
    api_url VARCHAR(255) NOT NULL,
    api_key VARCHAR(255) NOT NULL,
    enabled BOOLEAN DEFAULT true,
    description TEXT DEFAULT '',
    group VARCHAR(50) DEFAULT 'default',
    status VARCHAR(20) DEFAULT 'inactive',
    wechat_status VARCHAR(20) DEFAULT 'online',
    is_healthy BOOLEAN DEFAULT false,
    health_message VARCHAR(255) DEFAULT '',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```

---

### 2. webhook_urls - Webhook URL 表

存储告警 webhook 配置。

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | INTEGER | **PK**, AUTO | 主键 |
| `name` | VARCHAR(100) | NOT NULL | Webhook 名称 |
| `url` | VARCHAR(500) | NOT NULL | Webhook URL |
| `format` | VARCHAR(20) | DEFAULT 'bark' | 消息格式 |
| `enabled` | BOOLEAN | DEFAULT true | 是否启用 |
| `event_types` | TEXT | DEFAULT '' | 触发事件类型（逗号分隔） |
| `created_at` | TIMESTAMP | DEFAULT now | 创建时间 |
| `updated_at` | TIMESTAMP | DEFAULT now | 更新时间 |

**format 支持的格式：**
- `bark` - Bark 推送格式
- `wecom` - 企业微信
- `dingtalk` - 钉钉
- `feishu` - 飞书
- `telegram` - Telegram
- `serverchan` - Server酱

**event_types 支持的类型：**
- `node_offline` - 节点离线
- `node_error` - 节点错误
- `wechat_offline` - 微信离线
- `all` - 所有事件

---

### 3. logs - 日志表

存储系统运行日志。

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | INTEGER | **PK**, AUTO | 主键 |
| `timestamp` | TIMESTAMP | DEFAULT now | 日志时间 |
| `level` | VARCHAR(20) | NOT NULL | 日志级别 |
| `source` | VARCHAR(50) | NOT NULL | 日志来源 |
| `message` | TEXT | NOT NULL | 日志消息 |

**level 值：**
- `INFO` - 信息
- `WARNING` - 警告
- `ERROR` - 错误
- `SUCCESS` - 成功
- `DEBUG` - 调试

---

### 4. plugin_configs - 插件配置表

存储插件的配置和启用状态。

| 字段 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `id` | INTEGER | **PK**, AUTO | 主键 |
| `plugin_name` | VARCHAR(100) | **UNIQUE**, NOT NULL | 插件名称 |
| `config_json` | TEXT | DEFAULT '{}' | 插件配置（JSON格式） |
| `enabled` | BOOLEAN | DEFAULT false | 是否启用 |
| `created_at` | TIMESTAMP | DEFAULT now | 创建时间 |
| `updated_at` | TIMESTAMP | DEFAULT now | 更新时间 |

**config_json 示例：**
```json
{
    "node_id": "wx1",
    "receiver": "文件传输助手",
    "cron": "0 8 * * *",
    "http_url": "https://api.example.com/news",
    "message_template": "📰 {title}\n{url}"
}
```

---

## 数据库操作

### DatabaseService 主要方法

#### 节点操作
```python
# 获取所有节点
db_service.get_all_nodes() -> List[Node]

# 获取指定节点
db_service.get_node(node_id: str) -> Optional[Node]

# 添加节点
db_service.add_node(node_id, name, api_url, api_key, description, group)

# 更新节点
db_service.update_node(node_id, **kwargs) -> bool

# 删除节点
db_service.delete_node(node_id) -> bool

# 获取启用的节点
db_service.get_enabled_nodes() -> List[Node]
```

#### Webhook 操作
```python
# 获取所有 Webhook
db_service.get_all_webhooks() -> List[WebhookUrl]

# 获取启用的 Webhook
db_service.get_enabled_webhooks() -> List[WebhookUrl]

# 添加 Webhook
db_service.add_webhook(name, url, format, event_types) -> bool

# 更新 Webhook
db_service.update_webhook(webhook_id, **kwargs) -> bool

# 删除 Webhook
db_service.delete_webhook(webhook_id) -> bool
```

#### 插件配置操作
```python
# 获取插件配置
db_service.get_plugin_config(plugin_name: str) -> Optional[PluginConfig]

# 获取所有插件配置
db_service.get_all_plugin_configs() -> List[PluginConfig]

# 保存插件配置
db_service.save_plugin_config(plugin_name, config, enabled) -> bool

# 更新插件启用状态
db_service.update_plugin_enabled(plugin_name, enabled) -> bool
```

---

## 索引

```sql
-- nodes 表索引
CREATE INDEX idx_nodes_enabled ON nodes(enabled);
CREATE INDEX idx_nodes_group ON nodes(group);
CREATE INDEX idx_nodes_status ON nodes(status);

-- webhook_urls 表索引
CREATE INDEX idx_webhook_enabled ON webhook_urls(enabled);

-- logs 表索引
CREATE INDEX idx_logs_timestamp ON logs(timestamp);
CREATE INDEX idx_logs_level ON logs(level);
```

---

## 迁移注意

如果数据库已存在，新增 `plugin_configs` 表：

```sql
CREATE TABLE IF NOT EXISTS plugin_configs (
    id SERIAL PRIMARY KEY,
    plugin_name VARCHAR(100) UNIQUE NOT NULL,
    config_json TEXT DEFAULT '{}',
    enabled BOOLEAN DEFAULT false,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
```