Initial TodoList MySQL delivery

.env.example

@@ -0,0 +1,6 @@
+MYSQL_ROOT_PASSWORD=replace_with_a_strong_root_password
+MYSQL_DATABASE=todolist
+MYSQL_USER=todolist_app
+MYSQL_PASSWORD=replace_with_a_strong_app_password
+MYSQL_HOST=127.0.0.1
+MYSQL_PORT=3306

.gitignore

@@ -0,0 +1,7 @@
+.env
+.venv/
+__pycache__/
+*.py[cod]
+todos.json*
+db_test.py
+db_insert_test.py

README.md

@@ -0,0 +1,129 @@
+# TodoList 全栈项目（FastAPI + MySQL）
+
+这是一个用于学习后端开发的 TodoList 项目。前端由 Nginx 提供，`/api` 请求反向代理到 FastAPI，FastAPI 使用参数化 SQL 读写 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 后端
+frontend/index.html         前端页面
+compose.yaml                MySQL Docker Compose 配置
+schema.sql                  数据库建表脚本
+requirements.txt            Python 依赖及版本
+.env.example                环境变量示例（不含真实密码）
+deploy/nginx-todolist.conf  Nginx 站点配置
+deploy/todolist.service     systemd 服务配置
+验收记录.md                  已完成测试和已知限制
+```
+
+## 环境要求
+
+- Windows + WSL2 Ubuntu（当前部署方式）
+- Python 3.12 或兼容版本
+- Docker Engine 与 Docker Compose 插件
+- Nginx
+- systemd（用于后台运行 FastAPI）
+
+## 1. 准备 Python 环境
+
+```bash
+cd /home/dwh/code/fastapi_todolist
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install -r requirements.txt
+```
+
+如果部署用户或目录不同，需要同步修改 `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://192.168.10.55:8080`。该地址属于环境配置，不应视为固定生产地址。
+
+## API
+
+| 方法 | 路径 | 说明 |
+|---|---|---|
+| GET | `/health` | 健康检查 |
+| GET | `/todos` | 获取全部任务 |
+| POST | `/todos` | 新增任务 |
+| PATCH | `/todos/{todo_id}` | 修改任务文字或完成状态 |
+| DELETE | `/todos/{todo_id}` | 删除任务 |
+
+Nginx 对外使用 `/api` 前缀，例如浏览器访问 `/api/todos`，代理到 FastAPI 的 `/todos`。
+
+## 安全说明
+
+- 所有带用户数据的 SQL 均使用参数化查询，不使用 f-string 拼接。
+- `.env` 和 MySQL 数据卷不在交付包内。
+- 交付包中的 `.env.example` 只有占位符。

compose.yaml

@@ -0,0 +1,17 @@
+services:
+  mysql:
+    image: mysql:8.4
+    container_name: todolist_mysql
+    restart: unless-stopped
+    environment:
+      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
+      MYSQL_DATABASE: ${MYSQL_DATABASE}
+      MYSQL_USER: ${MYSQL_USER}
+      MYSQL_PASSWORD: ${MYSQL_PASSWORD}
+    ports: 
+      - "127.0.0.1:3306:3306"
+    volumes:
+      - mysql_data:/var/lib/mysql
+
+volumes:
+  mysql_data:

deploy/nginx-todolist.conf

@@ -0,0 +1,19 @@
+server {
+    listen 80 default_server;
+    listen [::]:80 default_server;
+
+    server_name _;
+
+    root /var/www/todolist;
+    index index.html;
+
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+
+    location /api/ {
+        proxy_pass http://127.0.0.1:8000/;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+    }
+}

deploy/todolist.service

@@ -0,0 +1,15 @@
+[Unit]
+Description=TodoList FastAPI service
+After=network.target
+
+[Service]
+Type=simple
+User=dwh
+WorkingDirectory=/home/dwh/code/fastapi_todolist
+ExecStart=/home/dwh/code/fastapi_todolist/.venv/bin/uvicorn main:app --host 127.0.0.1 --port 8000
+Restart=always
+RestartSec=3
+Environment=PYTHONUNBUFFERED=1
+
+[Install]
+WantedBy=multi-user.target

frontend/index.html

@@ -0,0 +1,337 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>待办清单</title>
+  <style>
+    :root {
+      color-scheme: light;
+      font-family: Arial, Helvetica, sans-serif;
+      background: #f5f7fb;
+      color: #172033;
+    }
+
+    * {
+      box-sizing: border-box;
+    }
+
+    body {
+      margin: 0;
+      min-height: 100vh;
+      display: flex;
+      align-items: flex-start;
+      justify-content: center;
+      padding: 48px 18px;
+    }
+
+    main {
+      width: min(760px, 100%);
+      background: #ffffff;
+      border: 1px solid #dfe5ef;
+      border-radius: 8px;
+      box-shadow: 0 16px 40px rgba(23, 32, 51, 0.08);
+      overflow: hidden;
+    }
+
+    header {
+      padding: 28px 30px 18px;
+      border-bottom: 1px solid #e8edf5;
+    }
+
+    h1 {
+      margin: 0 0 8px;
+      font-size: 28px;
+      line-height: 1.2;
+    }
+
+    .status {
+      min-height: 20px;
+      color: #657189;
+      font-size: 14px;
+    }
+
+    .composer {
+      display: flex;
+      gap: 10px;
+      padding: 20px 30px;
+      border-bottom: 1px solid #e8edf5;
+      background: #fbfcff;
+    }
+
+    input[type="text"] {
+      flex: 1;
+      min-width: 0;
+      height: 42px;
+      border: 1px solid #cbd5e1;
+      border-radius: 6px;
+      padding: 0 12px;
+      font-size: 15px;
+      outline: none;
+    }
+
+    input[type="text"]:focus {
+      border-color: #2563eb;
+      box-shadow: 0 0 0 3px rgba(37, 99, 235, 0.15);
+    }
+
+    button {
+      height: 42px;
+      border: 0;
+      border-radius: 6px;
+      padding: 0 14px;
+      background: #2563eb;
+      color: #ffffff;
+      font-size: 14px;
+      cursor: pointer;
+    }
+
+    button.secondary {
+      background: #e8edf5;
+      color: #172033;
+    }
+
+    button.danger {
+      background: #dc2626;
+    }
+
+    button:disabled {
+      opacity: 0.55;
+      cursor: not-allowed;
+    }
+
+    ul {
+      list-style: none;
+      margin: 0;
+      padding: 0;
+    }
+
+    li {
+      display: grid;
+      grid-template-columns: auto 1fr auto;
+      gap: 12px;
+      align-items: center;
+      padding: 16px 30px;
+      border-bottom: 1px solid #edf1f7;
+    }
+
+    li:last-child {
+      border-bottom: 0;
+    }
+
+    .task {
+      min-width: 0;
+      font-size: 16px;
+      overflow-wrap: anywhere;
+    }
+
+    .task.done {
+      color: #7b879c;
+      text-decoration: line-through;
+    }
+
+    .actions {
+      display: flex;
+      gap: 8px;
+    }
+
+    .empty {
+      padding: 34px 30px;
+      color: #657189;
+      text-align: center;
+    }
+
+    @media (max-width: 560px) {
+      body {
+        padding: 18px 10px;
+      }
+
+      header,
+      .composer,
+      li,
+      .empty {
+        padding-left: 16px;
+        padding-right: 16px;
+      }
+
+      .composer {
+        flex-direction: column;
+      }
+
+      li {
+        grid-template-columns: auto 1fr;
+      }
+
+      .actions {
+        grid-column: 1 / -1;
+        justify-content: flex-end;
+      }
+    }
+  </style>
+</head>
+<body>
+  <main>
+    <header>
+      <h1>待办清单</h1>
+      <div id="status" class="status">正在连接...</div>
+    </header>
+
+    <form id="todoForm" class="composer">
+      <input id="taskInput" type="text" placeholder="写下一件要做的事" autocomplete="off" maxlength="200">
+      <button type="submit">添加</button>
+    </form>
+
+    <ul id="todoList"></ul>
+  </main>
+
+  <script>
+    const API_URL = "/api";
+    const statusEl = document.getElementById("status");
+    const formEl = document.getElementById("todoForm");
+    const inputEl = document.getElementById("taskInput");
+    const listEl = document.getElementById("todoList");
+
+    let todos = [];
+
+    function setStatus(message) {
+      statusEl.textContent = message;
+    }
+
+    async function api(path, options = {}) {
+      const response = await fetch(`${API_URL}${path}`, {
+        headers: {
+          "Content-Type": "application/json",
+          ...(options.headers || {})
+        },
+        ...options
+      });
+
+      if (!response.ok) {
+        const error = await response.json().catch(() => ({ detail: response.statusText }));
+        throw new Error(error.detail || "Request failed");
+      }
+
+      return response.json();
+    }
+
+    function renderTodos() {
+      listEl.innerHTML = "";
+
+      if (todos.length === 0) {
+        const empty = document.createElement("li");
+        empty.className = "empty";
+        empty.textContent = "暂时没有任务。";
+        listEl.appendChild(empty);
+        return;
+      }
+
+      for (const todo of todos) {
+        const item = document.createElement("li");
+
+        const checkbox = document.createElement("input");
+        checkbox.type = "checkbox";
+        checkbox.checked = todo.completion;
+        checkbox.addEventListener("change", () => updateTodo(todo.id, { completion: checkbox.checked }));
+
+        const task = document.createElement("div");
+        task.className = todo.completion ? "task done" : "task";
+        task.textContent = todo.task;
+
+        const actions = document.createElement("div");
+        actions.className = "actions";
+
+        const editButton = document.createElement("button");
+        editButton.type = "button";
+        editButton.className = "secondary";
+        editButton.textContent = "编辑";
+        editButton.addEventListener("click", () => editTodo(todo));
+
+        const deleteButton = document.createElement("button");
+        deleteButton.type = "button";
+        deleteButton.className = "danger";
+        deleteButton.textContent = "删除";
+        deleteButton.addEventListener("click", () => deleteTodo(todo.id));
+
+        actions.append(editButton, deleteButton);
+        item.append(checkbox, task, actions);
+        listEl.appendChild(item);
+      }
+    }
+
+    async function loadTodos() {
+      try {
+        setStatus("正在加载...");
+        todos = await api("/todos");
+        renderTodos();
+        const completed = todos.filter((todo) => todo.completion).length;
+        setStatus(`共 ${todos.length} 项，已完成 ${completed} 项`);
+      } catch (error) {
+        setStatus(`连接失败：${error.message}`);
+      }
+    }
+
+    async function createTodo(task) {
+      await api("/todos", {
+        method: "POST",
+        body: JSON.stringify({ task })
+      });
+      await loadTodos();
+    }
+
+    async function updateTodo(id, updateData) {
+      await api(`/todos/${id}`, {
+        method: "PATCH",
+        body: JSON.stringify(updateData)
+      });
+      await loadTodos();
+    }
+
+    async function editTodo(todo) {
+      const task = prompt("修改任务", todo.task);
+
+      if (task === null) {
+        return;
+      }
+
+      const trimmed = task.trim();
+
+      if (trimmed === "") {
+        setStatus("任务内容不能为空。 ");
+        return;
+      }
+
+      await updateTodo(todo.id, { task: trimmed });
+    }
+
+    async function deleteTodo(id) {
+      await api(`/todos/${id}`, { method: "DELETE" });
+      await loadTodos();
+    }
+
+    formEl.addEventListener("submit", async (event) => {
+      event.preventDefault();
+
+      const task = inputEl.value.trim();
+
+      if (task === "") {
+        setStatus("任务内容不能为空。 ");
+        return;
+      }
+
+      formEl.querySelector("button").disabled = true;
+
+      try {
+        await createTodo(task);
+        inputEl.value = "";
+      } catch (error) {
+        setStatus(`添加失败：${error.message}`);
+      } finally {
+        formEl.querySelector("button").disabled = false;
+        inputEl.focus();
+      }
+    });
+
+    loadTodos();
+  </script>
+</body>
+</html>

main.py

@@ -0,0 +1,127 @@
+from fastapi import FastAPI, HTTPException
+from fastapi.middleware.cors import CORSMiddleware
+from pydantic import BaseModel
+import os
+import mysql.connector
+from dotenv import load_dotenv
+
+load_dotenv()
+
+app = FastAPI()
+app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+)
+
+
+def get_db_connection():
+    connection = mysql.connector.connect(
+            host = os.getenv("MYSQL_HOST"),
+            port = int(os.getenv("MYSQL_PORT")),
+            user = os.getenv("MYSQL_USER"),
+            password = os.getenv("MYSQL_PASSWORD"),
+            database = os.getenv("MYSQL_DATABASE"),
+            )
+    return connection
+
+
+class todocreate(BaseModel):
+    task: str
+
+class todoupdate(BaseModel):
+    completion: bool  | None = None
+    task: str | None = None
+
+class todoresponse(BaseModel):
+    id: int
+    task: str
+    completion: bool
+@app.get("/health")
+def health():
+    return {"status":"ok"}
+
+@app.get("/todos", response_model=list[todoresponse])
+def todos_get():
+    connection = get_db_connection()
+    cursor = connection.cursor(dictionary = True)
+    try:
+        cursor.execute("SELECT id, task, completion FROM todos")
+        results = cursor.fetchall()
+        return results
+    finally:
+            cursor.close()
+            connection.close()
+
+@app.post("/todos", response_model=todoresponse)
+def todos_create(todo_data:todocreate):
+    connection = get_db_connection()
+    cursor = connection.cursor(dictionary = True)
+    try:
+        sql = "INSERT INTO todos (task) VALUES (%s)"
+        params = (todo_data.task,)
+        cursor.execute(sql,params)
+        connection.commit()
+        new_id = cursor.lastrowid
+        new_todos = {
+        "id": new_id,
+        "task": todo_data.task, 
+        "completion": False
+        }
+        return new_todos
+    except mysql.connector.Error:
+        connection.rollback()
+        raise
+    finally:
+        cursor.close()
+        connection.close()
+@app.patch("/todos/{todo_id}", response_model=todoresponse)
+def todos_patch(todo_id:int, update_data:todoupdate):
+    connection = get_db_connection()
+    cursor = connection.cursor(dictionary = True)
+    try:
+        sql = """
+        UPDATE todos
+        SET task = COALESCE(%s,task),
+        completion = COALESCE(%s,completion)
+        WHERE id = %s
+        """
+        params = (update_data.task,update_data.completion,todo_id,)
+        cursor.execute(sql,params)
+        connection.commit()
+        select_params = (todo_id,)
+        cursor.execute("SELECT id, task, completion FROM todos WHERE id = %s",select_params)
+        result = cursor.fetchone() 
+
+        if result is None:
+            raise HTTPException(status_code = 404, detail = "Todo not found")
+        return result
+    except mysql.connector.Error:
+        connection.rollback()
+        raise
+    finally:
+        cursor.close()
+        connection.close()
+
+@app.delete("/todos/{todo_id}", response_model=todoresponse)
+def todos_delete(todo_id:int):
+    connection = get_db_connection()
+    cursor = connection.cursor(dictionary = True)
+    try:
+        params = (todo_id,)
+        cursor.execute("SELECT id,task,completion FROM todos WHERE id = %s",params)
+        result = cursor.fetchone()
+        if result is None:
+            raise HTTPException(status_code = 404, detail = "Todo not found")
+        sql = "DELETE FROM todos WHERE id = %s"
+        cursor.execute(sql,params)
+        connection.commit()
+        return result
+    except mysql.connector.Error:
+        connection.rollback()
+        raise
+    finally:
+        cursor.close()
+        connection.close()

requirements.txt

@@ -0,0 +1,15 @@
+annotated-doc==0.0.4
+annotated-types==0.7.0
+anyio==4.14.1
+click==8.4.2
+fastapi==0.139.0
+h11==0.16.0
+idna==3.18
+mysql-connector-python==9.7.0
+pydantic==2.13.4
+pydantic_core==2.46.4
+python-dotenv==1.2.2
+starlette==1.3.1
+typing-inspection==0.4.2
+typing_extensions==4.16.0
+uvicorn==0.51.0

schema.sql

@@ -0,0 +1,6 @@
+CREATE TABLE IF NOT EXISTS todos (
+    id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+    task VARCHAR(200) NOT NULL,
+    completion BOOLEAN NOT NULL DEFAULT FALSE,
+    PRIMARY KEY (id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

验收记录.md

@@ -0,0 +1,45 @@
+# TodoList 交付验收记录
+
+验收日期：2026-07-16
+
+## 已完成
+
+- FastAPI 已从 `todos.json` 迁移到 MySQL 8.4。
+- MySQL 通过 Docker Compose 运行，数据保存在命名卷 `mysql_data`。
+- Python 使用 `mysql-connector-python` 执行原始 SQL。
+- 数据库连接配置从 `.env` 读取，代码中未写死密码。
+- INSERT、UPDATE、DELETE 使用参数化 SQL，并包含提交、回滚和资源关闭逻辑。
+- GET、POST、PATCH、DELETE 已通过本机接口测试。
+- 不存在的 Todo ID 已验证返回 404。
+- 响应模型已将 `completion` 统一输出为 JSON 布尔值。
+- Nginx `/api` 反向代理已通过测试。
+- Windows 局域网地址已成功打开前端。
+- 页面新增、修改、完成状态、删除及刷新持久化链路已完成联调。
+
+## 当前运行链路
+
+```text
+Windows 192.168.10.55:8080
+  -> WSL Nginx :80
+  -> FastAPI 127.0.0.1:8000
+  -> MySQL 127.0.0.1:3306
+```
+
+## 未包含内容
+
+- 真实 `.env` 与数据库密码
+- Python `.venv`
+- MySQL Docker 数据卷
+- 旧 `todos.json` 数据及备份
+- 数据库连接测试脚本
+
+## 已知限制与后续建议
+
+- 当前没有用户登录和权限控制。
+- 当前没有自动化测试。
+- 当前没有 Alembic 等数据库版本迁移工具。
+- 当前每次请求建立一次数据库连接，后续可学习连接池。
+- `task` 的数据库长度上限为 200；建议后续在 Pydantic 请求模型中增加长度和空字符串校验。
+- CORS 当前为宽松配置；正式部署时应限制允许的来源。
+- systemd 文件包含当前用户与项目绝对路径，换机器部署时必须调整。
+- Windows 端口转发和防火墙规则属于当前机器的基础设施配置，未作为通用部署脚本放入本交付包。