网页PPT后端系统需求文档

项目概述

本项目为网页PPT前端系统配套的后端服务，主要功能包括用户认证、PPT数据管理、分享功能、历史记录管理等。系统设计为部署在Hugging Face Space上，使用Docker容器化部署。

技术架构

部署环境

平台: Hugging Face Space
容器化: Docker
运行时: Node.js 18 Alpine
端口: 7860

技术栈

后端框架: Express.js + TypeScript
数据存储:
- 临时数据库：内存存储（最大12GB）
- 永久数据库：GitHub仓库
图片处理: Sharp
定时任务: node-cron
安全: Helmet, bcryptjs, express-rate-limit

功能需求

1. 用户认证系统

1.1 内置账户

系统不支持公开注册，仅提供4个预配置账户：

用户名	密码	角色
PS01	admin_cybercity2025	admin
PS02	cybercity2025	user
PS03	cybercity2025	user
PS04	cybercity2025	user

1.2 认证功能

JWT token认证
登录失败锁定机制（5次失败锁定30分钟）
密码加密存储（bcrypt）
会话管理

2. 数据存储架构

2.1 临时数据库（内存）

存储介质: Hugging Face Space内存
容量限制: 最大12GB
数据类型:
- 用户信息
- PPT编辑数据
- 导出的PPT页面截图
- 分享链接数据
自动保存: 每10分钟自动保存修改的数据

2.2 永久数据库（GitHub）

存储介质: GitHub仓库
同步策略: 每天03:00自动同步修改的数据
配置方式: Space环境变量
- GITHUB_TOKEN: GitHub访问令牌
- GITHUB_REPO: 仓库地址（格式：owner/repo）
数据恢复: Space重启时自动从GitHub同步数据

2.3 数据同步规则

增量同步: 仅同步修改的数据，未修改数据不同步
容量控制: 同步数据量超过7GB时，仅同步最近的数据
按需加载: 用户访问早期数据时，临时从GitHub拉取

3. PPT分享功能

3.1 分享机制

在前端PPT页面缩略图上添加分享按钮
点击按钮调用前端导出图片功能
导出JPEG格式截图
保存到内存临时数据库
生成永久唯一公网链接

3.2 链接管理

链接是长期有效并且唯一的
链接格式：/api/sharelink/{PPT的slideID}
外网可通过链接直接访问图片
如果ppt修改，保存后将自动更新图片并按同样的流程上传内存数据库替换旧图片，外界通过这个链接读取更新的图片
访问日志记录

3.3 自动更新

PPT页面修改后，用户保存数据时自动重新生成截图
覆盖内存中的原截图
公网链接保持不变
外网访问获得更新后的页面

4. 历史PPT管理

4.1 管理界面

前端页面顶部添加历史PPT管理按钮
弹出历史PPT管理界面
支持分页显示（默认20条/页）
支持搜索和筛选功能

4.2 数据加载策略

优先从内存数据库读取
内存中不存在需要的数据再从GitHub仓库拉取，这部分数据编辑后保存自动同步回内存数据库
支持按需加载早期数据
提供加载状态指示

4.3 管理功能

查看PPT列表
打开历史PPT
复制PPT
删除PPT
导出PPT

5. API接口设计

5.1 认证接口

POST /api/auth/login          # 用户登录
GET  /api/auth/verify         # 验证token
POST /api/auth/logout         # 用户登出
GET  /api/auth/me             # 获取用户信息

5.2 PPT管理接口

POST /api/ppt/save            # 保存PPT
PUT  /api/ppt/:id             # 更新PPT
GET  /api/ppt/:id             # 获取PPT详情
DELETE /api/ppt/:id           # 删除PPT
GET  /api/ppt                 # 获取PPT列表
POST /api/ppt/:id/copy        # 复制PPT

5.3 分享接口

POST /api/share/slide         # 分享幻灯片
GET  /api/share/view/:shareId # 查看分享截图
GET  /api/share/info/:shareId # 获取分享信息
GET  /api/share/my-shares     # 获取我的分享
DELETE /api/share/:shareId    # 删除分享

5.4 历史管理接口

GET  /api/history/ppts        # 获取历史PPT列表
GET  /api/history/ppts/:id/from-github # 从GitHub获取PPT
POST /api/history/search      # 搜索历史PPT
GET  /api/history/stats       # 获取统计信息

6. 安全要求

6.1 认证安全

JWT token过期时间：24小时
密码加密：bcrypt（12轮）
登录失败锁定：5次失败锁定30分钟

6.2 API安全

请求频率限制：100请求/15分钟
CORS配置
Helmet安全头
输入验证和清理

6.3 数据安全

用户数据隔离
敏感信息不记录日志
GitHub token安全存储

7. 性能要求

7.1 响应时间

API响应时间 < 500ms
图片加载时间 < 2s
PPT列表加载 < 1s

7.2 并发处理

支持同时100个用户在线
数据库操作异步处理
图片压缩优化

7.3 内存管理

内存使用监控
自动清理过期数据
数据压缩存储

8. 监控和日志

8.1 日志记录

用户操作日志
系统错误日志
性能监控日志
GitHub同步日志

8.2 健康检查

服务健康状态检查
数据库连接状态
GitHub连接状态
内存使用情况

9. 部署配置

9.1 环境变量

# 基础配置
PORT=5000
NODE_ENV=production

# GitHub配置
GITHUB_TOKEN=your-github-token
GITHUB_REPO=owner/repo-name
GITHUB_BRANCH=main

# 可选配置
MAX_MEMORY_GB=7
AUTO_SAVE_INTERVAL=10
SYNC_HOUR=0

9.2 Docker配置

基础镜像：node:18-alpine
工作目录：/app
数据目录：/app/data
健康检查：GET /health

10. 维护和扩展

10.1 数据备份

自动GitHub同步
手动备份功能
数据恢复机制

10.2 系统维护

日志轮转
内存清理
性能优化

10.3 功能扩展

支持更多用户
增加协作功能
优化存储策略

项目结构

backend/
├── src/
│   ├── config/           # 配置文件
│   ├── middleware/       # 中间件
│   ├── routes/          # 路由
│   ├── services/        # 服务层
│   ├── types/           # 类型定义
│   ├── utils/           # 工具函数
│   └── index.ts         # 入口文件
├── data/                # 数据目录
├── Dockerfile           # Docker配置
├── package.json         # 依赖配置
├── tsconfig.json        # TypeScript配置
└── requirements.md      # 需求文档

开发和测试

开发环境

npm install
npm run dev

生产构建

npm run build
npm start

测试

npm test

总结

本后端系统为网页PPT应用提供完整的数据管理、用户认证、分享功能和历史记录管理。通过内存+GitHub的双重存储策略，确保数据的可靠性和访问性能。系统设计考虑了Hugging Face Space的特点和限制，提供了完整的解决方案。