spec-feature 1.1.2 → 1.1.4

package/spec/features/telegram-initData/plan.md

@@ -0,0 +1,46 @@
+# Implementation Plan
+
+**Plan:** На стороне клиента нужно отправлять на сервер telegram initData. На стороне сервера нужно добавить логику валидации initData. Результат выводить в console.log. Используется npm пакет `@telegram-apps/init-data-node`.
+
+## Data sources / schemas
+
+- InitData получается на клиенте из `window.Telegram.WebApp.initData` в виде строки (search parameters format: `query_id=...&user=...&auth_date=...&hash=...`).
+- Bot Token для валидации берется из переменных окружения сервера (например, `TELEGRAM_BOT_TOKEN`).
+- Данные передаются через HTTP запрос с телом запроса (POST) или query параметром (GET). Рекомендуется использовать POST для безопасности.
+- На сервере initData принимается как строка и передается в функцию `validate` из пакета `@telegram-apps/init-data-node`.
+- Не требуется создание специальных схем базы данных или миграций для этой функциональности.
+
+## Contracts and interfaces
+
+- Клиентский composable (расширение `useTelegram` или новый метод): метод `sendInitDataToServer()` или `validateInitData()`, который получает initData и отправляет на сервер.
+- Серверный API endpoint: `POST /api/telegram/validate-init-data` (или `/api/validate-init-data`) принимает body с полем `initData: string`.
+- Response формат: `{ success: boolean, message?: string }` или простой статус код без body (результат логируется на сервере).
+- Интерфейс для обработки ошибок: на клиенте используется try-catch, на сервере ошибки валидации перехватываются и логируются через `console.log`.
+- Валидация на сервере использует функцию `validate(initData: string, secretToken: string)` из пакета, которая может выбросить исключения типов: `ERR_AUTH_DATE_INVALID`, `ERR_HASH_INVALID`, `ERR_SIGN_INVALID`, `ERR_EXPIRED`.
+
+## Architecture / Components
+
+- Клиентская часть: расширить существующий composable `useTelegram` в `composables/useTelegram.ts`, добавив метод для получения и отправки initData, или создать отдельный composable `useTelegramInitData` для изоляции логики.
+- HTTP клиент: использовать встроенный `$fetch` из Nuxt или `useFetch` для отправки запроса на серверный endpoint.
+- Серверная часть: создать файл `server/api/telegram/validate-init-data.post.ts` (или `.get.ts` в зависимости от выбранного метода) в формате Nuxt 3 server route.
+- Валидация: установить пакет `@telegram-apps/init-data-node` и импортировать функцию `validate`. Вызвать её с initData и Bot Token из переменных окружения.
+- Логирование: использовать `console.log` для вывода результата валидации. Формат лога: `[Telegram InitData Validation] Success/Error: <message>`.
+- Обработка ошибок: обернуть вызов `validate` в try-catch блок, логировать тип ошибки через `isErrorOfType` если требуется, или просто выводить сообщение ошибки.
+- Инициализация: вызывать отправку initData автоматически после инициализации Telegram WebApp (в плагине `plugins/telegram.client.ts` или в composable при первом обращении).
+
+## Risks
+
+- Если initData недоступен на клиенте (приложение запущено не в Telegram), запрос не должен отправляться или должен обрабатываться корректно на сервере. Митигация: проверка наличия `window.Telegram?.WebApp?.initData` перед отправкой.
+- Bot Token может быть скомпрометирован, если логировать полный токен. Митигация: логировать только результат валидации, не логировать сам токен.
+- Ошибки валидации могут быть связаны с истечением срока действия initData (1 день по умолчанию). Митигация: логировать тип ошибки для диагностики.
+- Пакет `@telegram-apps/init-data-node` может требовать определенную версию Node.js. Митигация: проверить совместимость при установке и использовать последнюю стабильную версию пакета.
+
+## Assumptions
+
+- Bot Token будет предоставлен через переменные окружения и уже настроен для использования с ботом.
+- Nuxt 3 поддерживает создание server routes в директории `server/api/` с автоматической регистрацией endpoints.
+- Пакет `@telegram-apps/init-data-node` установится без проблем и совместим с текущей версией Node.js.
+- Существующий composable `useTelegram` можно расширить без нарушения обратной совместимости, или создание нового composable не вызовет конфликтов.
+- Инициализация Telegram WebApp происходит до момента отправки initData, поэтому данные будут доступны.
+- Для упрощения, endpoint может не возвращать детальную информацию об ошибке клиенту, только логировать на сервере (если не требуется иное поведение для UX).
+

package/spec/features/telegram-initData/spec.md

@@ -0,0 +1,40 @@
+# Telegram InitData Validation
+
+**Specification:** На стороне клиента нужно отправлять на сервер telegram initData. На стороне сервера нужно добавить логику валидации initData. Результат выводить в console.log. Используется npm пакет `@telegram-apps/init-data-node`.
+
+## User Stories
+
+- Как разработчик приложения, я хочу автоматически отправлять telegram initData на сервер при инициализации приложения, чтобы сервер мог проверить подлинность запроса от Telegram.
+- Как администратор системы, я хочу видеть результаты валидации initData в логах сервера, чтобы контролировать безопасность и выявлять потенциальные проблемы аутентификации.
+- Как пользователь Telegram Mini App, я хочу быть уверенным, что мое приложение защищено от несанкционированного доступа через валидацию данных инициализации Telegram.
+
+## Main scenarios and rules
+
+- При инициализации приложения на клиенте необходимо получить `initData` из объекта `window.Telegram.WebApp.initData` (или через Telegram WebApp SDK, если доступен).
+- Клиент отправляет `initData` на серверный API endpoint через HTTP запрос (POST или GET) сразу после инициализации Telegram WebApp или при загрузке приложения.
+- Серверный endpoint принимает `initData` в виде строки (raw search parameters format).
+- На сервере используется функция `validate` из пакета `@telegram-apps/init-data-node` для проверки подписи и валидности данных.
+- В качестве секретного токена для валидации используется Bot Token от Telegram Bot Father (или его хешированная версия).
+- Результат валидации (успех или ошибка) выводится в `console.log` на сервере с понятным сообщением.
+- При ошибке валидации функция `validate` выбрасывает исключение с типом ошибки (`ERR_AUTH_DATE_INVALID`, `ERR_HASH_INVALID`, `ERR_SIGN_INVALID`, `ERR_EXPIRED`), которую нужно обработать и залогировать.
+- По умолчанию функция `validate` проверяет срок действия initData (expiration), который установлен на 1 день (86400 секунд). Это поведение сохраняется без изменений.
+- Если initData отсутствует на клиенте (приложение запущено вне Telegram), клиент должен корректно обработать эту ситуацию и не отправлять запрос на сервер или отправить с соответствующим флагом.
+
+## Non-functional requirements
+
+- Серверная валидация должна выполняться синхронно и быстро (не более 50ms для стандартной валидации).
+- Логирование результатов валидации должно быть информативным и не содержать чувствительных данных (например, не логировать полный Bot Token).
+- Пакет `@telegram-apps/init-data-node` должен быть установлен только в зависимостях серверной части (devDependencies или dependencies, в зависимости от того, используется ли он в production).
+- Код должен быть типизирован с использованием TypeScript, ошибки валидации должны быть корректно обработаны через try-catch блоки.
+- API endpoint должен возвращать стандартный HTTP статус код (например, 200 при успехе, 400 при ошибке валидации).
+- Решение должно следовать принципам KISS и не содержать избыточной логики или сложных абстракций.
+
+## Assumptions
+
+- Bot Token будет храниться в переменных окружения сервера (например, `TELEGRAM_BOT_TOKEN` для Nuxt).
+- Приложение работает в контексте Nuxt 3, серверные роуты создаются в директории `server/api/`.
+- Пакет `@telegram-apps/init-data-node` совместим с Node.js версией, используемой в проекте.
+- Telegram WebApp SDK уже загружен и доступен в приложении через существующий composable `useTelegram`.
+- InitData доступен только на клиенте, поэтому его получение должно происходить в клиентском коде.
+- Если требуется отключить проверку expiration, это будет явно указано в отдельном запросе (по умолчанию проверка включена).
+

package/spec/features/telegram-initData/tasks.md

@@ -0,0 +1,52 @@
+# Orders
+
+**Context:** На стороне клиента нужно отправлять на сервер telegram initData. На стороне сервера нужно добавить логику валидации initData. Результат выводить в console.log. Используется npm пакет `@telegram-apps/init-data-node`.
+
+## Main directions
+
+### Клиентская часть: получение и отправка initData
+
+- [ ] Установить пакет `@telegram-apps/init-data-node` в зависимости проекта (через npm/pnpm/yarn).
+- [ ] Расширить composable `useTelegram` или создать новый `useTelegramInitData`, добавив метод для получения `initData` из `window.Telegram.WebApp.initData`.
+- [ ] Реализовать метод отправки initData на сервер через `$fetch` или `useFetch` на endpoint `/api/telegram/validate-init-data` (POST запрос с телом `{ initData: string }`).
+- [ ] Добавить проверку наличия `initData` перед отправкой (если приложение запущено вне Telegram, не отправлять запрос).
+- [ ] Интегрировать вызов метода отправки initData в плагин `plugins/telegram.client.ts` после успешной инициализации Telegram WebApp или вызвать при первом обращении к composable.
+
+**Проверка:** Убедиться, что initData корректно получается на клиенте и отправляется на сервер при наличии Telegram WebApp. Проверить в DevTools Network tab, что запрос отправляется с корректными данными.
+
+### Серверная часть: валидация initData
+
+- [ ] Создать серверный route `server/api/telegram/validate-init-data.post.ts` (или использовать GET метод, если требуется).
+- [ ] В handler endpoint получить `initData` из body запроса (или query параметра, если используется GET).
+- [ ] Получить Bot Token из переменных окружения (например, `process.env.TELEGRAM_BOT_TOKEN`).
+- [ ] Импортировать функцию `validate` из пакета `@telegram-apps/init-data-node`.
+- [ ] Обернуть вызов `validate(initData, botToken)` в try-catch блок.
+- [ ] При успешной валидации вывести в `console.log` сообщение: `[Telegram InitData Validation] Success: InitData is valid`.
+- [ ] При ошибке валидации перехватить исключение, определить тип ошибки (если нужно) и вывести в `console.log`: `[Telegram InitData Validation] Error: <error message>` или `[Telegram InitData Validation] Error: <error type> - <error message>`.
+- [ ] Вернуть HTTP ответ клиенту (например, статус 200 при успехе, 400 при ошибке валидации, 500 при других ошибках).
+
+**Проверка:** Проверить, что валидация работает корректно с валидным initData и корректно обрабатывает ошибки (неверная подпись, истекший срок и т.д.). Убедиться, что результаты выводятся в консоль сервера.
+
+### Конфигурация и окружение
+
+- [ ] Добавить переменную окружения для Bot Token в документацию или .env.example файл (если используется).
+- [ ] Убедиться, что Bot Token корректно читается из переменных окружения на сервере.
+
+**Проверка:** Проверить, что приложение работает с корректным Bot Token и корректно обрабатывает отсутствие токена.
+
+## Supporting orders
+
+- [ ] Документация: обновить README или добавить комментарии в код, описывающие процесс валидации initData и требования к переменным окружения.
+- [ ] Observability: логирование через `console.log` уже реализовано в основных задачах. При необходимости можно расширить формат логов для лучшей диагностики.
+- [ ] Code review and PR: подготовить изменения для review, убедиться что код соответствует стилю проекта, типизирован через TypeScript, не содержит чувствительных данных в логах.
+
+## Definition of Done
+
+- [ ] Все задачи выполнены и протестированы.
+- [ ] InitData корректно получается на клиенте и отправляется на сервер.
+- [ ] Серверная валидация работает с пакетом `@telegram-apps/init-data-node` и выводит результаты в `console.log`.
+- [ ] Ошибки валидации корректно обрабатываются и логируются.
+- [ ] Код типизирован, проходит линтер без ошибок.
+- [ ] Bot Token корректно читается из переменных окружения.
+- [ ] `/spec/core/verify.md` выполнен после завершения всех задач для проверки списка задач.
+

package/spec/features/tg-user-save-to-supabase/plan.md

@@ -0,0 +1,137 @@
+# Implementation Plan
+
+**Plan:** У нас есть серверная функция, которая принимает initData и валидирует его. Если валидация проходит успешно, то нужно парсить и сохранять пользователя в supabase в таблицу users используя server/utils/supabase.ts. Но нужно проверить, что если такой пользователь сохранен уже, то ничего не делать, не сохранять.
+
+## Data sources / schemas
+
+### Структура данных initData
+
+- `initData` представляет собой строку в формате URL query parameters (например, `user=%7B%22id%22%3A123%2C%22first_name%22%3A%22John%22%7D&auth_date=1234567890&hash=...`).
+- Параметр `user` содержит URL-encoded JSON-строку с данными пользователя Telegram.
+- Объект пользователя в декодированном виде содержит поля: `id` (number), `first_name` (string), `last_name?` (string, опционально), `username?` (string, опционально), `language_code?` (string, опционально), `is_premium?` (boolean, опционально), `photo_url?` (string, опционально).
+
+### Схема таблицы users в Supabase
+
+- Предполагается, что таблица `users` существует и имеет следующие колонки:
+  - `telegram_id` (bigint, primary key или unique) - уникальный идентификатор пользователя из Telegram
+  - `first_name` (text, nullable) - имя пользователя
+  - `last_name` (text, nullable) - фамилия пользователя
+  - `username` (text, nullable) - username пользователя в Telegram
+  - `language_code` (text, nullable) - код языка пользователя
+  - `is_premium` (boolean, nullable) - флаг наличия Telegram Premium
+  - `photo_url` (text, nullable) - URL фотографии профиля
+  - `created_at` (timestamp, default now()) - дата создания записи
+  - `updated_at` (timestamp, default now()) - дата последнего обновления
+
+- Для проверки существования пользователя используется колонка `telegram_id` с уникальным индексом.
+
+### Миграции базы данных
+
+- Не требуется создание новых миграций, так как таблица `users` предположительно уже существует.
+- Если таблица не существует, необходимо создать миграцию для создания таблицы и необходимых индексов.
+
+## Contracts and interfaces
+
+### Изменения в существующем API endpoint
+
+- **Endpoint**: `POST /api/telegram/validate-init-data`
+- **Request**: без изменений - `{ initData: string }`
+- **Response**: без изменений - `{ success: boolean }` или ошибка валидации
+- **Побочные эффекты**: после успешной валидации выполняется попытка сохранения пользователя в Supabase (не влияет на ответ API)
+
+### Интерфейс функции парсинга initData
+
+```typescript
+interface TelegramUser {
+  id: number
+  first_name: string
+  last_name?: string
+  username?: string
+  language_code?: string
+  is_premium?: boolean
+  photo_url?: string
+}
+
+function parseInitDataUser(initData: string): TelegramUser | null
+```
+
+- Принимает строку `initData`, парсит query-параметры, извлекает параметр `user`, декодирует URL-encoding и парсит JSON.
+- Возвращает объект пользователя или `null`, если парсинг не удался.
+
+### Интерфейс функции сохранения пользователя
+
+```typescript
+async function saveUserToSupabase(user: TelegramUser): Promise<void>
+```
+
+- Принимает объект пользователя Telegram.
+- Получает клиент Supabase через `getSupabaseClient()`.
+- Проверяет существование пользователя по `telegram_id`.
+- Если пользователь не существует, выполняет вставку новой записи.
+- Логирует все операции и ошибки.
+
+### Обработка ошибок
+
+- Ошибки парсинга и сохранения логируются, но не возвращаются клиенту.
+- Используется префикс `[Telegram User Save]` для всех логов, связанных с сохранением пользователя.
+
+## Architecture / Components
+
+### Компоненты реализации
+
+1. **Функция парсинга initData** (`parseInitDataUser`)
+   - Разбор query-параметров из строки `initData`
+   - Декодирование URL-encoded параметра `user`
+   - Парсинг JSON-строки в объект пользователя
+   - Обработка ошибок парсинга
+
+2. **Функция сохранения пользователя** (`saveUserToSupabase`)
+   - Получение клиента Supabase через `getSupabaseClient()`
+   - Проверка существования пользователя через `select().eq('telegram_id', user.id).single()` - значение поля `id` из объекта пользователя используется для сравнения с полем `telegram_id` в таблице `users`
+   - Обработка результата проверки (найден/не найден)
+   - Вставка новой записи через `insert()` если пользователь не найден, где поле `id` из объекта пользователя маппится в поле `telegram_id` в таблице `users`
+   - Логирование всех операций
+
+3. **Интеграция в существующий endpoint**
+   - Модификация `server/api/telegram/validate-init-data.post.ts`
+   - Добавление вызова `saveUserToSupabase` после успешной валидации
+   - Сохранение текущего поведения API (не нарушение контракта)
+
+### Зависимости
+
+- `@supabase/supabase-js` - уже используется через `server/utils/supabase.ts`
+- `@telegram-apps/init-data-node` - уже используется для валидации
+- Встроенные модули Node.js: `URLSearchParams`, `decodeURIComponent`, `JSON.parse`
+
+### Обработка ошибок Supabase
+
+- При проверке существования: ошибка с кодом `PGRST116` (или аналогичная) означает, что запись не найдена - это нормальная ситуация.
+- Другие ошибки при проверке логируются как предупреждения, но не прерывают выполнение.
+- Ошибки при вставке логируются, но не возвращаются клиенту.
+
+## Risks
+
+1. **Риск нарушения существующего контракта API**
+   - **Митигация**: Все операции сохранения выполняются асинхронно и не влияют на возвращаемый ответ API. Ошибки сохранения логируются, но не прерывают основной поток.
+
+2. **Риск race condition при одновременных запросах**
+   - **Описание**: Если два запроса с одинаковым пользователем приходят одновременно, оба могут не найти пользователя и попытаться вставить запись.
+   - **Митигация**: Использование уникального индекса на `telegram_id` в таблице `users` обеспечит, что вторая вставка завершится с ошибкой уникальности, которую можно обработать корректно.
+
+3. **Риск отсутствия таблицы users или неправильной схемы**
+   - **Митигация**: Проверка наличия таблицы перед реализацией, обработка ошибок Supabase с информативными сообщениями в логах.
+
+4. **Риск некорректного формата initData**
+   - **Митигация**: Парсинг выполняется в try-catch блоке, все ошибки логируются. Если парсинг не удался, функция сохранения просто не выполняется, но это не влияет на валидацию.
+
+5. **Риск снижения производительности endpoint**
+   - **Митигация**: Операции с базой данных выполняются асинхронно. Можно добавить таймаут для операций с Supabase, чтобы не блокировать ответ слишком долго.
+
+## Assumptions
+
+- Таблица `users` существует в Supabase с необходимой структурой колонок и уникальным индексом на `telegram_id`.
+- Клиент Supabase из `server/utils/supabase.ts` имеет права на чтение и запись в таблицу `users`.
+- Формат `initData` соответствует стандартному формату Telegram WebApp initData с параметром `user` в виде URL-encoded JSON-строки.
+- Пакет `@telegram-apps/init-data-node` не предоставляет готовой функции парсинга, поэтому парсинг выполняется вручную.
+- Текущий API endpoint должен продолжать работать как раньше, сохранение пользователя - это внутренняя операция, не влияющая на публичный контракт API.
+

package/spec/features/tg-user-save-to-supabase/spec.md

@@ -0,0 +1,54 @@
+# Telegram User Save to Supabase
+
+**Specification:** У нас есть серверная функция, которая принимает initData и валидирует его. Если валидация проходит успешно, то нужно парсить и сохранять пользователя в supabase в таблицу users используя server/utils/supabase.ts. Но нужно проверить, что если такой пользователь сохранен уже, то ничего не делать, не сохранять.
+
+## User Stories
+
+- Как система, я хочу автоматически сохранять данные пользователя Telegram в базу данных после успешной валидации initData, чтобы обеспечить персистентность информации о пользователях и возможность их дальнейшего использования в приложении.
+- Как администратор системы, я хочу, чтобы система не создавала дублирующие записи пользователей в базе данных, чтобы избежать избыточности данных и потенциальных проблем с целостностью данных.
+- Как пользователь Telegram Mini App, я хочу, чтобы мои данные были корректно сохранены в системе после первой успешной валидации, чтобы система могла идентифицировать меня в последующих сессиях.
+
+## Main scenarios and rules
+
+### Основной сценарий успешного сохранения
+
+1. Серверная функция `POST /api/telegram/validate-init-data` получает `initData` в теле запроса.
+2. Выполняется валидация `initData` с помощью функции `validate` из пакета `@telegram-apps/init-data-node`.
+3. Если валидация успешна, выполняется парсинг `initData` для извлечения данных пользователя.
+4. Из парсированного `initData` извлекается объект пользователя (обычно находится в параметре `user` в формате JSON-строки).
+5. Получается клиент Supabase через функцию `getSupabaseClient()` из `server/utils/supabase.ts`.
+6. Выполняется проверка существования пользователя в таблице `users` по полю `telegram_id`, используя значение поля `id` из объекта пользователя из `initData`.
+7. Если пользователь не существует, выполняется вставка новой записи в таблицу `users` с данными из `initData`, где значение поля `id` из объекта пользователя сохраняется в поле `telegram_id`.
+8. Если пользователь уже существует, операция вставки не выполняется, функция завершается без ошибки.
+
+### Правила обработки ошибок
+
+- Если валидация `initData` не прошла, процесс сохранения пользователя не запускается, возвращается ошибка валидации как обычно.
+- Если парсинг `initData` не удался (отсутствует поле `user` или оно некорректно), логируется предупреждение, но процесс не прерывается с ошибкой, чтобы не нарушать текущую работу валидации.
+- Если проверка существования пользователя в Supabase завершилась с ошибкой (кроме случая отсутствия записи), ошибка логируется, но не прерывает основной поток валидации.
+- Если вставка нового пользователя завершилась с ошибкой, ошибка логируется, но не возвращается клиенту, чтобы не нарушать текущий контракт API валидации.
+
+### Правила определения существования пользователя
+
+- Проверка выполняется по полю `telegram_id` в таблице `users` в Supabase.
+- Значение для проверки берется из поля `id` объекта пользователя, извлеченного из `initData`.
+- Используется метод `select` с фильтром `eq('telegram_id', user.id)` и `single()` для поиска пользователя в таблице `users`.
+- Если запись найдена, считается, что пользователь уже существует, и операция сохранения не выполняется.
+- Если запись не найдена (ошибка с кодом `PGRST116` или аналогичным), считается, что пользователь не существует и требуется вставка новой записи.
+
+## Non-functional requirements
+
+- **Производительность**: Операции проверки существования и вставки пользователя должны выполняться асинхронно и не блокировать основной поток обработки запроса валидации более чем на 200-300ms.
+- **Безопасность**: Данные пользователя из `initData` должны сохраняться только после успешной валидации подписи. Никакие данные не должны сохраняться, если валидация не прошла.
+- **Надежность**: Операции с базой данных должны быть устойчивы к временным сбоям. Ошибки при сохранении пользователя не должны нарушать основной функционал валидации.
+- **Логирование**: Все операции сохранения пользователя должны логироваться с соответствующими префиксами для удобства отладки и мониторинга.
+- **Совместимость**: Реализация должна быть совместима с существующим API endpoint и не нарушать текущие контракты с клиентской частью.
+
+## Assumptions
+
+- Таблица `users` уже существует в Supabase и имеет необходимые колонки для хранения данных пользователя Telegram, включая обязательное поле `telegram_id` для идентификации пользователя.
+- Поле `telegram_id` в таблице `users` является уникальным и используется для проверки существования пользователя. Значение `telegram_id` берется из поля `id` объекта пользователя из `initData`.
+- Объект пользователя в `initData` доступен в параметре `user` в формате JSON-строки, который может быть распарсен стандартными средствами JavaScript/TypeScript.
+- Пакет `@telegram-apps/init-data-node` не предоставляет готовой функции парсинга `initData`, поэтому парсинг будет выполняться вручную через разбор query-параметров и декодирование JSON.
+- Клиент Supabase настроен корректно и имеет необходимые права доступа для чтения и записи в таблицу `users`.
+

package/spec/features/tg-user-save-to-supabase/tasks.md

@@ -0,0 +1,58 @@
+# Orders
+
+**Context:** У нас есть серверная функция, которая принимает initData и валидирует его. Если валидация проходит успешно, то нужно парсить и сохранять пользователя в supabase в таблицу users используя server/utils/supabase.ts. Но нужно проверить, что если такой пользователь сохранен уже, то ничего не делать, не сохранять.
+
+## Main directions
+
+### Серверная часть: парсинг initData и извлечение данных пользователя
+
+- [x] Создать утилитарную функцию `parseInitDataUser(initData: string)` для парсинга initData и извлечения объекта пользователя.
+- [x] Реализовать разбор query-параметров из строки initData с использованием `URLSearchParams` или ручного парсинга.
+- [x] Реализовать декодирование URL-encoded параметра `user` с использованием `decodeURIComponent`.
+- [x] Реализовать парсинг JSON-строки в объект пользователя с обработкой ошибок парсинга.
+- [x] Добавить TypeScript интерфейс `TelegramUser` для типизации объекта пользователя из initData.
+- [x] Добавить логирование ошибок парсинга с префиксом `[Telegram User Save]`.
+
+**Проверка:** Убедиться, что функция корректно парсит различные форматы initData, обрабатывает отсутствие параметра `user`, корректно декодирует URL-encoded строки и парсит JSON. Протестировать с валидными и невалидными входными данными.
+
+### Серверная часть: сохранение пользователя в Supabase
+
+- [x] Создать функцию `saveUserToSupabase(user: TelegramUser)` для сохранения пользователя в таблицу `users`.
+- [x] Реализовать получение клиента Supabase через `getSupabaseClient()` из `server/utils/supabase.ts`.
+- [x] Реализовать проверку существования пользователя через запрос `select().eq('telegram_id', user.id).single()` к таблице `users`, где значение поля `id` из объекта пользователя сравнивается с полем `telegram_id` в таблице.
+- [x] Реализовать обработку результата проверки: если пользователь найден, завершить функцию без действий.
+- [x] Реализовать обработку ошибки `PGRST116` (или аналогичной) при проверке как нормальной ситуации (пользователь не найден).
+- [x] Реализовать вставку новой записи через `insert()` с данными пользователя, если пользователь не найден.
+- [x] Реализовать маппинг полей из объекта `TelegramUser` в колонки таблицы `users`, где поле `id` из объекта пользователя сохраняется в поле `telegram_id` таблицы, а остальные поля маппятся напрямую (first_name, last_name, username, language_code, is_premium, photo_url).
+- [x] Добавить логирование всех операций (проверка существования, вставка) с префиксом `[Telegram User Save]`.
+- [x] Добавить обработку ошибок вставки с логированием, но без прерывания выполнения.
+
+**Проверка:** Убедиться, что функция корректно проверяет существование пользователя, не создает дублирующие записи, корректно сохраняет данные при первом сохранении. Протестировать сценарии: новый пользователь, существующий пользователь, ошибки Supabase.
+
+### Серверная часть: интеграция в endpoint валидации
+
+- [x] Модифицировать файл `server/api/telegram/validate-init-data.post.ts` для добавления сохранения пользователя.
+- [x] Добавить вызов `parseInitDataUser()` после успешной валидации initData.
+- [x] Добавить проверку результата парсинга: если парсинг успешен, вызвать `saveUserToSupabase()`.
+- [x] Обеспечить, что все операции сохранения выполняются асинхронно и не блокируют возврат ответа API.
+- [x] Обеспечить, что ошибки парсинга и сохранения не влияют на успешный ответ валидации.
+- [x] Добавить обработку ошибок с логированием, но без изменения формата ответа API.
+
+**Проверка:** Убедиться, что endpoint продолжает возвращать `{ success: true }` при успешной валидации, независимо от результатов сохранения пользователя. Проверить, что валидация работает как раньше, сохранение пользователя происходит в фоне. Протестировать сценарии: успешная валидация с новым пользователем, успешная валидация с существующим пользователем, успешная валидация без данных пользователя в initData.
+
+## Supporting orders
+
+- [x] Документация: добавить JSDoc комментарии к функциям `parseInitDataUser` и `saveUserToSupabase` с описанием параметров, возвращаемых значений и примеров использования.
+- [x] Observability: убедиться, что все операции логируются с понятными префиксами для возможности мониторинга и отладки. Добавить логирование успешных операций сохранения пользователя.
+- [x] Code review and PR: подготовить изменения для review, убедиться, что код соответствует стандартам проекта, не нарушает существующие контракты API.
+
+## Definition of Done
+
+- [ ] Все задачи выполнены и протестированы.
+- [ ] Функция парсинга initData корректно извлекает данные пользователя из различных форматов initData.
+- [ ] Функция сохранения пользователя корректно проверяет существование и не создает дублирующие записи.
+- [ ] Интеграция в endpoint не нарушает существующий контракт API.
+- [ ] Все ошибки обрабатываются корректно с логированием, не прерывая основной поток валидации.
+- [ ] Код покрыт комментариями и готов для code review.
+- [ ] `/spec/core/verify.md` выполняется после завершения всех задач для верификации списка задач.
+

package/spec/features/user-profile/plan.md

@@ -0,0 +1,39 @@
+# Implementation Plan
+
+**Plan:** Реализовать динамическую страницу `/colleagues/[id]` для публичного профиля коллеги, обеспечить передачу идентификатора из списка команды, подготовить источник данных и компоненты для отображения контактов, активных задач и истории, сохранив фирменные стили приложения.
+
+## Data sources / schemas
+
+- Создать новый модуль `data/teamMembers.ts` (или расширить текущий `data/team.ts`, если допустимо) с полной моделью `TeamMemberProfile`, содержащей поля: `id`, `name`, `role`, `avatarUrl`, `bio`/`department`, `contacts` (telegram, phone, email), `orders` (массив с `id`, `title`, `status`, `dueDate`), `history` (массив завершённых задач). Определить перечисление статусов (`in-progress`, `completed`, `overdue`).
+- Добавить вспомогательные функции/композабл `useTeamMemberProfile(id)` для получения данных по идентификатору, с мемоизацией и обработкой отсутствующих записей. Возвращать состояния: `profile`, `isLoading`, `error`.
+- Обеспечить совместимость с существующим `useProjectTeam` — данные в списке коллег должны ссылаться на ту же `id`. При необходимости расширить `ProjectTeamMember` дополнительными полями или добавить маппинг `id -> profile`.
+
+## Contracts and interfaces
+
+- Определить интерфейс `OrderItem` с полями `title`, `status`, `dueDate`, `description?`. Для истории добавить `completedAt`.
+- Фильтры статусов реализовать как массив объектов `{ key, label }`, где `key` соответствует перечислению статусов. Контролировать активный фильтр через состояние компонента.
+- Навигация: карточка `TeamMemberCard` получает обработчик `@click` и `aria-label` для открытия `/colleagues/{id}` (через `router.push`). На странице профиля реализовать кнопку «Назад», использующую `router.back()` и fallback на `/projects/{projectId}/team` (если проект передал `from` в query).
+- Контактные элементы используют схемы ссылок: `href="https://t.me/${username}"`, `href="tel:${phone}"`, `href="mailto:${email}"`. Добавить атрибуты `rel="noopener noreferrer"` для внешних ссылок.
+
+## Architecture / Components
+
+- Структура страницы: Nuxt dynamic route `pages/colleagues/[id].vue`. Использовать `useRoute` для получения `id`, `useHead` для метаданных и тематического оформления, `onMounted`/async setup для загрузки профиля.
+- Верхний блок: `AppBar`/`header` с кнопкой назад, заголовком «Профиль коллеги», опциональной кнопкой «Написать» (если нужно). Применить существующие utility-классы (`bg-background-light`, `dark:bg-background-dark`, `font-display`).
+- Основной контент: компонент `ProfileSummary` (локальный или общий) с аватаром (через background-image или `<img>`), именем, ролью, дополнительным текстом. Ниже — карточка «Контакты» (flex-столбец), секция «Назначенные задачи» с horizontal pills фильтров и списком карточек, секция «История задач» с пониженной непрозрачностью.
+- Для задач реализовать вычисляемые списки по активному фильтру. Отображать индикаторы статуса (точка соответствующего цвета). При отсутствии данных показывать пустой state-компонент, используя существующие стили (`bg-white dark:bg-[#1C2431]`, текстовые цвета `text-gray-500`/`dark:text-[#9da6b9]`).
+- Предусмотреть состояние загрузки (skeleton блоки или спиннер) и ошибку (карточка с сообщением и кнопкой возврата).
+
+## Risks
+
+- Несоответствие идентификаторов между текущим списком команды и новым профилем может привести к ошибкам 404 — нужно синхронизировать источники данных.
+- Увеличение размера мок-данных (контакты, история задач) может затруднить поддержку — стоит структурировать данные и вынести в отдельный файл.
+- Возможны расхождения в палитре, если примерные цвета из макета не совпадают с палитрой проекта — необходимо проверять существующие переменные.
+- При отсутствии серверного API логика загрузки сведена к mock-данным; потребуется последующая адаптация, которую нужно предусмотреть в архитектуре (добавить уровень абстракции через composable).
+
+## Assumptions
+
+- Список коллег будет допилен, чтобы передавать query `from` с путём возврата; иначе кнопка «Назад» должна вести на список команды по умолчанию.
+- Пользователь всегда имеет хотя бы один контактный канал; если нет — выводить placeholder «нет данных».
+- Состояние загрузки можно эмулировать таймаутом или сразу отдавать данные — уточнить, нужен ли искусственный loader.
+- Статусы задач ограничиваются тремя основными значениями; дополнительная детализация не требуется.
+- Дизайн примера служит ориентиром по структуре, но все цвета и отступы берём из текущего проекта.

package/spec/features/user-profile/spec.md

@@ -0,0 +1,36 @@
+# Публичный профиль коллеги
+
+**Specification:** Создать динамическую страницу публичного профиля участника команды, доступную из списка коллег, которая показывает основную информацию о человеке, контакты и актуальные задачи, оформленные в общих стилях приложения.
+
+## User Stories
+
+- Как руководитель проекта я открываю профиль коллеги из списка команды, чтобы увидеть, чем он занимается и как с ним связаться.
+- Как HR-специалист я просматриваю карточку сотрудника, чтобы быстро найти контактные данные и актуальную занятость.
+- Как участник команды я хочу видеть историю выполненных задач коллеги, чтобы понимать контекст совместной работы.
+
+## Main scenarios and rules
+
+1. При клике по карточке участника в списке коллег открывается динамический маршрут с параметром `id`, где загружается профиль.
+2. Страница выводит аватар, имя, роль, краткое описание/команду и разделы: контакты, текущие задачи с индикаторами статуса и история выполненных задач.
+3. Данные профиля берутся из локального источника (mock) или API; при отсутствии записи отображается состояние «пользователь не найден» с кнопкой возврата.
+4. Контактные способы включают Telegram/мессенджер, телефон и email, каждый с подписью и возможностью скопировать/перейти (по клику открывается соответствующая схема `tel:`, `mailto:` или внешняя ссылка).
+5. Блок задач поддерживает фильтры по статусу (например, «В работе», «Завершено», «Просрочено») и отображает карточки с названием и датой; при отсутствии задач показывается дружелюбный пустой экран.
+6. История задач отображается в отдельной секции со слабым акцентом (пониженная непрозрачность); если данных нет — выводится пустое состояние.
+7. Страница использует общие темы (светлая/тёмная), шрифты Inter, палитру и компоненты кнопок, карточек, фильтров.
+8. Навигация предусматривает фиксированную верхнюю панель с кнопкой назад, ведущей на предыдущий экран или список коллег.
+
+## Non-functional requirements
+
+- Адаптивность: корректное отображение на мобильных устройствах (основной сценарий), планшетах и десктопе.
+- Производительность: загрузка данных профиля не должна блокировать интерфейс; показывать skeleton/loader при задержке.
+- Доступность: семантические элементы, aria-метки для кнопок возврата и фильтров, достаточный контраст в обеих темах.
+- Локализация: все тексты на русском языке с возможностью вынести в словари при будущей интернационализации.
+- Повторное использование стилей: использовать существующие utility-классы Tailwind и компоненты для единообразия.
+
+## Assumptions
+
+- Список коллег уже существует и передаёт идентификатор пользователя при переходе; если нет — нужно расширить текущую карточку участника.
+- Контактные данные и информация о задачах будут добавлены в mock-данные (например, `data/teamMembers.ts`), которые в дальнейшем заменят API.
+- История задач может быть ограничена несколькими последними записями; детальной расшифровки статусов не требуется.
+- Нет необходимости в редактировании профиля в рамках этой итерации; страница только для просмотра.
+- Нужно уточнить, какие статусы задач считать основными, если текущие статусы в проекте отличаются от примера.

package/spec/features/user-profile/tasks.md

@@ -0,0 +1,38 @@
+# Orders
+
+**Context:** Создать динамическую страницу публичного профиля коллеги с контактами и задачами, доступную из списка команды, соблюдая стили приложения.
+
+## Main directions
+
+### Данные и состояния
+
+- [ ] Подготовить расширенный источник данных (`data/teamMembers.ts` или расширение `data/team.ts`) с полной моделью профиля, включая контакты, активные задачи и историю.
+- [ ] Реализовать composable `useTeamMemberProfile` с API `profile`, `isLoading`, `error`, обеспечив поиск по `id`, мемоизацию и обработку отсутствующих данных.
+- [ ] Синхронизировать идентификаторы между списком коллег (`useProjectTeam`/`TeamMemberCard`) и профилями, добавить передачу `id` при клике.
+
+### Маршруты и навигация
+
+- [ ] Создать динамическую страницу `pages/colleagues/[id].vue`, настроить `useRoute`/`useRouter`, реализовать fallback-навигацию (query `from` → `router.back()` → `/projects/{projectId}/team`).
+- [ ] Настроить `useHead` для установки заголовка, темы и meta-тегов страницы профиля.
+- [ ] Обработать состояния загрузки, ошибки и пустых данных (профиль не найден, нет задач, нет истории).
+
+### UI и взаимодействия
+
+- [ ] Сверстать шапку профиля с аватаром, именем, ролью, опциональным описанием, используя общие классы (`bg-background-light`, `dark:bg-background-dark`, `font-display`).
+- [ ] Добавить карточку контактов с кликабельными ссылками (Telegram, телефон, email) и визуальными иконками.
+- [ ] Реализовать секцию «Назначенные задачи» с фильтрами по статусу и карточками задач (название, статус-индикатор, дедлайн).
+- [ ] Реализовать секцию «История задач» с карточками завершённых задач, пониженной контрастностью и пустым состоянием.
+- [ ] Обеспечить адаптивность и доступность: проверка контрастности, aria-метки для кнопок, фокусные состояния.
+
+## Supporting orders
+
+- [ ] Documentation: описать использование страницы и источника данных в README или соответствующем разделе.
+- [ ] Observability: Not required — reason: в рамках клиентского Nuxt-приложения без бекэнда нечего настраивать.
+- [ ] Code review and PR: подготовить PR с описанием изменений и скриншотами новой страницы.
+
+## Definition of Done
+
+- [ ] All orders are completed and tested.
+- [ ] Relevant unit/e2e/integration tests pass successfully.
+- [ ] Documentation and operational instructions are updated.
+- [ ] `/spec/core/verify.md` is executed after completing all orders to verify the order list.

package/spec/features/user-profile-edit/plan.md

@@ -0,0 +1,36 @@
+# Implementation Plan
+
+**Plan:** Deliver a profile editing page that loads data from the Pinia user store, allows form-based updates, and is reachable from the avatar in the main header.
+
+## Data sources / schemas
+
+- Reuse the existing `useUserStore` Pinia store as the single source of user data; ensure getters provide up-to-date values and loading state.
+- If updates require persistence, define a placeholder action in the store for now, returning mocked success until backend API is ready.
+- Map editable fields (first name, last name, username, language code) to form inputs; treat `is_premium` and `photo_url` as read-only display data.
+
+## Contracts and interfaces
+
+- UI contract: clicking the avatar triggers navigation to `/profile/edit`; ensure router configuration supports this path.
+- Form submission interface: emit an update event that calls a store action (e.g., `updateUserProfile`) with validated payload.
+- Validation contract: define required fields and constraints (length, allowed characters) consistent with other profile forms.
+- Feedback interface: use shared notification/toast or inline status component to inform users about success or error states.
+
+## Architecture / Components
+
+- Create a new page component at `pages/profile/edit.vue` (Nuxt route) with composition API and script setup.
+- Compose the page from shared layout primitives (page container, card, form components) to align with design guidelines.
+- Utilize composables or helpers for form state (e.g., `useForm` or local reactive object) and watchers to sync with store data.
+- Update the header component to wrap the avatar in a link or click handler that navigates to the edit page without breaking existing dropdown behavior.
+- Include responsive layout adjustments (stacked form on mobile, side-by-side summary on desktop if available).
+
+## Risks
+
+- Store might be empty when the page loads; need fallback UI and fetch trigger.
+- Saving without backend integration could mislead users; must clearly communicate temporary behavior.
+- Modifying header avatar click could interfere with other interactions (menus, tooltips); test across breakpoints.
+
+## Assumptions
+
+- Router already supports nested profile routes, and adding `/profile/edit` will not conflict with existing dynamic pages.
+- Shared form components are available; if not, custom components must mimic existing styles.
+- Localization resources can be extended without structural changes.