Tasks: boards and cards of the shop's own work

Резюме по-русски. Задачи магазина — доски задач (колонки) и карточки на них: название, описание, исполнитель, срок, метки, приоритет, чек-лист, ссылки. Это рабочий инструмент команды, а не заявки покупателей: права tasks:read / tasks:write, заявки ими не открываются и наоборот; колонки и саму доску задач правит тот же tasks:write (с 2026-09-24, W4). Решения владельца 2026-09-24: доски задач видят все участники магазина, непустую доску удалить нельзя, правила переходов досок заявок к задачам не применяются.

Status: draft · Verified: 2026-09-24, integration tests on PostgreSQL (TestTask*, handlers and PAT gates) and a wire probe of the real HTTP gateway (§7) · Owner: CRM line (backend-3D#15) Serves: GET /docs/tasks

1. What you can do here

Keep the shop's own to-do list through a token: list the task boards and their columns, create a board, create, read, edit, move and delete task cards, filter them by board, column, assignee or overdue. A card carries a title, a description, an assignee (a shop member by id or any name as text), a due date and an extra object with labels, priority, a checklist and links — the Trello vocabulary on purpose.

The OpenAPI of this area alone (eight task operations, nine shared board and column operations and the key passport, about 42 KB) is GET /openapi.json?scope=tasks; every scope and its operations is GET /docs/scopes.json.

2. Decide first (forks)

A task board is a board with view: "tasks". It never appears in the leads list (GET /sandboxes without view), a form never drops a lead onto it, and a task is never created on a leads board (TASK_BOARD_MISMATCH).

3. Objects, endpoints and the wire

Board — the same object as a leads board (Sandbox): id, name, view: "tasks", columns[] (id, label, kind: intake|normal, sort_order, settings). A new board gets three columns: the intake (kind: intake) and two normal ones, labelled in Russian — «К выполнению · В работе · Готово» — whatever the shop language; rename them with PUT /sandbox-columns/{id} (tasks:write). A new shop has no task board: GET /task-boards answering {"result": []} is normal, create one.

Board and column endpoints are shared with leads boards. The right is chosen by the kind of the board they touch: a task board needs tasks:*, a leads board forms:*. A key with only forms:write is refused on a task board, a key with only tasks:write on a leads board — 403 PAT_SCOPE_MISSING naming the scope that board needs.

Task — id, sandbox_id, column_id, title, description, position (dense order inside the column, 0..n-1), assignee_user_id (0 — none), assignee_name, due_at, extra, created_at, updated_at, created_by, updated_by (0 — unknown; a token write records the user who issued the key).

Every task operation is private to the token's shop: another shop's task answers exactly like a missing one. Reads work for a dev-contour key too; writes are live operations, so a dev key gets PAT_CONTOUR_MISMATCH — tasks have no draft. capabilities.tasks_read / tasks_write in GET /v1/account/token say what this key may call.

Wire gotchas

• 64-bit ids are JSON strings on output: "id": "42", "sandbox_id": "7", "column_id": "19". Input accepts both 19 and "19". 32-bit fields (position, assignee_user_id, created_by) are numbers.
• `extra` is base64 of a raw JSON object, both ways — it is a bytes field. Send "extra": "eyJwcmlvcml0eSI6ImhpZ2gifQ==" for {"priority":"high"}. A JSON object in its place is refused with 400 INVALID_REQUEST. An empty card reads "extra": "e30=" ({}).
• `column_id: 0` means the intake of the board on create. On move column_id is required (≥ 1).
• `due_at` is an RFC3339 string, "" means no due date. Any offset is accepted; it is returned in UTC (2026-10-01T18:00:00+03:00 reads back as 2026-10-01T15:00:00Z). Anything else is TASK_BAD_DUE_AT.
• `PATCH` knows presence. A field you do not send is left alone. assignee_user_id: 0 removes the member, due_at: "" removes the due date, assignee_name: "" clears the name. extra: absent or "" — unchanged, "e30=" ({}) — reset.
• Unknown body fields are refused, not ignored: PATCH with column_id answers 400 invalid request body: column_id — moving is PUT /tasks/{id}/position.
• `DELETE` needs a body: -d '{}'. Without it the gateway answers 400 invalid request body.
• extra is stored normalised: empty lists dropped, key order not kept (the column is JSONB). Compare meaning, not bytes.

extra whitelist

{
  "labels": ["seo", "urgent-fix"],
  "priority": "high",
  "checklist": [{"text": "Write the brief", "done": true}],
  "links": [{"title": "Spec", "url": "https://example.com/spec"}]
}

Any other key, at any depth, is refused with TASK_BAD_EXTRA and the reason after the code. A link must start with http:// or https://. Limits: §6.

Refusals

Proto validation (empty title, position < 0, over-long strings) answers 400 with the field name in the text.

Webhooks

task.created, task.updated (fields), task.moved (column or position, plus from_column_id) and task.deleted (the card before deletion) carry the card without description; ids are numbers there and extra is a JSON object. Any shop member may subscribe in the cabinet — class operational (/docs/webhooks §6).

4. Recipes

$API is the API base, $T is Bearer vz_pat_….

4.1 Find or create a board.

curl -s "$API/task-boards" -H "Authorization: $T"
curl -s -X POST "$API/task-boards" -H "Authorization: $T" -d '{"name":"Launch"}'

Verify: the board is in GET /task-boards with view: "tasks" and three columns, the first with kind: "intake".

4.2 Create a task with a checklist.

EXTRA=$(printf '%s' '{"priority":"high","checklist":[{"text":"Draft","done":false}]}' | base64 | tr -d '\n')
curl -s -X POST "$API/tasks" -H "Authorization: $T" -d '{
  "sandbox_id": "7", "column_id": 0, "title": "Prepare the autumn banner",
  "assignee_name": "Anna (designer)", "due_at": "2026-10-01T18:00:00Z",
  "extra": "'"$EXTRA"'"}'

Verify: GET /tasks/{id} returns the card in the intake column with the last position; jq -r .result.extra | base64 -d prints your object.

4.3 Move a card to "in progress", on top.

curl -s -X PUT "$API/tasks/42/position" -H "Authorization: $T" -d '{"column_id":"19","position":0}'

Verify: GET /tasks?column_id=19 lists it first; the source column is renumbered without a gap.

4.4 Tick a checklist item. extra is replaced whole: read the task, decode extra, change the item, encode, PATCH /tasks/{id} with the new extra. Verify by reading it back.

4.5 Overdue work of one person. GET /tasks?assignee_user_id=12&overdue=true — then drop the cards that sit in your "done" column yourself (§5).

4.6 Delete. curl -s -X DELETE "$API/tasks/42" -H "Authorization: $T" -d '{}'. Verify: GET /tasks/42 answers TASK_NOT_FOUND.

5. Silently ignored

• Unknown query parameters of `GET /tasks`. A misspelled filter (board_id=7, page.limit=5) is dropped and the answer is every task of the shop with a 200. The filters are exactly sandbox_id, column_id, assignee_user_id, overdue. Compare the count before and after a filter.
• No pagination. GET /tasks returns the whole filtered list; page.* parameters do nothing.
• Lead-board rules do not apply to tasks. A task board column can store settings (stage, no_return, require_comment, limit, deadline_days) and the board a mode through the leads endpoints; for tasks they are stored and have no effect — any card moves to any column of its board.
• `overdue=true` ignores the column. It is due_at < now(), so a finished card in "Готово" with a past due date is still overdue.
• `position` past the end puts the card at the tail. The actual position is in result.position.
• `extra: ""` on `PATCH` changes nothing; a reset is {} ("e30=").
• `assignee_name` is never checked and survives removing assignee_user_id: both are independent fields.

6. Limits

{
  "title_max_chars": 255,
  "description_max_chars": 20000,
  "assignee_name_max_chars": 255,
  "board_name_max_chars": 255,
  "extra_max_bytes": 16384,
  "extra_keys": ["labels", "priority", "checklist", "links"],
  "labels_max": 10,
  "label_max_chars": 32,
  "priority": ["low", "normal", "high", "urgent"],
  "checklist_max": 50,
  "checklist_text_max_chars": 200,
  "links_max": 20,
  "link_title_max_chars": 120,
  "link_url_max_bytes": 2000,
  "link_url_schemes": ["http", "https"],
  "list_pagination": false
}

extra numbers are checked against the domain constants by TestTasksAreaLimitsMatchDomain; string lengths come from the proto validation rules of api/catalog/catalog.proto.

7. How this was verified

• go test -tags=integration ./internal/api/catalog/ -run 'TestTask' on PostgreSQL (cart_dev): CRUD, dense renumbering on moves inside and between columns, concurrent moves, filters, shop isolation, the leads/tasks board boundary, column and board deletion, PAT (tasks:read reads, no scope — PAT_SCOPE_MISSING, dev key writing — PAT_CONTOUR_MISMATCH).
• -run 'TestSandboxScopesByView': board and column endpoints by the board's kind — tasks:write manages a task board and is refused on a leads board, forms:write the other way round, a foreign board stays SANDBOX_NOT_FOUND.
• Wire probe, 2026-09-24: the generated HTTP handlers of the Catalog service with the production JSON marshaler and gateway error writer, behind a stub service. Measured: int64 fields as strings, extra as base64, extra as an object → 400, PATCH with column_id → 400, DELETE without a body → 400 and with {} → 200, assignee_user_id: 0 reaches the handler as "present", GET /tasks?page.limit=5 → 200.
• Domain unit tests of the extra whitelist (internal/core/domain/task_test.go) and this document's §6 against the constants (internal/api/discovery/area_scopes_test.go).