# 数据库文档总览

本文档提供了整个数据库系统的概览，包括所有模型、表结构和关系。

## 数据库概览

这是一个基于 Koa3 和 Knex.js 构建的现代化 Web 应用数据库系统，使用 SQLite 作为数据库引擎。

### 技术栈

- **数据库**: SQLite3
- **ORM**: Knex.js
- **迁移工具**: Knex Migrations
- **种子数据**: Knex Seeds
- **数据库驱动**: sqlite3

## 数据模型总览

### 1. UserModel - 用户管理
- **表名**: `users`
- **功能**: 用户账户管理、身份验证、角色控制
- **主要字段**: id, username, email, password, role, phone, age
- **文档**: [UserModel.md](./UserModel.md)

### 2. ArticleModel - 文章管理
- **表名**: `articles`
- **功能**: 文章CRUD、状态管理、SEO优化、标签分类
- **主要字段**: id, title, content, author, category, tags, status, slug
- **文档**: [ArticleModel.md](./ArticleModel.md)

### 3. BookmarkModel - 书签管理
- **表名**: `bookmarks`
- **功能**: 用户书签管理、URL去重、用户隔离
- **主要字段**: id, user_id, title, url, description
- **文档**: [BookmarkModel.md](./BookmarkModel.md)

### 4. SiteConfigModel - 网站配置
- **表名**: `site_config`
- **功能**: 键值对配置存储、系统设置管理
- **主要字段**: id, key, value
- **文档**: [SiteConfigModel.md](./SiteConfigModel.md)

## 数据库表结构

### 表关系图

```
users (用户表)
├── id (主键)
├── username
├── email
├── password
├── role
├── phone
├── age
├── created_at
└── updated_at

articles (文章表)
├── id (主键)
├── title
├── content
├── author
├── category
├── tags
├── status
├── slug
├── published_at
├── view_count
├── featured_image
├── excerpt
├── reading_time
├── meta_title
├── meta_description
├── keywords
├── description
├── created_at
└── updated_at

bookmarks (书签表)
├── id (主键)
├── user_id (外键 -> users.id)
├── title
├── url
├── description
├── created_at
└── updated_at

site_config (网站配置表)
├── id (主键)
├── key (唯一)
├── value
├── created_at
└── updated_at
```

### 外键关系

- `bookmarks.user_id` → `users.id` (CASCADE 删除)
- 其他表之间暂无直接外键关系

## 数据库迁移文件

| 迁移文件 | 描述 | 创建时间 |
|----------|------|----------|
| `20250616065041_create_users_table.mjs` | 创建用户表 | 2025-06-16 |
| `20250621013128_site_config.mjs` | 创建网站配置表 | 2025-06-21 |
| `20250830014825_create_articles_table.mjs` | 创建文章表 | 2025-08-30 |
| `20250830015422_create_bookmarks_table.mjs` | 创建书签表 | 2025-08-30 |
| `20250830020000_add_article_fields.mjs` | 添加文章额外字段 | 2025-08-30 |

## 种子数据文件

| 种子文件 | 描述 | 创建时间 |
|----------|------|----------|
| `20250616071157_users_seed.mjs` | 用户示例数据 | 2025-06-16 |
| `20250621013324_site_config_seed.mjs` | 网站配置示例数据 | 2025-06-21 |
| `20250830020000_articles_seed.mjs` | 文章示例数据 | 2025-08-30 |

## 快速开始

### 1. 安装依赖

```bash
npm install
# 或
bun install
```

### 2. 运行数据库迁移

```bash
# 运行所有迁移
npx knex migrate:latest

# 回滚迁移
npx knex migrate:rollback

# 查看迁移状态
npx knex migrate:status
```

### 3. 运行种子数据

```bash
# 运行所有种子
npx knex seed:run

# 运行特定种子
npx knex seed:run --specific=20250616071157_users_seed.mjs
```

### 4. 数据库连接

```bash
# 查看数据库配置
cat knexfile.mjs

# 连接数据库
npx knex --knexfile knexfile.mjs
```

## 开发指南

### 创建新的迁移文件

```bash
npx knex migrate:make create_new_table
```

### 创建新的种子文件

```bash
npx knex seed:make new_seed_data
```

### 创建新的模型

1. 在 `src/db/models/` 目录下创建新的模型文件
2. 在 `src/db/docs/` 目录下创建对应的文档
3. 更新本文档的模型总览部分

## 最佳实践

### 1. 模型设计原则

- 每个模型对应一个数据库表
- 使用静态方法提供数据操作接口
- 实现适当的错误处理和验证
- 支持软删除和审计字段

### 2. 迁移管理

- 迁移文件一旦提交到版本控制，不要修改
- 使用描述性的迁移文件名
- 在迁移文件中添加适当的注释
- 测试迁移的回滚功能

### 3. 种子数据

- 种子数据应该包含测试和开发所需的最小数据集
- 避免在生产环境中运行种子
- 种子数据应该是幂等的（可重复运行）

### 4. 性能优化

- 为常用查询字段添加索引
- 使用批量操作减少数据库查询
- 实现适当的缓存机制
- 监控查询性能

## 故障排除

### 常见问题

1. **迁移失败**
   - 检查数据库连接配置
   - 确保数据库文件存在且有写入权限
   - 查看迁移文件语法是否正确

2. **种子数据失败**
   - 检查表结构是否与种子数据匹配
   - 确保外键关系正确
   - 查看是否有唯一性约束冲突

3. **模型查询错误**
   - 检查表名和字段名是否正确
   - 确保数据库连接正常
   - 查看SQL查询日志

### 调试技巧

```bash
# 启用SQL查询日志
DEBUG=knex:query node your-app.js

# 查看数据库结构
npx knex --knexfile knexfile.mjs
.tables
.schema users
```

## 贡献指南

1. 遵循现有的代码风格和命名规范
2. 为新功能添加适当的测试
3. 更新相关文档
4. 提交前运行迁移和种子测试

## 许可证

本项目采用 MIT 许可证。