# 项目结构说明

本文档详细说明了项目的目录结构和各文件的作用。

## 目录结构

```
blogweb/
├── backend/                      # 后端代码目录
│   ├── app/                       # FastAPI 应用主目录
│   │   ├── __init__.py
│   │   ├── main.py               # FastAPI 应用入口
│   │   │
│   │   ├── api/                   # API 路由模块
│   │   │   ├── __init__.py
│   │   │   └── api_v1/            # API v1 版本
│   │   │       ├── __init__.py
│   │   │       ├── api.py         # API 路由聚合
│   │   │       └── endpoints/     # API 端点
│   │   │           ├── __init__.py
│   │   │           ├── auth.py    # 认证相关端点
│   │   │           ├── users.py    # 用户相关端点
│   │   │           ├── todos.py    # 待办事项端点
│   │   │           └── posts.py    # 博客文章端点
│   │   │
│   │   ├── core/                  # 核心配置模块
│   │   │   ├── __init__.py
│   │   │   ├── config.py          # 应用配置
│   │   │   └── security.py        # 安全相关（密码哈希、JWT）
│   │   │
│   │   ├── db/                    # 数据库相关
│   │   │   ├── __init__.py
│   │   │   ├── base.py            # 数据库基础配置
│   │   │   ├── session.py         # 数据库会话管理
│   │   │   └── init_db.py         # 数据库初始化脚本 ⭐
│   │   │
│   │   ├── models/                # 数据模型（SQLModel）
│   │   │   ├── __init__.py
│   │   │   ├── user.py            # 用户模型
│   │   │   ├── todo.py            # 待办事项模型
│   │   │   ├── post.py            # 博客文章模型
│   │   │   ├── transaction.py     # 记账记录模型
│   │   │   ├── media.py           # 书影音收藏模型
│   │   │   ├── tag.py             # 标签模型
│   │   │   ├── chat.py            # 聊天消息模型
│   │   │   └── upload.py          # 文件上传模型
│   │   │
│   │   ├── schemas/               # Pydantic 模式（API 数据验证）
│   │   │   ├── __init__.py
│   │   │   ├── user.py            # 用户相关模式
│   │   │   ├── todo.py            # 待办事项相关模式
│   │   │   └── post.py            # 博客文章相关模式
│   │   │
│   │   └── initial_data/          # 初始数据模块
│   │       ├── __init__.py
│   │       └── README.md
│   │
│   ├── database.py                # （旧文件，可删除）
│   ├── models.py                  # （旧文件，可删除）
│   ├── init_db.py                 # （旧文件，可删除）
│   └── README.md                  # 后端说明文档
│
├── frontend/                      # 前端代码目录
│   ├── src/
│   │   ├── views/                 # 页面组件
│   │   │   ├── Home.vue           # 首页
│   │   │   ├── Login.vue          # 登录页
│   │   │   ├── Register.vue       # 注册页
│   │   │   ├── Todos.vue          # 待办事项页
│   │   │   └── Posts.vue          # 博客文章页
│   │   ├── stores/                # Pinia 状态管理
│   │   │   └── auth.js            # 认证状态
│   │   ├── router/                # 路由配置
│   │   │   └── index.js
│   │   ├── App.vue                # 根组件
│   │   └── main.js                # 前端入口
│   ├── index.html                 # HTML 模板
│   ├── package.json                # 前端依赖配置
│   └── vite.config.js             # Vite 配置
│
├── main.py                        # 项目启动入口 ⭐
├── requirements.txt               # Python 依赖
├── .env.example                   # 环境变量示例
├── .gitignore                     # Git 忽略规则
├── README.md                      # 项目说明文档
├── PROJECT_STRUCTURE.md           # 本文件
└── 数据库设计说明.md              # 数据库设计文档
```

## 关键文件说明

### ⭐ 重要文件

1. **`main.py`** - 项目启动入口
   - 用于开发环境快速启动 FastAPI 应用
   - 使用 uvicorn 运行 `app.main:app`

2. **`backend/app/main.py`** - FastAPI 应用主文件
   - 创建 FastAPI 应用实例
   - 配置 CORS 中间件
   - 注册 API 路由

3. **`backend/app/db/init_db.py`** - 数据库初始化脚本 ⭐
   - **位置已调整**：从 `backend/init_db.py` 移动到 `backend/app/db/init_db.py`
   - 运行方式：
     ```bash
     python -m app.db.init_db          # 创建表
     python -m app.db.init_db --reset  # 重置数据库
     ```

## 模块说明

### 后端模块

#### `app/core/` - 核心配置
- `config.py`: 应用配置（数据库、安全、CORS 等）
- `security.py`: 密码哈希、JWT 令牌生成和验证

#### `app/db/` - 数据库
- `base.py`: 数据库基础配置，导入所有模型
- `session.py`: 数据库会话管理和依赖注入
- `init_db.py`: 数据库初始化脚本

#### `app/models/` - 数据模型
- 使用 SQLModel 定义数据库表结构
- 每个模型一个文件，便于维护

#### `app/schemas/` - Pydantic 模式
- 用于 API 请求和响应的数据验证
- 定义创建、更新、响应等不同场景的模式

#### `app/api/` - API 路由
- `api_v1/api.py`: 聚合所有 API 路由
- `api_v1/endpoints/`: 各个功能模块的端点

### 前端模块

#### `src/views/` - 页面组件
- Vue 3 单文件组件
- 每个功能对应一个页面

#### `src/stores/` - 状态管理
- 使用 Pinia 管理全局状态
- `auth.js`: 用户认证状态

#### `src/router/` - 路由
- Vue Router 配置
- 定义前端路由规则

## 开发流程

1. **初始化数据库**
   ```bash
   python -m app.db.init_db
   ```

2. **启动后端**
   ```bash
   python main.py
   # 或
   uvicorn app.main:app --reload
   ```

3. **启动前端**
   ```bash
   cd frontend
   npm install
   npm run dev
   ```

## 注意事项

1. **数据库初始化脚本位置已调整**
   - 旧位置：`backend/init_db.py`
   - 新位置：`backend/app/db/init_db.py`
   - 运行方式：`python -m app.db.init_db`

2. **旧文件清理**
   - `backend/database.py`、`backend/models.py`、`backend/init_db.py` 可以删除
   - 新代码已迁移到 `backend/app/` 目录下

3. **环境变量**
   - 复制 `.env.example` 为 `.env`
   - 修改其中的配置项（特别是 `SECRET_KEY`）

4. **前后端分离**
   - 后端运行在 `http://localhost:8000`
   - 前端运行在 `http://localhost:5173`
   - 前端通过代理访问后端 API