@tinkcarlos/skillora 0.2.0

package/.claude/skills/fullstack-developer/references/skill-router-table.md

@@ -0,0 +1,304 @@
+# Skill Router Table
+
+## 核心原则
+
+**根据任务类型自动路由到对应的 Skills，不硬编码路径。**
+
+---
+
+## 技能路由表
+
+### 需求与规划类
+| 任务类型 | 调用 Skills | 触发条件 |
+|----------|-------------|----------|
+| 需求分析 | `product-requirements` | 所有开发任务开始前 |
+| 详细计划 | `writing-plans` | 复杂任务需要计划时 |
+| 头脑风暴 | `brainstorming` | 需求不清晰时 |
+
+### 后端开发类
+| 任务类型 | 调用 Skills | 触发条件 |
+|----------|-------------|----------|
+| API 脚手架 | `api-scaffolding` | 新建 API 端点 |
+| API 测试 | `api-testing-observability` | API 开发完成后 |
+| 数据库设计 | `database-migrations` | 涉及数据库变更 |
+
+#### api-scaffolding 子路由
+| 任务类型 | 调用 Agent | 触发条件 |
+|----------|------------|----------|
+| 后端架构设计 | `api-scaffolding/agents/backend-architect` | 微服务/分布式系统设计 |
+| FastAPI 开发 | `api-scaffolding/agents/fastapi-pro` | Python FastAPI 项目 |
+| Django 开发 | `api-scaffolding/agents/django-pro` | Python Django 项目 |
+| GraphQL 设计 | `api-scaffolding/agents/graphql-architect` | GraphQL API 设计 |
+| FastAPI 模板 | `api-scaffolding/skills/fastapi-templates` | FastAPI 项目模板 |
+
+#### api-testing-observability 子路由
+| 任务类型 | 调用 Agent/Command | 触发条件 |
+|----------|-------------------|----------|
+| API 文档生成 | `api-testing-observability/agents/api-documenter` | OpenAPI 文档、SDK 生成 |
+| Mock Server | `api-testing-observability/commands/api-mock` | 创建 Mock 服务 |
+
+### 前端开发类
+| 任务类型 | 调用 Skills | 触发条件 |
+|----------|-------------|----------|
+| UI 设计/审查 | `frontend-design` | 任何 UI/UX 工作 (双模式: CREATE/REVIEW) |
+| React 最佳实践 | `react-best-practices` | React/Next.js 开发 |
+
+### 测试类
+| 任务类型 | 调用 Skills | 触发条件 |
+|----------|-------------|----------|
+| 测试驱动 | `test-driven-development` | 编写测试用例 |
+| Web 自动化 | `webapp-testing` (如有) | 前端页面测试 |
+
+### 质量保证类
+| 任务类型 | 调用 Skills | 触发条件 |
+|----------|-------------|----------|
+| 代码审查 | `code-review` | 开发完成后 (强制) |
+| Bug 修复 | `bug-fixing` | 审查发现问题 |
+| 验证完成 | `verification-before-completion` | 准备交付前 |
+
+### 部署与分支类
+| 任务类型 | 调用 Skills | 触发条件 |
+|----------|-------------|----------|
+| 部署 | `vercel-deploy` | 需要部署时 |
+| 分支管理 | `finishing-a-development-branch` | 准备合并时 |
+| Git Worktree | `using-git-worktrees` | 需要隔离环境 |
+
+### 运维与安全类
+| 任务类型 | 调用 Skills | 触发条件 |
+|----------|-------------|----------|
+| 安全审计 | `security-audit` | 代码安全检查、OWASP 合规 |
+| 性能优化 | `performance-optimization` | 性能瓶颈分析、优化 |
+| CI/CD 配置 | `cicd-pipeline` | 流水线配置、自动化部署 |
+| 容器化 | `containerization` | Docker、Kubernetes 部署 |
+
+---
+
+## 自动路由规则
+
+### 关键词触发
+| 关键词 | 自动调用 |
+|--------|----------|
+| 需求、PRD、功能 | `product-requirements` |
+| API、接口、端点 | `api-scaffolding` + `api-testing-observability` |
+| REST、GraphQL、gRPC | `api-scaffolding` |
+| OpenAPI、Swagger | `api-scaffolding` |
+| Mock、模拟服务 | `api-testing-observability` |
+| 可观测性、监控、日志 | `api-testing-observability` |
+| 契约测试、API 测试 | `api-testing-observability` |
+| 数据库、表、迁移 | `database-migrations` |
+| 页面、组件、UI | `frontend-design` |
+| 测试、用例 | `test-driven-development` |
+| 审查、review | `code-review` |
+| bug、修复、错误 | `bug-fixing` |
+| 部署、上线 | `vercel-deploy` |
+| 安全、漏洞、OWASP | `security-audit` |
+| 性能、优化、慢、瓶颈 | `performance-optimization` |
+| CI/CD、流水线、GitHub Actions | `cicd-pipeline` |
+| Docker、容器、Kubernetes、K8s | `containerization` |
+| 日志、ELK、Sentry、追踪 | `api-testing-observability` |
+
+### 框架关键词触发
+| 关键词 | 自动调用 |
+|--------|----------|
+| FastAPI | `api-scaffolding/agents/fastapi-pro` |
+| Django | `api-scaffolding/agents/django-pro` |
+| GraphQL | `api-scaffolding/agents/graphql-architect` |
+| 微服务、分布式 | `api-scaffolding/agents/backend-architect` |
+
+### 强制调用规则
+| 条件 | 必须调用 | 原因 |
+|------|----------|------|
+| 任何开发任务 | `product-requirements` | 确保需求清晰 |
+| 任何 UI 工作 | `frontend-design` | 确保界面质量 |
+| 新建 API | `api-scaffolding` | Contract-first 开发 |
+| API 开发完成 | `api-testing-observability` | 契约测试 + 可观测性 |
+| 开发完成后 | `code-review` | 确保代码质量 |
+| 审查发现问题 | `bug-fixing` | 循环直到解决 |
+| 涉及数据库 | `database-migrations` | 确保 schema 同步 |
+| 安全敏感代码 | `security-audit` | 确保无漏洞 |
+| 性能问题 | `performance-optimization` | 确保性能达标 |
+| 准备部署 | `cicd-pipeline` + `containerization` | 确保部署流程 |
+
+---
+
+## 组合调用模式
+
+### 完整后端开发
+```
+product-requirements
+    ↓
+database-migrations (如需)
+    ↓
+api-scaffolding
+    │
+    ├── Contract 定义 (OpenAPI)
+    ├── 项目结构生成
+    ├── 端点实现 + 验证
+    └── 认证/授权
+    ↓
+api-testing-observability
+    │
+    ├── 契约测试
+    ├── 集成测试
+    ├── Mock Server (外部依赖)
+    └── 可观测性设置
+    ↓
+code-review → bug-fixing (循环)
+```
+
+### 完整前端开发
+```
+product-requirements
+    ↓
+frontend-design
+    ↓
+react-best-practices (如 React)
+    ↓
+web-design-guidelines
+    ↓
+test-driven-development
+    ↓
+code-review → bug-fixing (循环)
+```
+
+### 完整全栈开发
+```
+product-requirements
+    ↓
+database-migrations
+    ↓
+api-scaffolding
+    │
+    └── (选择框架 agent)
+        ├── fastapi-pro (Python)
+        ├── django-pro (Python)
+        └── backend-architect (架构设计)
+    ↓
+api-testing-observability
+    │
+    ├── api-documenter (文档生成)
+    └── api-mock (Mock 服务)
+    ↓
+frontend-design + react-best-practices
+    ↓
+web-design-guidelines
+    ↓
+test-driven-development
+    ↓
+code-review → bug-fixing (循环)
+    ↓
+verification-before-completion
+    ↓
+finishing-a-development-branch
+```
+
+### 生产部署流程
+```
+code-review 通过
+    ↓
+security-audit
+    │
+    ├── OWASP Top 10 检查
+    ├── 依赖漏洞扫描
+    └── 敏感信息检查
+    ↓
+performance-optimization (如需)
+    │
+    ├── 性能基准测试
+    └── 瓶颈优化
+    ↓
+containerization
+    │
+    ├── Dockerfile 优化
+    ├── 镜像构建
+    └── 安全扫描
+    ↓
+cicd-pipeline
+    │
+    ├── CI 流水线配置
+    ├── CD 部署配置
+    └── 安全扫描集成
+    ↓
+log-analysis
+    │
+    ├── 结构化日志配置
+    ├── 可观测性设置
+    └── 错误追踪集成
+    ↓
+部署完成
+```
+
+---
+
+## 技能切换通知
+
+每次切换技能时，必须输出：
+
+```markdown
+🔄 技能切换: [当前技能] → [新技能]
+原因: [切换原因]
+```
+
+---
+
+## Skill 核心功能速查
+
+### api-scaffolding
+| 功能 | 说明 |
+|------|------|
+| Contract-First | 先定义 OpenAPI 契约再写代码 |
+| 项目结构 | FastAPI / NestJS 标准结构 |
+| 安全模式 | JWT / OAuth2 / API Key |
+| 输入验证 | Pydantic / Zod schema |
+| 错误处理 | 统一错误响应格式 |
+
+### api-testing-observability
+| 功能 | 说明 |
+|------|------|
+| 契约测试 | Schemathesis 验证 OpenAPI |
+| 集成测试 | pytest + httpx / Jest + Supertest |
+| Mock Server | 场景化 Mock、状态管理 |
+| 可观测性 | Logging + Metrics + Tracing |
+| Health Check | liveness / readiness 端点 |
+
+### security-audit
+| 功能 | 说明 |
+|------|------|
+| OWASP Top 10 | 完整漏洞检查清单 |
+| SAST | 静态代码安全分析 |
+| 依赖扫描 | CVE 漏洞检测 |
+| 敏感信息 | 密钥/密码泄露检查 |
+| 认证审查 | Auth/AuthZ 逻辑审查 |
+
+### performance-optimization
+| 功能 | 说明 |
+|------|------|
+| CPU 分析 | cProfile / py-spy / pprof |
+| 内存分析 | Memory Profiler / Heap Snapshot |
+| 数据库优化 | N+1 检测、索引优化 |
+| 缓存策略 | 多级缓存、LRU/TTL |
+| 负载测试 | wrk / k6 / locust |
+
+### cicd-pipeline
+| 功能 | 说明 |
+|------|------|
+| GitHub Actions | CI/CD 工作流模板 |
+| GitLab CI | 多阶段流水线 |
+| 安全扫描 | Snyk / CodeQL / TruffleHog |
+| 部署策略 | Rolling / Blue-Green / Canary |
+
+### containerization
+| 功能 | 说明 |
+|------|------|
+| Dockerfile | 多阶段构建、最小镜像 |
+| docker-compose | 多容器编排 |
+| Kubernetes | Deployment / Service / ConfigMap |
+| 安全加固 | 非 root、镜像扫描 |
+
+### log-analysis
+| 功能 | 说明 |
+|------|------|
+| 结构化日志 | JSON 格式、请求 ID 关联 |
+| 日志聚合 | ELK Stack / Loki + Grafana |
+| 错误追踪 | Sentry 集成 |
+| 日志查询 | KQL / LogQL 语法 |

package/.claude/skills/fullstack-developer/references/state-sync.md

@@ -0,0 +1,217 @@
+# Frontend-Backend State Synchronization Patterns
+
+## Core Problem
+
+Frontend and backend state inconsistency causes:
+- User sees stale data
+- Operation results don't match expectations
+- Data loss (e.g., on interruption)
+
+---
+
+## Pattern 1: Optimistic Update + Rollback
+
+**Use When**: Most operations succeed; can rollback on failure
+
+```typescript
+const handleSave = async (newItem) => {
+  // 1. Optimistic: Update UI immediately
+  const prevItems = items;
+  setItems([...items, newItem]);
+  
+  try {
+    // 2. Background: Sync to server
+    await api.post('/items', newItem);
+  } catch (error) {
+    // 3. Rollback on failure
+    setItems(prevItems);
+    showError('Save failed, please retry');
+  }
+};
+```
+
+**Pros**: Instant UI response  
+**Cons**: Requires rollback logic
+
+---
+
+## Pattern 2: LocalStorage Cache + Server Sync
+
+**Use When**: User may navigate away before save completes
+
+```typescript
+// On action: Save to localStorage
+const handleChange = (data) => {
+  setData(data);
+  localStorage.setItem(`draft_${sessionId}`, JSON.stringify({
+    data,
+    timestamp: Date.now()
+  }));
+};
+
+// Background: Periodic sync
+useEffect(() => {
+  const interval = setInterval(async () => {
+    const draft = localStorage.getItem(`draft_${sessionId}`);
+    if (draft) await api.post('/autosave', JSON.parse(draft));
+  }, 30000);  // Every 30s
+  return () => clearInterval(interval);
+}, [sessionId]);
+
+// On return: Merge local and server data
+const loadSession = async (id) => {
+  const local = JSON.parse(localStorage.getItem(`draft_${id}`));
+  const server = await fetchData(id);
+  
+  // Choose newer version
+  if (local?.timestamp > server.timestamp) return local.data;
+  return server;
+};
+```
+
+---
+
+## Pattern 3: Server Authority + Client Cache
+
+**Use When**: Server is source of truth; client only caches
+
+```typescript
+// React Query / SWR style
+const { data, refetch } = useQuery(
+  ['messages', sessionId],
+  () => fetchMessages(sessionId),
+  {
+    staleTime: 30000,           // Use cache for 30s
+    refetchOnWindowFocus: true, // Refresh on focus
+  }
+);
+
+// Force refresh after mutation
+const handleSave = async (data) => {
+  await api.post('/messages', data);
+  await refetch();
+};
+```
+
+---
+
+## Pattern 4: Real-time Sync (WebSocket/SSE)
+
+**Use When**: Real-time updates needed (collaboration, chat)
+
+```typescript
+useEffect(() => {
+  const eventSource = new EventSource(`/api/stream/${sessionId}`);
+  
+  eventSource.onmessage = (event) => {
+    setMessages(prev => [...prev, JSON.parse(event.data)]);
+  };
+  
+  eventSource.onerror = () => {
+    setStatus('reconnecting');
+    setTimeout(() => reconnect(), 1000);
+  };
+  
+  return () => eventSource.close();
+}, [sessionId]);
+```
+
+---
+
+## Pattern 5: Interrupt Recovery
+
+**Use When**: Long operations may be interrupted (AI generation)
+
+### On Interrupt
+```typescript
+// Frontend: Cache immediately
+const handleStop = () => {
+  localStorage.setItem('pending_messages', JSON.stringify({
+    sessionId,
+    messages,
+    timestamp: Date.now()
+  }));
+  abortController.abort();
+  // Don't wait for backend save
+};
+```
+
+```python
+# Backend: Schedule background save
+except asyncio.CancelledError:
+    task_manager.schedule(
+        f"save_{uuid.uuid4().hex[:8]}",
+        session_id,
+        save_partial_content(content)
+    )
+    raise
+```
+
+### On Recovery
+```typescript
+const loadSession = async (sessionId) => {
+  // 1. Wait for background save if running
+  if (await checkSaveStatus(sessionId)) {
+    await waitForComplete(sessionId);
+  }
+  
+  // 2. Fetch server data
+  const server = await fetchMessages(sessionId);
+  
+  // 3. Check local cache
+  const cached = JSON.parse(localStorage.getItem('pending_messages'));
+  if (cached?.sessionId === sessionId && Date.now() - cached.timestamp < 300000) {
+    // Use more complete version
+    if (cached.messages.length > server.length) {
+      return mergeMessages(server, cached.messages);
+    }
+    localStorage.removeItem('pending_messages');
+  }
+  
+  return server;
+};
+```
+
+---
+
+## Merge Strategies
+
+| Conflict Type | Strategy | Example |
+|---------------|----------|---------|
+| Local update | Local wins | Draft autosave |
+| Server authority | Server wins | Multi-user editing |
+| Latest version | Compare timestamps | Offline sync |
+| More complete | Compare length | Interrupt recovery |
+| User choice | Show conflict dialog | Critical data |
+
+---
+
+## Checklist
+
+- [ ] Refresh data after successful operation?
+- [ ] Rollback on network failure?
+- [ ] Save draft before user leaves?
+- [ ] Check local cache on return?
+- [ ] Status API for background tasks?
+- [ ] Can interrupted operations recover?
+- [ ] Who is authority on merge conflicts?
+
+---
+
+## Universality Notes
+
+These patterns are **technology-agnostic** and apply to:
+
+| Stack | Applicability |
+|-------|---------------|
+| React / Vue / Angular | ✅ All frontend frameworks |
+| FastAPI / Django / Express | ✅ All backend frameworks |
+| PostgreSQL / MySQL / MongoDB | ✅ All databases |
+| REST / GraphQL | ✅ All API styles |
+| Mobile (React Native / Flutter) | ✅ Same patterns apply |
+
+**Key adaptations by platform:**
+- **Mobile**: Use AsyncStorage instead of localStorage
+- **GraphQL**: Use Apollo/urql cache instead of React Query
+- **WebSocket**: Replace SSE with WS for bidirectional comms
+- **Offline-first**: Add IndexedDB for large data caching