chore: organize documentation structure for monorepo
- Create /docs structure (microdao, daarion, agents) - Organize 61 cursor technical docs - Add README files for each category - Copy key documents to public categories - Add GitHub setup instructions and scripts
This commit is contained in:
Apple
596
docs/cursor/50_daarion_city_website_integration.md
Normal file
596
docs/cursor/50_daarion_city_website_integration.md
Normal file
@@ -0,0 +1,596 @@
|
||||
# 50 — DAARION.city Website Integration (MicroDAO)
|
||||
|
||||
*Специфікація інтеграції MicroDAO у офіційний сайт DAARION.city як перший публічний MicroDAO*
|
||||
|
||||
---
|
||||
|
||||
## 1. Purpose & Scope
|
||||
|
||||
Документ визначає:
|
||||
|
||||
- як вбудовувати MicroDAO у офіційний сайт DAARION.city,
|
||||
- API для публічного каналу міста,
|
||||
- UI/UX для публічного каналу на сайті,
|
||||
- Authentication flow для користувачів сайту,
|
||||
- SEO та метадані для публічного каналу,
|
||||
- Embedding/iframe інтеграцію (опційно),
|
||||
- Analytics та tracking.
|
||||
|
||||
Це перша інтеграція MicroDAO у зовнішній сайт.
|
||||
|
||||
---
|
||||
|
||||
## 2. Architecture Overview
|
||||
|
||||
### 2.1 High-Level Integration
|
||||
|
||||
```text
|
||||
DAARION.city Website (Next.js/React)
|
||||
↓
|
||||
Public Channel Embed
|
||||
↓
|
||||
MicroDAO API Gateway
|
||||
↓
|
||||
MicroDAO Backend Services
|
||||
```
|
||||
|
||||
### 2.2 Integration Modes
|
||||
|
||||
**Mode 1: Embedded Widget (Recommended)**
|
||||
- MicroDAO публічний канал вбудовується як React компонент на сайті
|
||||
- Використовує MicroDAO API напряму
|
||||
- Повний контроль над UI/UX
|
||||
|
||||
**Mode 2: iframe Embed**
|
||||
- MicroDAO публічний канал відкривається в iframe
|
||||
- Простіша інтеграція, менше контролю
|
||||
- Використовується для швидкого прототипування
|
||||
|
||||
**Mode 3: Full Redirect**
|
||||
- Посилання з сайту веде на окрему сторінку MicroDAO
|
||||
- Найпростіша реалізація
|
||||
- Втрачається контекст сайту
|
||||
|
||||
---
|
||||
|
||||
## 3. DAARION.city as First MicroDAO
|
||||
|
||||
### 3.1 Team Setup
|
||||
|
||||
DAARION.city має бути створений як перший MicroDAO:
|
||||
|
||||
```sql
|
||||
INSERT INTO teams (
|
||||
id,
|
||||
name,
|
||||
slug,
|
||||
type,
|
||||
mode,
|
||||
description,
|
||||
created_at
|
||||
) VALUES (
|
||||
'daarion-city',
|
||||
'DAARION.city',
|
||||
'daarion',
|
||||
'city',
|
||||
'public',
|
||||
'Офіційна спільнота міста DAARION',
|
||||
NOW()
|
||||
);
|
||||
```
|
||||
|
||||
### 3.2 Public Channel Setup
|
||||
|
||||
Створюється публічний канал для міста:
|
||||
|
||||
```sql
|
||||
INSERT INTO channels (
|
||||
id,
|
||||
team_id,
|
||||
title,
|
||||
slug,
|
||||
type,
|
||||
is_public,
|
||||
created_at
|
||||
) VALUES (
|
||||
'daarion-city-general',
|
||||
'daarion-city',
|
||||
'Загальний канал міста',
|
||||
'general',
|
||||
'public',
|
||||
true,
|
||||
NOW()
|
||||
);
|
||||
```
|
||||
|
||||
### 3.3 City Agent Setup
|
||||
|
||||
Створюється міський агент:
|
||||
|
||||
```sql
|
||||
INSERT INTO agents (
|
||||
id,
|
||||
team_id,
|
||||
name,
|
||||
role,
|
||||
system_prompt,
|
||||
memory_scope,
|
||||
created_at
|
||||
) VALUES (
|
||||
'daarion-city-agent',
|
||||
'daarion-city',
|
||||
'Міський Асистент',
|
||||
'team_assistant',
|
||||
'Ти — міський асистент DAARION.city. Допомагаєш мешканцям та гостям міста.',
|
||||
'team',
|
||||
NOW()
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Public Channel API
|
||||
|
||||
### 4.1 Get Public Channel Info
|
||||
|
||||
```http
|
||||
GET /api/v1/channels/{slug}/public
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"id": "daarion-city-general",
|
||||
"team_id": "daarion-city",
|
||||
"title": "Загальний канал міста",
|
||||
"slug": "general",
|
||||
"description": "Публічний канал для обговорення міських питань",
|
||||
"message_count": 1234,
|
||||
"member_count": 567,
|
||||
"is_public": true,
|
||||
"team": {
|
||||
"id": "daarion-city",
|
||||
"name": "DAARION.city",
|
||||
"slug": "daarion"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 Get Public Messages
|
||||
|
||||
```http
|
||||
GET /api/v1/channels/{slug}/public/messages?limit=50&before={message_id}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"messages": [
|
||||
{
|
||||
"id": "msg-123",
|
||||
"sender": {
|
||||
"id": "user-456",
|
||||
"name": "Олександр",
|
||||
"avatar_url": "https://..."
|
||||
},
|
||||
"body": "Привіт, місто!",
|
||||
"created_at": "2024-11-14T10:00:00Z",
|
||||
"reactions": []
|
||||
}
|
||||
],
|
||||
"pagination": {
|
||||
"has_more": true,
|
||||
"next_cursor": "msg-124"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4.3 Post Message (Authenticated)
|
||||
|
||||
```http
|
||||
POST /api/v1/channels/{slug}/public/messages
|
||||
Authorization: Bearer {token}
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"body": "Повідомлення від користувача"
|
||||
}
|
||||
```
|
||||
|
||||
### 4.4 Register as Viewer/Member
|
||||
|
||||
```http
|
||||
POST /api/v1/channels/{slug}/public/join
|
||||
Content-Type: application/json
|
||||
|
||||
{
|
||||
"email": "user@example.com",
|
||||
"name": "Ім'я Користувача",
|
||||
"viewer_type": "member" | "visitor"
|
||||
}
|
||||
```
|
||||
|
||||
**Response:**
|
||||
```json
|
||||
{
|
||||
"user_id": "user-789",
|
||||
"access_token": "jwt-token",
|
||||
"membership": {
|
||||
"role": "member",
|
||||
"viewer_type": "member"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. UI/UX for Website Integration
|
||||
|
||||
### 5.1 Embedded Widget Component
|
||||
|
||||
**React Component:**
|
||||
```tsx
|
||||
<MicroDAOChannelEmbed
|
||||
channelSlug="general"
|
||||
teamSlug="daarion"
|
||||
apiUrl="https://api.microdao.xyz/v1"
|
||||
theme="light"
|
||||
showHeader={true}
|
||||
allowJoin={true}
|
||||
/>
|
||||
```
|
||||
|
||||
**Props:**
|
||||
- `channelSlug`: slug каналу
|
||||
- `teamSlug`: slug команди
|
||||
- `apiUrl`: URL API Gateway
|
||||
- `theme`: "light" | "dark"
|
||||
- `showHeader`: показувати заголовок каналу
|
||||
- `allowJoin`: дозволити реєстрацію з віджета
|
||||
|
||||
### 5.2 Widget Layout
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ # Загальний канал міста │
|
||||
│ DAARION.city │
|
||||
├─────────────────────────────────────┤
|
||||
│ │
|
||||
│ [Messages List] │
|
||||
│ │
|
||||
│ ┌───────────────────────────────┐ │
|
||||
│ │ [Input Field] [Send] │ │
|
||||
│ └───────────────────────────────┘ │
|
||||
│ │
|
||||
│ [Join Button] (if not authenticated)│
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 5.3 Authentication Flow
|
||||
|
||||
**Step 1: Guest View**
|
||||
- Користувач бачить повідомлення (read-only)
|
||||
- Кнопка "Приєднатися до обговорення"
|
||||
|
||||
**Step 2: Join Modal**
|
||||
- Форма: Email, Ім'я, Тип участі (Member/Visitor)
|
||||
- Відправка запиту на `/api/v1/channels/{slug}/public/join`
|
||||
- Отримання JWT токену
|
||||
|
||||
**Step 3: Authenticated View**
|
||||
- Користувач може писати повідомлення
|
||||
- Відображається його профіль
|
||||
- Доступ до повної функціональності каналу
|
||||
|
||||
---
|
||||
|
||||
## 6. SEO & Metadata
|
||||
|
||||
### 6.1 Open Graph Tags
|
||||
|
||||
```html
|
||||
<meta property="og:title" content="Загальний канал міста DAARION.city" />
|
||||
<meta property="og:description" content="Публічний канал для обговорення міських питань" />
|
||||
<meta property="og:type" content="website" />
|
||||
<meta property="og:url" content="https://daarion.city/channel/general" />
|
||||
<meta property="og:image" content="https://daarion.city/og-image.png" />
|
||||
```
|
||||
|
||||
### 6.2 Twitter Cards
|
||||
|
||||
```html
|
||||
<meta name="twitter:card" content="summary_large_image" />
|
||||
<meta name="twitter:title" content="Загальний канал міста DAARION.city" />
|
||||
<meta name="twitter:description" content="Публічний канал для обговорення міських питань" />
|
||||
<meta name="twitter:image" content="https://daarion.city/twitter-image.png" />
|
||||
```
|
||||
|
||||
### 6.3 Structured Data (JSON-LD)
|
||||
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "DiscussionForumPosting",
|
||||
"headline": "Загальний канал міста DAARION.city",
|
||||
"description": "Публічний канал для обговорення міських питань",
|
||||
"author": {
|
||||
"@type": "Organization",
|
||||
"name": "DAARION.city"
|
||||
},
|
||||
"datePublished": "2024-11-14T10:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Security & Privacy
|
||||
|
||||
### 7.1 CORS Configuration
|
||||
|
||||
API Gateway має дозволяти запити з `https://daarion.city`:
|
||||
|
||||
```typescript
|
||||
const corsOptions = {
|
||||
origin: [
|
||||
'https://daarion.city',
|
||||
'https://www.daarion.city',
|
||||
'http://localhost:3000' // для розробки
|
||||
],
|
||||
credentials: true,
|
||||
methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
|
||||
allowedHeaders: ['Content-Type', 'Authorization']
|
||||
};
|
||||
```
|
||||
|
||||
### 7.2 Rate Limiting
|
||||
|
||||
Публічний канал має обмеження:
|
||||
|
||||
- **Guest (read-only):** 100 requests/minute
|
||||
- **Authenticated (write):** 30 messages/minute
|
||||
- **Join requests:** 5 requests/hour per IP
|
||||
|
||||
### 7.3 Content Moderation
|
||||
|
||||
- Автоматична модерація через Agent
|
||||
- Фільтрація спаму
|
||||
- Блокування токсичного контенту
|
||||
- Можливість скарг від користувачів
|
||||
|
||||
---
|
||||
|
||||
## 8. Analytics & Tracking
|
||||
|
||||
### 8.1 Events to Track
|
||||
|
||||
```typescript
|
||||
type AnalyticsEvent =
|
||||
| { type: 'channel_view', channel_slug: string }
|
||||
| { type: 'message_sent', channel_slug: string, user_id: string }
|
||||
| { type: 'join_clicked', channel_slug: string }
|
||||
| { type: 'join_completed', channel_slug: string, viewer_type: string }
|
||||
| { type: 'widget_loaded', channel_slug: string, load_time: number };
|
||||
```
|
||||
|
||||
### 8.2 Integration with Analytics
|
||||
|
||||
- Google Analytics 4
|
||||
- Plausible Analytics (privacy-friendly)
|
||||
- Custom analytics endpoint
|
||||
|
||||
---
|
||||
|
||||
## 9. Implementation Steps
|
||||
|
||||
### Step 1: Backend Setup
|
||||
|
||||
1. Створити DAARION.city team у БД
|
||||
2. Створити публічний канал
|
||||
3. Створити міського агента
|
||||
4. Налаштувати CORS для `daarion.city`
|
||||
5. Додати rate limiting для публічного каналу
|
||||
|
||||
### Step 2: API Endpoints
|
||||
|
||||
1. `GET /api/v1/channels/{slug}/public` — інформація про канал
|
||||
2. `GET /api/v1/channels/{slug}/public/messages` — повідомлення
|
||||
3. `POST /api/v1/channels/{slug}/public/messages` — надіслати повідомлення
|
||||
4. `POST /api/v1/channels/{slug}/public/join` — приєднатися
|
||||
|
||||
### Step 3: Frontend Widget
|
||||
|
||||
1. Створити React компонент `MicroDAOChannelEmbed`
|
||||
2. Інтегрувати з API
|
||||
3. Додати authentication flow
|
||||
4. Додати real-time оновлення (WebSocket/SSE)
|
||||
|
||||
### Step 4: Website Integration
|
||||
|
||||
1. Додати компонент на сторінку `daarion.city/channel/general`
|
||||
2. Налаштувати SEO метадані
|
||||
3. Додати analytics tracking
|
||||
4. Тестування на production
|
||||
|
||||
---
|
||||
|
||||
## 10. Example Integration Code
|
||||
|
||||
### 10.1 Next.js Page
|
||||
|
||||
```tsx
|
||||
// pages/channel/[slug].tsx
|
||||
import { MicroDAOChannelEmbed } from '@/components/MicroDAOChannelEmbed';
|
||||
import Head from 'next/head';
|
||||
|
||||
export default function ChannelPage({ channelSlug }) {
|
||||
return (
|
||||
<>
|
||||
<Head>
|
||||
<title>Загальний канал міста DAARION.city</title>
|
||||
<meta name="description" content="Публічний канал для обговорення міських питань" />
|
||||
{/* Open Graph tags */}
|
||||
{/* Twitter Cards */}
|
||||
</Head>
|
||||
|
||||
<div className="container mx-auto py-8">
|
||||
<MicroDAOChannelEmbed
|
||||
channelSlug={channelSlug}
|
||||
teamSlug="daarion"
|
||||
apiUrl={process.env.NEXT_PUBLIC_MICRODAO_API_URL}
|
||||
theme="light"
|
||||
showHeader={true}
|
||||
allowJoin={true}
|
||||
/>
|
||||
</div>
|
||||
</>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### 10.2 React Widget Component
|
||||
|
||||
```tsx
|
||||
// components/MicroDAOChannelEmbed.tsx
|
||||
import { useState, useEffect } from 'react';
|
||||
import { useChannelMessages, useJoinChannel } from '@/hooks/useMicroDAO';
|
||||
|
||||
export function MicroDAOChannelEmbed({
|
||||
channelSlug,
|
||||
teamSlug,
|
||||
apiUrl,
|
||||
theme,
|
||||
showHeader,
|
||||
allowJoin
|
||||
}) {
|
||||
const [isAuthenticated, setIsAuthenticated] = useState(false);
|
||||
const { messages, loadMore } = useChannelMessages(channelSlug, apiUrl);
|
||||
const { join } = useJoinChannel(channelSlug, apiUrl);
|
||||
|
||||
const handleJoin = async (email: string, name: string, viewerType: string) => {
|
||||
const result = await join(email, name, viewerType);
|
||||
if (result.access_token) {
|
||||
localStorage.setItem('microdao_token', result.access_token);
|
||||
setIsAuthenticated(true);
|
||||
}
|
||||
};
|
||||
|
||||
return (
|
||||
<div className={`microdao-widget theme-${theme}`}>
|
||||
{showHeader && (
|
||||
<div className="widget-header">
|
||||
<h2># Загальний канал міста</h2>
|
||||
<p>DAARION.city</p>
|
||||
</div>
|
||||
)}
|
||||
|
||||
<div className="messages-list">
|
||||
{messages.map(msg => (
|
||||
<Message key={msg.id} message={msg} />
|
||||
))}
|
||||
</div>
|
||||
|
||||
{isAuthenticated ? (
|
||||
<MessageInput channelSlug={channelSlug} apiUrl={apiUrl} />
|
||||
) : (
|
||||
allowJoin && <JoinButton onJoin={handleJoin} />
|
||||
)}
|
||||
</div>
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. Testing Checklist
|
||||
|
||||
### 11.1 Backend Tests
|
||||
|
||||
- [ ] Публічний канал створено для DAARION.city
|
||||
- [ ] API endpoints повертають коректні дані
|
||||
- [ ] CORS налаштовано правильно
|
||||
- [ ] Rate limiting працює
|
||||
- [ ] Authentication flow працює
|
||||
|
||||
### 11.2 Frontend Tests
|
||||
|
||||
- [ ] Widget завантажується на сайті
|
||||
- [ ] Повідомлення відображаються коректно
|
||||
- [ ] Join flow працює
|
||||
- [ ] Real-time оновлення працюють
|
||||
- [ ] Responsive design на мобільних
|
||||
|
||||
### 11.3 Integration Tests
|
||||
|
||||
- [ ] SEO метадані відображаються
|
||||
- [ ] Analytics tracking працює
|
||||
- [ ] Content moderation працює
|
||||
- [ ] Error handling коректний
|
||||
|
||||
---
|
||||
|
||||
## 12. Integration with Other Docs
|
||||
|
||||
Цей документ доповнює:
|
||||
|
||||
- `DAARION_city_integration.md` — загальна архітектура DAARION.city
|
||||
- `47_messaging_channels_and_privacy_layers.md` — архітектура каналів
|
||||
- `04_ui_ux_onboarding_chat.md` — UI/UX специфікація
|
||||
- `03_api_core_snapshot.md` — API контракти
|
||||
|
||||
---
|
||||
|
||||
## 13. Завдання для Cursor
|
||||
|
||||
```text
|
||||
You are a senior full-stack engineer. Implement DAARION.city website integration using:
|
||||
- 50_daarion_city_website_integration.md
|
||||
- DAARION_city_integration.md
|
||||
- 47_messaging_channels_and_privacy_layers.md
|
||||
- 03_api_core_snapshot.md
|
||||
|
||||
Tasks:
|
||||
1) Create DAARION.city team in database (type='city', slug='daarion', mode='public').
|
||||
2) Create public channel for DAARION.city (slug='general', type='public', is_public=true).
|
||||
3) Create city agent for DAARION.city (role='team_assistant', memory_scope='team').
|
||||
4) Implement Public Channel API endpoints:
|
||||
- GET /api/v1/channels/{slug}/public (channel info)
|
||||
- GET /api/v1/channels/{slug}/public/messages (messages with pagination)
|
||||
- POST /api/v1/channels/{slug}/public/messages (send message, authenticated)
|
||||
- POST /api/v1/channels/{slug}/public/join (register as viewer/member)
|
||||
5) Configure CORS for daarion.city domain.
|
||||
6) Add rate limiting for public channel (guest: 100 req/min, authenticated: 30 msg/min, join: 5 req/hour).
|
||||
7) Create React component MicroDAOChannelEmbed (props: channelSlug, teamSlug, apiUrl, theme, showHeader, allowJoin).
|
||||
8) Implement authentication flow (guest view → join modal → authenticated view).
|
||||
9) Add real-time updates (WebSocket/SSE for new messages).
|
||||
10) Add SEO metadata (Open Graph, Twitter Cards, JSON-LD).
|
||||
11) Add analytics tracking (channel_view, message_sent, join_clicked, join_completed, widget_loaded).
|
||||
12) Add content moderation (spam filter, toxic content detection, user reports).
|
||||
|
||||
Output:
|
||||
- list of modified files
|
||||
- diff
|
||||
- summary
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 14. Summary
|
||||
|
||||
Інтеграція MicroDAO у офіційний сайт DAARION.city:
|
||||
|
||||
- DAARION.city стає першим MicroDAO типу "city"
|
||||
- Публічний канал вбудовується на сайт як React компонент
|
||||
- API endpoints для публічного каналу
|
||||
- Authentication flow для користувачів сайту
|
||||
- SEO та метадані для публічного каналу
|
||||
- Analytics та tracking
|
||||
- Security (CORS, rate limiting, content moderation)
|
||||
|
||||
Це перша інтеграція MicroDAO у зовнішній сайт, яка стане основою для подальших інтеграцій з іншими платформами.
|
||||
|
||||
---
|
||||
|
||||
**Версія:** 1.0
|
||||
**Останнє оновлення:** 2024-11-14
|
||||
|
||||
|
||||
Reference in New Issue
Block a user