qzl
74 lines
2.3 KiB
Markdown
74 lines
2.3 KiB
Markdown
# 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.
|