# Todo Data Protocol

## Scope

Defines the backend/frontend data contract for `/api/v1/todos`.

## Endpoints

| Method | Path | Description |
|---|---|---|
| POST | `/api/v1/todos` | Create todo |
| GET | `/api/v1/todos` | List todos (supports status/priority filter) |
| GET | `/api/v1/todos/{todo_id}` | Get todo detail |
| PATCH | `/api/v1/todos/reorder` | Batch reorder todos |
| PATCH | `/api/v1/todos/{todo_id}` | Update todo |
| POST | `/api/v1/todos/{todo_id}/complete` | Mark todo completed |
| DELETE | `/api/v1/todos/{todo_id}` | Delete todo |

## Field Definitions

- `id`: string (UUID)
- `owner_id`: string (UUID)
- `title`: string, `1..255`
- `description`: string or `null`, max `1000`
- `priority`: int, quadrant value in `[1, 4]`
- `order`: int, zero-based ordering inside the same `priority` bucket, `>= 0`
- `status`: enum string: `pending | done | canceled`
- `completed_at`: datetime string or `null`
- `created_at`: datetime string
- `updated_at`: datetime string
- `schedule_items`: array

## Request Contracts

### Create Todo (`POST /api/v1/todos`)

- required: `title`
- optional: `description`, `priority`, `order`, `schedule_item_ids`
- `order` omitted: backend assigns append position in the target quadrant.

### Update Todo (`PATCH /api/v1/todos/{todo_id}`)

- optional: `title`, `description`, `priority`, `order`, `status`, `schedule_item_ids`
- `order` is interpreted inside the todo's final `priority` quadrant.

### List Todos (`GET /api/v1/todos`)

- query `status`: `pending | done | canceled` (optional)
- query `priority`: integer in `[1, 4]` (optional)

### Reorder Todos (`PATCH /api/v1/todos/reorder`)

- body: `{ items: Array<{ id, priority, order }> }`
- each item requires:
  - `id`: UUID
  - `priority`: integer in `[1, 4]`
  - `order`: integer `>= 0`

### Complete Todo (`POST /api/v1/todos/{todo_id}/complete`)

- body: `{}`
- effect: sets todo status to `done` and updates `completed_at`

## Ordering Rules

- Todo list API returns items sorted by `priority ASC`, then `order ASC`.
- Drag reorder in same quadrant updates `order` to a continuous sequence starting from `0`.
- Drag move across quadrants updates both `priority` and `order`, and source/target quadrants should both stay contiguous from `0`.

## Compatibility Notes

- `due_at` is removed from todo protocol.
- Clients must not send or depend on `due_at` for todo ordering.