@tinkcarlos/skillora 0.2.0

package/.claude/skills/fullstack-developer/references/async-patterns.md

@@ -0,0 +1,220 @@
+# Async-First Architecture Patterns
+
+## When to Use Async
+
+| Operation | Expected Duration | Sync? | Async? |
+|-----------|------------------|-------|--------|
+| Simple CRUD | < 100ms | ✅ | ❌ |
+| File upload | Seconds | ❌ | ✅ |
+| AI generation | Seconds~Minutes | ❌ | ✅ (SSE) |
+| Data export | Seconds~Minutes | ❌ | ✅ |
+| Email sending | Seconds | ❌ | ✅ |
+| User-interruptible ops | Any | ❌ | ✅ |
+| Batch processing | Minutes | ❌ | ✅ |
+
+---
+
+## Architecture Pattern
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    ASYNC OPERATION FLOW                 │
+├─────────────────────────────────────────────────────────┤
+│                                                         │
+│  Frontend                    Backend                    │
+│  ────────                    ───────                    │
+│                                                         │
+│  [User Click]                                           │
+│       │                                                 │
+│       ▼                                                 │
+│  Optimistic Update ──────────► Schedule Background Task │
+│       │                              │                  │
+│       ▼                              ▼                  │
+│  Show "Saving..." ◄─────────── Task Manager             │
+│       │                              │                  │
+│       ▼                              ▼                  │
+│  Poll /status API ◄────────────► Worker Executes        │
+│       │                              │                  │
+│       ▼                              ▼                  │
+│  [is_saving: false] ◄────────── Task Complete           │
+│       │                                                 │
+│       ▼                                                 │
+│  Refresh Data                                           │
+│                                                         │
+└─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Backend Implementation
+
+### 1. Task Manager (Singleton)
+
+```python
+from dataclasses import dataclass
+from enum import Enum
+import asyncio
+from datetime import datetime
+
+class TaskStatus(str, Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    COMPLETED = "completed"
+    FAILED = "failed"
+
+@dataclass
+class BackgroundTask:
+    task_id: str
+    session_id: str
+    status: TaskStatus
+    created_at: datetime
+    completed_at: datetime | None = None
+
+class BackgroundTaskManager:
+    _instance = None
+    
+    def __new__(cls):
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._tasks = {}
+        return cls._instance
+    
+    def schedule(self, task_id, session_id, coro):
+        task = BackgroundTask(task_id, session_id, TaskStatus.RUNNING, datetime.utcnow())
+        self._tasks[task_id] = task
+        asyncio.create_task(self._run(task_id, coro))
+        return task
+    
+    async def _run(self, task_id, coro):
+        try:
+            await coro
+            self._tasks[task_id].status = TaskStatus.COMPLETED
+        except Exception:
+            self._tasks[task_id].status = TaskStatus.FAILED
+        finally:
+            self._tasks[task_id].completed_at = datetime.utcnow()
+    
+    def has_pending(self, session_id) -> bool:
+        return any(
+            t.session_id == session_id and t.status == TaskStatus.RUNNING
+            for t in self._tasks.values()
+        )
+
+task_manager = BackgroundTaskManager()
+```
+
+### 2. Status API
+
+```python
+@router.get("/sessions/{session_id}/save-status")
+async def get_save_status(session_id: str):
+    return {"is_saving": task_manager.has_pending(session_id)}
+```
+
+### 3. Using Background Tasks
+
+```python
+def schedule_save(session_id: str, content: str):
+    async def save_coro():
+        # Use independent connection (original may be closed)
+        async with async_session_maker() as db:
+            db.add(Message(content=content))
+            await db.commit()
+    
+    task_manager.schedule(f"save_{uuid.uuid4().hex[:8]}", session_id, save_coro())
+```
+
+---
+
+## Frontend Implementation
+
+### 1. Status Hook
+
+```typescript
+export function useAsyncStatus(sessionId: string) {
+  const [isSaving, setIsSaving] = useState(false);
+  
+  const checkStatus = async (): Promise<boolean> => {
+    const res = await api.get(`/sessions/${sessionId}/save-status`);
+    return res.data.is_saving === true;
+  };
+  
+  const waitForComplete = async (pollMs = 300, timeoutMs = 10000) => {
+    const start = Date.now();
+    setIsSaving(true);
+    while (Date.now() - start < timeoutMs) {
+      if (!(await checkStatus())) {
+        setIsSaving(false);
+        return true;
+      }
+      await new Promise(r => setTimeout(r, pollMs));
+    }
+    setIsSaving(false);
+    return false;
+  };
+  
+  return { isSaving, checkStatus, waitForComplete };
+}
+```
+
+### 2. Sync Indicator
+
+```tsx
+const SyncIndicator = ({ isSaving }: { isSaving: boolean }) => {
+  if (!isSaving) return null;
+  return (
+    <div className="flex items-center gap-2 px-4 py-2 bg-amber-500/10 rounded-lg">
+      <Loader2 className="h-4 w-4 animate-spin" />
+      <span>Syncing...</span>
+    </div>
+  );
+};
+```
+
+---
+
+## Best Practices
+
+### 1. Independent DB Connections
+Background tasks cannot reuse request's connection (may be closed).
+
+```python
+# ❌ Wrong: Reuse connection
+async def background_task(self):
+    await self.db.commit()  # May be closed
+
+# ✅ Correct: New connection
+async def background_task():
+    async with async_session_maker() as db:
+        await db.commit()
+```
+
+### 2. Task Timeout
+```python
+async def _run(self, task_id, coro):
+    try:
+        await asyncio.wait_for(coro, timeout=60)
+    except asyncio.TimeoutError:
+        self._tasks[task_id].status = TaskStatus.FAILED
+```
+
+### 3. Periodic Cleanup
+```python
+def cleanup_old_tasks(self, max_age_seconds=3600):
+    now = datetime.utcnow()
+    to_remove = [tid for tid, t in self._tasks.items()
+                 if t.completed_at and (now - t.completed_at).seconds > max_age_seconds]
+    for tid in to_remove:
+        del self._tasks[tid]
+```
+
+---
+
+## Error Handling
+
+| Scenario | Frontend | Backend |
+|----------|----------|---------|
+| Task timeout | Show error + retry | Mark failed, log |
+| Task failed | Show error details | Return error field |
+| Poll failed | Retry 3x then stop | Ensure API stable |
+| User leaves | No impact | Task continues |