44 lines
1.4 KiB
Markdown
44 lines
1.4 KiB
Markdown
|
# 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.
|