docs: 更新 README，添加项目完整文档

2026-08-06 18:56:22 +08:00
parent bd37926295
commit 549d85162d
1 changed files with 97 additions and 2 deletions
@@ -1,3 +1,98 @@
-# blog
+# 🍊 柚子博客 · 前端

-`重新起航`
+暖色玻璃拟态风格的个人博客前端（Vue 3 + TypeScript + Vite 7），配套后端 API 为 `https://www.hxyouzi.com/api`。
+
+> 项目标语：**重新起航**
+
+## ✨ 功能特性
+
+- 📰 **博客模块**：文章列表、分类筛选、文章详情阅读（`md-editor-v3` 渲染）
+- 🧭 **导航主页**：搜索式导航首页，支持快捷搜索、站点导航增删改、右侧卡片/侧栏
+- 🖼️ **画廊 / 图床**：文件资源浏览、搜索、分享（瀑布流 + 懒加载）
+- 🔗 **友链**：友情链接展示与申请添加
+- 🌤️ **天气 / 生活**：IP 定位、天气查询、每日一言、热榜、节假日（防御式处理）
+- 🎵 **音乐播放**：基于 APlayer + Meting 的音乐播放器
+- 👤 **用户体系**：登录 / 注册 / 自动登录（JWT，cookie 持久化）
+- 🗂️ **其他页面**：小工具（Widget）、应用（Apps）等
+
+## 🛠️ 技术栈
+
+| 分类      | 技术                                                       |
+| --------- | ---------------------------------------------------------- |
+| 核心框架  | Vue 3、TypeScript、Vite 7、Vue Router 5                    |
+| UI 组件库 | naive-ui（自动按需注册）、vue-devui（Tag）                 |
+| 样式方案  | UnoCSS（重度 arbitrary values）、Less（全局注入主色变量）  |
+| 状态管理  | Pinia（`nav` / `log` stores）                              |
+| 网络请求  | Axios（拦截器自动带 Bearer token）                         |
+| Markdown  | md-editor-v3                                               |
+| 音频      | aplayer + @meting/core                                     |
+| 其他      | pinia、vue3-cookies、nprogress、es-toolkit、qweather-icons |
+
+## 🚀 快速开始
+
+环境要求：Node.js `^20.19.0 || >=22.12.0`
+
+```bash
+# 安装依赖
+npm install
+
+# 启动开发服务器（端口 8989，路径 base /blog/，首页 /home）
+npm run dev
+
+# 类型检查（改完代码必跑）
+npm run type-check
+
+# 构建（type-check + build）
+npm run b
+
+# 仅构建
+npm run build-only
+```
+
+## 📁 项目结构
+
+```
+src/
+├── api/            # API 模块（自动挂载到 $http.<模块>.<函数>）
+├── assets/         # 全局样式、字体、图片
+├── components/     # 通用组件（自动注册，如 Gallery、Login、aplayer 等）
+├── config/         # 全局配置（自动挂载 $http/$store/$cookies 等）
+├── icon/           # SVG 图标（顶层自动注册为 <icon-<name> />）
+├── lib/            # 内部组件库（Waterfall、LazyImg 及工具）
+├── logo/           # 站点 logo 图
+├── router/         # 路由（文件系统路由 + NProgress 守卫）
+├── stores/         # Pinia stores（nav / log）
+├── util/           # 请求封装、工具函数、主题配置
+└── views/          # 页面（unplugin-vue-router 文件系统路由）
+```
+
+## 🔗 全局约定（使用前必读）
+
+项目大量使用**全局变量与自动导入**，使用时**无需重复 import**（类型声明见 `env.d.ts`）：
+
+| 全局变量   | 说明                                                                      |
+| ---------- | ------------------------------------------------------------------------- |
+| `$http`    | API 聚合对象：`$http.<模块>.<函数>()`（如 `$http.blog.getBlogList`）      |
+| `$store`   | Pinia store 聚合：`$store.nav.useNavStore()` / `$store.log.useLogStore()` |
+| `$msg`     | naive-ui message 实例：`$msg.success/warning/error/info`                  |
+| `$cookies` | vue3-cookies 封装：`get/set/remove`                                       |
+| `$modal`   | 全局弹窗：`$modal({ title, content, contType: 'text'\|'input', ... })`    |
+
+- **组合式 API** 已自动导入（`ref`/`computed`/`watch`/`useRoute`/`defineStore`/`useMessage` 等）。
+- `src/components/` 组件与 naive-ui `<n-xxx>` 均自动注册，模板中直接使用。
+- **新增 icon / api / store 文件后需重启 dev server**（`import.meta.glob` 构建时静态分析）。
+- 登录态：cookie `userinfo` 存在即视为已登录。
+
+## 🎨 设计规范
+
+- **主色调**：暖色玻璃拟态，主色 `#ec66ab`（Less 变量 `@primary`）、主题按钮色 `#D71A44`
+- **背景模板**：暖色径向渐变 + 两个 blur 圆 + 网格 overlay（参考 `src/views/index.vue` 顶部）
+- **阴影规范**：三层体系（接触 + 主体 + 暖色高光 + inset 高光），避免纯冷灰阴影
+- **字体**：霞鹜文楷（正文）+ Fira Code（代码）
+- **页面布局**：统一减去导航栏高度（`$store.nav.useNavStore().navH`）
+
+> 详细开发约定与常见陷阱见仓库根目录 `AGENTS.md`。
+
+## 📄 License
+
+本项目为个人项目，遵循 MIT License（以仓库实际声明为准）。