# Todo Data Protocol

## Scope

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

## 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.

## 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.