# studyroom

**Repository Path**: gsphelow/studyroom

## Basic Information

- **Project Name**: studyroom
- **Description**: 个人学习室studyroom
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: codex/auth-foundation
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-16
- **Last Updated**: 2026-11-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 我的学习室

“我的学习室”是一个以沉浸式专注、学习计划和学习时长记录为核心的个人学习操作系统。当前仓库包含第一阶段的 Next.js 前端实现和 FastAPI 智能体后端；登录和云端同步仍在后续阶段完善。二期知识库已具备服务端权限前置的检索、重排、引用、离线评测，以及文档上传与索引状态 HTTP 接口；检索默认关闭，需由部署方显式开启。

## 当前状态

第一阶段前端已可本地运行，使用匿名 fixture 数据和浏览器 `localStorage` 完成以下闭环：

- 公共产品入口和匿名学习工作台；首次无缓存时自动展示 Python 示例学习计划与今日任务，用户主动清空已有数据后仍可进入空状态。首页桌面端采用左侧放大月历/统计、右侧“今天的学习 + 拆解新计划”上下双卡布局。
- 手动创建学习任务、学习计划总览和计划生命周期操作。
- AI 学习计划草稿工作台：草稿编辑、显式确认后写入正式计划、今日安排二次确认。
- 独立 `/focus` 沉浸式学习室：番茄钟/自由计时、学习时长记录、今日计划卡、环境设置、六套场景和 `frontend/public/audio/backaudio.aac` 循环环境音；切换后的场景、环境音、音量、透明度和计划面板显示会在刷新后保留，其中透明度只作用于番茄钟区域与右侧计划面板。
- 首页、计划页、AI 工作台和专注室共用同一个六枚圆形玻璃导航；第五个入口是“学习计划智能体”。

详细的当前实现、文件入口、视觉资源和下一步建议见 [前端交接文档](docs/FRONTEND_HANDOFF.md)。

## 目录结构

```text
docs/
  superpowers/specs/    产品规格与交互规则
  superpowers/plans/    前端与后端实施计划
  superpowers/handoffs/ 各批次交接文档与当前验证基线
  mockups/              设计图与视觉参考
  FRONTEND_HANDOFF.md   下一次会话的前端状态交接
  superpowers/specs/2026-09-09-learning-agent-backend-design.md
                         智能体后端、LLM 插拔与二期 RAG 设计规格
  superpowers/plans/2026-09-09-learning-agent-backend.md
                         智能体后端分任务实施计划
frontend/
  app/                  Next.js App Router 页面与 Route Groups
  components/           工作台壳、共享导航、计划和专注室组件
  lib/                  领域类型、匿名 Store、排程和计时逻辑
  public/images/        书房背景、头像和六套沉浸式场景图
  tests/                领域与页面回归测试
backend/                FastAPI 后端服务、迁移、领域服务和测试
```

`app/(public)` 与 `app/(workspace)` 中的括号是 Next.js Route Groups，只用于组织布局，不会出现在 URL 中。前端单独放在 `frontend/`，为后续在仓库根目录增加后端服务保留边界。

## 快速开始

```bash
cd frontend
npm install
npm run dev
```

然后打开 <http://localhost:3000>。完整命令、路由、数据边界、目录职责和本地数据重置方式见 [frontend/README.md](frontend/README.md)。

## 数据与后端边界

未配置 API URL 时，匿名领域数据只保存在浏览器 `localStorage` 的 `learning-room-v1` 键中，不依赖登录或后端；配置 API URL 后，Agent 工作台使用 `backend/` 的服务端 API。专注室的场景和显示偏好单独保存在 `learning-room-focus-ui-v1`，它只属于本地 UI 偏好，不是领域数据。所有后端领域数据的查询和写入都必须由服务端按已认证的 `user_id` 限定，并执行授权检查；不能信任客户端传入的用户标识。

真实智能体后端的设计基线见 [学习计划智能体后端设计规格](docs/superpowers/specs/2026-09-09-learning-agent-backend-design.md)，具体分任务、测试顺序和验收矩阵见 [后端实施计划](docs/superpowers/plans/2026-09-09-learning-agent-backend.md)。二期的文档处理、权限前置混合检索、确定性重排、版本固定引用及其离线评测边界见 [检索与引用设计](docs/superpowers/specs/2026-09-10-knowledge-retrieval-evaluation-design.md) 和 [实施计划](docs/superpowers/plans/2026-09-10-knowledge-retrieval-evaluation.md)。后端 Tasks 1–18 已实现并集成的当前状态、验证命令与已知边界见 [知识库接口与 Embedding 交接](docs/superpowers/handoffs/2026-09-10-knowledge-api-and-embedding-handoff.md)。LLM Key、模型调用和领域写入都必须留在服务端。

知识库、知识笔记、复习中心、复习卡片、学习复盘和账号体系不属于当前第一阶段，不应在没有更新规格的情况下加入页面或 Store。第一阶段允许 AI 生成学习计划草稿；知识库 RAG 属于第二阶段。

## 验证

在 `frontend/` 目录运行：

```bash
npm test
npm run lint
npm run build
```

截至 2026-09-10，`npm test`（41 passed）、`npm run lint` 和 `npx next build --webpack` 均已通过；若当前环境的 Turbopack 子进程无法绑定端口，可使用 webpack 构建路径完成生产编译验证。

后端在 `backend/` 目录运行：

```bash
PYTHONPATH="$PWD" .venv/bin/pytest -q
PYTHONPATH="$PWD" .venv/bin/ruff check app tests
PYTHONPATH="$PWD" .venv/bin/mypy app tests
```

截至 2026-09-10，预期为 `250 passed, 3 skipped`、Ruff `All checks passed!`、mypy `Success`；三个跳过项是缺少 `LEARNING_POSTGRES_TEST_URL` 的可选 PostgreSQL 集成测试。知识库聚焦套件用 `PYTHONPATH="$PWD" .venv/bin/pytest -q tests/knowledge`（123 passed）。