# software-testing-todo-list

**Repository Path**: Mather/software-testing-todo-list

## Basic Information

- **Project Name**: software-testing-todo-list
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-08-26
- **Last Updated**: 2026-09-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 序事 Todo List

<p align="center">
  <img src="desktop.png" alt="序事 Todo List 桌面端界面" width="860" />
</p>

一个由 **Python Flask + Vue 3 + Vite** 构建的现代 Todo List 全栈项目。前后端分别放在 `backend/` 与 `frontend/` 文件夹中，支持任务的**增删改查**、完成状态切换、优先级、截止日期、搜索与筛选。

## 项目结构

```text
todo-list/
├── backend/
│   ├── src/todo_api/
│   │   ├── app.py          # Flask 应用、路由与参数校验
│   │   └── storage.py      # MySQL 存储与 JSON 文件降级存储
│   ├── tests/test_api.py   # API CRUD 测试
│   ├── .python-version     # uv 默认使用的 Python 版本（3.14）
│   ├── pyproject.toml      # uv 项目、依赖与清华 PyPI 镜像配置
│   ├── .env.example
│   └── Dockerfile
├── frontend/
│   ├── src/
│   │   ├── App.vue         # 页面状态与交互
│   │   ├── api.js          # API 请求封装
│   │   ├── components/     # Todo 表单与列表项
│   │   └── styles.css       # 响应式视觉样式
│   ├── package.json
│   ├── .npmrc              # npmmirror 镜像源及相关二进制依赖下载配置
│   ├── vite.config.js
│   └── Dockerfile
├── docs/
│   └── api.md              # 完整 API 接口文档
├── docker-compose.yml
└── README.md
```

## 软件环境

- **Python 3.8～3.14**：后端支持该范围内的所有 Python 次要版本，推荐使用 **Python 3.14**
- 项目通过 `.python-version` 将本地默认版本设为 **Python 3.14**；`uv.lock` 包含适用于 Python 3.8～3.14 的依赖分支
- **uv 0.4+**：Python 环境与依赖管理
- **Node.js 20.19+ 或 22.12+、npm 10+**：Vue 3 前端构建
- 可选：**MySQL 5.7**。没有可用数据库时，后端会自动改用 JSON 文件。

## 本地开发

### 1. 启动后端

```bash
cd backend           #切换到后端目录
cp .env.example .env # 仅第一次拉取项目需要

uv sync --extra dev # 创建虚拟环境

uv run todo-api     #运行服务
```

后端默认监听 `http://127.0.0.1:5000`。首次启动会尝试连接 `.env` 中的 **MySQL 5.7**，并自动创建数据库 `todo_list` 与 `todos` 表。若连接超时、认证失败或数据库未启动，API 会自动使用 `backend/data/todos.json`，无需修改代码即可继续开发。

强制使用文件存储：

```env
TODO_STORAGE=file
```

### 2. 启动前端

另开一个终端：

```bash
cd frontend          # 切换到前端目录
npm install          # 安装依赖
cp .env.example .env # 复制环境变量
npm run dev          # 运行本地服务器
```

浏览器访问 `http://127.0.0.1:5173`。Vite 开发服务器会将 `/api` 请求代理到 Flask 的 5000 端口。

## API 接口

后端共提供 **6 个 REST API 接口**，覆盖服务状态检测和工作清单的完整增删改查：

1. 服务状态检测。
2. 获取全部工作清单。
3. 获取单条工作清单。
4. 创建工作清单。
5. 修改工作清单。
6. 删除工作清单。

接口的请求路径、请求方法、请求头、参数表格以及成功和失败响应示例，请查看 [完整 API 接口文档](docs/api.md)。

## 测试与构建

```bash
cd backend
uv run pytest

cd ../frontend
npm run build
```

后端测试使用临时 JSON 文件，不依赖 MySQL；前端构建产物位于 `frontend/dist/`。

## Docker Compose 部署

项目提供包含 **MySQL 5.7、Waitress 托管的 Flask API、Nginx 前端** 的完整编排：

后端镜像默认使用推荐的 **Python 3.14**。如需单独构建其他受支持版本，可在 `backend/` 目录传入构建参数，例如 `docker build --build-arg PYTHON_VERSION=3.8 .`；`PYTHON_VERSION` 可选择 **3.8～3.14**。

```bash
docker compose up --build -d
```

访问 `http://127.0.0.1:8080`。查看日志：

```bash
docker compose logs -f backend
```

停止服务但保留数据库数据：

```bash
docker compose down
```

如需同时删除数据卷，请确认数据已备份后执行 `docker compose down -v`。

## 学习建议

1. 从 `backend/src/todo_api/app.py` 了解 Flask 路由、请求校验与 CORS。
2. 阅读 `backend/src/todo_api/storage.py`，对比抽象存储接口、MySQL 参数化 SQL 和原子 JSON 写入。
3. 从 `frontend/src/App.vue` 观察 Vue 3 Composition API、响应式状态和 CRUD 调用。
4. 修改 `frontend/src/components/TodoForm.vue`，练习表单校验与组件事件通信。
5. 用浏览器开发者工具查看 Network 面板，理解前端如何调用 REST API。

## 设计说明

- 无登录功能，适合个人本地使用或内网部署。
- API 默认开放 CORS；生产环境建议设置 `CORS_ORIGINS` 为实际前端域名。
- MySQL 连接信息只通过环境变量注入，不写入源码。
- 文件降级存储使用临时文件替换，避免进程中断时留下半写入 JSON。