# AGENTS.md

This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.

## 项目概述

Easy Study 是一个为 6 岁儿童设计的英语学习系统，核心是**自然拼读 + 牛津树绘本阅读**的学习闭环。项目采用前后端分离架构，通过 Nginx 反向代理统一入口。

## 常用命令

### 后端 (FastAPI, 端口 8000)

```bash
cd bookshelf/backend
python -m venv .venv # Windows
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000        # API 文档: http://localhost:8000/docs
```

### 前端 (React + Vite, 端口 5173)

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

### 统一入口 (Nginx, 端口 80)

运行 `deploy/nginx/win-link.bat` (Windows) 或 `deploy/nginx/linux-link.sh` (Linux) 建立软链接，然后加载 Nginx 配置。

## 架构要点

### 技术栈

- **前端**: React 19 + TypeScript + Vite 8, React Router 7, antd-mobile, zustand
- **后端**: Python 3.11+, FastAPI, Uvicorn, Pydantic
- **数据存储**: JSON 文件 (`docs/data/`)，无数据库
- **部署**: Nginx 反向代理

### 目录结构

- `bookshelf/backend/` - FastAPI 后端 API
  - `app/routers/books.py` - 绘本相关接口
  - `app/routers/words.py` - 单词/拼读接口
  - `app/config.py` - 全局配置（路径、CORS）
  - `tools/` - 数据处理脚本（OCR、拼读、TTS）
- `bookshelf/frontend/` - React 前端应用
  - `src/pages/child/` - 孩子端页面（Home, Learn, Quiz, BookReader）
  - `src/pages/parent/` - 家长端页面（Dashboard）
  - `src/api/client.ts` - API 客户端
- `docs/data/` - 结构化数据（绘本索引、OCR 结果、拼读数据）
- `251228-words/` - 第一代单词学习游戏（纯前端）

### 关键配置

后端路径配置统一在 `bookshelf/backend/app/config.py`，通过环境变量覆盖：

- `EASYSTUDY_WORKHOME` - 主工作空间路径（默认 Windows: `E:\nginx-1.8.0\html`）
- `EASYSTUDY_HOST` - 资源访问 host（空 = 同源相对路径）
- `EASYSTUDY_CORS_ORIGINS` - CORS 源（逗号分隔）

### API 路由

- `/api/books/`* - 绘本列表、详情、页面
- `/api/words/*` - 单词查询、拼读数据
- `/api/health` - 健康检查

### 数据流

绘本图片 → OCR 提取文字 → 结构化 JSON → 关联自然拼读 → 前端展示

## 开发注意事项

1. **前后端联调**: 前端 `/api`、`/images`、`/audio` 等路径需经 Nginx 反代，直接访问前端 dev server 无法调用后端
2. **数据文件**: 当前使用 JSON 文件存储，位于 `docs/data/`，包括 `book-index.json`、`book-ocr/`、`book-structured/`
3. **静态资源**: 绘本图片、音频等通过 Nginx alias 直出，路径配置在 `deploy/nginx/nginx-win.conf`
4. **Python 依赖**: 基础依赖在 `requirements.txt`，额外需要 `edge-tts`、`easyocr`、`nltk`（按需安装）