将课程与教辅材料转为可检索、可生成、可测验的个性化学习流：多格式文档处理与分段、基于 pgvector 的语义检索与关联推荐、OpenAI 驱动的翻译/摘要/术语表与闪卡扩展，并规划模拟考试（多题型、评分与进度）与学术诚信侧的来源追踪、审计与权限模型。
实现细节、环境变量与接口以 GitHub 仓库 README 与 docs/ 为准；下列内容为站内策展摘要，并收录系统架构、数据流、数据模型与分阶段路线图（与 docs/ARCHITECTURE.md / ROADMAP.md 对齐，以仓库为准）。
pgvector 语义检索环境要求：Node.js 18+；PostgreSQL 15+（含 pgvector）；Redis 6+；对象存储（如 MinIO，与 S3 兼容）；进程管理可选 PM2。
git clone https://github.com/songzhiyuan98/study-assistant.git cd study-assistant pnpm install # 若仓库锁定为 npm，请以 README 为准
cp packages/db/.env.example packages/db/.env # 编辑 packages/db/.env
常用变量：DATABASE_URL（PostgreSQL）、OPENAI_API_KEY、NEXTAUTH_SECRET 等；完整列表见仓库示例文件。
npm run docker:up # PostgreSQL、Redis、MinIO 等（以 package.json 脚本为准） npm run db:migrate npm run db:seed
npm run dev
浏览器访问 http://localhost:3000（端口以本地配置为准）。
以下「当前快照」更新节点为 2025-09-08；与仓库 ROADMAP.md 冲突时以仓库为准。
已完成：
进行中：PDF / TXT 解析管道——文档内容提取与分段。
完成度（规划口径）：第 1 阶段约 67%（4/6 项主任务）；总体约 22%（4/18 项主任务）。
| 功能 | 状态 | 说明 |
|---|---|---|
| 文件夹管理 | 已完成 | 多层级文档组织 |
| 用户认证 | 已完成 | 邮箱 / Google OAuth |
| PDF 处理 | 开发中 | 文本提取与分段 |
| AI 翻译 | 计划中 | 多语言 |
| 考试系统 | 计划中 | 自动出题与评分 |
text-embedding-ada-002（或后续模型，以配置为准）学习助手采用现代模块化 Monorepo：Web 与 API 解耦，重任务走队列 + Worker，文件走对象存储，结构化与向量数据进 PostgreSQL，长耗时推理与嵌入调用外部 AI。形态上接近微服务协作，部署上可按进程/容器水平扩展。
用户 → Web 前端 → API 服务（Fastify） → PostgreSQL（业务 + 向量）
│
├→ Redis 队列（BullMQ）→ 后台 Worker（ingest / generate / export）
│
├→ MinIO / S3（原始文件与导出物）
│
└→ OpenAI 等（嵌入与生成）
payloadJson、sourceRefs）→ 通知或拉取展示USER（用户）
├── FOLDER（文件夹）
│ └── LECTURE（讲义 / 文档）
│ └── SEGMENT（段落，含向量嵌入）
├── SELECTION（用户对段落的选择）
│ └── ITEM（生成内容：翻译、总结等）
└── EXAM（考试，路线图中）
└── EXAM_ATTEMPT（作答记录）
| 实体 | 要点 |
|---|---|
| User | id、邮箱、姓名、密码（可选）、角色（RBAC） |
| Folder | id、名称、描述、userId |
| Lecture | id、folderId、标题、fileUrl、类型、处理 status |
| Segment | id、lectureId、正文、embedding（向量）、页码 / 锚点 |
| Selection | id、userId、lectureId、segmentIds[] |
| Item | id、selectionId、类型、payloadJson、sourceRefs |
app/web/src/ ├── app/ │ ├── (auth)/ # 登录注册等 │ ├── dashboard/ # 控制台 │ ├── upload/ # 上传 │ ├── library/ # 文档库 │ └── api/ # Next.js Route Handlers（若存在） ├── components/ │ ├── ui/ # 基础 UI │ ├── forms/ │ └── layout/ ├── lib/ └── providers/
app/ ├── api/ # Fastify：routes、plugins、middleware ├── workers/ # BullMQ：ingest、generate、export 等 └── sidecar/ # 可选：Python OCR 等独立服务
document:ingest — 文档摄取与解析content:generate — AI 内容生成export:data — 导出cleanup:files — 清理vector:index — 向量索引更新/api/v1/POST /api/auth/register POST /api/auth/login GET /api/auth/session POST /api/lectures GET /api/lectures/:id GET /api/folders POST /api/selections POST /api/items/generate GET /api/items/:id
study-assistant/ ├── app/ │ ├── web/ # Next.js 前端 │ ├── api/ # Fastify API │ └── workers/ # 后台 Worker ├── packages/ │ ├── db/ # Prisma 与迁移 │ ├── shared/ │ └── ui/ ├── docs/ # ROADMAP、ARCHITECTURE、OPERATIONS 等 └── CLAUDE.md # AI 协作说明（若保留）
周次为规划节奏；勾选状态以仓库最新提交与 ROADMAP 为准。
目标：核心文档处理管道 + 基础内容生成闭环。
第 1 周（基础设施）
第 2 周（选择与生成）
目标：高级文档能力与考试系统 MVP。
第 3 周：PPTX、OCR（Python sidecar）、双栏论文布局、表格 / 公式、向量侧边栏、导出（Markdown、CSV、Anki 等）。
第 4 周：考试蓝图、基于证据的出题、考试播放器与计时、自动评分与 rubric、性能分析与错题改进建议。
目标：安全、性能与部署。
第 5 周：学术诚信策略、全链路审计、RBAC、成本与 token 预算、加密与隐私、合规报告。
第 6 周：OpenTelemetry、缓存与性能、Docker / K8s 清单、CI/CD、错误追踪与告警、生产部署模板。
本文档与站内策展在每次主要功能交付后应同步更新进度与时间表调整。
npm run dev # 本地开发 npm run build # 生产构建 npm run test # 测试 npm run db:migrate # 迁移 npm run db:seed # 种子数据 npm run db:studio # Prisma Studio npm run lint npm run type-check npm run format
脚本名以仓库根目录 package.json 为准。
Fork 本仓库 → 功能分支 → 提交 → Push → 发起 Pull Request；规范见 CONTRIBUTING.md。
文档索引：docs/ROADMAP.md、docs/ARCHITECTURE.md、docs/OPERATIONS.md、API 说明、CHANGELOG、CLAUDE 协作指南等。
License：MIT。
致谢：Next.js、Prisma、pgvector、OpenAI 等开源与服务商。