# 🗃️ 项目数据库设计说明

本文档描述了本 FastAPI 练手网站的数据库实体（表）结构与关系设计。  
所有用户相关数据均通过 `user_id` 外键关联，实现**多用户数据隔离**。  
数据库使用 **SQLite（开发阶段）**，ORM 框架推荐 **SQLModel**（兼容 Pydantic + SQLAlchemy）。

> 💡 **注**：天气查询功能调用第三方 API，**不持久化存储**，故无对应表。

---

## 📚 实体列表

| 表名             | 用途说明                     |
|------------------|------------------------------|
| `users`          | 用户账户信息                 |
| `todos`          | 待办事项列表                 |
| `posts`          | 博客文章                     |
| `transactions`   | 个人记账记录                 |
| `media`          | 书影音收藏条目               |
| `tags`           | 媒体标签（用于分类/打标）    |
| `media_tags`     | `media` 与 `tags` 的多对多关联表 |
| `chat_messages`  | 聊天室消息记录               |
| `uploads`        | 用户上传的文件元数据         |

---

## 🔍 详细表结构

### 1. `users` — 用户表

| 字段名            | 类型           | 约束/说明                     |
|-------------------|----------------|-------------------------------|
| `id`              | INTEGER        | 主键 (PK)                     |
| `username`        | VARCHAR(50)    | 唯一，非空                    |
<|`email`|VARCHAR(100)|唯一，可为空|
| `hashed_password` | TEXT           | bcrypt 哈希后的密码           |
| `created_at`      | DATETIME       | 默认当前时间                  |

---

### 2. `todos` — 待办事项

| 字段名       | 类型        | 约束/说明                |
|--------------|-------------|--------------------------|
| `id`         | INTEGER     | PK                       |
| `title`      | VARCHAR(200)| 非空                     |
| `done`       | BOOLEAN     | 默认 `FALSE`             |
| `created_at` | DATETIME    | 默认当前时间             |
| `user_id`    | INTEGER     | 外键 → `users.id`        |

---

### 3. `posts` — 博客文章

| 字段名        | 类型        | 约束/说明                              |
|---------------|-------------|----------------------------------------|
| `id`          | INTEGER     | PK                                     |
| `title`       | VARCHAR(200)| 非空                                   |
| `slug`        | VARCHAR(200)| URL 友好标识，建议 `(user_id, slug)` 唯一 |
| `content`     | TEXT        | 支持 Markdown                          |
| `created_at`  | DATETIME    | 默认当前时间                           |
| `updated_at`  | DATETIME    | 可为空                                 |
| `user_id`     | INTEGER     | 外键 → `users.id`                      |

---

### 4. `transactions` — 记账记录

| 字段名        | 类型           | 约束/说明                        |
|---------------|----------------|----------------------------------|
| `id`          | INTEGER        | PK                               |
| `amount`      | NUMERIC(10,2)  | 正数为收入，负数为支出           |
| `category`    | VARCHAR(50)    | 如“餐饮”、“交通”、“工资”等       |
| `description` | VARCHAR(200)   | 可为空                           |
| `date`        | DATE           | 交易发生日期                     |
| `user_id`     | INTEGER        | 外键 → `users.id`                |

---

### 5. `media` — 书影音收藏

| 字段名         | 类型        | 约束/说明                                      |
|----------------|-------------|------------------------------------------------|
| `id`           | INTEGER     | PK                                             |
| `title`        | VARCHAR(200)| 非空                                           |
| `media_type`   | VARCHAR(20) | 枚举值：`book` / `movie` / `music`             |
| `rating`       | FLOAT       | 0.0 ~ 5.0                                      |
| `comment`      | TEXT        | 用户短评                                       |
| `external_id`  | VARCHAR(100)| 如 ISBN、IMDb ID（用于对接外部 API）           |
| `cover_url`    | VARCHAR(300)| 封面图片 URL（可缓存）                         |
| `created_at`   | DATETIME    | 默认当前时间                                   |
| `user_id`      | INTEGER     | 外键 → `users.id`                              |

---

### 6. `tags` — 媒体标签

| 字段名   | 类型        | 约束/说明     |
|----------|-------------|---------------|
| `id`     | INTEGER     | PK            |
| `name`   | VARCHAR(50) | 唯一，非空    |

---

### 7. `media_tags` — 媒体-标签关联表（多对多）

| 字段名      | 类型     | 约束/说明                   |
|-------------|----------|-----------------------------|
| `media_id`  | INTEGER  | 外键 → `media.id`           |
| `tag_id`    | INTEGER  | 外键 → `tags.id`            |
| （联合主键）| —        | `(media_id, tag_id)` 唯一   |

---

### 8. `chat_messages` — 聊天消息

| 字段名      | 类型     | 约束/说明                         |
|-------------|----------|-----------------------------------|
| `id`        | INTEGER  | PK                                |
| `content`   | TEXT     | 非空                              |
| `sent_at`   | DATETIME | 默认当前时间                      |
| `user_id`   | INTEGER  | 外键 → `users.id`（发送者）       |
| `room`      | VARCHAR(50)| 聊天室名称（如 `"main"`）         |

---

### 9. `uploads` — 文件上传记录

| 字段名         | 类型        | 约束/说明                                  |
|----------------|-------------|--------------------------------------------|
| `id`           | INTEGER     | PK                                         |
| `filename`     | VARCHAR(200)| 原始文件名                                 |
| `stored_path`  | VARCHAR(300)| 服务器存储路径（如 `/uploads/abc.jpg`）    |
| `file_size`    | INTEGER     | 字节数                                     |
| `mime_type`    | VARCHAR(100)| 如 `image/jpeg`, `application/pdf`         |
| `uploaded_at`  | DATETIME    | 默认当前时间                               |
| `expires_at`   | DATETIME    | 可为空（表示永不过期）                     |
| `user_id`      | INTEGER     | 外键 → `users.id`                          |

> ⚠️ **安全提示**：前端不应直接访问 `stored_path`，应通过受控路由（如 `/download/{id}`）提供下载，并验证用户权限。

---

## 🔗 实体关系图（ERD）

```mermaid
erDiagram
    users ||--o{ todos : "1:N"
    users ||--o{ posts : "1:N"
    users ||--o{ transactions : "1:N"
    users ||--o{ media : "1:N"
    users ||--o{ chat_messages : "1:N"
    users ||--o{ uploads : "1:N"

    media }o--o{ tags : "N:M via media_tags"