# flipbook

**Repository Path**: lifeofcode/flipbook

## Basic Information

- **Project Name**: flipbook
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-31
- **Last Updated**: 2026-05-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenFlipbook

> **AI 驱动的知识探索平台。** 每一页是 AI 生成的交互式图解。点击图片任意区域，VLM 解析点击对象并生成下一页。支持 3D 模型、语音辅导、真人切换、内容导出。所有模型可在后台配置管理。

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D20-green.svg)](package.json)
[![Next.js](https://img.shields.io/badge/Next.js-15-black.svg)](https://nextjs.org)
[![Python](https://img.shields.io/badge/Python-3.12-3776AB.svg)](https://python.org)

## 功能概览

### 核心体验

- **图文即界面** — 每页一张 AI 图解，点击任意区域进入下一页
- **三种操作模式** — query（文字提问）、tap（点击探索）、edit（图片编辑）
- **智能追问** — Agent 根据输入清晰度自动 0-5 轮追问
- **格式判断** — 自动选择 2D 图解 / 3D GLB 模型 / 视频动画
- **三重锁** — Domain Lock（学科锁定）、Style Lock（画风锁定）、Language Lock（语言锁定）

### 模型管理

- **Provider 供应商体系** — 统一管理 LLM、VLM、生图、GLB、TTS、STT、RTC 等 8 类供应商
- **ModelConfig 配置** — 9 种角色 × 3 个档位（fast/balanced/pro），优先级路由
- **后台管理界面** — 模型管理、TTS 音色、教师管理、通话监控、调用追踪

### 实时通话

- **AI 语音辅导** — WebRTC 实时语音交互，AI 导师引导探索
- **真人教师切换** — AI → 真人无缝切换，上下文快照自动转交
- **页面状态同步** — 教师实时查看学生当前页面

### 导出与分享

- **三种导出格式** — Flipbook 翻页书 / GLB 3D 展示 / 交互演示
- **分享链接** — 一键生成可分享的导出页面
- **Fork 续学** — 从分享页直接 fork 继续探索

```
  ┌────────────────────────┐                  ┌─────────────────────────┐
  │  文字提问 / 点击探索     │                  │  交互式知识图解          │
  └─────────┬──────────────┘                  └─────────┬───────────────┘
            │                                           │ 点击区域
            ▼                                           ▼
   ┌───────────────────┐   plan page    ┌──────────────────────────┐
   │  LLM (Planner)    │ ─────────────▶ │  Image/3D/Video 生成      │
   │  + VLM (Click)    │                │  fal / Meshy / 视频模型    │
   └───────────────────┘                └──────────────┬───────────┘
            ▲                                          │
            │  subject phrase                          │
            ▼                                          ▼
   ┌───────────────────┐              ┌──────────────────────────┐
   │   Provider 统一管理  │              │  实时通话 (Agora WebRTC)  │
   │   后台可配置切换      │              │  AI 语音 + 真人切换       │
   └───────────────────┘              └──────────────────────────┘

                        persistence: MySQL + Prisma + OSS
```

## 快速开始

```bash
git clone https://github.com/eren23/openflipbook
cd openflipbook

# 安装依赖
pnpm install

# 环境配置
cp .env.example apps/web/.env.local
# 编辑 .env.local，填写数据库、OSS、API Key 等

# 数据库初始化
npx prisma migrate dev
npx prisma db seed   # 创建默认管理员 admin / admin123

# 启动开发
pnpm dev
open http://localhost:3000/play

# 管理后台
open http://localhost:3000/admin/login
```

## 技术栈

| 层级 | 技术 | 说明 |
|------|------|------|
| 前端 | Next.js 15 + React 19 | App Router, Server Components, R3F (3D) |
| 后端 | Python FastAPI on Modal | Agent Loop, SSE 管线, 模型调度 |
| 数据库 | MySQL + Prisma ORM | 14 张表, 完整 Schema |
| 缓存 | Redis | 配置缓存, 限流 |
| 对象存储 | OSS (S3 兼容) | 图片/3D/视频存储 |
| 实时通信 | Agora WebRTC | AI/真人语音通话 |
| 认证 | JWT (HS256) | jose 库, middleware 保护 |
| 可观测性 | Sentry | 前后端统一接入 |

## 项目结构

```
apps/
  web/                  Next.js 15 前端应用
    app/
      admin/            管理后台 (模型/音色/教师/监控/追踪)
      play/             核心探索页面
      tutor/            教师工作台
      share/            分享页面
      api/              API 路由 (auth, admin, tutor, export, ...)
    components/         UI 组件 (GlbViewer, VoiceCallWidget, ...)
    lib/                工具库 (auth, db, admin-api, ...)
  modal-backend/        Python Agent 后端
    agent/              Agent Loop, SSE 管线, 上下文管理
    providers/          模型供应商 (LLM, Image, GLB, Video, TTS)
    export/             内容导出 (Flipbook, GLB, Demo)
  rtc-service/          WebRTC 实时通话服务
prisma/
  schema.prisma         数据库 Schema (14 张表)
  seed.ts               种子数据 (管理员, 教师, 供应商, 模型)
packages/
  config/               共享 TypeScript 类型
docs/                   文档
```

## 支持的模型供应商

| 类型 | 支持的供应商 | 配置方式 |
|------|-------------|---------|
| LLM / VLM | OpenRouter, OpenAI, Azure, 自定义 | base_url + api_key |
| 图片生成 | fal.ai (nano-banana, Seedream) | api_key |
| 图片编辑 | fal.ai (nano-banana/edit, Kontext) | api_key |
| 3D 生成 | Meshy API, OpenAI 兼容接口 | api_key + 轮询 |
| 视频生成 | fal.ai (LTX-Video, Wan 2.2) | api_key |
| TTS | Agora, 自定义 | voice_id |
| RTC | Agora WebRTC | app_id + certificate |

所有供应商通过后台 `/admin/models` 页面配置，支持动态切换无需重启。

## 管理后台

| 页面 | 路径 | 功能 |
|------|------|------|
| 模型管理 | `/admin/models` | 供应商 + 模型配置 (双 Tab) |
| TTS 音色 | `/admin/tts-voices` | 音色管理 + 在线试听 |
| 教师管理 | `/admin/tutors` | 教师账号 CRUD |
| 通话监控 | `/admin/live` | 实时通话状态 |
| 调用追踪 | `/admin/trace` | API 调用记录 |

管理后台受 JWT middleware 保护，默认管理员: `admin / admin123`。

## 环境变量

完整列表见 [`.env.example`](.env.example)。核心变量：

```env
# 数据库
DATABASE_URL=mysql://root:password@localhost:3306/openflipbook

# JWT 密钥
JWT_SECRET=your-secret-key

# 前端 URL（Python 后端调用 Next.js API 时使用）
NEXT_PUBLIC_BASE_URL=http://localhost:3000

# AI 服务
FAL_KEY=              # 图片/视频生成
OPENROUTER_API_KEY=   # LLM / VLM

# 对象存储
OSS_ENDPOINT=
OSS_ACCESS_KEY_ID=
OSS_ACCESS_KEY_SECRET=
OSS_BUCKET=openflipbook
```

## 文档

- [架构文档](docs/ARCHITECTURE.md) — 代码结构、模块划分、数据流
- [Docker 部署](docs/DOCKER.md) — 容器化部署指南
- [本地开发](docs/LOCAL_DEV.md) — 不用 Docker 的开发流程
- [密钥配置](docs/BYO-KEYS.md) — 各服务商密钥获取指南

## 许可证

[MIT](LICENSE) © 2026 Eren Akbulut.