# Shared_blackboard

**Repository Path**: cuihongkang/shared_blackboard

## Basic Information

- **Project Name**: Shared_blackboard
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-16
- **Last Updated**: 2026-07-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 青松一对一互动课堂

面向 iPad、Apple Pencil 和桌面浏览器的一对一实时做题系统。老师创建课堂，学生用 6 位邀请码加入；双方在同一题目页书写，笔迹通过 WebSocket 近实时同步并在完成时持久化。

## 技术栈

- 前端：React、Vite、严格 TypeScript、Canvas Pointer Events、按需 `pdfjs-dist`。
- 服务端：Node.js、Express、`ws`、Zod、内置 SQLite、scrypt、HMAC JWT。
- 部署：单 Node 实例 + Nginx + Docker Compose，不依赖 Redis 或外部数据库。

目录：`apps/client` 为浏览器端，`apps/server` 为 API/实时服务，`packages/shared` 为共享协议与算法，`migrations` 为数据库迁移。

## 已实现

- 老师/学生注册登录和独立工作台。
- 老师创建课堂、邀请码/链接、唯一学生绑定、第三人拒绝。
- 空白、文本、图片和 PDF 题目页；老师可上传图片/PDF。
- Apple Pencil/手指 Pointer Events、归一化坐标、Retina 重绘、30ms 点批。
- 钢笔、荧光笔、整笔擦除、颜色、粗细、个人撤销/重做、老师清空。
- 双方指针、在线状态、学生写入锁、换页和结束课堂。
- 心跳、指数退避、离线队列和重连权威快照。
- 服务端鉴权、成员过滤、schema 校验、消息/频率/点数限制。

## 本地运行

需要 Node.js 24+。

```bash
npm install
cp .env.example .env
# 修改 .env：本地路径可改回 ./data/...，JWT_SECRET 至少 32 个随机字符
npm run dev
```

前端默认 `http://localhost:5173`，Vite 将 `/api` 和 `/ws` 代理到 `http://localhost:3000`。服务端启动时自动运行迁移。

常用命令：

```bash
npm run lint
npm run typecheck
npm test -- --run
npm run build
```

## 环境变量

- `NODE_ENV`：`development`、`test` 或 `production`。
- `HOST` / `PORT`：Node 监听地址和端口。
- `JWT_SECRET`：至少 32 字符，生产环境使用随机值并妥善保管。
- `DATABASE_PATH`：SQLite 文件路径。
- `UPLOAD_DIR`：图片/PDF 持久化目录。
- `UPLOAD_MAX_BYTES`：单文件上限，默认 20 MiB。
- `STATIC_DIR`：Vite 构建输出路径。

任何密钥、域名和数据库路径都不硬编码。题目文件只保存路径/URL到数据库，不存大字段。

## 数据库

`migrations/001_initial.sql` 创建：

- `users`：角色、显示名、邮箱和 scrypt 密码摘要。
- `classrooms`：老师/学生、邀请码、状态、当前页、写入锁和版本。
- `classroom_pages`：空白/文本/图片/PDF 页面与资源 URL。
- `whiteboard_strokes`：完整归一化笔迹及软删除标志。
- `whiteboard_operations`：创建、删除、撤销、清空、换页等审计事件。

SQLite 开启外键、WAL、`busy_timeout`。实时点只在内存中转发，`stroke_end` 才写数据库。

## 实时协议

协议详见 [docs/realtime-protocol.md](docs/realtime-protocol.md)。共享 Zod schema 位于 `packages/shared/src/protocol.ts`，前后端不分别维护消息格式。

## 生产部署

```bash
cp .env.example .env
# 设置安全 JWT_SECRET
docker compose up -d --build
docker compose ps
```

详细的阿里云、HTTPS、Nginx、备份和 2 核 2G 建议见 [docs/deployment.md](docs/deployment.md)。真实 iPad 验收见 [docs/ipad-test-checklist.md](docs/ipad-test-checklist.md)。

## 范围与风险

- 当前为单实例设计；不可直接横向运行多个 Node 副本。
- PDF 每个课堂页面显示所选 PDF 的第一页；若要把多页 PDF 自动拆页，后续可在上传流程增加客户端页数选择。
- 浏览器自动化不能替代真实 Apple Pencil、iPad 锁屏和 Safari 后台测试，必须执行人工清单。
- 未包含音视频；未来应在课堂 UI 外接第三方 RTC。
- 当前离线操作队列有界；极长时间离线且超过上限时会丢弃最早待发消息并显示后续服务端状态。

本项目没有 fork 或复制外部白板源码。实现仅参考了成熟开源产品的交互习惯，运行依赖均由 `package-lock.json` 锁定。