Jiao77/Jiao77-Blog
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update docs

Browse Source
This commit is contained in:
Jiao77
2026-03-01 21:48:34 +08:00
parent 7b1b99bca1
commit 2de1869fd4
3 changed files with 313 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
README.md
View File

@@ -176,6 +176,36 @@ heroImage: /images/hero.jpg
- **[使用指南](./docs/user-guide.md)** - 博客使用教程，包括文章编写、MDX 组件、Typst 排版、主题定制等
- **[开发文档](./docs/developer-guide.md)** - 面向开发者的技术文档，包括 API 接口、数据库结构、深度定制指南等
## 🤖 AI 使用声明
本系统大部分代码由 AI 辅助生成，但所有代码都经过了人工审核和测试。
### 为什么使用 AI 辅助开发？
AI 辅助开发能够显著提高开发效率，让我更专注于系统设计和用户体验。同时，我也深知大家对 AI 生成代码的担忧：
### 常见担忧与应对
| 担忧 | 应对措施 |
|------|----------|
| **隐私泄露风险** | 系统完全本地部署，不会向任何第三方服务器发送数据。所有用户数据（评论、点赞等）仅存储在您自己的 SQLite 数据库中 |
| **代码安全性** | 所有 AI 生成的代码都经过人工逐行审查，重点检查：SQL 注入、XSS 攻击、敏感信息泄露等安全漏洞 |
| **代码质量** | 对 AI 生成的代码进行了重构和优化，确保符合最佳实践 |
| **后门/恶意代码** | 代码完全开源，您可以自行审计每一行代码。没有任何隐藏的网络请求或数据收集行为 |
| **依赖安全** | 所有依赖包都经过筛选，使用知名、活跃维护的开源项目，避免引入有安全隐患的第三方库 |
### 我的承诺
- ✅ **隐私优先**：您的数据属于您自己，我无权也无从访问
- ✅ **透明公开**：坦诚披露 AI 的参与，不隐瞒开发方式
- ✅ **人工把关**：AI 只是辅助工具，最终的决策和审核由人工完成
- ✅ **开源审计**：代码完全开源，欢迎社区审查和改进
如果您对代码有任何疑虑，欢迎：
- 查看完整的 [开发文档](./docs/developer-guide.md) 了解技术细节
- 直接阅读源代码进行审计
- 提交 Issue 反馈问题或建议
## 📜 License
MIT License © 2024

221
docs/developer-guide.md
View File

@@ -73,7 +73,16 @@ NovaBlog/
│ │ ├── LoginForm.vue # 登录表单
│ │ ├── UserStatus.vue # 用户状态栏
│ │ ├── Counter.vue # 计数器示例
│ │ └── TableOfContents.astro # 目录组件
│ │ ├── TableOfContents.astro # 目录组件
│ │ └── react/ # React 组件
│ │ ├── AnimatedCard.tsx
│ │ ├── FlipCard.tsx
│ │ ├── ParticleBackground.tsx
│ │ ├── TypewriterText.tsx
│ │ ├── Heatmap.tsx # 热力图组件
│ │ ├── MicroList.tsx # 微语列表
│ │ ├── MicroComposer.tsx # 发布微语
│ │ └── MicroPage.tsx # 微语页面容器
│ ├── content/ # 内容集合
│ │ ├── config.ts # 内容配置
│ │ └── blog/ # 博客文章
@@ -83,6 +92,7 @@ NovaBlog/
│ ├── pages/ # 页面路由
│ │ ├── index.astro # 首页
│ │ ├── login.astro # 登录页
│ │ ├── micro.astro # 微语页
│ │ ├── blog/ # 博客相关页面
│ │ ├── tags/ # 标签页面
│ │ └── categories/ # 分类页面
@@ -99,6 +109,10 @@ NovaBlog/
│ │ ├── config/ # 配置管理
│ │ ├── database/ # 数据库连接
│ │ ├── handlers/ # HTTP 处理器
│ │ │ ├── auth.go # 认证处理
│ │ │ ├── comment.go # 评论处理
│ │ │ ├── like.go # 点赞处理
│ │ │ └── micro.go # 微语处理
│ │ ├── middleware/ # 中间件
│ │ ├── models/ # 数据模型
│ │ └── utils/ # 工具函数
@@ -316,6 +330,171 @@ Authorization: Bearer <token> // 可选
**响应**: 同切换接口
### 微语接口
#### 获取微语列表
```http
GET /api/micros?page=1&page_size=20&user_id=1
Authorization: Bearer <token> // 可选
```
**参数**:
- `page` (可选): 页码，默认 1
- `page_size` (可选): 每页数量，默认 20，最大 50
- `user_id` (可选): 指定用户的微语
**响应**:
```json
{
"data": [
{
"id": 1,
"content": "今天天气真好！",
"images": "[]",
"tags": "[\"生活\", \"日常\"]",
"is_public": true,
"created_at": "2024-01-15T10:00:00Z",
"updated_at": "2024-01-15T10:00:00Z",
"user": {
"id": 1,
"username": "testuser",
"nickname": "测试用户",
"avatar": "https://..."
},
"like_count": 5,
"is_liked": false
}
],
"pagination": {
"page": 1,
"page_size": 20,
"total": 100,
"total_page": 5
}
}
```
#### 获取单条微语
```http
GET /api/micros/:id
Authorization: Bearer <token> // 可选
```
#### 发布微语
```http
POST /api/micros
Authorization: Bearer <token>
Content-Type: application/json
{
"content": "string", // 必填，最多 2000 字
"images": ["url1", "url2"], // 可选，图片 URL 数组
"tags": ["tag1", "tag2"], // 可选，标签数组
"is_public": true // 可选，默认 true
}
```
**响应**:
```json
{
"id": 1,
"content": "今天天气真好！",
"images": "[]",
"tags": "[\"生活\"]",
"is_public": true,
"created_at": "2024-01-15T10:00:00Z",
"user": {...},
"like_count": 0,
"is_liked": false
}
```
#### 更新微语
```http
PUT /api/micros/:id
Authorization: Bearer <token>
Content-Type: application/json
{
"content": "string",
"images": ["url1"],
"tags": ["tag1"],
"is_public": true
}
```
**权限**: 仅作者可修改
#### 删除微语
```http
DELETE /api/micros/:id
Authorization: Bearer <token>
```
**权限**: 作者或管理员可删除
#### 点赞/取消点赞微语
```http
POST /api/micros/:id/like
Authorization: Bearer <token>
```
**响应**:
```json
{
"liked": true,
"message": "点赞成功"
}
```
#### 获取热力图数据
```http
GET /api/micros/heatmap?year=2024&user_id=1
```
**参数**:
- `year` (可选): 年份，默认当前年
- `user_id` (可选): 指定用户
**响应**:
```json
[
{ "date": "2024-01-15", "count": 3 },
{ "date": "2024-01-16", "count": 1 },
{ "date": "2024-01-20", "count": 5 }
]
```
#### 获取统计数据
```http
GET /api/micros/stats?user_id=1
```
**响应**:
```json
{
"total_micros": 150,
"total_users": 25,
"top_users": [
{
"user_id": 1,
"username": "admin",
"nickname": "管理员",
"avatar": "...",
"post_count": 45
}
]
}
```
### 错误响应格式
```json
@@ -418,6 +597,46 @@ CREATE TABLE post_meta (
CREATE INDEX idx_post_meta_post_id ON post_meta(post_id);
```
### micro_posts 表
```sql
CREATE TABLE micro_posts (
id INTEGER PRIMARY KEY AUTOINCREMENT,
created_at DATETIME,
updated_at DATETIME,
deleted_at DATETIME, -- 软删除
user_id INTEGER NOT NULL, -- 关联 users.id
content TEXT NOT NULL, -- 微语内容，最多 2000 字
images TEXT, -- JSON 数组存储图片 URL
tags TEXT, -- JSON 数组存储标签
is_public BOOLEAN DEFAULT 1, -- 是否公开
FOREIGN KEY (user_id) REFERENCES users(id)
);
CREATE INDEX idx_micro_posts_user_id ON micro_posts(user_id);
CREATE INDEX idx_micro_posts_deleted_at ON micro_posts(deleted_at);
CREATE INDEX idx_micro_posts_created_at ON micro_posts(created_at);
```
### micro_post_likes 表
```sql
CREATE TABLE micro_post_likes (
id INTEGER PRIMARY KEY AUTOINCREMENT,
created_at DATETIME,
micro_post_id INTEGER NOT NULL, -- 关联 micro_posts.id
user_id INTEGER NOT NULL, -- 关联 users.id
FOREIGN KEY (micro_post_id) REFERENCES micro_posts(id),
FOREIGN KEY (user_id) REFERENCES users(id)
);
-- 防止同一用户重复点赞同一条微语
CREATE UNIQUE INDEX idx_micropost_user ON micro_post_likes(micro_post_id, user_id);
CREATE INDEX idx_micropost_likes_user_id ON micro_post_likes(user_id);
```
---
## 前端组件开发

67
docs/user-guide.md
View File

@@ -12,10 +12,11 @@
4. [React 动效组件](#react-动效组件)
5. [动效 HTML 块](#动效-html-块)
6. [评论系统](#评论系统)
7. [用户注册与登录](#用户注册与登录)
8. [主题定制](#主题定制)
9. [附件管理](#附件管理)
10. [常见问题](#常见问题)
7. [微语功能](#微语功能)
8. [用户注册与登录](#用户注册与登录)
9. [主题定制](#主题定制)
10. [附件管理](#附件管理)
11. [常见问题](#常见问题)
---
@@ -567,6 +568,64 @@ NovaBlog 内置评论系统，支持多级嵌套回复和 Markdown 语法。
---
## 微语功能
微语是一个轻量级的分享空间，让你可以随时记录生活中的点滴、灵感与感悟。类似于社交媒体的动态功能，所有注册用户都可以发布。
### 访问微语
点击导航栏中的"微语"链接，或访问 `/micro` 页面。
### 发布微语
1. 登录你的账号
2. 在微语页面顶部的输入框中输入内容
3. 可选：添加标签（用逗号或空格分隔）
4. 选择是否公开可见
5. 点击"发布"按钮
**内容限制**：
- 单条微语最多 2000 字
- 支持多标签
### 微语列表
- 所有公开的微语都会显示在列表中
- 支持分页加载更多
- 显示发布者头像、昵称和发布时间
- 支持点赞功能
### 热力图
微语页面右侧显示 GitHub 风格的热力图，展示一年内的发布活动：
- **颜色深浅**：表示当天发布的微语数量
- **悬停查看**：鼠标悬停可查看具体日期和数量
- **年度统计**：显示全年发布的微语总数
### 点赞微语
1. 登录后可以给微语点赞
2. 点击心形图标即可点赞或取消点赞
3. 点赞数会实时更新
### 删除微语
- 用户可以删除自己发布的微语
- 管理员可以删除任何微语
### 微语与博客的区别
| 特性 | 博客文章 | 微语 |
|------|----------|------|
| 内容长度 | 无限制 | 最多 2000 字 |
| 格式支持 | Markdown + MDX | 纯文本 |
| 发布权限 | 管理员 | 所有注册用户 |
| 适用场景 | 长篇教程、技术文章 | 随手记录、灵感分享 |
| 互动功能 | 评论 | 点赞 |
---
## 用户注册与登录
### 注册账号