social-app/docs/protocols/models/todo.md

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.