- 框架: React 18.2.0
- 路由: React Router Dom 6.14.2
- 构建工具: Vite 4.3.9
- UI样式: Tailwind CSS 3.3.3
- 视频播放: hls.js 1.5.7
- 图标库: lucide-react 0.263.1
- 开发语言: JavaScript + JSX

- 运行环境: Node.js v22
- Web框架: Fastify 4.26.1
- 数据库: SQLite 3 (sqlite3 5.1.7)
- 身份认证: JWT (jsonwebtoken 9.0.2)
- 密码加密: bcryptjs 2.4.3
- 视频转码: fluent-ffmpeg 2.1.3
- 文件上传: @fastify/multipart 7.7.3
- 静态文件: @fastify/static 6.12.0
- 文件系统: fs-extra 11.2.0
- MIME类型: mime-types 2.1.35

lite.class_1.0.6/
├── app/                      # 应用主目录
│   ├── server/              # 后端服务
│   │   ├── index.js         # 服务器入口文件 (2264行)
│   │   ├── transcoder.js    # 视频转码模块 (905行)
│   │   ├── package.json     # 后端依赖配置
│   │   ├── public/          # 静态资源目录
│   │   │   └── uploads/     # 上传文件存储
│   │   └── liteclass.db     # SQLite数据库
│   ├── frontend/            # 前端应用
│   │   ├── src/
│   │   │   ├── api/         # API封装
│   │   │   ├── components/  # React组件
│   │   │   ├── hooks/       # 自定义Hook
│   │   │   ├── utils/       # 工具函数
│   │   │   ├── App.jsx      # 应用入口
│   │   │   └── main.jsx     # 渲染入口
│   │   ├── index.html       # HTML模板
│   │   └── package.json     # 前端依赖配置
│   ├── ui/                  # UI界面资源
│   └── config/              # 应用配置
├── cmd/                     # 命令脚本目录
│   ├── main                 # 主控脚本（启动/停止/状态）
│   ├── install_callback     # 安装回调
│   ├── install_init         # 安装初始化
│   ├── uninstall_callback   # 卸载回调
│   ├── uninstall_init       # 卸载初始化
│   ├── upgrade_callback     # 升级回调
│   ├── upgrade_init         # 升级初始化
│   ├── config_callback      # 配置回调
│   └── config_init          # 配置初始化
├── wizard/                  # 安装向导
│   ├── install              # 安装配置（端口/管理员账号）
│   └── uninstall            # 卸载配置
├── config/                  # 系统配置
│   ├── privilege            # 权限配置
│   └── resource             # 资源配置
├── manifest                 # 应用清单文件（元数据）
├── ICON.PNG                 # 应用图标
└── ICON_256.PNG             # 应用大图标

components/
├── Login.jsx               # 登录页面
├── Layout.jsx              # 布局组件（底部导航栏）
├── Home.jsx                # 首页（学习日历）
├── Courses.jsx             # 课程列表
├── CourseDetail.jsx        # 课程详情与播放器 (84KB)
├── CourseChapterManager.jsx # 章节管理
├── HlsPlayer.jsx           # HLS播放器组件
├── Profile.jsx             # 个人中心 (74KB)
├── ConfirmModal.jsx        # 确认对话框
└── PreviewModal.jsx        # 文件预览弹窗

CREATE TABLE users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    username TEXT UNIQUE NOT NULL,          -- 用户名
    password_hash TEXT NOT NULL,            -- 密码哈希
    role TEXT DEFAULT 'user',               -- 角色: admin/user
    nickname TEXT,                          -- 昵称
    avatar TEXT,                            -- 头像路径
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE categories (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT UNIQUE NOT NULL                -- 分类名称
);
-- 默认分类: ID=1, name='未分类'

CREATE TABLE courses (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    title TEXT NOT NULL,                    -- 课程标题
    description TEXT,                       -- 课程描述
    cover_image TEXT,                       -- 封面图片
    category_id INTEGER,                    -- 所属分类
    type TEXT DEFAULT 'manual',            -- 类型: manual(手动)/uploaded(上传)/mount(挂载)
    folder_path TEXT,                       -- 存储路径
    is_shared BOOLEAN DEFAULT 0,           -- 是否公开(0=隐藏, 1=公开)
    creator_id INTEGER DEFAULT 1,          -- 创建者ID
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE course_materials (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    course_id INTEGER NOT NULL,             -- 所属课程
    chapter_title TEXT,                     -- 章节标题（支持树形结构）
    title TEXT NOT NULL,                    -- 素材标题
    file_path TEXT NOT NULL,                -- 文件路径
    media_type TEXT,                        -- 媒体类型: video/audio/document/attachment
    file_size INTEGER,                      -- 文件大小（字节）
    duration INTEGER,                       -- 时长（秒）
    sort_order INTEGER DEFAULT 0,           -- 排序序号
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE learning_progress (
    user_id INTEGER,
    course_id INTEGER,
    material_id INTEGER,
    played_seconds INTEGER DEFAULT 0,      -- 播放时长（秒）
    is_finished BOOLEAN DEFAULT 0,          -- 是否完成
    last_updated DATETIME DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (user_id, course_id, material_id)
);

CREATE TABLE learning_notes (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER,
    material_id INTEGER,
    content TEXT,                           -- 笔记内容
    video_timestamp INTEGER DEFAULT 0,       -- 视频时间戳
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE system_settings (
    key TEXT PRIMARY KEY,
    value TEXT
);
-- 默认设置:
-- allow_registration: false
-- allow_course_creation: true
-- enable_transcoding: false
-- max_material_size: 100 (MB)

CREATE TABLE favorites (
    user_id INTEGER,
    course_id INTEGER,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (user_id, course_id)
);

CREATE TABLE user_materials (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER NOT NULL,
    course_id INTEGER NOT NULL,
    title TEXT NOT NULL,
    file_path TEXT NOT NULL,
    file_size INTEGER,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

{
  "username": "string",
  "password": "string",
  "nickname": "string"
}

{
  "username": "string",
  "password": "string"
}

{
  "token": "jwt_token",
  "user": {
    "id": 1,
    "username": "admin",
    "nickname": "管理员",
    "role": "admin",
    "avatar": "/avatars/xxx.png"
  }
}

{
  "allow_registration": false,
  "allow_course_creation": true,
  "max_material_size": 100,
  "enable_transcoding": false,
  "appName": "轻课堂",
  "version": "1.0.6",
  "transcode": {
    "enabled": false
  }
}

{
  "title": "课程标题",
  "description": "课程描述",
  "cover_image": "封面路径",
  "category_id": 1,
  "folder_path": "存储路径（可选）"
}

{
  "course_id": 1,
  "material_id": 10,
  "played_seconds": 120,
  "is_finished": false
}

transcode_cache/
├── {materialId}_original.mp4       # 原画质缓存
├── {materialId}_1080p.mp4           # 1080p缓存
├── hls_{materialId}_original/        # HLS临时目录
│   ├── playlist.m3u8
│   ├── segment_000.ts
│   ├── segment_001.ts
│   └── ...

/
├── /login                           # 登录页（公开）
└── [PrivateRoute]                   # 需要认证
    ├── /                            # 首页（学习日历）
    ├── /courses                     # 课程列表
    ├── /course/:id                  # 课程详情与播放
    ├── /course/:id/manage           # 章节管理
    └── /profile                     # 个人中心

1. 系统启动
   ↓
2. 执行 cmd/main start
   ↓
3. 读取配置
   - 端口配置 (port.conf)
   - 管理员凭据 (环境变量)
   ↓
4. 环境变量设置
   - DATABASE_URL
   - DATA_DIR
   - UPLOAD_DIR
   - PORT
   - ADMIN_USERNAME
   - ADMIN_PASSWORD
   ↓
5. 创建必要目录
   - 共享目录 (SHARE_DIR)
   - 上传目录 (UPLOAD_DIR)
   ↓
6. 启动Node.js服务
   cd app/server && node index.js
   ↓
7. 服务初始化
   - 连接SQLite数据库
   - 初始化数据表
   - 执行数据库迁移
   - 初始化转码服务
   - 创建管理员账号（如果不存在）
   ↓
8. 监听端口
   默认: 8083 (可通过配置修改)
   ↓
9. 启动完成
   用户可通过浏览器访问

1. 用户打开应用
   ↓
2. 前端检查Token
   - 有Token → 验证有效性
   - 无Token → 跳转登录页
   ↓
3. 输入用户名密码
   ↓
4. POST /api/auth/login
   ↓
5. 后端验证
   - 查询用户
   - bcrypt.compare对比密码
   ↓
6. 生成JWT Token
   jwt.sign({id, username, role}, secret, {expiresIn: '7d'})
   ↓
7. 返回Token和用户信息
   ↓
8. 前端存储
   - localStorage.setItem('token', token)
   - localStorage.setItem('user', JSON.stringify(user))
   ↓
9. 跳转到首页

1. 用户进入课程详情
   ↓
2. GET /api/courses/:id
   - 获取课程信息
   - 获取章节列表
   ↓
3. 用户点击播放章节
   ↓
4. 检查视频格式
   ↓
5. GET /api/stream/:materialId
   ├─ 原生格式
   │   ├─ 支持Range请求
   │   ├─ 直接流式传输
   │   └─ 前端Video标签播放
   │
   └─ 需要转码格式
       ├─ 检查缓存
       │   └─ 有缓存 → 直接播放缓存MP4
       │
       └─ 无缓存
           ├─ 启动HLS转码 (transcoder.startHlsTranscode)
           │   ├─ 检测GPU编码器
           │   ├─ 构建FFmpeg参数
           │   ├─ 启动FFmpeg进程
           │   ├─ 等待m3u8生成
           │   └─ 同时启动后台缓存 (transcoder.startBackgroundCache)
           │
           ├─ 返回HLS信息
           │   {
           │     needsTranscode: true,
           │     hlsUrl: '/api/stream/:materialId/hls/playlist.m3u8'
           │   }
           │
           └─ 前端HlsPlayer加载m3u8
               ├─ 请求playlist.m3u8
               ├─ 按需请求segment_XXX.ts
               └─ 实时播放
   ↓
6. 播放进度记录
   - 每30秒或暂停时保存
   - POST /api/progress
   - {course_id, material_id, played_seconds, is_finished}

1. 用户选择文件
   ↓
2. 前端检查文件大小
   - 超过限制（默认100MB）→ 提示分片上传
   ↓
3. 小文件（单次上传）
   ├─ 构建FormData
   │   {courseId, file}
   ├─ POST /api/upload
   ├─ 保存到课程目录
   ├─ 插入数据库
   └─ 返回成功
   ↓
4. 大文件（分片上传）
   ├─ 文件切片（每片10MB）
   ├─ 逐片上传
   │   POST /api/upload/chunk
   │   {fileId, chunkIndex, totalChunks, courseId}
   │   ↓
   │   保存到临时目录
   │   UPLOAD_DIR/temp/fileId/chunk_0
   │   UPLOAD_DIR/temp/fileId/chunk_1
   │   ...
   ↓
   ├─ 所有分片上传完成
   │   POST /api/upload/merge
   │   {fileId, filename, courseId, totalChunks}
   │   ↓
   │   合并分片
   │   ├─ 读取所有分片
   │   ├─ 按顺序拼接
   │   ├─ 写入最终文件
   │   └─ 清理临时目录
   │
   └─ 插入数据库
   ↓
5. 上传完成
   - 刷新章节列表

1. 管理员创建挂载课程
   POST /api/courses
   {title, type: 'mount', folder_path: '/shares/course1'}
   ↓
2. 后台启动扫描
   setImmediate(() => scanDirectory(courseId, folderPath))
   ↓
3. 递归扫描目录
   scanDirectoryRecursive(courseId, basePath, relativePath, existingPaths)
   ├─ 遍历所有文件和子目录
   ├─ 识别媒体类型（video/audio/document）
   ├─ 跳过已存在的文件
   ├─ 插入新文件到数据库
   └─ 记录chapter_title（相对路径）
   ↓
4. 清理已删除的文件
   ├─ 对比数据库记录
   ├─ 删除不存在的记录
   ↓
5. 重新排序
   resortCourseMaterials(courseId)
   ├─ 智能排序算法
   ├─ 支持中英文数字
   ├─ 更新sort_order字段
   ↓
6. 自动生成封面
   autoUpdateCourseCover(courseId)
   ├─ 查找第一个视频
   ├─ 使用FFmpeg生成缩略图
   └─ 保存到DATA_DIR/covers/
   ↓
7. 扫描完成
   - 前端刷新课程列表

1. 用户在播放器中打开笔记面板
   ↓
2. GET /api/notes/:materialId
   - 获取该视频的所有笔记
   - 按时间戳排序
   ↓
3. 添加新笔记
   ├─ 输入内容
   ├─ 可选：上传图片
   │   POST /api/upload/note-image
   │   保存到 DATA_DIR/note_images/{userId}/
   ↓
   ├─ POST /api/notes
   │   {
   │     materialId: 10,
   │     content: "笔记内容",
   │     timestamp: 120  // 当前播放时间
   │   }
   │   ↓
   └─ 插入数据库
   ↓
4. 编辑笔记
   ├─ PUT /api/notes/:id
   └─ 更新内容
   ↓
5. 删除笔记
   ├─ DELETE /api/notes/:id
   └─ 从数据库删除
   ↓
6. 笔记关联
   - 笔记永久保存
   - 即使课程被删除，笔记仍可访问
   - 通过"历史课程"查看

视频播放中
    ↓
每30秒或以下事件触发
- 播放暂停
- 播放结束
- 切换章节
- 页面关闭
    ↓
保存进度
POST /api/progress
{
  course_id: 1,
  material_id: 10,
  played_seconds: 245,
  is_finished: false
}
    ↓
后端UPSERT
INSERT INTO learning_progress ...
ON CONFLICT(...) DO UPDATE SET
  played_seconds = excluded.played_seconds,
  is_finished = excluded.is_finished,
  last_updated = datetime('now')
    ↓
前端更新状态
- 更新进度条
- 更新"已看X分X秒"
- 如果看完，标记为完成

# 数据库路径
export DATABASE_URL="$SHARE_DIR/liteclass.db"

# 持久化数据目录
export DATA_DIR="$TRIM_PKGVAR"

# 上传目录
export UPLOAD_DIR="$SHARE_DIR/user-uploads"

# 服务端口
export PORT="$APP_PORT"

# 监听地址
export HOST="::"

# 管理员账号
export ADMIN_USERNAME="$admin_username"
export ADMIN_PASSWORD="$admin_password"

# fnOS
/var/packages/ffmpeg/target/bin/ffmpeg

# Synology
/usr/bin/ffmpeg

# Debian/Ubuntu
apt-get install ffmpeg

# CentOS/RHEL
yum install ffmpeg

tail -f $TRIM_PKGVAR/info.log

cp $SHARE_DIR/liteclass.db $SHARE_DIR/liteclass.db.backup

cp $SHARE_DIR/liteclass.db.backup $SHARE_DIR/liteclass.db

fastify.get('/api/new-endpoint', { preValidation: [fastify.authenticate] }, async (request, reply) => {
    // 处理逻辑
    return { data: 'response' };
});

// 在initSchema函数的migrations数组中添加
const migrations = [
    // ...现有迁移
    "ALTER TABLE courses ADD COLUMN new_field TEXT",
];