FlownBug/AcgStyleBlog
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b7e9699dbd236972fc73a1fba41b2b5a264ff4f2
AcgStyleBlog/开发路径.md

19 KiB
Raw Blame History

ACG Blog 开发路径

二次元风格博客系统 - 分阶段开发计划

最后更新：2026-03-24

当前状态：前端基础搭建完成 ✅ | 后端开发未开始 ❌

系统架构设计

整体架构图

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

前端模块架构

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

后端模块架构

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)

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
    }

数据流架构图

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 基础搭建 ✅

  • Vite + Vue 3 项目初始化
  • 配置 Tailwind CSS v4
  • 配置 Naive UI 主题（二次元配色）
  • 配置路由（Vue Router）

5.2 状态管理 ✅

  • Pinia Store 结构设计
  • store/user.ts - 用户状态
  • store/theme.ts - 主题状态
  • store/kanban.ts - 看板娘状态

5.3 API 封装 ✅

  • Axios 基础配置
  • 请求/响应拦截器（JWT 处理）
  • API 模块化封装

阶段六：前端核心页面

优先级：P2 | 状态：⚠️ 部分完成

6.1 布局组件 ✅

  • layouts/AdminLayout.vue - 管理后台布局
  • components/Navbar.vue - 导航栏
  • components/Footer.vue - 页脚
  • components/Hero.vue - Hero 区域

6.2 公共组件 ⚠️

  • components/Kanban.vue - Live2D 看板娘
  • components/PostCard.vue - 文章卡片
  • components/MarkdownEditor.vue - Markdown 编辑器
  • components/Sidebar.vue - 侧边栏

6.3 核心页面 ⚠️

  • views/Home.vue - 首页（文章列表）
  • views/PostDetail.vue - 文章详情（占位）
  • views/Category.vue - 分类页（占位）
  • views/Archive.vue - 归档页
  • views/About.vue - 关于页（占位）

阶段七：用户功能页面

优先级：P2 | 状态：⚠️ 部分完成

7.1 认证页面 ⚠️

  • views/auth/Login.vue - 登录页（框架）
  • views/auth/Register.vue - 注册页（框架）

7.2 用户中心 ⚠️

  • views/user/Profile.vue - 个人资料（框架）
  • views/user/Settings.vue - 用户设置
  • views/user/MyPosts.vue - 我的文章

阶段八：管理后台

优先级：P3 | 状态：⚠️ 部分完成

8.1 后台布局 ✅

  • admin/Dashboard.vue - 仪表盘（框架）
  • admin/Sidebar.vue - 侧边栏（在 AdminLayout 中）

8.2 后台功能 ⚠️

  • admin/PostManage.vue - 文章管理（框架）
  • admin/CategoryManage.vue - 分类管理（框架）
  • admin/TagManage.vue - 标签管理（框架）
  • admin/CommentManage.vue - 评论管理
  • admin/UserManage.vue - 用户管理
  • admin/Statistics.vue - 数据统计

阶段九：动效与优化

优先级：P4 | 状态：⚠️ 部分完成

9.1 动画效果 ⚠️

  • GSAP 页面转场动画
  • 卡片悬浮效果 ✅
  • 看板娘互动动画
  • 毛玻璃特效实现 ✅

9.2 性能优化

  • 图片懒加载
  • 路由懒加载
  • 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