# PdocHub

**Repository Path**: thomascatlee/pdoc-hub

## Basic Information

- **Project Name**: PdocHub
- **Description**: 用CodeBuddy实现的资料收集和归纳系统
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-18
- **Last Updated**: 2025-09-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: Codebuddy, Python, Flask

## README

# 产品资料共享系统

这是一个功能完整的多媒体内容管理和共享平台，支持用户注册登录、多种格式文件上传、智能内容处理、全文搜索、社交互动等功能。系统采用Flask框架开发，具有完善的数据库迁移机制和生产环境部署支持。

## ✨ 核心功能

### 🔐 用户管理系统
- **用户注册与登录**：支持用户名/邮箱登录，密码安全加密存储
- **用户资料管理**：支持修改邮箱、密码等个人信息
- **权限控制**：基于角色的访问控制，支持普通用户和管理员角色
- **私信系统**：用户间私信交流，支持未读消息提醒

### 📁 多格式文件支持
- **文本内容**：直接输入文本内容，自动提取关键词和摘要
- **图片文件**：支持JPG、PNG、GIF、BMP、WebP格式，集成EasyOCR进行文字识别
- **Markdown文档**：自动渲染为HTML，支持代码高亮、表格、目录等扩展
- **PDF文档**：使用PyMuPDF提取文本内容、目录结构，支持在线预览和搜索
- **文本文件**：支持.txt格式，自动检测编码（UTF-8/GBK）
- **网页链接**：自动抓取网页内容，提取标题和正文

### 🔍 智能搜索引擎
- **全文搜索**：支持内容、标题、关键词、评论的全文检索
- **搜索结果分类**：区分内容搜索和评论搜索结果
- **搜索引擎风格界面**：类似Google的简洁搜索体验
- **PDF内文搜索**：支持在PDF文档内搜索特定文本并高亮显示

### 💬 社交互动功能
- **评论系统**：支持对内容进行评论和回复，支持嵌套回复，实时显示评论数量徽章
- **批注功能**：支持对文档内容进行精确定位的批注和回复，智能锚点定位技术
- **用户互动**：查看其他用户资料、发送私信，支持未读消息实时轮询提醒
- **内容管理**：用户可以内联编辑关键词（点击添加/删除）、删除自己的内容

### 🛠️ 高级功能
- **内容下载**：支持下载原始文件或导出为文本格式
- **关键词内联编辑**：点击关键词区域直接添加/删除，支持实时保存
- **文件预览系统**：上传前预览（图片、文本、PDF），支持多种格式
- **截图上传**：智能检测图片上传页面，支持Ctrl+V粘贴截图直接上传
- **PDF高级功能**：在线预览、全文搜索、页面跳转、搜索结果高亮
- **批注协作**：文本选区批注，支持上下文锚点、回复功能、智能定位
- **实时通知**：未读私信轮询、评论数量动态更新
- **数据库迁移**：完善的数据库版本控制和自动迁移机制
=======

## 🚀 快速开始

### 方法一：一键启动（推荐）

**Windows用户**：
```bash
# 双击运行或在命令行执行
start_conda.bat

# 支持的参数：
start_conda.bat -d        # 以守护进程方式运行
start_conda.bat -s        # 停止运行中的应用
start_conda.bat -r        # 重启应用
```

**Linux/Mac用户**：
```bash
# 添加执行权限并运行
chmod +x start_conda.sh
./start_conda.sh

# 支持的参数：
./start_conda.sh -d       # 以守护进程方式运行
./start_conda.sh -s       # 停止运行中的应用
./start_conda.sh -r       # 重启应用
```

### 方法二：手动环境配置

#### 使用Conda环境
```bash
# 1. 创建conda环境（自动安装Python 3.12和基础依赖）
conda env create -f environment.yml

# 2. 激活环境
conda activate multimedia_editor

# 3. 运行应用
python run.py
```

#### 使用现有环境
```bash
# 激活您的Python环境
conda activate web  # 或 source venv/bin/activate

# 安装依赖
pip install -r requirements.txt

# 运行应用
python run.py
```

### 方法三：最小化安装
```bash
# 核心依赖（必需）
pip install flask werkzeug requests beautifulsoup4 pillow

# 可选依赖（增强功能）
pip install jieba easyocr markdown python-dotenv gunicorn PyMuPDF
```

### 生产环境部署
```bash
# 以守护进程方式运行（推荐用于生产环境）
python run.py -d

# 停止应用
python run.py -s

# 重启应用
python run.py -r
```
=======

## 📖 使用指南

### 首次使用
1. **启动应用**：运行启动脚本或 `python run.py`
2. **访问系统**：打开浏览器访问 http://127.0.0.1:5000
3. **用户注册**：点击"注册"按钮创建账户
4. **登录系统**：使用用户名/邮箱和密码登录

### 内容上传
1. **点击"上传内容"**按钮进入上传页面
2. **选择内容类型**：
   - **文本**：直接输入文本内容
   - **图片**：支持拖拽上传或Ctrl+V粘贴截图
   - **文件**：上传Markdown、PDF、文本文件等
   - **网页链接**：输入URL自动抓取内容
3. **自动处理**：系统自动提取关键词、生成摘要
4. **查看结果**：显示处理结果和提取的信息

### 搜索功能
1. **关键词搜索**：在搜索框输入关键词，支持回车快速搜索
2. **分类结果**：系统分别显示内容匹配和评论匹配结果
3. **内容预览**：点击内容标题在模态框中查看详细信息
4. **PDF内搜索**：在PDF文档内搜索特定文本，支持结果高亮和页面跳转
5. **搜索统计**：显示搜索结果总数和分类统计

### 社交互动
1. **查看内容**：浏览其他用户分享的内容，实时显示评论数量
2. **发表评论**：对感兴趣的内容进行评论，支持多层级嵌套回复
3. **回复评论**：点击回复按钮进行针对性回复，支持@用户功能
4. **发送私信**：点击用户名查看资料并发送私信，支持主题和内容
5. **添加批注**：选中文档文本添加批注，支持精确定位和上下文保存
6. **批注协作**：查看他人批注、回复批注、删除自己的批注
7. **实时通知**：未读私信数量实时更新，支持标记已读功能

### 内容管理
1. **编辑关键词**：修改自己内容的关键词标签
2. **下载内容**：下载原始文件或导出文本
3. **删除内容**：删除自己上传的内容
4. **查看统计**：查看个人内容和评论统计

### 系统管理
- **数据库自动迁移**：系统启动时自动检查并更新数据库结构
- **日志记录**：详细的操作日志记录在 `logs/` 目录
- **进程管理**：支持守护进程运行，PID文件管理
=======

## 📁 项目结构

```
Productions_DB/
├── 🚀 启动文件
│   ├── app.py                          # Flask主应用，包含所有API路由
│   ├── run.py                          # 生产环境启动脚本，支持守护进程
│   ├── start_conda.bat                 # Windows一键启动脚本
│   └── start_conda.sh                  # Linux/Mac一键启动脚本
│
├── ⚙️ 配置文件
│   ├── config.py                       # 应用配置管理
│   ├── requirements.txt                # Python依赖包列表
│   ├── environment.yml                 # Conda环境配置
│   └── .devdbrc                        # 开发环境数据库配置
│
├── 🗄️ 数据库相关
│   ├── db_migration.py                 # 数据库迁移和版本控制核心
│   ├── migrate_db.py                   # 手动数据库迁移工具
│   ├── db_migration_annotation_replies.py  # 批注回复迁移
│   └── migrate_annotations_anchor.py   # 批注锚点迁移
│
├── 🔌 API模块
│   ├── annotation_replies_api.py       # 批注回复API蓝图
│   └── test_api.py                     # API测试脚本
│
├── 🎨 前端资源
│   ├── templates/
│   │   └── index.html                  # 单页面应用主模板
│   └── static/
│       ├── css/
│       │   ├── style.css               # 主样式文件
│       │   ├── comment_search.css      # 评论搜索样式
│       │   └── user_profile.css        # 用户资料样式
│       ├── js/
│       │   ├── script.js               # 主JavaScript逻辑
│       │   ├── annotations.js          # 批注功能脚本
│       │   └── search_comments.js      # 评论搜索脚本
│       └── uploads/                    # 用户上传文件存储目录
│
├── 📊 数据存储
│   ├── data/
│   │   └── content.db                  # SQLite数据库（自动创建）
│   └── logs/                           # 应用日志目录
│       ├── app.log                     # 应用运行日志
│       ├── daemon.log                  # 守护进程日志
│       └── app.pid                     # 进程ID文件
│
└── 📚 文档
    ├── README.md                       # 项目说明文档
    ├── README_DB_MIGRATION.md          # 数据库迁移文档
    └── LICENSE                         # 开源许可证
```

## 🛠️ 技术栈

### 后端技术
- **Web框架**：Flask 2.3.3 - 轻量级Python Web框架
- **WSGI服务器**：Gunicorn 21.2.0 - 生产环境WSGI服务器
- **数据库**：SQLite - 轻量级关系型数据库，支持自动迁移
- **安全认证**：Werkzeug 2.3.7 - 密码哈希和安全工具

### 数据处理
- **中文分词**：jieba 0.42.1 - 中文文本分词和关键词提取
- **OCR识别**：EasyOCR 1.7.0 - 图像文字识别，支持中英文
- **网页解析**：BeautifulSoup4 4.12.2 - HTML/XML解析和内容提取
- **PDF处理**：PyMuPDF 1.23.7 - PDF文档解析、文本提取和预览
- **Markdown渲染**：markdown 3.5 - Markdown到HTML转换
- **图像处理**：Pillow 10.0.0 - 图像文件处理和格式转换

### 前端技术
- **UI框架**：Bootstrap 5.2.3 - 响应式UI组件库和模态框系统
- **图标库**：Bootstrap Icons 1.10.0 - 矢量图标集
- **JavaScript**：原生ES6+ - 现代JavaScript特性，无框架依赖
- **交互特性**：文本选区处理、拖拽上传、粘贴截图、实时搜索
- **样式预处理**：CSS3 - 现代CSS特性、动画效果和响应式布局
- **模块化设计**：分离的JS模块（主逻辑、批注系统、搜索功能）

### 开发工具
- **环境管理**：Conda/pip - Python包和环境管理
- **版本控制**：Git - 代码版本控制
- **配置管理**：python-dotenv 1.0.0 - 环境变量管理
- **进程管理**：自定义守护进程实现 - 支持后台运行

### 数据库设计
- **用户表**：用户认证和权限管理
- **内容表**：多媒体内容存储和索引
- **评论表**：支持嵌套回复的评论系统
- **私信表**：用户间私信通信
- **批注表**：文档批注和协作功能
- **版本控制表**：数据库结构版本管理

## 🌟 功能亮点

### 智能内容处理
- **自动关键词提取**：基于jieba分词的中文关键词智能提取
- **多格式支持**：统一处理文本、图片、PDF、Markdown等多种格式
- **OCR文字识别**：自动识别图片中的中英文文字内容
- **网页内容抓取**：智能提取网页标题和正文内容

### 高级搜索功能
- **全文检索**：支持内容、标题、关键词的全文搜索
- **PDF内搜索**：在PDF文档内精确搜索并高亮显示
- **搜索结果分类**：区分内容搜索和评论搜索结果
- **实时搜索建议**：输入时提供搜索建议

### 协作与社交
- **精确批注**：基于文本选区的智能批注系统，支持上下文锚点和字符偏移量定位
- **批注回复**：支持对批注进行回复讨论，形成完整的协作对话
- **嵌套评论**：多层级评论和回复系统，支持树状结构显示
- **私信系统**：用户间私密通信，支持未读提醒和实时轮询更新
- **用户资料**：完整的用户信息管理，支持在线修改邮箱和密码
- **权限控制**：内容所有者可删除自己的内容和批注

### 系统特性
- **数据库自动迁移**：版本升级时自动更新数据库结构
- **守护进程支持**：支持后台运行，适合生产环境
- **完整日志系统**：详细的操作和错误日志记录
- **安全性保障**：密码加密存储，XSS防护，SQL注入防护

## 🚀 部署说明

### 开发环境
```bash
# 克隆项目
git clone <repository-url>
cd Productions_DB

# 使用一键启动脚本
./start_conda.sh  # Linux/Mac
# 或
start_conda.bat   # Windows
```

### 生产环境
```bash
# 1. 安装依赖
pip install -r requirements.txt

# 2. 配置环境变量（可选）
export SECRET_KEY="your-secret-key"
export DATABASE="data/production.db"
export HOST="0.0.0.0"
export PORT="5000"

# 3. 以守护进程方式启动
python run.py -d

# 4. 检查运行状态
ps aux | grep python
cat logs/app.pid
```

### Docker部署（推荐）
```dockerfile
# Dockerfile示例
FROM python:3.12-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY . .
EXPOSE 5000

CMD ["python", "run.py"]
```

### Nginx反向代理配置
```nginx
server {
    listen 80;
    server_name your-domain.com;
    
    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
    
    location /static {
        alias /path/to/Productions_DB/static;
        expires 30d;
    }
}
```

## 🔧 配置说明

### 环境变量
| 变量名 | 默认值 | 说明 |
|--------|--------|------|
| `SECRET_KEY` | `dev-secret-change-me` | Flask密钥，生产环境必须修改 |
| `DATABASE` | `data/content.db` | 数据库文件路径 |
| `UPLOAD_FOLDER` | `static/uploads` | 文件上传目录 |
| `MAX_CONTENT_LENGTH` | `16777216` | 最大上传文件大小（16MB） |
| `DEBUG` | `true` | 调试模式开关 |
| `HOST` | `0.0.0.0` | 监听地址 |
| `PORT` | `5000` | 监听端口 |

### 可选依赖说明
- **jieba**：中文分词和关键词提取，未安装时使用基础算法
- **easyocr**：图片OCR识别，未安装时无法识别图片文字
- **markdown**：Markdown渲染，未安装时显示原始文本
- **PyMuPDF**：PDF处理，未安装时无法处理PDF文件
- **gunicorn**：生产环境WSGI服务器，未安装时使用Flask内置服务器

## 🐛 故障排除

### 常见问题

**1. 数据库初始化失败**
```bash
# 删除数据库文件重新初始化
rm data/content.db
python run.py
```

**2. 端口被占用**
```bash
# 查看端口占用
netstat -tulpn | grep :5000
# 或修改端口
export PORT=8080
python run.py
```

**3. 依赖安装失败**
```bash
# 升级pip
pip install --upgrade pip
# 使用国内镜像
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/
```

**4. OCR功能不可用**
```bash
# 安装EasyOCR
pip install easyocr
# 如果安装失败，可以跳过OCR功能
```

**5. 守护进程启动失败**
```bash
# 检查日志
cat logs/daemon_error.log
# 手动启动
python run.py
```

### 日志文件说明
- `logs/app.log`：应用运行日志
- `logs/daemon.log`：守护进程日志
- `logs/daemon_error.log`：守护进程错误日志
- `logs/access.log`：访问日志（使用gunicorn时）
- `logs/error.log`：错误日志（使用gunicorn时）

## 📄 许可证

本项目采用开源许可证，详见 [LICENSE](LICENSE) 文件。

## 🤝 贡献指南

欢迎提交Issue和Pull Request来改进项目！

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

## 📞 技术支持

如果您在使用过程中遇到问题，可以：

1. 查看本文档的故障排除部分
2. 检查 `logs/` 目录下的日志文件
3. 在Gitee上提交Issue
4. 查看 [数据库迁移文档](README_DB_MIGRATION.md) 了解数据库相关问题

---

**开发团队** | **最后更新**: 2025年9月
=======
=======