Initial commit: MVP structure + Cursor documentation + Onboarding components

docs/cursor/05_coding_standards.md

@@ -0,0 +1,241 @@
+# 05 — MicroDAO Coding Standards (MVP)
+
+Цей документ визначає мінімальні стандарти коду, яким повинен відповідати фронтенд MicroDAO.
+Його мета — забезпечити якість, узгодженість і стабільність розробки, особливо при використанні Cursor.
+
+## 1. Загальні принципи
+
+1. **Тільки TypeScript.**
+   Заборонено `any` та `unknown`, окрім явно позначених місць.
+
+2. **Компоненти — функціональні.**
+   Не використовувати класові компоненти.
+
+3. **Стан — мінімалістичний.**
+   Локальний стан → React useState
+   Глобальний короткочасний стан → Context або Zustand
+   Дані з API → React Query
+
+4. **Ясність важливіша за магію.**
+   Прості компоненти, зрозумілі хуки, передбачувані сторінки.
+
+5. **Принцип: один файл — одна відповідальність.**
+
+## 2. Архітектура проєкту
+
+```
+src/
+api/          // Typed API clients
+components/   // UI components (buttons, inputs, modals)
+features/     // Business-level modules (chat, onboarding, agents)
+hooks/        // Reusable react hooks
+layout/       // Application layout
+routes/       // Route definitions
+store/        // Zustand stores (optional)
+styles/       // Global CSS/tokens
+utils/        // Formatting, validation
+```
+
+- `features/*` містять логіку конкретних модулів.
+- `components/*` — лише dumb UI-компоненти (без бізнес-логіки).
+
+## 3. TypeScript Правила
+
+### 3.1. Строгий режим
+
+У `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "strict": true
+  }
+}
+```
+
+### 3.2. Заборонено
+
+* `any`
+* `!` non-null assertion (за винятком рідкісних випадків)
+* глобальний mutable state
+
+### 3.3. API-типи
+
+* Генеруємо типи з API Snapshot / OpenAPI.
+* Типи для відповідей зберігаються в `src/api/types.ts`.
+
+## 4. React Query (network layer)
+
+### 4.1. Fetch wrapper
+
+Один універсальний wrapper:
+
+```ts
+export async function api<T>(path: string, options?: RequestInit): Promise<T> {
+  const res = await fetch(`/v1${path}`, {
+    headers: {
+      "Content-Type": "application/json",
+      ...options?.headers
+    },
+    ...options
+  });
+
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    throw new Error(err.message || `Request failed: ${res.status}`);
+  }
+
+  return res.json();
+}
+```
+
+### 4.2. Query Keys
+
+```
+["teams"]
+["teams", teamId]
+["channels", teamId]
+["messages", channelId]
+["followups", teamId]
+["projects", teamId]
+```
+
+## 5. Стандарти компонентів
+
+### 5.1. Іменування
+
+* Компоненти: `PascalCase`
+* Хуки: `useCamelCase`
+* Файли: `camel-case.tsx`
+* Папки: `kebab-case`
+
+### 5.2. Компонент повинен мати:
+
+* Чіткий props-інтерфейс:
+
+  ```ts
+  interface MyCompProps {
+    title: string;
+    onClick: () => void;
+  }
+  ```
+* Внутрішній стан не змішується з зовнішнім API-станом.
+* Міжкомпонентна логіка виноситься в хуки (наприклад: `useMessages(channelId)`).
+
+## 6. Обробка помилок
+
+### 6.1. Toast/notification
+
+Помилка API → коротке повідомлення:
+
+> "Не вдалося виконати дію. Спробуйте ще раз."
+
+### 6.2. ErrorBoundary
+
+Окрема сторінка помилки для критичних збоїв.
+
+### 6.3. Retry policy
+
+React Query retry: `retry: 1` для GET-запитів
+POST — без retry.
+
+## 7. i18n стандарти
+
+Всі тексти повинні бути в словнику:
+
+```
+src/i18n/uk.json
+src/i18n/en.json
+```
+
+Формат ключів:
+
+```
+onboarding.welcome_title
+onboarding.next
+chat.send
+chat.input_placeholder
+followup.create
+```
+
+Форсувати одразу правильну структуру.
+
+## 8. UI та дизайн
+
+### 8.1. Кольори
+
+```
+--primary: #3F51F5;
+--success: #43A047;
+--error:   #E53935;
+--gray-100: #F8F9FA;
+--gray-200: #ECEFF1;
+--gray-800: #263238;
+```
+
+### 8.2. Типографіка
+
+* System font stack:
+  `"Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto`
+
+### 8.3. Контрасти
+
+Всі текстові елементи повинні відповідати WCAG AA (axe test).
+
+## 9. Робота з WebSockets
+
+* Використовуємо один хук: `useChannelStream(channelId)`.
+* WS підключається коли відкрито чат.
+* Події:
+
+  * `message.created`
+  * `message.updated`
+
+Не зберігати WS-стан у глобальному store.
+
+## 10. Обмеження для MVP
+
+Що треба **вимкнути** у коді, щоб не перевантажити ранніх користувачів:
+
+* Без drag'n'drop для файлів.
+* Без реакцій (emoji).
+* Без WYSIWYG редактора.
+* Без Co-Memory (файли/документи), лише stub.
+* Без granular RBAC.
+
+## 11. Патерни, які Cursor повинен дотримуватися
+
+1. **Atomic commits**: 1 Фіча → 1 commit.
+2. **File-oriented prompts**: кожен запит до Cursor повинен містити список файлів для зміни.
+3. **Не переписувати цілі модулі**, якщо не потрібно.
+4. **Перевіряти типи** перед генерацією нового коду.
+5. **Не вигадувати API** — брати тільки з `03_api_core_snapshot.md`.
+
+## 12. Приклад робочого промта для Cursor
+
+```
+You are a senior React/TS engineer.
+
+Implement Step 2 of the onboarding flow (/onboarding).
+
+Specs:
+- design from 04_ui_ux_onboarding_chat.md
+- API from 03_api_core_snapshot.md
+- coding standards from 05_coding_standards.md
+
+Please output:
+- list of files to modify
+- code diff
+```
+
+## 13. Мета документа
+
+Цей файл — "правила дорожнього руху" для команди і Cursor.
+
+Він гарантує:
+
+* узгоджений стиль,
+* передбачуваний код,
+* мінімум помилок,
+* легку підтримку,
+* зрозумілість структури для нових девелоперів.