# FastApiBase

**Repository Path**: my919/FastApiBase

## Basic Information

- **Project Name**: FastApiBase
- **Description**: No description available
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-13
- **Last Updated**: 2026-03-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FastApiBase

基于 [FastAPI Best Practices](https://github.com/zhanymkanov/fastapi-best-practices) 标准创建的 FastAPI 项目模板。

## 项目结构

```
FastApiBase/
├── alembic/                 # 数据库迁移
├── src/
│   ├── auth/                # 认证模块
│   │   ├── router.py
│   │   ├── schemas.py
│   │   ├── models.py
│   │   ├── service.py
│   │   ├── dependencies.py
│   │   ├── config.py
│   │   ├── constants.py
│   │   ├── exceptions.py
│   │   └── utils.py
│   ├── posts/               # 文章模块
│   │   └── (同上结构)
│   ├── config.py            # 全局配置
│   ├── database.py         # 数据库连接
│   ├── models.py            # 全局模型元数据
│   ├── schemas.py           # 全局 Pydantic 基类
│   ├── exceptions.py        # 全局异常
│   ├── pagination.py        # 分页
│   └── main.py              # 应用入口
├── tests/
├── requirements/
├── .env.example
├── alembic.ini
└── pyproject.toml
```

## 快速开始

1. **创建虚拟环境并安装依赖**

```bash
cd FastApiBase
python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

pip install -r requirements/base.txt
pip install -r requirements/dev.txt  # 开发依赖
```

2. **配置环境变量**

```bash
cp .env.example .env
# 编辑 .env 设置 DATABASE_URL 等
```

3. **初始化数据库迁移**

```bash
alembic revision --autogenerate -m "initial"
alembic upgrade head
```

4. **启动服务**

```bash
uvicorn src.main:app --reload --host 0.0.0.0 --port 8000
```

## 最佳实践要点

- **按领域组织模块**：每个领域（auth、posts）拥有独立的 router、schemas、models、service 等
- **异步优先**：路由与依赖均使用 async
- **依赖链**：`valid_post_id` → `valid_owned_post` 链式依赖复用
- **Pydantic 配置**：CustomModel 统一序列化、时区格式
- **配置拆分**：AuthConfig 与全局 Config 分离
- **文档控制**：生产环境默认隐藏 OpenAPI 文档

## 刷题模块（数学 1–9 级）

题型：`fill_blank`（填空）、`choice`（选择）、`essay`（解答）。科目当前为 `math`。

### 数据库表（PostgreSQL）

| 表名 | 说明 |
|------|------|
| `quiz_question` | 题目：`subject`, `level`(1–9), `question_type`, `stem`, `options`(JSON), `correct_answer`(JSON), `explanation` |
| `quiz_attempt` | 每次作答：`user_id`, `question_id`, `user_answer`, `is_correct` |
| `quiz_wrong_book` | 错题聚合：`wrong_count`, `last_wrong_at`, `is_cleared` |

迁移：`alembic upgrade head`（在已有 `user` 表前提下）。

### API（均需登录，`Authorization: Bearer placeholder_token_{用户UUID}`）

- `POST /quiz/questions` — 录入题目  
- `GET /quiz/questions` — 题目列表（含答案）  
- `GET /quiz/practice/next` — 随机下一题（不含答案）  
- `POST /quiz/practice/submit` — 提交 `{ "question_id", "user_answer" }`  
- `GET /quiz/wrong-book` — 错题回顾  
- `DELETE /quiz/wrong-book/{question_id}` — 移出错题本  

### `correct_answer` / `user_answer` 约定

- **选择**：`correct_answer`: `["A"]` 或 `["A","C"]`；`user_answer`: `{"choice":"A"}` 或 `{"choices":["A","C"]}`  
- **填空**：单空 `correct_answer`: `["可接受答案1","答案2"]`；`user_answer`: `{"text":"..."}`。多空：`correct_answer`: `[["空1候选"],["空2候选"]]`；`user_answer`: `{"blanks":["...","..."]}`  
- **解答**：`correct_answer`: `{"keywords":["关键词"]}` 或 `{"reference":"参考答案"}`；`user_answer`: `{"text":"..."}`。无关键词时可能返回 `is_correct: null`，不写入错题本  

## 开发

```bash
# 运行测试
pytest

# 代码格式化与检查
ruff check --fix src
ruff format src
```