fastapi-todolist/README.md

# TodoList 全栈项目（FastAPI + MySQL）

这是一个用于学习后端开发的 TodoList 项目。前端由 Nginx 提供，`/api` 请求反向代理到 FastAPI，FastAPI 使用 SQLAlchemy 2.x ORM 和 PyMySQL 驱动读写 Docker 中的 MySQL 8.4。

## 架构

```text
浏览器
  -> Windows 局域网端口 8080（当前环境使用端口转发）
  -> WSL Nginx :80
  -> FastAPI/Uvicorn 127.0.0.1:8000
  -> MySQL 127.0.0.1:3306
```

## 目录

```text
main.py                     FastAPI 路由和接口逻辑
database.py                 数据库 URL、Engine 和 ORM Base
models.py                   SQLAlchemy ORM 数据模型
frontend/index.html         前端页面
compose.yaml                MySQL Docker Compose 配置
schema.sql                  数据库建表脚本
pyproject.toml              项目元数据和直接依赖
uv.lock                     uv 锁文件（完整、精确的依赖图）
.env.example                环境变量示例（不含真实密码）
deploy/nginx-todolist.conf  Nginx 站点配置
deploy/todolist.service     systemd 服务配置
验收记录.md                  已完成测试和已知限制
```

## 环境要求

- Windows + WSL2 Ubuntu（当前部署方式）
- Python 3.12 或兼容版本
- uv 0.11 或兼容版本
- Docker Engine 与 Docker Compose 插件
- Nginx
- systemd（用于后台运行 FastAPI）

## 1. 准备 Python 环境

```bash
cd /home/dwh/code/fastapi_todolist
uv sync --locked
```

`uv sync --locked` 会根据 `uv.lock` 创建 `.venv` 并安装已锁定的精确版本。
`--locked` 要求锁文件必须与 `pyproject.toml` 一致，不会在部署时悄悄改写依赖解析结果。

开发时可以使用 uv 在项目环境中运行命令：

```bash
uv run uvicorn main:app --host 127.0.0.1 --port 8000
```

项目的依赖来源是 `pyproject.toml` 和 `uv.lock`。新增或删除依赖时使用 `uv add` 或 `uv remove`，不手动维护第二套依赖清单。

如果部署用户或目录不同，需要同步修改 `deploy/todolist.service` 中的 `User`、`WorkingDirectory` 和 `ExecStart`。

## 2. 准备环境变量

```bash
cp .env.example .env
chmod 600 .env
vim .env
```

请替换两个密码占位符。不要提交或对外发送真实 `.env`。

## 3. 启动 MySQL 并建表

```bash
docker compose up -d
docker compose ps
```

首次创建数据卷后执行建表脚本：

```bash
docker compose exec -T mysql sh -lc 'exec mysql -u"$MYSQL_USER" -p"$MYSQL_PASSWORD" "$MYSQL_DATABASE"' < schema.sql
```

MySQL 端口仅绑定到 `127.0.0.1:3306`，不会直接暴露给局域网。

## 4. 安装前端与 Nginx 配置

```bash
sudo mkdir -p /var/www/todolist
sudo cp frontend/index.html /var/www/todolist/index.html
sudo cp deploy/nginx-todolist.conf /etc/nginx/sites-available/todolist
sudo ln -s /etc/nginx/sites-available/todolist /etc/nginx/sites-enabled/todolist
sudo nginx -t
sudo systemctl restart nginx
```

若 `/etc/nginx/sites-enabled/default` 与交付配置同时声明 `default_server`，请先停用默认站点或去掉其中一方的 `default_server`。

## 5. 安装 FastAPI systemd 服务

```bash
sudo cp deploy/todolist.service /etc/systemd/system/todolist.service
sudo systemctl daemon-reload
sudo systemctl enable --now todolist.service
sudo systemctl status todolist.service --no-pager -l
```

## 6. 验证

直连 FastAPI：

```bash
curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8000/todos
```

通过 Nginx：

```bash
curl http://127.0.0.1/
curl http://127.0.0.1/api/todos
```

Windows 局域网入口为 `http://<Windows-LAN-IP>:8080`。DHCP 或网络切换可能改变该地址，因此不应将它视为固定生产地址。

## API

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/health` | 健康检查 |
| GET | `/todos` | 获取全部任务 |
| POST | `/todos` | 新增任务 |
| PATCH | `/todos/{todo_id}` | 修改任务文字或完成状态 |
| DELETE | `/todos/{todo_id}` | 删除任务 |

Nginx 对外使用 `/api` 前缀，例如浏览器访问 `/api/todos`，代理到 FastAPI 的 `/todos`。

## 安全说明

- CRUD 接口通过 SQLAlchemy ORM 操作数据库；SQLAlchemy 使用绑定参数传递用户数据，不使用 f-string 拼接 SQL。
- 数据库密码通过 `.env` 读取，并使用 `URL.create()` 构建连接地址，不写死在 Python 代码中。
- `.env` 和 MySQL 数据卷不在交付包内。
- 交付包中的 `.env.example` 只有占位符。