FlownBug/AcgStyleBlog
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

关闭开发路径的跟踪和添加.gitignore

Browse Source
This commit is contained in:
KiriAky 107
2026-03-24 14:29:18 +08:00
parent b7e9699dbd
commit 6d70f73aea
1 changed files with 0 additions and 672 deletions
Download Patch File Download Diff File Expand all files Collapse all files

672
开发路径.md
View File

@@ -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*