# Web Content Recorder

**Repository Path**: cquptgame/web-content-recorder

## Basic Information

- **Project Name**: Web Content Recorder
- **Description**: 一个统一的Web内容收集和管理系统，帮助用户快速记录、组织和管理浏览网页时遇到的各种信息。支持离线使用，确保在任何网络环境下都能可靠工作。一个统一的Web内容收集和管理系统，帮助用户快速记录、组织和管理浏览网页时遇到的各种信息。支持离线使用，确保在任何网络环境下都能可靠工作。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-02
- **Last Updated**: 2025-11-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Web Content Recorder (快速记录项目)

一个统一的Web内容收集和管理系统，帮助用户快速记录、组织和管理浏览网页时遇到的各种信息。支持离线使用，确保在任何网络环境下都能可靠工作。

## 🚀 功能特性

### 📱 核心功能
- **快速记录**: 浏览器扩展支持一键记录网页内容和链接，自动获取页面URL和标题
- **统一管理**: Web管理界面提供完整的记录管理功能，支持批量选择和操作
- **智能组织**: 基于标签的分类和强大的搜索功能，支持按域名和URL过滤
- **来源追踪**: 自动记录内容来源网址，方便追溯和管理

### 🌐 离线功能 (v1.1.0 新增)
- **离线记录存储**: 网络不可用时自动保存记录到本地存储
- **智能同步状态**: 清晰标识记录的同步状态（待同步、同步失败、重试中）
- **离线内容查看**: 专用界面查看和管理所有未同步记录
- **连接状态监控**: 实时检测与服务器的连接状态
- **自动同步**: 网络恢复时自动同步所有离线记录

### 📧 邮件功能
- **定时邮件**: 支持每日/每周/每月定时发送记录摘要
- **主动邮件**: 手动选择记录立即发送邮件
- **QQ邮箱集成**: 完整的QQ SMTP邮件服务支持

### 📊 数据管理
- **增强导出系统**: 支持JSON、CSV、Markdown、Word文档、Excel表格和PDF等多种导出格式
- **智能标签管理**: 完整的标签系统，支持标签创建、编辑、批量操作和统计分析
- **导出进度管理**: 实时导出进度跟踪，支持暂停、恢复和取消操作
- **预设和模板**: 保存导出配置预设，支持自定义导出模板
- **数据安全**: 本地部署，数据完全由用户控制，支持AES加密存储
- **备份恢复**: 自动数据备份和完整的恢复机制

## 🏗️ 系统架构

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   浏览器扩展    │    │   Web管理界面   │    │   后端API服务   │
│  (Chrome/Edge)  │◄──►│   (React.js)    │◄──►│  (Node.js/Express) │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                                       │
                                              ┌─────────────────┐
                                              │   SQLite数据库  │
                                              └─────────────────┘
                                                       │
                                              ┌─────────────────┐
                                              │   邮件服务      │
                                              │  (QQ SMTP)      │
                                              └─────────────────┘
```

## 📦 快速开始

### 使用Docker (推荐)

1. **克隆项目**
   ```bash
   git clone <repository-url>
   cd web-content-recorder
   ```

2. **启动服务**
   ```bash
   # 使用Docker Compose启动所有服务
   npm run start
   
   # 或者手动启动
   docker-compose up -d
   ```

3. **访问应用**
   - 管理界面: http://localhost
   - API服务: http://localhost:8000
   - 浏览器扩展: 加载 `extension/dist` 目录

### 手动部署

1. **安装依赖**
   ```bash
   npm run install:all
   ```

2. **配置环境**
   ```bash
   # 创建环境配置文件
   npm run env:create
   
   # 编辑 .env 文件，配置数据库路径、JWT密钥等
   ```

3. **构建应用**
   ```bash
   npm run build
   ```

4. **启动服务**
   ```bash
   # 启动后端服务
   cd backend && npm start
   
   # 启动前端服务 (开发模式)
   cd frontend && npm run dev
   ```

## 🔧 开发环境

### 环境要求

- **Node.js**: 20.0+ (推荐 LTS 版本)
- **包管理器**: npm 9+ 或 yarn 1.22+
- **Docker**: 20.10+ (可选，推荐用于生产部署)
- **浏览器**: Chrome 88+ 或 Microsoft Edge 88+ (用于扩展)
- **操作系统**: Windows 10+, macOS 10.15+, Ubuntu 18.04+

### 开发模式启动

```bash
# 安装所有依赖
npm run install:all

# 启动开发环境
npm run dev

# 或使用Docker开发环境
npm run dev:docker
```

### 构建扩展

```bash
cd extension
npm run build

# 在Chrome中加载扩展
# 1. 打开 chrome://extensions/
# 2. 启用"开发者模式"
# 3. 点击"加载已解压的扩展程序"
# 4. 选择 extension/dist 目录
```

## 🧪 测试

### 测试覆盖范围
- **单元测试**: 核心业务逻辑和工具函数
- **集成测试**: API接口和数据库操作
- **E2E测试**: 完整用户工作流程
- **扩展测试**: 浏览器扩展功能测试

### 运行所有测试

```bash
# 完整测试套件 (单元 + 集成 + E2E)
npm run test:all
```

### 分别运行测试

```bash
# 单元测试 (所有组件)
npm test

# 后端单元测试
npm run test:backend

# 前端单元测试  
npm run test:frontend

# 扩展单元测试
npm run test:extension

# 集成测试
npm run test:integration

# 工作流测试
npm run test:workflow

# E2E测试 (无头模式)
npm run e2e:test

# E2E测试 (可视化模式)
npm run e2e:test:headed

# E2E测试 (交互式UI)
npm run e2e:test:ui
```

### 测试报告

```bash
# 生成E2E测试报告
npm run e2e:report

# 查看测试覆盖率
npm run test:coverage
```

## 📋 使用说明

### 1. 初始设置

1. 访问管理界面 http://localhost:3000
2. 设置初始密码
3. 配置邮件设置 (可选)
4. 安装浏览器扩展

### 2. 记录内容

**使用浏览器扩展:**
- 选择网页文本后点击快速记录按钮，系统会自动获取当前页面URL和标题
- 右键点击链接选择"记录链接"
- 使用扩展弹窗添加详细信息和标签
- **离线模式**: 网络不可用时自动保存到本地存储
- **智能同步**: 网络恢复时自动同步所有离线记录

**使用管理界面:**
- 在记录列表页面点击"新建记录"
- 填写内容、URL、标签等信息
- 保存记录

**离线内容管理:**
- 点击扩展图标，切换到"离线内容"标签页
- 查看所有未同步的离线记录
- 手动同步单个或批量记录
- 在离线状态下编辑记录标签和备注

### 3. 管理记录

- **查看**: 在记录列表中浏览所有记录，包含来源网址信息
- **搜索**: 使用搜索框查找特定内容，支持全文搜索
- **筛选**: 点击标签进行筛选，支持按域名和URL模式过滤
- **批量选择**: 使用复选框选择多条记录进行批量操作
- **编辑**: 点击编辑按钮修改记录
- **删除**: 点击删除按钮移除记录
- **来源跳转**: 点击记录的来源网址可直接跳转到原始页面

### 4. 标签管理

**创建和管理标签:**
1. 进入标签管理页面
2. 点击"新建标签"创建标签
3. 设置标签名称、颜色和描述
4. 使用搜索和筛选功能管理标签
5. 查看标签使用统计和分析

**批量标签操作:**
- 选择多个标签进行批量删除
- 合并重复或相似的标签
- 批量更新标签属性
- 导入导出标签配置

**标签统计分析:**
- 查看标签使用趋势和热门标签
- 识别未使用的标签
- 导出标签统计报告

### 5. 增强数据导出

**基础导出:**
1. 进入增强导出页面
2. 选择导出格式：
   - **JSON**: 结构化数据格式，适合程序处理和数据迁移
   - **CSV**: 表格格式，适合Excel等工具打开和数据分析
   - **Markdown**: 文档格式，适合阅读、编辑和版本控制
   - **Word文档**: 专业文档格式，支持目录、格式化和打印
   - **Excel表格**: 电子表格格式，支持多工作表、图表和数据透视
   - **PDF文档**: 便携文档格式，适合分享、打印和归档
3. 配置筛选条件（时间范围、标签筛选等）
4. 设置导出选项（包含元数据、按标签分组、内容筛选等）
5. 预览导出内容和统计信息
6. 开始导出并监控进度

**高级功能:**
- **导出预设**: 保存常用的导出配置，快速应用
- **批量导出**: 同时导出多种格式或按不同条件分别导出
- **导出进度管理**: 实时查看导出进度，支持暂停、恢复和取消
- **导出历史**: 查看历史导出记录，重新下载已完成的导出文件
- **自定义模板**: 为Markdown、Word和PDF格式自定义导出模板

**导出进度管理:**
1. 点击"导出进度"按钮查看所有导出任务
2. 监控实时导出进度和状态
3. 管理导出队列，支持暂停、恢复、取消操作
4. 下载完成的导出文件
5. 查看导出任务详情和错误信息

### 6. 邮件功能

**定时邮件配置:**
1. 进入系统设置页面
2. 配置QQ邮箱地址和SMTP设置
3. 选择发送频率 (每日/每周/每月)
4. 测试邮件配置
5. 启用自动发送

**主动邮件发送:**
1. 在记录列表页面选择要发送的记录
2. 点击"发送邮件"按钮
3. 配置邮件选项（主题、是否包含URL等）
4. 预览邮件内容
5. 确认发送

## ⚙️ 配置说明

### 环境变量配置

```bash
# 应用环境
NODE_ENV=production

# 服务端口
PORT=8000

# 数据库配置
DATABASE_PATH=./data/database.sqlite
DATABASE_BACKUP_PATH=./data/backups

# 安全配置
JWT_SECRET=your-jwt-secret-key-32-chars-min
ENCRYPTION_KEY=your-32-char-encryption-key
SESSION_TIMEOUT=24h

# QQ邮箱SMTP配置
SMTP_HOST=smtp.qq.com
SMTP_PORT=465
SMTP_SECURE=true
SMTP_USER=your-qq-email@qq.com
SMTP_PASS=your-qq-email-auth-code

# 应用配置
MAX_RECORDS_PER_PAGE=50
MAX_EXPORT_RECORDS=10000
OFFLINE_SYNC_INTERVAL=30000
CONNECTION_TIMEOUT=5000

# 日志配置
LOG_LEVEL=info
LOG_FILE_PATH=./logs/app.log
LOG_MAX_SIZE=10MB
LOG_MAX_FILES=5
```

### 快速配置

```bash
# 创建默认配置文件
npm run env:create

# 验证配置文件
npm run env:validate

# 查看配置信息
npm run env:info
```

### Docker配置

```yaml
# docker-compose.yml - 生产环境
version: '3.8'
services:
  app:
    build: .
    ports:
      - "80:80"
      - "8000:8000"
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs
    environment:
      - NODE_ENV=production

# docker-compose.dev.yml - 开发环境  
version: '3.8'
services:
  app:
    build:
      dockerfile: Dockerfile.dev
    ports:
      - "3000:3000"
      - "8000:8000"
    volumes:
      - .:/app
      - /app/node_modules
```

### Docker 命令

```bash
# 构建生产镜像
npm run docker:build

# 构建开发镜像
npm run docker:build:dev

# 多平台构建
npm run docker:build:multi

# 镜像优化
npm run docker:optimize

# 安全扫描
npm run docker:scan

# 清理镜像
npm run docker:clean
```

## 🔒 安全说明

- 所有用户数据使用AES加密存储
- JWT令牌用于API身份验证
- 支持密码保护和会话管理
- 定期自动备份数据
- 支持完全删除用户数据

## 📊 监控和日志

### 健康检查

- `/api/health` - 基本健康检查
- `/api/health/ready` - 就绪检查
- `/api/health/live` - 存活检查
- `/api/health/detailed` - 详细系统信息

### 日志管理

- 开发环境: 控制台输出
- 生产环境: 文件日志 (`logs/app.log`)
- 错误追踪和性能监控
- 安全事件记录

## 🚀 部署选项

### 1. 本地部署

适合个人使用，数据完全本地存储：

```bash
npm run build
npm run start
```

### 2. 云服务器部署

适合远程访问和多设备同步：

```bash
# 使用Docker部署
docker-compose up -d

# 配置反向代理 (Nginx)
# 设置SSL证书
# 配置域名解析
```

### 3. 容器化部署

支持Kubernetes、Docker Swarm等：

```bash
# 构建镜像
npm run docker:build

# 推送到镜像仓库
docker tag web-content-recorder your-registry/web-content-recorder
docker push your-registry/web-content-recorder
```

## 🛠️ 开发指南

### 项目结构

```
web-content-recorder/
├── backend/          # Node.js API服务
├── frontend/         # React管理界面
├── extension/        # Chrome浏览器扩展
├── shared/           # 共享类型定义
├── e2e/             # 端到端测试
├── config/          # 配置文件
├── scripts/         # 构建和部署脚本
└── docs/            # 文档
```

### 技术栈

- **后端**: Node.js 20+ + Express.js + TypeScript + SQLite
- **前端**: React 18 + TypeScript + Ant Design 5 + Vite 6
- **扩展**: Chrome Manifest V3 + TypeScript + Webpack 5
- **测试**: Jest 29 + Vitest 2 + Playwright
- **部署**: Docker + Docker Compose + Nginx
- **邮件**: Nodemailer + QQ SMTP
- **安全**: JWT + bcrypt + AES加密

### 贡献指南

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

## 📝 更新日志

### v1.2.0 (当前版本) - 增强导出和标签管理重大更新

#### 🎉 新增功能
- ✅ **增强导出系统**: 支持PDF导出，新增Word和Excel高级功能
- ✅ **智能标签管理**: 完整的标签CRUD、批量操作和统计分析
- ✅ **导出进度管理**: 实时进度跟踪、任务队列和状态管理
- ✅ **导出预设系统**: 保存和管理导出配置，快速应用常用设置
- ✅ **批量导出功能**: 同时导出多种格式，按条件分别导出
- ✅ **标签统计分析**: 使用趋势、热门标签、未使用标签识别
- ✅ **记录标签集成**: 增强的记录列表和编辑界面标签功能

#### 🔧 技术改进
- ✅ **导出架构重构**: 模块化导出器设计，支持插件扩展
- ✅ **标签数据模型**: 完整的标签关联和统计计算
- ✅ **性能优化**: 大数据量导出优化，内存使用控制
- ✅ **用户体验**: 拖拽排序、自动完成、智能推荐
- ✅ **错误处理**: 完善的错误处理和用户反馈机制

### v1.1.0 - 离线功能重大更新

#### 🎉 新增功能
- ✅ **离线内容查看器**: 专用界面管理离线记录
- ✅ **智能同步机制**: 自动检测连接状态并同步离线数据
- ✅ **连接状态监控**: 实时显示网络连接状态
- ✅ **离线记录管理**: 支持离线状态下的记录编辑和删除
- ✅ **冲突处理机制**: 智能处理同步过程中的数据冲突

#### 🔧 技术改进
- ✅ **权限优化**: 新增 `alarms` 和 `offscreen` 权限支持
- ✅ **性能优化**: 内存缓存、搜索索引、虚拟滚动
- ✅ **安全增强**: 本地数据加密存储和数据校验
- ✅ **用户体验**: 响应式设计、键盘支持、无障碍访问

#### 📱 核心功能
- ✅ 完整的记录管理功能
- ✅ 浏览器扩展支持，自动获取页面URL和标题
- ✅ 邮件定时发送和主动发送功能
- ✅ 多格式数据导出（JSON、CSV、Markdown、Word、Excel）
- ✅ 来源网址自动记录和追踪
- ✅ 批量选择和操作功能
- ✅ 用户认证和安全
- ✅ Docker部署支持
- ✅ 数据库迁移系统
- ✅ 完整的测试覆盖

## 📚 文档

### 用户指南
- [API 文档](docs/API_DOCUMENTATION.md) - 完整的API接口说明
- [新功能指南](docs/NEW_FEATURES_GUIDE.md) - v1.1.0 离线功能使用说明
- [数据库迁移指南](docs/DATABASE_MIGRATION_GUIDE.md) - 数据库升级和迁移
- [扩展发布说明](extension/RELEASE_NOTES_v1.1.0.md) - v1.1.0 详细功能说明

### 开发者指南
- [弃用警告控制指南](docs/DEPRECATION_WARNINGS_GUIDE.md) - Node.js 警告控制和故障排除
- [构建和部署](README.md#快速开始) - 项目构建和部署说明
- [扩展开发指南](extension/src/services/README.md) - 浏览器扩展开发文档
- [离线功能架构](extension/src/services/CONNECTION_SERVICE_README.md) - 连接服务和离线功能

### 技术文档
- [自动同步服务](extension/src/services/AUTO_SYNC_README.md) - 自动同步机制说明
- [错误处理系统](extension/src/services/ERROR_HANDLING_README.md) - 错误处理和用户反馈
- [性能优化报告](performance-report.md) - 系统性能分析和优化建议


## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## �  版本兼容性

### 浏览器支持
- **Chrome 88+**: 完整功能支持，包括离线功能
- **Microsoft Edge 88+**: 完整功能支持
- **其他Chromium内核**: 基本功能支持
- **Firefox**: 由于Manifest V3支持限制，不推荐使用

### 升级说明
- **从 v1.0.x 升级**: 自动升级，保留所有数据和设置
- **数据迁移**: 自动处理，无需手动操作
- **配置兼容**: 向后兼容，新功能默认启用

## 🤝 贡献指南

### 开发流程
1. Fork 项目到你的 GitHub 账户
2. 创建功能分支: `git checkout -b feature/amazing-feature`
3. 安装依赖: `npm run install:all`
4. 开发和测试: `npm run dev` 和 `npm test`
5. 提交更改: `git commit -m 'Add amazing feature'`
6. 推送分支: `git push origin feature/amazing-feature`
7. 创建 Pull Request

### 代码规范
- 使用 TypeScript 进行类型安全开发
- 遵循 ESLint 和 Prettier 代码格式规范
- 编写单元测试覆盖新功能
- 更新相关文档

### 问题反馈
- 🐛 [报告 Bug](https://github.com/your-repo/issues/new?template=bug_report.md)
- 💡 [功能建议](https://github.com/your-repo/issues/new?template=feature_request.md)
- 📖 [文档改进](https://github.com/your-repo/issues/new?template=documentation.md)

## 🙏 致谢

感谢所有为这个项目做出贡献的开发者和用户！特别感谢：

- 所有提供功能建议和Bug反馈的用户
- 参与代码审查和测试的贡献者
- 开源社区提供的优秀工具和库

## 📄 许可证

本项目采用 [MIT 许可证](LICENSE) - 查看 LICENSE 文件了解详情。

---

**Web Content Recorder v1.1.0** - 让网页内容收集变得简单高效，支持离线使用 🚀

*最后更新: 2024年11月*