内容
# BookVault
一款跨平台的个人图书库管理系统（BookVault），允许用户组织、分析和丰富他们的阅读体验。该平台支持移动端（Flutter）和网页端（Angular），并通过Node.js API提供可选的AI/MCP集成，以提供智能的图书洞察。
## 📌 概述
- 个人图书馆平台使用户能够：
- 创建和管理个人图书收藏
- 存储摘要、笔记和引用
- 分析小说，包含人物、套路和情节洞察
- 使用AI辅助智能搜索和探索图书
- 通过移动端和网页端无缝访问平台
该系统设计为单一代码库，以确保所有平台的一致性、可扩展性和可维护性。
## 🏗️ 架构概要
```
Flutter 移动应用 ─┐
├── REST / JSON APIs ── Node.js 后端 ── 数据库
Angular 网页应用 ─┘ │
└── AI / MCP 集成
```
- 前端（网页）：Angular（最新稳定版），Angular Material
- 前端（移动端）：Flutter
- 后端：Node.js + Express（TypeScript）
- AI 集成：基于MCP的AI（如Gemini MCP）
- 数据库：MongoDB（推荐）或PostgreSQL
- 部署：支持Docker（云平台无关）
📁 代码库结构
```
bookvault/
│
├── apps/
│ ├── mobile/ # Flutter 移动应用
│ ├── web/ # Angular 网页应用
│ └── backend/ # Node.js / Express API
│
├── packages/ # 共享合约/模型（未来准备）
│
├── docs/
│ ├── PRD-Mobile.md
│ ├── PRD-Web.md
│ ├── Architecture.md
│ ├── API-Spec.md
│ └── Roadmap.md
│
├── diagrams/ # 架构和工作流程图
│
├── scripts/ # 设置和自动化脚本
│
├── .github/
│ └── workflows/ # CI 流水线
│
├── README.md
├── .gitignore
└── LICENSE
```
## ✨ 主要功能
核心功能
- 个人图书库管理
- 图书元数据：标题、作者、类型、状态
- 笔记、高亮和引用
- 搜索和筛选
小说特定功能
- 故事摘要
- 人物列表和角色
- 情节和套路分析
- 主题洞察
AI驱动功能
- 提问图书
- 生成摘要和洞察
- 比较图书或作者
- 阅读推荐（未来）
## 🚀 快速入门
前提条件
| 工具 | 版本 |
| -- | -- |
| Node.js | ≥ 24（或最新） |
| npm / pnpm | 最新 |
| Angular CLI | 21（或最新） |
| Flutter SDK | 稳定版 |
| Docker | 最新 |
## 🔧 后端设置
```
cd apps/backend
npm install
cp .env.example .env
npm run dev
```
后端默认运行在：
```
http://localhost:3000
```
## 🌐 网页应用设置（Angular）
```
cd apps/web
npm install
ng serve
```
网页应用可在以下地址访问：
```
http://localhost:4200
```
## 📱 移动应用设置（Flutter）
```
cd apps/mobile
flutter pub get
flutter run
```
支持Android模拟器、iOS模拟器或物理设备。
## 🔐 环境变量
每个应用程序都使用自己的环境配置。
示例（apps/backend/.env.example）：
```
PORT=3000
DATABASE_URL=
AI_MCP_API_KEY=
JWT_SECRET=
```
重要：永远不要提交真实的`.env`文件。
🧪 测试（计划中/可选）
- 后端：Jest
- 网页：Angular TestBed
- 移动端：Flutter测试框架
## 🔄 分支策略
```
main → 生产就绪
develop → 活跃开发
feature/* → 新功能
bugfix/* → 修复
docs/* → 文档更新
```
提交遵循Conventional Commits：
```
feat(web): add book detail view
feat(mobile): implement offline storage
fix(api): handle empty AI response
docs(prd): update mobile scope
```
## 📄 文档
所有关键文档都存放在 `/docs` 中：
- PRD-Mobile.md – 移动产品需求
- PRD-Web.md – 网页产品需求
- Architecture.md – 系统设计
- API-Spec.md – REST API合约
- Roadmap.md – 功能规划
这些文档被视为真实来源。
## 🧩 路线图（高级别）
- ✅ MVP（图书馆、笔记、搜索）
- 🔄 AI集成（图书问答、摘要）
- 🔄 身份验证和同步
- 🔄 公开发布（v1.0）
- 🔄 社交和分享功能
## 📦 版本控制
项目遵循语义版本控制：
```
v0.1.0 MVP
v0.2.0 AI功能
v1.0.0 公开发布
```
## 🛡️ 许可证
该项目在MIT许可证下授权。
参见 [LICENSE](LICENSE) 文件了解详情。
👤 作者
Sachin Samad
