diff --git a/开发路径.md b/开发路径.md deleted file mode 100644 index 7e77143..0000000 --- a/开发路径.md +++ /dev/null @@ -1,672 +0,0 @@ -# ACG Blog 开发路径 - -> 二次元风格博客系统 - 分阶段开发计划 -> -> **最后更新**：2026-03-24 -> -> **当前状态**：前端基础搭建完成 ✅ | 后端开发未开始 ❌ - ---- - -## 系统架构设计 - -### 整体架构图 - -```mermaid -graph TB - subgraph Frontend["前端 (Vue 3 + Vite)"] - FE_Vue[Vue 3 应用] - FE_Router[Vue Router] - FE_Pinia[Pinia 状态管理] - FE_UI[Naive UI 组件库] - FE_CSS[Tailwind CSS] - FE_GSAP[GSAP 动画] - FE_Editor[V-MD-Editor] - end - - subgraph Backend["后端 (FastAPI)"] - BE_API[API 路由层] - BE_Service[Service 服务层] - BE_Crud[CRUD 数据操作层] - BE_Schema[Schema 数据校验层] - BE_Core[Core 核心配置层] - end - - subgraph BaaS["Supabase (BaaS)"] - SB_Auth[Auth 认证] - SB_DB[(PostgreSQL)] - SB_Storage[Storage 存储] - SB_Realtime[Realtime 实时] - end - - subgraph Cache["Redis 缓存"] - RC_Stats[访问统计] - RC_Hot[热搜排行] - RC_Session[会话存储] - end - - FE_Vue --> |HTTP/JSON| BE_API - FE_Router --> FE_Vue - FE_Pinia --> FE_Vue - FE_GSAP --> FE_Vue - FE_Editor --> FE_Vue - BE_API --> BE_Service - BE_Service --> BE_Crud - BE_Crud --> BE_Schema - BE_Schema --> BE_Core - BE_Core --> SB_Auth - BE_Core --> SB_DB - BE_Core --> SB_Storage - BE_Service --> RC_Stats - BE_Service --> RC_Hot - BE_Service --> RC_Session -``` - -### 前端模块架构 - -```mermaid -graph TB - subgraph Views["页面视图"] - Home[首页 Home.vue] - PostDetail[文章详情 PostDetail.vue] - Category[分类页 Category.vue] - Archive[归档页 Archive.vue] - About[关于页 About.vue] - end - - subgraph Auth["认证模块"] - Login[登录 Login.vue] - Register[注册 Register.vue] - Profile[个人资料 Profile.vue] - end - - subgraph Admin["管理后台"] - Dashboard[仪表盘 Dashboard.vue] - PostManage[文章管理 PostManage.vue] - CategoryManage[分类管理 CategoryManage.vue] - TagManage[标签管理 TagManage.vue] - end - - subgraph Components["公共组件"] - Navbar[导航栏 Navbar.vue] - Hero[Hero 区域 Hero.vue] - Footer[页脚 Footer.vue] - PostCard[文章卡片 PostCard.vue] - Sidebar[侧边栏 Sidebar.vue] - Kanban[看板娘 Kanban.vue] - end - - subgraph Store["状态管理"] - UserStore[user.ts 用户状态] - ThemeStore[theme.ts 主题状态] - KanbanStore[kanban.ts 看板娘状态] - end - - subgraph API["接口层"] - AuthAPI[auth.ts 认证接口] - PostAPI[post.ts 文章接口] - IndexAPI[index.ts 基础配置] - end - - Navbar --> Home - Hero --> Home - PostCard --> Home - Sidebar --> Home - Footer --> Views - Home --> PostDetail - Home --> Category - Login --> Auth - Register --> Auth - Profile --> Auth - Dashboard --> Admin - PostManage --> Admin - UserStore --> Store - ThemeStore --> Store - AuthAPI --> API - PostAPI --> API -``` - -### 后端模块架构 - -```mermaid -graph TB - subgraph API["API 路由层 api/endpoints/"] - AuthAPI[auth.py 认证接口] - UserAPI[users.py 用户接口] - PostAPI[posts.py 文章接口] - CategoryAPI[categories.py 分类接口] - TagAPI[tags.py 标签接口] - CommentAPI[comments.py 评论接口] - KanbanAPI[kanban.py 看板娘接口] - StatsAPI[stats.py 统计接口] - UploadAPI[upload.py 上传接口] - end - - subgraph Service["服务层 services/"] - AuthService[auth_service.py] - PostService[post_service.py] - KanbanService[kanban_service.py] - StatsService[stats_service.py] - UploadService[upload_service.py] - end - - subgraph Crud["CRUD 层 crud/"] - UserCrud[user.py] - PostCrud[post.py] - CategoryCrud[category.py] - TagCrud[tag.py] - CommentCrud[comment.py] - end - - subgraph Schema["Schema 层 schemas/"] - UserSchema[user.py] - PostSchema[post.py] - AuthSchema[auth.py] - TokenSchema[token.py] - end - - subgraph Core["核心层 core/"] - Config[config.py 配置] - Security[security.py JWT/密码] - Logger[logger.py 日志] - Supabase[supabase_client.py] - end - - AuthAPI --> AuthService - PostAPI --> PostService - KanbanAPI --> KanbanService - AuthService --> UserCrud - PostService --> PostCrud - UserCrud --> UserSchema - PostCrud --> PostSchema - UserSchema --> Supabase - PostSchema --> Supabase - UserCrud --> Supabase - PostCrud --> Supabase - AuthService --> Security - Core --> Config -``` - -### 数据库模型关系图 (Supabase PostgreSQL) - -```mermaid -erDiagram - USER ||--o{ POST : writes - USER ||--o{ COMMENT : writes - POST ||--o{ COMMENT : has - POST }o--o{ TAG : tagged_with - POST ||--|{ CATEGORY : belongs_to - USER { - uuid id PK - string username - string email - string avatar_url - boolean is_active - boolean is_superuser - datetime created_at - datetime updated_at - } - POST { - uuid id PK - string title - string slug - text content - text summary - string cover_url - uuid author_id FK - uuid category_id FK - integer view_count - string status - datetime created_at - datetime updated_at - } - CATEGORY { - uuid id PK - string name - string slug - text description - datetime created_at - } - TAG { - uuid id PK - string name - datetime created_at - } - COMMENT { - uuid id PK - text content - uuid author_id FK - uuid post_id FK - uuid parent_id - datetime created_at - } - POST_TAG { - uuid post_id FK - uuid tag_id FK - } -``` - -### 数据流架构图 - -```mermaid -sequenceDiagram - participant U as 用户 - participant FE as 前端 Vue - participant API as FastAPI 后端 - participant S as Service - participant SB as Supabase - participant R as Redis - - U->>FE: 访问页面 - FE->>API: HTTP Request - API->>S: 业务逻辑处理 - - Note over S,SB: 数据库操作 - S->>SB: Supabase SDK 调用 - SB-->>S: 查询结果 - - Note over S,R: 缓存操作 - S->>R: 检查/写入缓存 - R-->>S: 缓存数据 - - S-->>FE: JSON 响应 - FE-->>U: 渲染页面 -``` - ---- - -## 开发阶段 - -### 阶段一：后端基础架构搭建 - -**优先级：P0** | **状态：❌ 未开始** - -#### 1.1 核心配置层 -- [ ] `core/config.py` - 环境变量与全局配置（Pydantic Settings） -- [ ] `core/supabase.py` - Supabase 客户端初始化 -- [ ] `core/security.py` - JWT 生成、验证与密码哈希（python-jose + passlib） -- [ ] `core/logger.py` - Loguru 日志配置 -- [ ] `.env.example` - 环境变量模板 - -#### 1.2 数据库表结构 (Supabase PostgreSQL) -- [ ] 创建 profiles 表（用户扩展信息） -- [ ] 创建 posts 表（文章） -- [ ] 创建 categories 表（分类） -- [ ] 创建 tags 表（标签） -- [ ] 创建 comments 表（评论） -- [ ] 创建 post_tags 表（文章-标签关联） -- [ ] 配置 RLS (Row Level Security) 策略 -- [ ] 设计数据库索引 - -#### 1.3 Pydantic Schema 层 -- [ ] `schemas/user.py` - 用户数据验证 -- [ ] `schemas/post.py` - 文章数据验证 -- [ ] `schemas/auth.py` - 认证相关 Schema -- [ ] `schemas/token.py` - Token Schema - -#### 1.4 CRUD 操作层 -- [ ] `crud/user.py` - 用户 CRUD（通过 Supabase SDK） -- [ ] `crud/post.py` - 文章 CRUD -- [ ] `crud/category.py` - 分类 CRUD -- [ ] `crud/tag.py` - 标签 CRUD -- [ ] `crud/comment.py` - 评论 CRUD - ---- - -### 阶段二：认证与用户模块 - -**优先级：P0** | **状态：❌ 未开始** - -#### 2.1 认证接口 -- [ ] `api/endpoints/auth.py` - - [ ] POST `/api/v1/auth/register` - 用户注册 - - [ ] POST `/api/v1/auth/login` - 用户登录 - - [ ] POST `/api/v1/auth/refresh` - 刷新 Token - - [ ] POST `/api/v1/auth/logout` - 用户登出 - -#### 2.2 用户管理接口 -- [ ] `api/endpoints/users.py` - - [ ] GET `/api/v1/users/me` - 获取当前用户信息 - - [ ] PUT `/api/v1/users/me` - 更新当前用户信息 - - [ ] PUT `/api/v1/users/me/password` - 修改密码 - -#### 2.3 依赖注入与中间件 -- [ ] `api/deps.py` - 依赖注入（获取当前用户等） -- [ ] JWT 认证中间件 - ---- - -### 阶段三：文章管理模块 - -**优先级：P1** | **状态：❌ 未开始** - -#### 3.1 文章接口 -- [ ] `api/endpoints/posts.py` - - [ ] GET `/api/v1/posts/` - 文章列表（分页） - - [ ] GET `/api/v1/posts/{post_id}` - 获取单篇文章 - - [ ] POST `/api/v1/posts/` - 创建文章（需认证） - - [ ] PUT `/api/v1/posts/{post_id}` - 更新文章 - - [ ] DELETE `/api/v1/posts/{post_id}` - 删除文章 - - [ ] POST `/api/v1/posts/{post_id}/view` - 增加浏览量 - -#### 3.2 分类与标签接口 -- [ ] `api/endpoints/categories.py` - - [ ] GET `/api/v1/categories/` - 分类列表 - - [ ] POST `/api/v1/categories/` - 创建分类（管理员） -- [ ] `api/endpoints/tags.py` - - [ ] GET `/api/v1/tags/` - 标签列表 - - [ ] POST `/api/v1/tags/` - 创建标签（管理员） - -#### 3.3 评论接口 -- [ ] `api/endpoints/comments.py` - - [ ] GET `/api/v1/posts/{post_id}/comments` - 获取文章评论 - - [ ] POST `/api/v1/posts/{post_id}/comments` - 发表评论 - - [ ] DELETE `/api/v1/comments/{comment_id}` - 删除评论 - ---- - -### 阶段四：特色功能开发 - -**优先级：P3** | **状态：❌ 未开始** - -#### 4.1 看板娘系统 -- [ ] `services/kanban_service.py` - 看板娘互动逻辑 -- [ ] `api/endpoints/kanban.py` - - [ ] GET `/api/v1/kanban/greeting` - 随机问候语 - - [ ] POST `/api/v1/kanban/mood` - 切换看板娘心情 - - [ ] GET `/api/v1/kanban/stats` - 看板娘统计信息 - -#### 4.2 统计与热搜 -- [ ] Redis 缓存集成 -- [ ] `services/stats_service.py` - 访问统计逻辑 -- [ ] `api/endpoints/stats.py` - - [ ] GET `/api/v1/stats/hot-posts` - 热搜文章排行 - - [ ] GET `/api/v1/stats/visits` - 访问量统计 - - [ ] GET `/api/v1/stats/archive` - 归档统计 - -#### 4.3 文件上传 -- [ ] `services/upload_service.py` - 图片上传处理 -- [ ] `api/endpoints/upload.py` - - [ ] POST `/api/v1/upload/image` - 上传图片 - - [ ] 图片压缩与缩略图生成（Pillow） - ---- - -### 阶段五：前端项目初始化 - -**优先级：P1** | **状态：✅ 已完成** - -#### 5.1 基础搭建 ✅ -- [x] Vite + Vue 3 项目初始化 -- [x] 配置 Tailwind CSS v4 -- [x] 配置 Naive UI 主题（二次元配色） -- [x] 配置路由（Vue Router） - -#### 5.2 状态管理 ✅ -- [x] Pinia Store 结构设计 -- [x] `store/user.ts` - 用户状态 -- [x] `store/theme.ts` - 主题状态 -- [ ] `store/kanban.ts` - 看板娘状态 - -#### 5.3 API 封装 ✅ -- [x] Axios 基础配置 -- [x] 请求/响应拦截器（JWT 处理） -- [x] API 模块化封装 - ---- - -### 阶段六：前端核心页面 - -**优先级：P2** | **状态：⚠️ 部分完成** - -#### 6.1 布局组件 ✅ -- [x] `layouts/AdminLayout.vue` - 管理后台布局 -- [x] `components/Navbar.vue` - 导航栏 -- [x] `components/Footer.vue` - 页脚 -- [x] `components/Hero.vue` - Hero 区域 - -#### 6.2 公共组件 ⚠️ -- [ ] `components/Kanban.vue` - Live2D 看板娘 -- [x] `components/PostCard.vue` - 文章卡片 -- [ ] `components/MarkdownEditor.vue` - Markdown 编辑器 -- [x] `components/Sidebar.vue` - 侧边栏 - -#### 6.3 核心页面 ⚠️ -- [x] `views/Home.vue` - 首页（文章列表） -- [x] `views/PostDetail.vue` - 文章详情（占位） -- [x] `views/Category.vue` - 分类页（占位） -- [ ] `views/Archive.vue` - 归档页 -- [x] `views/About.vue` - 关于页（占位） - ---- - -### 阶段七：用户功能页面 - -**优先级：P2** | **状态：⚠️ 部分完成** - -#### 7.1 认证页面 ⚠️ -- [x] `views/auth/Login.vue` - 登录页（框架） -- [x] `views/auth/Register.vue` - 注册页（框架） - -#### 7.2 用户中心 ⚠️ -- [x] `views/user/Profile.vue` - 个人资料（框架） -- [ ] `views/user/Settings.vue` - 用户设置 -- [ ] `views/user/MyPosts.vue` - 我的文章 - ---- - -### 阶段八：管理后台 - -**优先级：P3** | **状态：⚠️ 部分完成** - -#### 8.1 后台布局 ✅ -- [x] `admin/Dashboard.vue` - 仪表盘（框架） -- [x] `admin/Sidebar.vue` - 侧边栏（在 AdminLayout 中） - -#### 8.2 后台功能 ⚠️ -- [x] `admin/PostManage.vue` - 文章管理（框架） -- [x] `admin/CategoryManage.vue` - 分类管理（框架） -- [x] `admin/TagManage.vue` - 标签管理（框架） -- [ ] `admin/CommentManage.vue` - 评论管理 -- [ ] `admin/UserManage.vue` - 用户管理 -- [ ] `admin/Statistics.vue` - 数据统计 - ---- - -### 阶段九：动效与优化 - -**优先级：P4** | **状态：⚠️ 部分完成** - -#### 9.1 动画效果 ⚠️ -- [ ] GSAP 页面转场动画 -- [x] 卡片悬浮效果 ✅ -- [ ] 看板娘互动动画 -- [x] 毛玻璃特效实现 ✅ - -#### 9.2 性能优化 -- [ ] 图片懒加载 -- [x] 路由懒加载 -- [ ] API 请求防抖节流 -- [ ] 前端缓存策略 - ---- - -### 阶段十：测试与部署 - -**优先级：P5** | **状态：❌ 未开始** - -#### 10.1 测试 -- [ ] 后端单元测试（pytest） -- [ ] API 集成测试 -- [ ] 前端组件测试（Vitest） - -#### 10.2 部署配置 -- [ ] `Dockerfile`（后端） -- [ ] `Dockerfile`（前端） -- [ ] `docker-compose.yml` - 完整编排 -- [ ] Nginx 配置 -- [ ] CI/CD 流程 - ---- - -## 项目结构（当前） - -``` -ACG-Blog/ -├── backend/ -│ ├── app/ -│ │ ├── api/ -│ │ │ └── endpoints/ # API 路由 -│ │ │ ├── auth.py # 认证接口 -│ │ │ ├── users.py # 用户接口 -│ │ │ ├── posts.py # 文章接口 -│ │ │ ├── categories.py # 分类接口 -│ │ │ ├── tags.py # 标签接口 -│ │ │ ├── comments.py # 评论接口 -│ │ │ ├── kanban.py # 看板娘接口 -│ │ │ ├── stats.py # 统计接口 -│ │ │ └── upload.py # 上传接口 -│ │ ├── core/ # 核心配置 -│ │ │ ├── config.py # 环境变量配置 -│ │ │ ├── supabase.py # Supabase 客户端 -│ │ │ ├── security.py # JWT/密码安全 -│ │ │ └── logger.py # 日志配置 -│ │ ├── crud/ # CRUD 操作 -│ │ │ ├── user.py -│ │ │ ├── post.py -│ │ │ ├── category.py -│ │ │ ├── tag.py -│ │ │ └── comment.py -│ │ ├── models/ # 数据模型（Pydantic） -│ │ │ ├── user.py -│ │ │ ├── post.py -│ │ │ ├── category.py -│ │ │ ├── tag.py -│ │ │ └── comment.py -│ │ ├── schemas/ # Pydantic Schema -│ │ │ ├── auth.py -│ │ │ ├── token.py -│ │ │ └── ... -│ │ └── services/ # 业务服务 -│ │ ├── kanban_service.py -│ │ ├── stats_service.py -│ │ └── upload_service.py -│ ├── main.py # FastAPI 入口 -│ ├── requirements.txt # Python 依赖 -│ └── venv/ # 虚拟环境 -│ -├── frontend/ -│ ├── public/ # 静态资源 -│ │ ├── favicon.svg -│ │ ├── icons.svg -│ │ └── live2d/ # Live2D 模型文件 -│ ├── src/ -│ │ ├── api/ # API 封装 ✅ -│ │ │ ├── index.ts # Axios 配置 -│ │ │ ├── auth.ts # 认证接口 -│ │ │ └── post.ts # 文章接口 -│ │ ├── assets/ # 静态资源 -│ │ ├── components/ # 公共组件 ✅ -│ │ │ ├── Footer.vue -│ │ │ ├── Hero.vue -│ │ │ ├── Kanban.vue # 看板娘组件 -│ │ │ ├── Navbar.vue -│ │ │ ├── PostCard.vue -│ │ │ └── Sidebar.vue -│ │ ├── layouts/ # 布局组件 -│ │ │ └── AdminLayout.vue -│ │ ├── router/ # 路由配置 -│ │ ├── store/ # 状态管理 ✅ -│ │ ├── views/ # 页面视图 -│ │ ├── App.vue -│ │ ├── main.ts -│ │ └── style.css -│ ├── package.json -│ ├── tsconfig.json -│ ├── vite.config.ts -│ ├── tailwind.config.js -│ └── postcss.config.js -│ -├── docker-compose.yml # Docker 编排 -├── README.md -└── 开发路径.md -``` - ---- - -## 技术栈汇总 - -### 后端技术 -| 技术 | 版本 | 用途 | -|------|------|------| -| Python | 3.11+ | 运行环境 | -| FastAPI | 0.110.0 | Web 框架 | -| Uvicorn | 0.27.1 | ASGI 服务器 | -| **Supabase** | - | BaaS 平台（内置 Auth + PostgreSQL + Storage） | -| Redis | - | 缓存/会话（热搜排行、访问统计） | -| Pydantic | 2.6.3 | 数据校验 | -| python-jose | 3.3.0 | JWT 认证 | -| Passlib | 1.7.4 | 密码哈希 | -| Loguru | 0.7.2 | 日志 | -| Pillow | 10.2.0 | 图片处理 | -| httpx | 0.27.0 | 异步 HTTP | -| python-multipart | 0.0.9 | 文件上传 | - -### 前端技术 -| 技术 | 版本 | 用途 | -|------|------|------| -| Vue | 3.5.30 | 框架 | -| Vite | 8.0.0 | 构建工具 | -| TypeScript | 5.9.3 | 类型系统 | -| Vue Router | 5.0.3 | 路由 | -| Pinia | 3.0.4 | 状态管理 | -| Naive UI | 2.44.1 | UI 组件库 | -| Tailwind CSS | 4.2.1 | CSS 框架 | -| Axios | 1.13.6 | HTTP 客户端 | -| @vueuse/core | 14.2.1 | Vue 组合式工具 | -| **GSAP** | - | 动画库（页面转场、交互动画） | -| **V-MD-Editor** | - | Markdown 编辑器 | - ---- - -## 优先级建议 - -| 优先级 | 阶段 | 说明 | 状态 | -|--------|------|------|------| -| P0 | 一、二 | 后端基础 + 认证系统（核心） | ❌ 未开始 | -| P1 | 三、五 | 文章管理 + 前端初始化 | ❌ / ⚠️ | -| P2 | 六、七 | 核心页面 + 用户功能 | ⚠️ 部分完成 | -| P3 | 四、八 | 特色功能 + 管理后台 | ❌ / ⚠️ | -| P4 | 九 | 动效优化 | ⚠️ 部分完成 | -| P5 | 十 | 测试与部署 | ❌ 未开始 | - ---- - -## 下一步开发计划 - -根据当前项目状态，建议按以下顺序继续开发： - -### 立即执行（Next Step） -1. **完成后端核心配置** (`core/config.py`, `core/security.py`) -2. **创建数据库模型** (`models/`) -3. **实现认证接口** (`api/endpoints/auth.py`) -4. **前后端 API 对接** - -### 看板娘集成（可选） -- 可使用 Live2D Cubism SDK 或 `vue-live2d` 等第三方库 - ---- - -## 注意事项 - -1. **Supabase**：使用 Supabase 作为 BaaS 平台，内置 Auth、PostgreSQL、Storage -2. **环境变量**：敏感信息（Supabase URL、anon key、JWT密钥）必须通过 `.env` 管理 -3. **前端主题**：使用二次元风格的配色（粉色 #FFB7C5、浅蓝 #A8D8EA、紫色 #D4B5E6） -4. **看板娘**：可使用 Live2D Cubism SDK 或第三方开源实现（如 vue-live2d） -5. **图片处理**：确保上传的图片有合适的压缩和尺寸限制（Pillow） -6. **Tailwind 4.x**：注意 `@apply` 指令使用限制，优先使用 CSS 原生语法 -7. **Redis**：用于缓存热搜排行、访问统计等高频访问数据 - ---- - -*文档版本：v2.0 | 更新日期：2026-03-24*