01-需求分析与项目规则

把 TODO 工具改成 API，支持增删改查，能给前端用。

{
  "error": {
    "code": "TODO_TITLE_REQUIRED",
    "message": "title 不能为空"
  }
}

GET /health

{
  "status": "ok"
}

POST /todos
Content-Type: application/json

{
  "title": "整理 API 验收清单"
}

{
  "id": 1,
  "title": "整理 API 验收清单",
  "completed": false,
  "created_at": "2026-09-05T10:30:00Z",
  "updated_at": "2026-09-05T10:30:00Z"
}

GET /todos

{
  "items": [
    {
      "id": 1,
      "title": "整理 API 验收清单",
      "completed": false,
      "created_at": "2026-09-05T10:30:00Z",
      "updated_at": "2026-09-05T10:30:00Z"
    }
  ],
  "count": 1
}

{
  "items": [],
  "count": 0
}

PATCH /todos/1/complete
Content-Type: application/json

{}

{
  "id": 1,
  "title": "整理 API 验收清单",
  "completed": true,
  "created_at": "2026-09-05T10:30:00Z",
  "updated_at": "2026-09-05T10:35:00Z"
}

DELETE /todos/1

CREATE TABLE todos (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  title TEXT NOT NULL,
  completed INTEGER NOT NULL DEFAULT 0,
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL
);

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "error": {
    "code": "TODO_TITLE_REQUIRED",
    "message": "title 不能为空"
  }
}

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "code": "TODO_NOT_FOUND",
    "message": "待办 99 不存在"
  }
}

# TODO API

## 项目

本地单用户 TODO HTTP API。Python 3.11、FastAPI、Uvicorn、SQLite、pytest。
服务只监听 127.0.0.1:8000，不是公网服务。

## 常用命令

- 安装依赖：`python -m pip install -r requirements.txt`
- 启动服务：`python -m uvicorn app.main:app --host 127.0.0.1 --port 8000`
- 运行测试：`python -m pytest -q`
- 检查语法：`python -m compileall app tests`

## 目录约定

- `app/`：应用代码
- `tests/`：自动化测试
- `data/`：本地运行数据，不提交数据库文件
- `requirements.txt`：已批准的运行和测试依赖

## API 规则

- 所有错误使用 `error.code` 和 `error.message` 的 JSON 结构。
- 标题去除首尾空白后必须为 1 到 200 个字符。
- 删除成功返回 204 且无响应体。
- 完成接口可以重复调用，但不支持撤销完成。
- 时间使用 UTC ISO 8601 字符串，ID 由数据库生成。

## 修改边界

- 不修改旧 CLI、生产配置、部署文件或数据库文件，除非任务明确授权。
- 不新增依赖；确需新增时先说明理由并等待确认。
- 不访问外部服务，不提交、不推送、不发布，除非任务明确授权。
- 不把密钥、个人数据、`.env`、日志或 `data/*.db` 加入 Git。

## 完成前必须做

1. 先读取相关代码和测试，再提出计划。
2. 修改后运行 `python -m pytest -q`。
3. 再运行 `python -m compileall app tests`。
4. 检查 `git diff --check` 和 `git status --short`。
5. 汇报变更文件、测试输出、未验证假设和回滚方式。

请先只读检查当前仓库，不要修改文件、安装依赖、访问网络、提交或推送。

背景：我们要做一个本地单用户 TODO HTTP API，使用 Python 3.11、FastAPI、Uvicorn、SQLite 和 pytest。

请先读取：
- 现有 README、依赖文件和目录结构；
- 现有 CLI 或 TODO 相关代码；
- 现有测试和 Git 状态；
- 当前生效的 AGENTS.md。

请输出四部分：
1. 仓库现状和可复用代码；
2. 与下面需求基线冲突的地方；
3. 需要我确认的问题；
4. 你建议的最小文件变更和验证命令。

本次需求基线：
- GET /health 返回 {"status":"ok"}；
- POST /todos 创建 title，去首尾空白后长度 1 到 200；
- GET /todos 按 id 升序，最多 100 条；
- PATCH /todos/{id}/complete 将 completed 设为 true，重复调用成功；
- DELETE /todos/{id} 成功返回 204 且无响应体；
- 数据保存到 data/todos.db，测试必须使用临时数据库；
- 错误统一为 {"error":{"code":"...","message":"..."}}。

非目标：认证、用户隔离、CORS、公网部署、搜索、标签、截止日期、分页、撤销完成、修改旧 CLI。

在我确认计划前，不要编辑任何文件。

发现：仓库已有 todo.py CLI，但没有 app/、tests/ 或 requirements.txt。
冲突：现有 CLI 使用内存列表，无法满足 API 重启后持久化；本次应新增 API 目录而不改 CLI。
待确认：当前仓库是否已有 FastAPI 依赖和统一错误处理约定？
建议变更：新增 app/main.py、app/db.py、app/models.py、tests/test_todos.py、requirements.txt 或复用现有依赖文件。
建议验证：python -m pytest -q；python -m compileall app tests。

T1 仓库/依赖确认
  |
  v
T2 数据访问边界
  |
  +--> T3 读取与健康检查
  |       |
  +------>+--> T4 创建与校验
                  |
                  v
            T5 完成与删除
                  |
                  v
            T6 集成验证与交接

项目：本地单用户 TODO API

已确认目标：
- GET /health -> 200 {"status":"ok"}
- POST /todos -> 201，title 去首尾空白后 1-200 字符
- GET /todos -> 200，items 按 id 升序，最多 100 条
- PATCH /todos/{id}/complete -> 200，completed=true，重复调用成功
- DELETE /todos/{id} -> 204，无响应体
- 数据持久化到 data/todos.db，测试使用临时数据库
- 错误统一为 error.code + error.message JSON

明确非目标：
- 认证、用户隔离、CORS、公网部署
- PostgreSQL、Redis、搜索、标签、截止日期、分页
- 撤销完成、批量操作、前端页面
- 修改旧 CLI、安装未确认依赖、提交、推送、发布

必须遵守的项目规则：
- 先读代码并给计划，再编辑
- 不把数据库、日志、.env、密钥加入 Git
- 修改后运行 python -m pytest -q
- 再运行 python -m compileall app tests
- 最后检查 git diff --check 和 git status --short

待执行任务：T1 -> T2 -> T3 -> T4 -> T5 -> T6。
当前停点：先完成 T1 的仓库、依赖和现有测试调查，不要直接编码。

下一页需要产出：
- 按文件和验证命令展开的执行计划；
- 每个任务的完成条件和回滚点；
- Codex 会话中可直接使用的开发提示词。