百变书屋 - 私人智能图书馆

一个基于AI技术的智能图书推荐和阅读平台，为用户提供个性化的阅读体验。

项目进度

第一阶段（已完成）

前端部分 ✅

• 创建了主页面布局和样式
• 实现了响应式设计
• 配置了Tailwind CSS和Alpine.js
• 解决了样式编译问题
• 完成了主要页面的UI设计：
  • 首页布局
  • 书籍展示卡片
  • 分类导航
  • 用户界面组件

数据库部分 ✅

• 完成数据库设计
  • 用户模型（User）
  • 书籍模型（Book）
  • 书架模型（Bookshelf）
• 实现数据库配置和连接
• 创建数据库初始化脚本
• 配置模型关联关系

第二阶段（已完成）

前后端集成 ✅

• 用户认证界面
  • 登录页面与API对接
  • 注册页面与API对接
  • 密码重置功能
• 书籍展示功能
  • 主页书籍列表数据加载
  • 书籍详情页面
  • 分类筛选功能
• 书架管理功能
  • "添加到书架"功能
  • 书架页面数据展示
  • 阅读进度管理

导航和路由 ✅

• 统一的导航栏设计
• 页面间跳转逻辑
• 用户状态管理
• 权限控制

数据初始化 ✅

• 创建示例数据
  • 书籍数据
  • 用户数据
  • 分类数据
• 实现数据迁移
• 添加数据备份机制

功能测试 ✅

• API基础测试
• 前端单元测试
• 集成测试
• 性能测试

Bug修复和UI优化 ✅

• 修复登录认证问题
• 优化登录和注册页面UI
• 修复用户界面样式不一致问题
• 修复导航和路由问题

第三阶段（进行中）

阅读器功能开发 🔄

• 在线阅读器实现
  • 基本阅读功能
  • 页面滚动/翻页
  • 字体大小调整
  • 阅读进度保存
• 阅读统计
  • 阅读时长记录
  • 阅读进度分析
  • 阅读习惯建议

社区功能 🔄

• 社区页面设计
• 评论系统实现
  • 发表评论
  • 回复评论
  • 评论点赞
• 读书笔记功能
  • 创建笔记
  • 分享笔记
  • 查看他人笔记

AI功能集成 ⏳

• DeepSeek API集成
• 智能推荐系统
• 个性化阅读建议
• 基于阅读历史的推荐

第四阶段（进行中）

书源解析引擎（进行中）

• 书源配置格式设计
  • 定义JSON配置结构
  • 设计选择器规则
  • 创建书源验证机制
• 网页抓取模块
  • HTTP请求封装
  • HTML解析工具
  • 内容提取规则
• 书源管理功能
  • 书源导入/导出
  • 书源测试工具
  • 书源分享功能

统一配置和部署优化（新增）

• 统一配置管理
  • 前端配置集中化
  • 后端配置统一
  • 环境变量标准化
• Vercel部署支持
  • 前端部署配置
  • 后端部署配置
  • 环境变量管理
• 开发和生产环境分离
  • 环境检测
  • 配置自动适应

内容搜索与推荐（预计2周）

• 高级搜索功能
  • 多书源并行搜索
  • 搜索结果合并
  • 搜索结果排序
• AI内容匹配
  • 用户兴趣输入界面
  • DeepSeek API集成
  • 推荐结果展示
• 个性化推荐
  • 基于阅读历史的推荐
  • 基于用户标签的推荐
  • 推荐结果反馈机制

阅读体验增强（预计2周）

• 阅读器高级功能
  • 多种阅读模式（滚动/分页）
  • 自定义主题与样式
  • 章节预加载
  • 离线阅读支持
• 阅读数据记录
  • 精确阅读进度跟踪
  • 阅读时长统计
  • 阅读习惯分析
• 内容增强
  • 生词查询功能
  • AI内容摘要
  • 章节导航增强

性能与安全（预计2周）

• 性能优化
  • 内容缓存机制
  • 请求并发控制
  • 资源压缩与优化
• 安全措施
  • 内容安全检测
  • 书源合法性验证
  • 用户数据保护
• 系统稳定性
  • 错误处理与恢复
  • 负载均衡策略
  • 监控与报警机制

当前迭代任务详情（第四阶段）

书源解析引擎

1. 书源配置格式设计

   • 设计书源JSON配置格式（包含规则定义、XPath/CSS选择器、HTTP请求方式等）
   • 参考开源项目如legado、阅读3.0的书源格式
   • 创建书源配置验证工具
   • 设计书源测试流程

2. 网页抓取与解析模块

   • 开发通用的网页抓取模块
   • 实现HTML内容解析器
   • 添加内容清洗与格式化功能
   • 支持多种选择器（XPath、CSS、正则表达式）

3. 书源管理功能

   • 实现书源导入/导出功能
   • 开发书源编辑界面
   • 添加书源分类与标签
   • 创建书源分享与同步机制

DeepSeek API集成

1. API客户端封装

   • 创建DeepSeek API客户端
   • 实现请求与响应处理
   • 添加错误处理与重试机制
   • 设计API请求缓存

2. 内容匹配算法

   • 设计用户兴趣提取算法
   • 实现内容相似度计算
   • 开发推荐结果排序机制
   • 添加推荐反馈学习功能

3. 推荐系统UI

   • 设计用户兴趣输入界面
   • 创建推荐结果展示组件
   • 实现推荐结果筛选
   • 添加推荐原因说明

阅读器增强

1. 高级阅读器功能

   • 实现多种阅读模式（滚动/分页）
   • 添加自定义主题与样式
   • 开发章节预加载功能
   • 实现离线阅读支持

2. 阅读数据记录

   • 设计阅读进度记录模型
   • 实现精确阅读位置跟踪
   • 开发阅读时长统计
   • 创建阅读习惯分析报告

3. 内容增强功能

   • 添加生词查询功能
   • 实现AI内容摘要
   • 开发章节导航增强
   • 创建阅读辅助工具

技术架构

前端技术栈

• HTML5 + CSS3 + JavaScript
• Tailwind CSS 用于样式
• Alpine.js 用于交互
• 自定义Web组件用于阅读器
• Vite 用于构建和开发

后端技术栈

• Node.js + Express
• MySQL 用于核心数据存储
• MongoDB 用于书源管理
• RESTful API
• JWT 认证
• Sequelize ORM

AI集成

• DeepSeek API 用于内容推荐
• 自定义推荐算法
• 内容分析与匹配

书源解析

• 自定义书源格式（JSON）
• HTTP请求与HTML解析
• 内容提取与格式化
• 缓存与并发控制

功能测试指南

本地测试环境搭建

1. 启动前端开发服务器

cd web
npm run dev
# 访问 http://localhost:3000

2. 启动API服务器

cd server
npm run dev
# API服务运行在 http://localhost:3001

3. 数据库准备

# 确保数据库已初始化
cd web
npm run init-db

测试用户账号

• 邮箱: test@example.com
• 密码: test123
• 用户名: testuser

功能测试流程

用户认证测试

1. 访问登录页面 /src/pages/login.html
2. 使用测试账号登录
3. 验证登录状态保持
4. 测试注册功能
5. 测试密码重置功能

书籍展示测试

1. 访问首页，验证书籍列表加载
2. 点击书籍卡片，验证详情页面
3. 测试分类筛选功能
4. 验证推荐算法

书源功能测试（新增）

1. 导入测试书源配置
2. 执行书源搜索测试
3. 验证内容抓取功能
4. 测试章节列表获取
5. 验证内容渲染效果

AI推荐测试（新增）

1. 输入用户兴趣内容
2. 验证DeepSeek API响应
3. 测试推荐结果展示
4. 验证推荐书籍详情获取
5. 测试推荐反馈功能

UI设计规范

重要提示：所有页面必须严格按照model文件夹下的原型文件进行实现

1. 使用MCP工具查看原型文件样式：

# 启动开发服务器
cd model
npx serve
# 访问 http://localhost:5000

2. 使用MCP工具进行页面比对：

   • 截取原型页面截图
   • 截取实现页面截图
   • 对比差异并调整

3. 设计规范要点：

   • 颜色方案必须与原型一致
   • 组件间距与原型保持一致
   • 响应式布局必须符合原型设计
   • 交互效果（悬停、点击等）必须实现

已知问题与解决进度

界面问题

• 导航栏样式统一问题
• 登录表单验证错误消息不清晰
• 个人资料按钮点击无法正确跳转
• 登录页面自动填充问题
• 移动端菜单折叠问题
• 书籍详情页布局在小屏幕上显示异常

功能问题

• 登录认证失败（已修复：邮箱字段问题）
• 书架同步延迟问题
• 搜索结果偶尔不精确
• 阅读进度同步失败
• 部分API返回错误格式不统一

性能问题

• 首页加载时间过长
• 大量图片导致页面卡顿
• API响应时间不稳定
• 移动端性能优化不足

技术栈

前端

• HTML5/CSS3/JavaScript
• Tailwind CSS：原子化CSS框架
• Alpine.js：轻量级JavaScript框架
• Font Awesome：图标库

后端

• Node.js + Express：后端框架
• MySQL：关系型数据库
• Sequelize：ORM框架
• JWT：用户认证
• OpenAI API：AI推荐功能

本地开发环境搭建

前置要求

• Node.js >= 18
• MySQL >= 8.0
• MongoDB >= 4.0 (可选，用于书源管理)
• Git

启动步骤

1. 克隆项目

git clone https://github.com/OneSmallPig/bookstore.git
cd bookstore

2. 前端环境配置

cd web
npm install
npm run dev  # 启动前端开发服务器
# 前端将在 http://localhost:5173 上运行

3. 后端环境配置

cd server
npm install
cp .env.example .env  # 复制环境变量文件
# 编辑.env文件，设置数据库连接信息
npm run dev  # 启动API服务器
# 后端将在 http://localhost:3000 上运行

4. 数据库配置

# 在MySQL中创建数据库
mysql -u root -p
CREATE DATABASE versatile_bookstore;

5. 初始化数据库

cd server
npm run db:init

开发规范

代码规范

• 使用ESLint和Prettier保持代码风格一致
• 保持代码注释完整
• 遵循组件化开发原则

Git工作流

• 主分支：main
• 开发分支：dev
• 功能分支：feature/*
• 修复分支：hotfix/*

提交规范

• feat: 新功能
• fix: 修复bug
• docs: 文档更新
• style: 代码格式化
• refactor: 代码重构

贡献指南

如果您想为项目做出贡献，请遵循以下步骤：

1. Fork本仓库
2. 创建您的功能分支 (git checkout -b feature/amazing-feature)
3. 提交您的修改 (git commit -m 'feat: add amazing feature')
4. 推送到您的分支 (git push origin feature/amazing-feature)
5. 开启一个Pull Request

团队成员

• 项目负责人：OneSmallPig
• 前端开发：待添加
• 后端开发：待添加
• UI设计：待添加
• 测试：待添加

配置管理

本项目使用统一的配置管理方式，支持不同环境的灵活配置和部署：

前端配置

前端配置文件位于 web/src/js/config.js，自动根据环境适配不同配置。

相关环境变量文件：

• web/.env.development - 开发环境
• web/.env.production - 生产环境

后端配置

后端统一配置文件位于 server/src/config/config.js，会根据环境变量和环境名称自动加载对应配置。

相关环境变量文件：

• server/.env - 开发环境
• server/.env.production - 生产环境（用于Vercel部署）

部署指南

详细的部署指南请参阅项目根目录下的 DEPLOYMENT.md 文件，其中包含：

• 本地开发环境设置
• Vercel部署步骤
• 数据库配置说明
• 环境变量配置