blogweb/PROJECT_STRUCTURE.md

项目结构说明

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

目录结构

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
   • 运行方式：

     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. 初始化数据库

   python -m app.db.init_db
   

2. 启动后端

   python main.py
   # 或
   uvicorn app.main:app --reload
   

3. 启动前端

   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