zjpb.net/CHANGELOG_v3.0.md

# ZJPB v3.0 版本更新日志

**发布日期：** 2025-02-06
**版本代号：** User System
**重要程度：** 🔴 重大更新

---

## 🎯 核心功能

### 1. 用户系统 (User System)

#### ✨ 用户注册与登录
- 用户注册功能（用户名 + 密码）
- 用户登录/登出
- 多用户类型支持（Admin 和 User 分离）
- 会话管理和状态持久化

#### ⭐ 工具收藏功能
- 一键收藏/取消收藏工具
- 收藏状态实时同步
- 收藏按钮视觉反馈（未收藏/已收藏状态）
- 未登录用户引导登录

#### 📁 收藏分组管理
- 创建自定义文件夹
- 文件夹增删改查
- 收藏移动到不同文件夹
- 文件夹图标自定义

#### 👤 用户中心
- 个人资料展示
- 收藏统计（收藏数、文件夹数）
- 最近收藏列表
- 收藏列表页面（网格展示 + 分页）

---

## 🗄️ 数据库变更

### 新增表

**users（用户表）**
```sql
- id: 主键
- username: 用户名（唯一，索引）
- password_hash: 密码哈希
- email: 邮箱（可选，唯一，索引）
- avatar: 头像URL
- bio: 个人简介
- is_active: 是否启用
- is_public_profile: 是否公开资料
- created_at: 创建时间
- last_login: 最后登录时间
```

**folders（收藏分组表）**
```sql
- id: 主键
- user_id: 用户ID（外键，索引）
- name: 文件夹名称
- description: 描述
- icon: 图标emoji
- sort_order: 排序权重
- is_public: 是否公开
- public_slug: 公开链接标识（唯一，索引）
- created_at: 创建时间
- 唯一约束: (user_id, name)
```

**collections（收藏记录表）**
```sql
- id: 主键
- user_id: 用户ID（外键，索引）
- site_id: 网站ID（外键，索引）
- folder_id: 文件夹ID（外键，索引，可选）
- note: 备注
- created_at: 创建时间
- updated_at: 更新时间
- 唯一约束: (user_id, site_id, folder_id)
- 复合索引: (user_id, folder_id)
```

---

## 🔌 API 端点

### 认证 API

```
POST /register              - 用户注册
POST /login                 - 用户登录
GET  /logout                - 用户登出
GET  /api/auth/status       - 获取登录状态
```

### 收藏 API（需登录）

```
POST /api/collections/toggle           - 收藏/取消收藏
GET  /api/collections/status/:code     - 查询收藏状态
GET  /api/collections/list             - 获取收藏列表
PUT  /api/collections/:id/note         - 更新收藏备注
PUT  /api/collections/:id/move         - 移动收藏
```

### 文件夹 API（需登录）

```
GET    /api/folders         - 获取文件夹列表
POST   /api/folders         - 创建文件夹
PUT    /api/folders/:id     - 更新文件夹
DELETE /api/folders/:id     - 删除文件夹
```

### 用户中心

```
GET /user/profile           - 用户中心主页
GET /user/collections       - 收藏列表页面
PUT /api/user/profile       - 更新用户资料
```

---

## 🎨 前端更新

### 新增页面

1. **用户注册页面** (`/register`)
   - Tailwind CSS 设计
   - 表单验证
   - 密码可见性切换

2. **用户登录页面** (`/login`)
   - 与管理员登录页面风格一致
   - 支持 next 参数跳转

3. **用户中心** (`/user/profile`)
   - 侧边栏导航
   - 统计卡片
   - 最近收藏展示

4. **收藏列表** (`/user/collections`)
   - 文件夹标签切换
   - 工具网格展示
   - 分页支持
   - 空状态提示

### 界面优化

- **导航栏**：登录后显示用户头像和下拉菜单
- **工具详情页**：添加收藏按钮（带动画效果）
- **响应式设计**：所有新页面支持移动端

---

## 🔒 安全增强

### 权限隔离

- ✅ Admin 和 User 完全分离
- ✅ 普通用户无法访问管理后台
- ✅ 管理员无法使用收藏功能
- ✅ 所有管理员 API 添加权限检查

### 受保护的路由（共14个）

**Flask-Admin 后台：**
- SecureModelView（网站、标签、新闻等管理）
- SecureAdminIndexView（控制台首页）

**管理员页面：**
- /admin/change-password
- /admin/seo-tools
- /admin/batch-import

**管理员 API：**
- /api/fetch-website-info
- /api/upload-logo
- /api/generate-features
- /api/generate-description
- /api/generate-tags
- /api/fetch-site-news
- /api/fetch-all-news
- /api/generate-static-sitemap
- /api/notify-search-engines

### 密码安全

- Werkzeug 密码哈希
- 最短密码长度：6位
- 最短用户名长度：3位

---

## 📁 文件变更

### 新增文件（7个）

```
templates/auth/register.html          - 注册页面
templates/auth/login.html             - 登录页面
templates/user/profile.html           - 用户中心
templates/user/collections.html       - 收藏列表
create_user_tables.py                 - 数据库迁移脚本
USER_SYSTEM_README.md                 - 用户系统文档
CHANGELOG_v3.0.md                     - 本更新日志
```

### 修改文件（4个）

```
models.py                             - 新增 User、Folder、Collection 模型
app.py                                - 新增路由和 API，权限检查
templates/base_new.html               - 导航栏用户菜单
templates/detail_new.html             - 收藏按钮
```

---

## 🚀 部署指南

### 1. 数据库迁移

```bash
python create_user_tables.py
```

### 2. 启动应用

```bash
python app.py
```

### 3. 测试流程

1. 访问 `/register` 注册新用户
2. 登录后访问工具详情页
3. 点击"收藏"按钮测试
4. 访问 `/user/collections` 查看收藏

---

## ⚠️ 破坏性变更

### Admin 模型变更

- `Admin.get_id()` 现在返回 `"admin:{id}"` 格式
- 旧的管理员账号需要重新登录一次

### 权限系统

- 所有管理员路由现在强制检查用户类型
- 普通用户无法访问任何管理功能

---

## 🔄 兼容性

- ✅ 向后兼容 v2.x 的所有功能
- ✅ 现有管理员账号无需迁移
- ✅ 现有网站数据完全兼容
- ⚠️ 管理员需要重新登录一次

---

## 📊 性能优化

- 收藏列表查询使用 JOIN 避免 N+1 问题
- 添加必要的数据库索引
- 分页支持大量收藏数据

---

## 🎯 后续计划（v3.1+）

### 待实现功能

- [ ] 收藏备注编辑 UI
- [ ] 文件夹拖拽排序
- [ ] 批量收藏操作
- [ ] 收藏导出（CSV/JSON）
- [ ] 公开收藏列表（分享功能）
- [ ] 收藏统计图表
- [ ] 邮箱验证
- [ ] 忘记密码
- [ ] 头像上传
- [ ] 第三方登录（微信、GitHub）

---

## 👥 贡献者

- **开发：** Claude Sonnet 4.5
- **需求：** 项目团队
- **测试：** 待进行

---

## 📝 注意事项

1. **首次部署必须运行数据库迁移脚本**
2. **管理员和普通用户使用不同的登录入口**
   - 管理员：`/admin/login`
   - 普通用户：`/login`
3. **删除用户会级联删除其所有收藏和文件夹**
4. **建议在生产环境部署前进行完整测试**

---

## 🐛 已知问题

- 无

---

## 📞 技术支持

如有问题，请查看：
- 用户系统文档：`USER_SYSTEM_README.md`
- Flask-Login 文档：https://flask-login.readthedocs.io/
- SQLAlchemy 文档：https://docs.sqlalchemy.org/

---

**版本：** v3.0.0
**发布状态：** ✅ 稳定版
**推荐升级：** 是