my-blog

Imported from Unihur/Unihur.github.io (my-blog/AGENTS.md). Install upstream with npx skills add Unihur/Unihur.github.io --skill my-blog. Copyright stays with the author.

AGENTS.md — UniHur's Blog 开发指南

本文档供 AI 助手（及人类开发者）快速理解项目结构、约定与开发流程。修改代码前请先通读本文档。

项目概述

UniHur's Blog 是一个个人博客系统的前端，基于 Vue 3 + Vite + Element Plus 构建，配合自研 Python FastAPI 后端（blog-backend/，部署在 https://unihur.xyz）使用。

技术栈

常用命令

# 开发
npm run dev              # 启动开发服务器（localhost:5173，自动代理 /api → 后端）

# 构建
npm run build            # 生产构建到 dist/
npm run preview          # 本地预览生产包

# 代码质量（修改代码后必须运行）
npm run lint             # ESLint 自动修复
npm run lint:check       # 仅检查不修改（应保持 0 warning）
npm run format           # Prettier 格式化
npm run format:check     # 仅检查

重要：完成任何代码修改后，务必运行 npm run lint:check 和 npm run build 验证无报错。

目录结构

my-blog/
├── src/
│   ├── api/              # 接口层（统一 axios 实例 + 按模块拆分）
│   │   ├── request.js    #   axios 实例 + 拦截器（token 注入、401 处理）
│   │   ├── auth.js       #   登录/用户信息/头像/改昵称
│   │   ├── article.js    #   文章 CRUD + 点赞/分享
│   │   ├── comment.js    #   评论 CRUD + 点赞点踩/置顶
│   │   ├── category.js   #   分类 CRUD
│   │   ├── settings.js   #   全站公开设置 + 访客统计
│   │   ├── visitor.js    #   管理员访客管理
│   │   ├── upload.js     #   图片上传/图库
│   │   └── index.js      #   统一出口
│   ├── stores/           # Pinia 状态
│   │   ├── user.js       #   登录/用户/管理员判定
│   │   └── site.js       #   站点配置/主题/Banner
│   ├── composables/      # 可复用逻辑
│   │   ├── useTypewriter.js  # 打字机（模块级单例）
│   │   └── useLive2d.js      # Live2D 看板娘
│   ├── utils/            # 工具函数
│   │   ├── markdown.js   #   共享 md 实例 + extractToc
│   │   └── format.js     #   formatDate / formatDuration
│   ├── views/            # 页面视图（路由懒加载）
│   │   ├── HomeView.vue      # 首页：Banner+文章列表+分类/标签筛选
│   │   ├── ArticleView.vue   # 文章页：Markdown渲染+TOC目录(含跳转评论区)+评论
│   │   ├── WriteView.vue     # 写作页（管理员）：Markdown编辑+封面+图库
│   │   └── VisitorsView.vue  # 访客管理（管理员）：审核+称号编辑
│   ├── components/       # 展示组件
│   │   ├── AppHeader.vue     # 顶部导航栏 + 登录弹窗 + 设置抽屉
│   │   ├── ProfileCard.vue   # 个人资料卡片
│   │   ├── MusicPlayer.vue   # 音乐播放器
│   │   ├── MouseTrail.vue    # 鼠标拖尾特效
│   │   └── SettingDrawer.vue # 博客高级设置抽屉
│   ├── router/
│   │   └── index.js      # 路由 + 守卫（requiresAdmin）
│   ├── assets/           # 静态资源（会被 Vite 处理）
│   ├── App.vue           # 应用外壳（挂载 Header + 路由出口 + 鼠标特效）
│   ├── main.js           # 入口（注册 Pinia + Router）
│   └── style.css         # 全局样式（玻璃材质/主题色/夜间模式）
├── public/               # 静态资源（原样拷贝，不经过 Vite）
│   ├── avatar.png / favicon.svg / *.cur
│   ├── banner/           # 横幅图片
│   ├── musics/           # 音乐文件
│   ├── ulk/              # Live2D 模型
│   └── markdown_image/   # markdown 图片
├── .env                  # 开发环境变量
├── .env.production       # 生产环境变量
├── vite.config.js        # Vite 配置（@ 别名 + 代理 + Element Plus 自动导入）
├── eslint.config.js      # ESLint 配置
├── .prettierrc.json      # Prettier 配置
└── package.json

架构约定

1. API 调用规则（重要）

永远不要在组件里直接 import axios。所有后端调用必须走 src/api/ 模块：

// ✅ 正确
import { listArticles, login } from '@/api'

// ❌ 错误
import axios from 'axios'
axios.get('https://unihur.xyz/api/articles')

api/request.js 已统一处理：

• baseURL（来自 VITE_API_BASE_URL）
• 请求拦截器：自动注入 token 和 Authorization: Bearer xxx 两种头
• 响应拦截器：401 自动登出，403 权限提示

新增接口时，加到对应模块文件，并在 api/index.js 中通过 export * 暴露。

2. 状态管理规则

永远不要用 provide/inject 传全局状态。用 Pinia store：

import { useUserStore } from '@/stores/user'
import { useSiteStore } from '@/stores/site'

const userStore = useUserStore()
const siteStore = useSiteStore()

• useUserStore：登录态、用户信息、isAdmin（直接比较 username === VITE_ADMIN_USERNAME）、canWrite（写作权限）
• useSiteStore：站点配置、主题材质+颜色、Banner、夜间模式；主题/夜间/Banner 随账号保存（调 updateUser 同步到后端用户配置）

3. 路由守卫

管理员页面在路由 meta 标记 requiresAdmin: true，由 router.beforeEach 统一拦截。不要在组件内自行判断 isAdmin 来决定是否渲染（会导致刷新闪烁）。

4. Composables

跨组件复用的逻辑抽到 composables/：

• useTypewriter()：模块级单例，全应用只需 start() 一次
• useLive2d(siteConfig)：Live2D 实例管理

5. 工具函数

• Markdown 渲染：import { md, extractToc } from '@/utils/markdown'
• 时间格式化：import { formatDate } from '@/utils/format'

不要在多个组件里重复 new MarkdownIt()，统一用 utils/markdown.js 的共享实例。

环境变量

开发代理不做 rewrite：前端请求 /api/articles，代理转发到 https://unihur.xyz/api/articles（后端路由都带 /api 前缀）。

管理员权限约定（重要）

本项目只有一个管理员账号，账号名为 unihur（由 VITE_ADMIN_USERNAME 环境变量配置）。

判定规则

// stores/user.js
const isAdmin = computed(() => {
  if (!isLoggedIn.value) return false
  return username.value === ADMIN_USERNAME  // 直接比较用户名
})

• 不依赖后端 is_admin 字段，避免后端未返回时出现判定异常
• 非管理员（用户名 ≠ unihur）的 isAdmin 永远为 false

权限控制清单

注意：写作/设置按钮的权限检查在前端完成，不发请求到后端，避免触发 401 拦截器导致非管理员被意外登出。

代码风格约定

• 无分号、单引号、100 字宽（Prettier 强制）
• Vue 组件用 <script setup> + Composition API
• 路径用 @/ 别名，不用相对路径（../ 容易出错）
• 空的 catch 块用 catch (_) 或 catch (_) {}，加注释说明为什么忽略
• console.log 会触发 lint warning，用 console.warn / console.error 代替
• v-html 仅用于 markdown 渲染（已全局关闭 vue/no-v-html 规则）

前后端接口对应

已知技术债（未来优化方向）

功能特性补充说明

文章页 TOC 目录

• 位于左侧栏，position: sticky; top: 80px 吸顶
• 液态玻璃/清透水晶模式下需额外规则保持 sticky（见 ArticleView.vue 样式）
• 目录底部有"前往评论区"箭头按钮（el-tooltip + :teleported="false" 确保吸顶时 tooltip 跟随）

自定义称号系统

• 管理员在访客管理页为每个用户设置自定义称号 + 颜色
• 颜色提供 8 种预设：红/蓝/绿/紫/橙/粉/青/金
• 评论区和访客管理页展示称号；管理员账号固定显示红色"管理员"标签
• 后端 User 模型新增 title / title_color 字段，启动时自动迁移

评论管理员标识

• 评论作者显示逻辑：有自定义称号 → 显示称号（用 author_title_color 着色）；无称号但作者是管理员 → 回退显示默认"管理员"
• 管理员评论作者名变红色（.admin-name）

后端开发

后端代码在 ../blog-backend/（同级目录），技术栈：FastAPI + SQLAlchemy + SQLite。

• 入口：main.py
• 数据模型：models.py
• 数据库：database.py（SQLite，文件 blog.db）

重启后端（服务器上）：

cd /root/blog-backend
pkill -f uvicorn
source .venv/bin/activate
nohup uvicorn main:app --host 0.0.0.0 --port 8000 > backend.log 2>&1 &

数据库迁移：main.py 启动时执行 _auto_migrate()，自动检测并补充新增列。改了数据库字段不需要 rm blog.db，自动迁移会处理；只有改了字段类型或删除字段时才需手动重建。

开发流程检查清单

修改代码后，依次运行：

1. npm run lint — 自动修复格式问题
2. npm run lint:check — 确认 0 warning
3. npm run build — 确认编译通过
4. （可选）npm run dev — 本地启动验证页面正常

永远不要在未验证的情况下提交代码。