# 用户注册登录和收藏功能实现说明

## 功能概述

本次更新为ZJPB项目添加了完整的用户系统，包括：
- ✅ 用户注册/登录（用户名+密码）
- ✅ 工具收藏功能
- ✅ 收藏分组管理（文件夹）
- ✅ 用户中心（个人资料、收藏列表）
- ✅ 多用户类型支持（Admin和User）

## 部署步骤

### 1. 创建数据库表

运行数据库迁移脚本创建新表：

```bash
python create_user_tables.py
```

这将创建以下表：
- `users` - 用户表
- `folders` - 收藏分组表
- `collections` - 收藏记录表

### 2. 启动应用

```bash
python app.py
```

或使用现有的启动方式。

## 功能说明

### 1. 用户注册

**访问路径：** `/register`

- 用户名：至少3个字符
- 密码：至少6个字符
- 注册成功后自动登录并跳转到首页

### 2. 用户登录

**访问路径：** `/login`

- 输入用户名和密码
- 登录成功后跳转到首页或之前访问的页面

### 3. 导航栏用户菜单

登录后，导航栏右侧会显示用户菜单：
- 显示用户名和头像（或首字母）
- 下拉菜单包含：
  - 👤 个人中心
  - ⭐ 我的收藏
  - 🚪 退出登录

### 4. 收藏功能

**在工具详情页：**
- 登录后可看到"收藏"按钮
- 点击按钮收藏/取消收藏
- 已收藏时按钮变为金色
- 未登录时点击会提示登录

**前端页面：**
- detail_new.html - 添加了收藏按钮
- 自动检查登录状态和收藏状态
- Toast消息提示操作结果

### 5. 用户中心

**访问路径：** `/user/profile`

显示内容：
- 侧边栏：头像、用户名、个人简介、导航菜单
- 主内容区：
  - 统计卡片（收藏数、文件夹数）
  - 最近收藏列表（最多5条）

### 6. 我的收藏

**访问路径：** `/user/collections`

功能：
- 文件夹标签页切换
- 工具卡片网格展示
- 分页支持
- 空状态提示

## API端点

### 认证API

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

### 收藏API（需登录）

```
POST /api/collections/toggle           - 收藏/取消收藏
  Body: { site_code: "12345678" }

GET  /api/collections/status/:site_code - 查询收藏状态
  Response: { is_collected: true/false, collection_id: 1, folder_id: null }

GET  /api/collections/list             - 获取收藏列表
  Query: folder_id, page, per_page
  Response: { collections: [...], total: 10, page: 1, ... }

PUT  /api/collections/:id/note         - 更新收藏备注
  Body: { note: "备注内容" }

PUT  /api/collections/:id/move         - 移动收藏到文件夹
  Body: { folder_id: 1 }
```

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

```
GET    /api/folders     - 获取文件夹列表
POST   /api/folders     - 创建文件夹
  Body: { name: "文件夹名", description: "", icon: "📁" }

PUT    /api/folders/:id - 更新文件夹
  Body: { name: "", description: "", icon: "", sort_order: 0 }

DELETE /api/folders/:id - 删除文件夹（级联删除收藏）
```

### 用户资料API（需登录）

```
PUT /api/user/profile - 更新用户资料
  Body: { bio: "", avatar: "", is_public_profile: false }
```

## 数据库模型

### User（用户表）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Integer | 主键 |
| username | String(50) | 用户名（唯一） |
| password_hash | String(255) | 密码哈希 |
| email | String(100) | 邮箱（可选） |
| avatar | String(500) | 头像URL |
| bio | String(200) | 个人简介 |
| is_active | Boolean | 是否启用 |
| is_public_profile | Boolean | 是否公开资料 |
| created_at | DateTime | 创建时间 |
| last_login | DateTime | 最后登录时间 |

### Folder（收藏分组表）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Integer | 主键 |
| user_id | Integer | 用户ID |
| name | String(50) | 文件夹名称 |
| description | String(200) | 描述 |
| icon | String(50) | 图标emoji |
| sort_order | Integer | 排序权重 |
| is_public | Boolean | 是否公开 |
| public_slug | String(100) | 公开链接标识 |
| created_at | DateTime | 创建时间 |

### Collection（收藏记录表）

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Integer | 主键 |
| user_id | Integer | 用户ID |
| site_id | Integer | 网站ID |
| folder_id | Integer | 文件夹ID（可选） |
| note | Text | 备注 |
| created_at | DateTime | 创建时间 |
| updated_at | DateTime | 更新时间 |

## 技术实现

### 多用户类型支持

- Admin模型：`get_id()` 返回 `"admin:{id}"`
- User模型：`get_id()` 返回 `"user:{id}"`
- `user_loader` 根据前缀加载不同类型的用户

### 安全特性

- 密码使用 Werkzeug 的 `generate_password_hash` 加密
- 最短密码长度：6位
- 最短用户名长度：3位
- Flask-Login 管理会话
- 路由保护：`@login_required` 装饰器
- 用户类型检查：`isinstance(current_user, User)`

### 前端特性

- Tailwind CSS 设计风格（复用admin_login.html）
- JavaScript无侵入式增强
- 异步API调用（Fetch）
- Toast消息提示
- 响应式设计

## 文件清单

### 新增文件

```
templates/auth/register.html      - 注册页面
templates/auth/login.html         - 登录页面
templates/user/profile.html       - 用户中心
templates/user/collections.html   - 收藏列表
create_user_tables.py             - 数据库迁移脚本
USER_SYSTEM_README.md            - 本说明文档
```

### 修改文件

```
models.py              - 添加User、Folder、Collection模型，修改Admin.get_id()
app.py                 - 添加认证路由、收藏API、文件夹API、用户路由
templates/base_new.html   - 更新导航栏，添加用户菜单
templates/detail_new.html - 添加收藏按钮和JavaScript
```

## 测试步骤

1. **用户注册流程**
   - 访问 `/register`
   - 输入用户名和密码
   - 提交表单
   - 验证自动登录成功

2. **用户登录流程**
   - 访问 `/login`
   - 输入正确的用户名和密码
   - 验证登录成功并跳转

3. **收藏功能**
   - 登录后访问任意工具详情页
   - 点击"收藏"按钮
   - 验证按钮状态变为"已收藏"
   - 再次点击取消收藏

4. **我的收藏**
   - 访问 `/user/collections`
   - 验证收藏的工具显示正确
   - 测试文件夹切换

5. **用户中心**
   - 访问 `/user/profile`
   - 验证统计数据正确
   - 验证最近收藏列表

## 后续优化方向

### 已实现的MVP功能
- ✅ 基础注册登录
- ✅ 收藏/取消收藏
- ✅ 收藏列表展示
- ✅ 基础文件夹管理

### 待实现的增强功能
- ⏳ 收藏备注编辑UI
- ⏳ 文件夹拖拽移动
- ⏳ 批量收藏操作
- ⏳ 收藏导出（CSV/JSON）
- ⏳ 公开收藏列表（分享）
- ⏳ 收藏统计图表
- ⏳ 邮箱验证
- ⏳ 忘记密码
- ⏳ 头像上传
- ⏳ 第三方登录

## 注意事项

1. **管理员与普通用户分离**
   - 管理员账号无法使用收藏功能
   - 管理员登录入口：`/admin/login`
   - 普通用户登录入口：`/login`

2. **数据完整性**
   - 删除用户会级联删除其所有收藏和文件夹
   - 删除文件夹会级联删除其中的收藏记录
   - 删除网站不会删除相关收藏（保留历史记录）

3. **性能优化**
   - 收藏列表查询使用了join避免N+1问题
   - 添加了必要的数据库索引
   - 分页支持大量收藏

## 技术支持

如有问题，请查看：
- Flask-Login 文档：https://flask-login.readthedocs.io/
- SQLAlchemy 文档：https://docs.sqlalchemy.org/
- Tailwind CSS 文档：https://tailwindcss.com/

---

**版本：** v1.0
**更新日期：** 2025-02-06
**作者：** Claude Sonnet 4.5