Skip to content

Commit 9b2c834

Browse files
zyx3721claude
zyx3721
and
claude
committed
docs: 优化 README 目录结构说明并新增 v1.0.1 版本日志
- 重构 1.4 目录结构章节，改为统一的项目树形结构展示 - 新增详细的目录注释说明，包含各模块功能描述 - 补充 deploy/ 和 verchanglog/ 目录说明 - 新增 v1.0.1 版本更新日志文档 - 记录 RSS 订阅功能增强的完整变更历史 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent d3ab5cb commit 9b2c834

2 files changed

Lines changed: 313 additions & 71 deletions

File tree

‎README.md‎

Lines changed: 105 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -84,78 +84,111 @@ JeriBlog 是一个三端分离的博客系统，围绕内容创作这件事，
8484

8585
## 1.4 目录结构
8686

87-
### 1.4.1 Server
88-
89-
```bash
90-
server/
91-
├── api/ # API 定义
92-
│ ├── middleware/ # 中间件 (认证、CORS、日志、限流、RBAC等)
93-
│ ├── router/ # 路由配置
94-
│ └── v1/ # API v1 版本接口（文章、用户、评论、标签、分类、友链、动态、菜单、通知、反馈、订阅、RSS、AI、系统等）
95-
├── cmd/ # 应用入口
96-
│ └── main.go
97-
├── config/ # 配置管理
98-
├── docs/ # Swagger 生成的文档
99-
├── internal/ # 内部业务逻辑
100-
│ ├── dto/ # 数据传输对象
101-
│ ├── model/ # 数据模型
102-
│ ├── repository/ # 数据访问层
103-
│ └── service/ # 业务逻辑层（文章、用户、评论、标签、分类、友链、动态、菜单、通知、反馈、订阅、RSS、系统、配置等）
104-
├── pkg/ # 可复用的包
105-
│ ├── database/ # 数据库连接管理
106-
│ ├── email/ # 邮件发送
107-
│ ├── errcode/ # 统一错误码
108-
│ ├── feishu/ # 飞书 SDK
109-
│ ├── notification/ # 通知服务（邮件/飞书聚合）
110-
│ ├── response/ # 统一响应格式
111-
│ ├── scheduler/ # 定时任务调度
112-
│ └── upload/ # 文件上传管理
113-
├── templates/ # 模板文件
114-
└── go.mod
115-
```
116-
117-
### 1.4.2 Admin
118-
119-
```bash
120-
admin/
121-
├── src/
122-
│ ├── api/ # API 接口
123-
│ ├── assets/ # 静态资源
124-
│ ├── components/ # 公共组件
125-
│ ├── layouts/ # 页面布局
126-
│ ├── router/ # 路由配置
127-
│ ├── types/ # TypeScript 类型定义
128-
│ ├── utils/ # 工具函数
129-
│ ├── views/ # 页面组件
130-
│ ├── App.vue # 根组件
131-
│ └── main.ts # 入口文件
132-
├── public/ # 公共文件
133-
├── index.html # HTML 模板
134-
├── vite.config.ts # Vite 配置
135-
├── nginx.conf # Nginx 配置
136-
└── Dockerfile # Docker 配置
137-
```
138-
139-
### 1.4.3 Blog
140-
14187
```bash
142-
blog/
143-
├── app/ # 应用主目录
144-
│ ├── assets/ # 静态资源
145-
│ ├── components/ # Vue 组件
146-
│ ├── composables/ # 组合式函数
147-
│ ├── layouts/ # 页面布局
148-
│ ├── pages/ # 页面路由
149-
│ ├── plugins/ # Nuxt 插件
150-
│ ├── utils/ # 工具函数
151-
│ └── app.vue # 根组件
152-
├── public/ # 公共文件
153-
├── server/ # 服务端代码
154-
│ ├── plugins/ # 服务端插件
155-
│ └── routes/ # API 路由
156-
├── types/ # TypeScript 类型定义
157-
├── nuxt.config.ts # Nuxt 配置
158-
└── Dockerfile # Docker 配置
88+
JeriBlog/
89+
├── server/ # 后端服务 (Go + Gin + GORM)
90+
│ ├── api/ # API 层
91+
│ │ ├── middleware/ # 中间件 (认证、CORS、日志、限流、RBAC)
92+
│ │ ├── router/ # 路由配置
93+
│ │ └── v1/ # API v1 接口 (文章、用户、评论、标签、分类、友链、动态、菜单、通知、反馈、订阅、RSS、AI、系统)
94+
│ ├── cmd/ # 应用入口
95+
│ │ └── main.go # 主程序入口
96+
│ ├── config/ # 配置管理
97+
│ ├── docs/ # Swagger API 文档
98+
│ ├── internal/ # 内部业务逻辑
99+
│ │ ├── dto/ # 数据传输对象 (Data Transfer Object)
100+
│ │ ├── model/ # 数据模型 (GORM 实体)
101+
│ │ ├── repository/ # 数据访问层 (Repository Pattern)
102+
│ │ └── service/ # 业务逻辑层 (Service Layer)
103+
│ ├── pkg/ # 可复用的公共包
104+
│ │ ├── database/ # 数据库连接管理
105+
│ │ ├── email/ # 邮件发送服务
106+
│ │ ├── errcode/ # 统一错误码定义
107+
│ │ ├── feishu/ # 飞书 SDK 封装
108+
│ │ ├── logger/ # 日志工具
109+
│ │ ├── notification/ # 通知服务聚合 (邮件/飞书)
110+
│ │ ├── response/ # 统一响应格式
111+
│ │ ├── scheduler/ # 定时任务调度器
112+
│ │ ├── upload/ # 文件上传管理 (本地/MinIO/OSS/COS/七牛云)
113+
│ │ └── utils/ # 通用工具函数
114+
│ ├── templates/ # 邮件等模板文件
115+
│ ├── go.mod # Go 模块依赖
116+
│ └── Dockerfile # Docker 镜像构建文件
117+
│
118+
├── admin/ # 管理后台 (Vue 3 + Element Plus)
119+
│ ├── src/
120+
│ │ ├── api/ # API 接口封装
121+
│ │ ├── assets/ # 静态资源 (图片、字体、样式)
122+
│ │ ├── components/ # 公共组件
123+
│ │ │ ├── common/ # 通用组件 (表格、表单、对话框)
124+
│ │ │ └── editor/ # Markdown 编辑器组件
125+
│ │ ├── layouts/ # 页面布局组件
126+
│ │ ├── router/ # Vue Router 路由配置
127+
│ │ ├── types/ # TypeScript 类型定义
128+
│ │ ├── utils/ # 工具函数 (日期、验证、请求)
129+
│ │ ├── views/ # 页面组件
130+
│ │ │ ├── article/ # 文章管理
131+
│ │ │ ├── comment/ # 评论管理
132+
│ │ │ ├── dashboard/ # 仪表盘
133+
│ │ │ ├── friend/ # 友链管理
134+
│ │ │ ├── moment/ # 动态管理
135+
│ │ │ ├── rssfeed/ # RSS 订阅管理
136+
│ │ │ ├── system/ # 系统设置
137+
│ │ │ └── user/ # 用户管理
138+
│ │ ├── App.vue # 根组件
139+
│ │ └── main.ts # 应用入口
140+
│ ├── public/ # 公共静态文件
141+
│ ├── index.html # HTML 模板
142+
│ ├── vite.config.ts # Vite 构建配置
143+
│ ├── nginx.conf # Nginx 配置
144+
│ ├── package.json # npm 依赖
145+
│ └── Dockerfile # Docker 镜像构建文件
146+
│
147+
├── blog/ # 博客前台 (Nuxt 4 + SSR)
148+
│ ├── app/ # 应用主目录
149+
│ │ ├── assets/ # 静态资源 (样式、图片)
150+
│ │ ├── components/ # Vue 组件
151+
│ │ │ ├── article/ # 文章相关组件
152+
│ │ │ ├── comment/ # 评论组件
153+
│ │ │ ├── layout/ # 布局组件 (头部、底部、侧边栏)
154+
│ │ │ └── widget/ # 小部件 (标签云、归档、友链)
155+
│ │ ├── composables/ # 组合式函数 (Composables)
156+
│ │ ├── layouts/ # 页面布局
157+
│ │ ├── pages/ # 页面路由 (基于文件系统)
158+
│ │ │ ├── article/ # 文章页面
159+
│ │ │ ├── category/ # 分类页面
160+
│ │ │ ├── tag/ # 标签页面
161+
│ │ │ ├── friend/ # 友链页面
162+
│ │ │ └── about/ # 关于页面
163+
│ │ ├── plugins/ # Nuxt 插件
164+
│ │ ├── utils/ # 工具函数
165+
│ │ └── app.vue # 根组件
166+
│ ├── public/ # 公共静态文件
167+
│ ├── server/ # 服务端代码 (SSR)
168+
│ │ ├── plugins/ # 服务端插件
169+
│ │ └── routes/ # API 路由
170+
│ ├── types/ # TypeScript 类型定义
171+
│ ├── nuxt.config.ts # Nuxt 配置
172+
│ ├── package.json # npm 依赖
173+
│ └── Dockerfile # Docker 镜像构建文件
174+
│
175+
├── deploy/ # 部署相关文件
176+
│ ├── docker-compose.yml # Docker Compose 配置
177+
│ ├── Dockerfile # 统一多阶段构建文件
178+
│ └── nginx/ # Nginx 配置文件
179+
│
180+
├── verchanglog/ # 版本更新日志
181+
│ ├── v1.0.0.md # v1.0.0 版本日志
182+
│ └── v1.0.1.md # v1.0.1 版本日志
183+
│
184+
├── .github/ # GitHub 配置
185+
│ ├── images/ # README 预览图片
186+
│ └── workflows/ # GitHub Actions CI/CD
187+
│
188+
├── .env.example # 环境变量示例
189+
├── .gitignore # Git 忽略文件
190+
├── LICENSE # 开源许可证
191+
└── README.md # 项目说明文档
159192
```
160193

161194
## 1.5 特性
@@ -1470,6 +1503,7 @@ systemctl reload nginx
14701503
- `GET /api/v1/admin/rssfeed` - 获取 RSS 文章列表
14711504
- `PUT /api/v1/admin/rssfeed/:id/read` - 标记文章已读（需超级管理员权限）
14721505
- `PUT /api/v1/admin/rssfeed/read-all` - 全部标记已读（需超级管理员权限）
1506+
- `POST /api/v1/admin/rssfeed/refresh` - 立即刷新 RSS 订阅源（需超级管理员权限）
14731507

14741508
### 6.4.18 邮件订阅者管理
14751509

‎verchanglog/v1.0.1.md‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
# JeriBlog v1.0.1 版本更新日志
2+
3+
**发布日期**: 2026-04-21
4+
**提交数量**: 59 次提交
5+
**版本类型**: 功能增强版本
6+
7+
---
8+
9+
## 📋 版本概述
10+
11+
JeriBlog v1.0.1 主要围绕 **RSS 订阅功能** 进行了全面优化和增强，新增了文章变更检测、删除恢复机制、重复文章自动清理等核心功能，显著提升了 RSS 订阅管理的智能化水平。
12+
13+
---
14+
15+
## ✨ 新增特性
16+
17+
### RSS 订阅功能增强
18+
19+
- **文章变更检测系统**
20+
- 支持检测标题、链接、发布时间三个维度的变更
21+
- 前端显示变更标签（标题已更新、链接已更新、发布时间已更新）
22+
- 可同时显示多个变更标签
23+
- 标记已读后自动清空变更标签
24+
- 新增 `update_type` 字段记录变更类型（逗号分隔）
25+
26+
- **文章删除与恢复机制**
27+
- 新增 `is_deleted` 字段支持软删除
28+
- RSS 源中移除的文章自动标记为已删除
29+
- RSS 源中恢复的文章自动恢复为未读状态
30+
- 支持按删除状态筛选文章
31+
32+
- **RSS 订阅管理功能**
33+
- 新增"立即刷新 RSS"按钮（手动触发抓取所有订阅源）
34+
- 支持关键词搜索文章标题
35+
- 支持按状态筛选（未读/已读/已删除）
36+
- 支持按友链来源筛选
37+
- 优化列表布局和居中显示
38+
39+
- **重复文章自动清理**
40+
- 标题和链接都变化时自动删除旧文章
41+
- 文章更新后自动检查并删除重复项
42+
- 优先保留链接匹配的文章（链接作为更稳定的标识符）
43+
- 避免同一篇文章因标题/链接反复变化而重复出现
44+
45+
- **友链 RSS 地址变更处理**
46+
- 友链 RSS 地址变更时自动清理该友链的所有旧文章
47+
- 新增 `DeleteByFriendID` 方法支持批量删除
48+
49+
---
50+
51+
## 🐛 Bug 修复
52+
53+
### 后端修复
54+
55+
- 修复 RSS 文章列表返回数据中遗漏 `UpdateType` 字段的问题
56+
- 修复标题和链接都变化时的文章匹配逻辑
57+
- 修复 repository 编译错误并新增 `GetByFriendIDAndTitle` 方法
58+
- 修复友链服务依赖注入，传入 RSS 订阅仓储
59+
- 修复访问趋势数据为空时的报错问题
60+
- 移除未定义的 logger 调用
61+
62+
### 前端修复
63+
64+
- 修复标记已读后更新标签未立即消失的问题
65+
- 修复标记已读时 TypeScript 类型检查错误
66+
- 修复 RSS 订阅列表文章标题列居中显示
67+
- 修复 RSS 订阅列表文章标题列的标签显示和对齐问题
68+
69+
---
70+
71+
## 🚀 性能优化
72+
73+
### 数据库优化
74+
75+
- 更新数据库索引策略，支持双重查询优化
76+
- 移除唯一索引约束，改用普通索引支持双重查询
77+
- 实现双重查询策略支持多维度变更检测（标题查询 + 链接查询）
78+
79+
### 查询优化
80+
81+
- RSS 文章匹配逻辑优化：分别用标题和链接查询，提高匹配准确性
82+
- 优化 RSS 订阅列表状态筛选逻辑
83+
84+
---
85+
86+
## 🔧 重构优化
87+
88+
### 代码重构
89+
90+
- 简化 RSS 文章变更检测逻辑，仅跟踪链接和发布时间变化（后调整为标题、链接、发布时间三维度）
91+
- 移除 RSS 文章模型中的 `Description` 字段（简化数据结构）
92+
- 移除 RSS 文章 DTO 中的 `Description` 字段
93+
- 移除 RSS 订阅服务中的 `Description` 字段处理逻辑
94+
- 更新数据库初始化脚本，移除 RSS 文章表的 `description` 字段
95+
- 删除重复的 `UpdateArticleWithChangeDetection` 方法定义
96+
- 删除不需要的 RSS 迁移脚本文件
97+
98+
### 架构优化
99+
100+
- RSS 服务层改用链接作为唯一标识并支持标题变更检测
101+
- RSS 仓储层添加变更检测方法 `UpdateArticleWithChangeDetection`
102+
- RSS 仓储层新增删除状态管理方法（`MarkDeletedByFriendAndLinks`、`RestoreArticle`）
103+
- RSS 仓储层新增 `DeleteByFriendID` 方法
104+
- RSS 仓储层新增 `DeleteArticle` 方法（物理删除）
105+
- RSS 仓储层新增 `DeleteDuplicatesByTitleOrLink` 方法（清理重复文章）
106+
107+
---
108+
109+
## 📚 文档更新
110+
111+
- 更新 Swagger API 文档，新增 RSS 手动刷新接口
112+
- 更新 README.md 的 API 文档章节，补充 RSS 订阅管理接口
113+
114+
---
115+
116+
## 🔄 API 变更
117+
118+
### 新增接口
119+
120+
- `POST /api/v1/admin/rssfeed/refresh` - 立即刷新 RSS 订阅源（需超级管理员权限）
121+
122+
### 接口优化
123+
124+
- `GET /api/v1/admin/rssfeed` - 新增搜索和筛选参数支持
125+
- `PUT /api/v1/admin/rssfeed/:id/read` - 标记已读时清空 `update_type` 字段
126+
- `PUT /api/v1/admin/rssfeed/read-all` - 批量标记已读时清空 `update_type` 字段
127+
128+
---
129+
130+
## 📊 数据库变更
131+
132+
### 新增字段
133+
134+
- `rss_articles.is_deleted` - 软删除标记（BOOLEAN，默认 false）
135+
- `rss_articles.update_type` - 变更类型记录（VARCHAR(50)，存储格式：`title,link,published_at`）
136+
137+
### 移除字段
138+
139+
- `rss_articles.description` - 文章描述（简化数据结构）
140+
141+
### 索引优化
142+
143+
- 移除 `(friend_id, title)` 唯一索引约束
144+
- 移除 `(friend_id, link)` 唯一索引约束
145+
- 改用普通索引支持双重查询策略
146+
147+
---
148+
149+
## 🎯 技术栈
150+
151+
与 v1.0.0 保持一致，无变更。
152+
153+
---
154+
155+
## 📝 已知问题
156+
157+
无
158+
159+
---
160+
161+
## 🔄 升级说明
162+
163+
### 数据库迁移
164+
165+
从 v1.0.0 升级到 v1.0.1 需要执行以下数据库变更：
166+
167+
```sql
168+
-- 1. 移除 description 字段
169+
ALTER TABLE rss_articles DROP COLUMN IF EXISTS description;
170+
171+
-- 2. 新增 is_deleted 字段
172+
ALTER TABLE rss_articles ADD COLUMN IF NOT EXISTS is_deleted BOOLEAN DEFAULT false;
173+
174+
-- 3. 新增 update_type 字段
175+
ALTER TABLE rss_articles ADD COLUMN IF NOT EXISTS update_type VARCHAR(50) DEFAULT '';
176+
177+
-- 4. 移除唯一索引约束
178+
DROP INDEX IF EXISTS idx_friend_title;
179+
DROP INDEX IF EXISTS idx_friend_link;
180+
181+
-- 5. 创建普通索引
182+
CREATE INDEX IF NOT EXISTS idx_friend_title ON rss_articles(friend_id, title);
183+
CREATE INDEX IF NOT EXISTS idx_friend_link ON rss_articles(friend_id, link);
184+
```
185+
186+
### 注意事项
187+
188+
- 升级后首次刷新 RSS 订阅源时，会自动检测并清理重复文章
189+
- 已删除的文章会被标记为 `is_deleted = true`，不会物理删除
190+
- 文章变更检测仅对升级后新抓取的文章生效
191+
192+
---
193+
194+
## 👥 贡献者
195+
196+
- Jerion (416685476@qq.com)
197+
- Claude Opus 4.6
198+
199+
---
200+
201+
## 📄 许可证
202+
203+
MIT License
204+
205+
---
206+
207+
**完整提交记录**: 59 次提交
208+
**开发周期**: 2026-04-20 至 2026-04-21 (2 天)

0 commit comments

Comments
 (0)