05 — MicroDAO Coding Standards (MVP)

Цей документ визначає мінімальні стандарти коду, яким повинен відповідати фронтенд MicroDAO. Його мета — забезпечити якість, узгодженість і стабільність розробки, особливо при використанні Cursor.

1. Загальні принципи

Тільки TypeScript. Заборонено any та unknown, окрім явно позначених місць.
Компоненти — функціональні. Не використовувати класові компоненти.
Стан — мінімалістичний. Локальний стан → React useState Глобальний короткочасний стан → Context або Zustand Дані з API → React Query
Ясність важливіша за магію. Прості компоненти, зрозумілі хуки, передбачувані сторінки.
Принцип: один файл — одна відповідальність.

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
```text

- `features/*` містять логіку конкретних модулів.
- `components/*` — лише dumb UI-компоненти (без бізнес-логіки).

## 3. TypeScript Правила

### 3.1. Строгий режим

У `tsconfig.json`:

```json
{
  "compilerOptions": {
    "strict": true
  }
}
```text

### 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();
}
```text

### 4.2. Query Keys

```text
["teams"]
["teams", teamId]
["channels", teamId]
["messages", channelId]
["followups", teamId]
["projects", teamId]
```text

## 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
```text

Формат ключів:

```text
onboarding.welcome_title
onboarding.next
chat.send
chat.input_placeholder
followup.create
```text

Форсувати одразу правильну структуру.

## 8. UI та дизайн

### 8.1. Кольори

```text
--primary: #3F51F5;
--success: #43A047;
--error:   #E53935;
--gray-100: #F8F9FA;
--gray-200: #ECEFF1;
--gray-800: #263238;
```text

### 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

```text
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
```text

## 13. Мета документа

Цей файл — "правила дорожнього руху" для команди і Cursor.

Він гарантує:

- узгоджений стиль,
- передбачуваний код,
- мінімум помилок,
- легку підтримку,
- зрозумілість структури для нових девелоперів.

6.6 KiB Raw Permalink Blame History Unescape Escape