@tinkcarlos/skillora 0.2.0

package/.claude/skills/fullstack-developer/references/dependency-and-integrity-protocol.md

@@ -0,0 +1,390 @@
+# Dependency Management & Code Integrity Protocol
+
+> **核心原则**: 新增依赖必须安装 → 依赖文件必须更新 → 完成后必须验证 → 验证包括兼容性和文件完整性
+
+---
+
+## 🔴 依赖管理门禁 (Dependency Management Gate)
+
+### 触发条件
+
+当代码中出现以下情况时，**必须执行依赖管理流程**：
+
+| 触发条件 | 示例 |
+|----------|------|
+| 新增 import/require 语句 | `import { Collapsible } from "@radix-ui/react-collapsible"` |
+| 安装新的组件库/UI 框架 | shadcn/ui, Ant Design, Material UI |
+| 引入新的工具函数库 | lodash, date-fns, zod |
+| 使用新的后端框架/库 | FastAPI, LangChain, Pydantic |
+| 调用新的第三方 API SDK | Stripe, OpenAI, AWS SDK |
+
+---
+
+## 依赖检测规则 (通用)
+
+### Step 1: 识别依赖类型
+
+| 项目类型 | 依赖文件 | 安装命令 |
+|----------|---------|----------|
+| Node.js/前端 | `package.json` | `npm install <pkg>` / `yarn add <pkg>` / `pnpm add <pkg>` |
+| Python | `requirements.txt` / `pyproject.toml` | `pip install <pkg>` / `uv add <pkg>` |
+| Go | `go.mod` | `go get <pkg>` |
+| Rust | `Cargo.toml` | `cargo add <pkg>` |
+| Java/Kotlin | `pom.xml` / `build.gradle` | Maven/Gradle 手动添加 |
+
+### Step 2: 检查依赖是否已存在
+
+```bash
+# Node.js - 检查 package.json
+grep "<package-name>" package.json
+
+# Python - 检查 requirements.txt
+grep "<package-name>" requirements.txt
+
+# 通用 - 检查 node_modules / venv
+ls node_modules/<package-name> 2>/dev/null || echo "Not installed"
+```
+
+### Step 3: 安装缺失依赖
+
+**🔴 必须在代码修改前或立即之后安装依赖！**
+
+```bash
+# Node.js
+npm install <package-name>
+# 或指定版本
+npm install <package-name>@<version>
+```
+
+#### 🔴 Python 虚拟环境强制要求 (NON-NEGOTIABLE)
+
+**Python 项目的所有依赖操作必须在虚拟环境中进行！**
+
+```bash
+# Step 1: 检查虚拟环境是否存在
+ls venv/ 2>/dev/null || ls .venv/ 2>/dev/null || echo "虚拟环境不存在"
+
+# Step 2: 如果不存在，创建虚拟环境
+python -m venv venv
+
+# Step 3: 激活虚拟环境 (必须!)
+# Windows CMD
+venv\Scripts\activate
+# Windows PowerShell
+.\venv\Scripts\Activate.ps1
+# Linux/Mac
+source venv/bin/activate
+
+# Step 4: 在虚拟环境中安装依赖
+pip install <package-name>
+# 或指定版本
+pip install <package-name>==<version>
+
+# Step 5: 更新 requirements.txt
+pip freeze > requirements.txt
+```
+
+**❌ 禁止事项**:
+- 禁止在全局 Python 环境中安装项目依赖
+- 禁止不激活虚拟环境就执行 `pip install`
+- 禁止使用系统 Python 运行项目脚本
+
+**✅ 验证虚拟环境激活**:
+```bash
+# 检查 which/where python 指向虚拟环境
+which python  # Linux/Mac: 应显示 .../venv/bin/python
+where python  # Windows: 应显示 ...\venv\Scripts\python.exe
+```
+
+### Step 4: 更新依赖文件
+
+**🔴 安装后必须验证依赖文件已更新！**
+
+| 项目类型 | 验证方式 |
+|----------|---------|
+| Node.js | 检查 `package.json` 和 `package-lock.json` 是否包含新依赖 |
+| Python | 执行 `pip freeze > requirements.txt` 或手动添加到 requirements.txt |
+
+---
+
+## 🔴 代码文件完整性检查 (File Integrity Check)
+
+### 触发条件
+
+当新增功能涉及以下情况时，**必须执行文件完整性检查**：
+
+| 场景 | 检查内容 |
+|------|----------|
+| 使用 UI 组件库 | 组件文件是否存在于 `components/ui/` |
+| 引用工具函数 | 工具函数文件是否存在于 `lib/` 或 `utils/` |
+| 导入类型定义 | 类型文件是否存在于 `types/` |
+| 调用 API 服务 | 服务文件是否存在于 `services/` 或 `api/` |
+
+### 检查流程
+
+```
+代码中有新 import
+       ↓
+┌──────────────────────────────────────────────────────┐
+│ Step 1: 解析 import 路径                              │
+│ ─────────────────────────────────────────────────────│
+│ 相对路径? → 检查文件是否存在                          │
+│ 别名路径 (@/)? → 解析别名后检查文件是否存在           │
+│ 包路径? → 检查 node_modules 或 site-packages         │
+└──────────────────────────────────────────────────────┘
+       ↓
+┌──────────────────────────────────────────────────────┐
+│ Step 2: 文件不存在时的处理                            │
+│ ─────────────────────────────────────────────────────│
+│ UI 组件? → 创建组件文件 (shadcn/ui 风格)              │
+│ 工具函数? → 创建工具函数文件                          │
+│ 第三方包? → 安装依赖                                  │
+└──────────────────────────────────────────────────────┘
+```
+
+### 常见缺失文件场景
+
+| 场景 | 缺失类型 | 解决方案 |
+|------|---------|----------|
+| shadcn/ui 组件 | `components/ui/xxx.tsx` | 使用 `npx shadcn@latest add xxx` 或手动创建 |
+| Radix UI 原语 | npm 包未安装 | `npm install @radix-ui/react-xxx` |
+| 自定义 Hook | `hooks/useXxx.ts` | 创建 Hook 文件 |
+| API 服务 | `services/xxxService.ts` | 创建服务文件 |
+
+---
+
+## 🔴 兼容性检查 (Compatibility Check)
+
+### 版本兼容性矩阵
+
+| 检查项 | 方法 | 风险等级 |
+|--------|------|----------|
+| **Peer Dependencies** | 检查 npm 警告信息 | 🔴 高 |
+| **Node.js 版本** | 对比 `engines` 字段 | 🔴 高 |
+| **TypeScript 版本** | 检查类型定义兼容性 | 🟡 中 |
+| **React 版本** | 检查 Hooks/API 可用性 | 🔴 高 |
+| **Python 版本** | 对比 `python_requires` | 🔴 高 |
+| 🔴 **原生模块 (Electron/RN)** | 检查是否需要编译 | 🔴 高 |
+
+---
+
+## 🔴 原生模块选型指南 (Electron/React Native)
+
+> **原则**: Electron/React Native 项目优先选择纯 JS 实现，避免原生模块编译问题
+
+### 什么是原生模块？
+
+原生模块 = 使用 C/C++/Rust 编写并编译为 `.node` 文件的 Node.js 模块
+
+**识别方法**:
+```bash
+# 方法 1: 检查 .node 文件
+ls node_modules/<pkg>/*.node
+
+# 方法 2: 检查 binding.gyp
+ls node_modules/<pkg>/binding.gyp
+
+# 方法 3: npm info
+npm info <pkg> | grep -i "native\|gyp\|c++"
+```
+
+### 原生模块 vs 纯 JS 替代方案
+
+| 功能领域 | ❌ 原生模块 (避免) | ✅ 纯 JS 替代 (推荐) |
+|----------|-------------------|---------------------|
+| **SQLite 数据库** | `better-sqlite3`, `sqlite3` | `sql.js` |
+| **图片处理** | `sharp` | `jimp`, `pica` |
+| **密码哈希** | `bcrypt` | `bcryptjs` |
+| **SCSS 编译** | `node-sass` | `sass` (dart-sass) |
+| **画布渲染** | `canvas` | HTML Canvas API |
+| **文件监听** | `fsevents` | `chokidar` |
+| **LevelDB** | `leveldown` | `level-js` |
+
+### 选型决策流程
+
+```
+需要某个依赖
+    │
+    ▼
+┌─────────────────────────────────────────────────────┐
+│ Step 1: 检查是否为 Electron/React Native 项目        │
+└─────────────────────────────────────────────────────┘
+    │
+    ▼ 是
+┌─────────────────────────────────────────────────────┐
+│ Step 2: 检查候选依赖是否为原生模块                   │
+│ → npm info <pkg> | grep -i "gyp\|native"            │
+└─────────────────────────────────────────────────────┘
+    │
+    ▼ 是原生模块
+┌─────────────────────────────────────────────────────┐
+│ Step 3: 搜索纯 JS 替代方案                           │
+│ → 搜索 "<功能> pure javascript" 或 "<功能> wasm"    │
+└─────────────────────────────────────────────────────┘
+    │
+    ├─ 有替代 → ✅ 使用纯 JS 版本
+    │
+    └─ 无替代 → 配置 electron-rebuild + asarUnpack
+```
+
+### 必须使用原生模块时的配置
+
+```json
+// package.json
+{
+  "scripts": {
+    "postinstall": "electron-rebuild"
+  }
+}
+
+// electron-builder.json5
+{
+  "asarUnpack": ["**/node_modules/<native-pkg>/**"]
+}
+
+// vite.config.ts
+{
+  rollupOptions: {
+    external: ['<native-pkg>']
+  },
+  optimizeDeps: {
+    exclude: ['<native-pkg>']
+  }
+}
+```
+
+### 🔴 强制运行时验证
+
+**安装任何依赖后，必须执行启动测试：**
+
+```bash
+# Electron 项目
+npm run dev
+# 确保无 "Cannot find module" 错误
+# 确保无 "NODE_MODULE_VERSION mismatch" 错误
+```
+
+### 兼容性检查命令
+
+```bash
+# Node.js - 检查 peer dependency 警告
+npm ls 2>&1 | grep -i "peer dep"
+
+# Node.js - 审计安全问题
+npm audit
+
+# Python - 检查依赖冲突
+pip check
+
+# Python - 查看依赖树
+pip show <package-name>
+```
+
+### 常见兼容性问题处理
+
+| 问题 | 症状 | 解决方案 |
+|------|------|----------|
+| Peer dependency 不满足 | npm 警告 | 安装兼容版本或使用 `--legacy-peer-deps` |
+| TypeScript 类型错误 | 编译失败 | 安装 `@types/xxx` 或升级 TS 版本 |
+| React 版本不匹配 | 运行时错误 | 检查组件库的 React 版本要求 |
+| Python 版本不兼容 | ImportError | 检查库的 Python 版本要求 |
+
+---
+
+## 任务完成验证清单 (Post-Task Verification)
+
+**🔴 每个开发任务结束前，必须完成以下检查：**
+
+### 依赖验证
+
+- [ ] **依赖安装完成**: 所有新增依赖已安装到项目中
+- [ ] **依赖文件更新**: `package.json` / `requirements.txt` 已包含新依赖
+- [ ] **Lock 文件同步**: `package-lock.json` / `poetry.lock` 已更新
+- [ ] **无兼容性警告**: `npm ls` / `pip check` 无报错
+
+### 文件完整性验证
+
+- [ ] **所有 import 可解析**: 无 "Cannot find module" / "ModuleNotFoundError"
+- [ ] **组件文件存在**: UI 组件文件均存在于正确路径
+- [ ] **类型定义完整**: 无 TypeScript 类型错误
+
+### 运行时验证
+
+- [ ] **开发服务器启动**: `npm run dev` / `python run.py` 无报错
+- [ ] **无控制台错误**: 浏览器/终端无红色错误
+- [ ] **核心功能正常**: 主要功能可正常使用
+
+---
+
+## 验证命令速查
+
+```bash
+# ===== Node.js 项目 =====
+# 检查依赖安装
+npm ls --depth=0
+
+# 检查 peer dependency
+npm ls 2>&1 | grep -i "peer\|missing\|invalid"
+
+# 启动开发服务器验证
+npm run dev
+
+# ===== Python 项目 (🔴 必须在虚拟环境中!) =====
+# Step 0: 检查虚拟环境是否存在
+ls venv/ 2>/dev/null || ls .venv/ 2>/dev/null || echo "需要创建虚拟环境"
+
+# Step 1: 创建虚拟环境 (如果不存在)
+python -m venv venv
+
+# Step 2: 激活虚拟环境 (🔴 必须!)
+# Windows CMD
+venv\Scripts\activate
+# Windows PowerShell  
+.\venv\Scripts\Activate.ps1
+# Linux/Mac
+source venv/bin/activate
+
+# Step 3: 验证虚拟环境已激活
+which python  # 应指向 venv/bin/python 或 venv\Scripts\python.exe
+
+# Step 4: 安装依赖
+pip install -r requirements.txt
+
+# Step 5: 检查依赖安装
+pip list | grep <package-name>
+
+# Step 6: 检查依赖冲突
+pip check
+
+# Step 7: 导出依赖 (安装新包后)
+pip freeze > requirements.txt
+
+# Step 8: 运行项目 (使用虚拟环境 Python)
+python run.py  # 或 venv/bin/python run.py
+```
+
+---
+
+## 输出契约 (Dependency Gate Report)
+
+**任务完成时，在 Output Contract 中添加：**
+
+```markdown
+## 依赖管理报告
+
+### 新增依赖
+| 包名 | 版本 | 用途 | 安装状态 |
+|------|------|------|----------|
+| @radix-ui/react-collapsible | ^1.0.0 | Collapsible 组件 | ✅ 已安装 |
+
+### 文件完整性
+| 文件 | 类型 | 状态 |
+|------|------|------|
+| components/ui/collapsible.tsx | UI 组件 | ✅ 已创建 |
+
+### 验证结果
+- [x] 依赖安装完成
+- [x] 依赖文件更新
+- [x] 无兼容性警告
+- [x] 开发服务器启动正常
+```

package/.claude/skills/fullstack-developer/references/development-phases.md

@@ -0,0 +1,333 @@
+# Development Phases Guide
+
+> Incremental delivery: Complete, test, and integrate each phase before moving on.
+
+## Phase Structure
+
+```
+┌────────────────────────────────────────────────────────────┐
+│                    DEVELOPMENT PHASES                       │
+├────────────────────────────────────────────────────────────┤
+│                                                             │
+│  Phase 1: Requirements    ─────► Approved requirements     │
+│      │                                                      │
+│      ▼                                                      │
+│  Phase 2: API Contract    ─────► Swagger/OpenAPI spec      │
+│      │                                                      │
+│      ▼                                                      │
+│  Phase 3: Backend Dev     ─────► Working APIs + tests      │
+│      │                                                      │
+│      ▼                                                      │
+│  Phase 4: Frontend Dev    ─────► UI with mocks             │
+│      │                                                      │
+│      ▼                                                      │
+│  Phase 5: Integration     ─────► Real API integration      │
+│      │                                                      │
+│      ▼                                                      │
+│  Phase 6: Polish          ─────► Edge cases + UX           │
+│      │                                                      │
+│      ▼                                                      │
+│  Phase 7: Testing         ─────► E2E + acceptance          │
+│                                                             │
+│  ⚠️ IMPORTANT: Test after EACH phase, not at the end!     │
+└────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Phase 1: Requirements Clarification
+
+### Input
+- User request / feature idea
+
+### Activities
+1. Ask clarifying questions
+2. Define scope and boundaries
+3. Identify user personas
+4. Document acceptance criteria
+5. Get user approval
+
+### Output
+- Approved requirement document
+
+### Gate Criteria
+- [ ] User has confirmed understanding
+- [ ] Scope is clear and bounded
+- [ ] Success criteria defined
+- [ ] Edge cases identified
+
+### If Needed
+→ Invoke `product-requirements` skill for formal PRD
+
+---
+
+## Phase 2: API Contract Definition
+
+### Input
+- Approved requirements
+
+### Activities
+1. Design API endpoints
+2. Define request/response schemas
+3. Document error responses
+4. Write OpenAPI/Swagger spec
+5. Review with stakeholders
+
+### Output
+- Complete OpenAPI specification
+- Swagger UI accessible
+
+### Gate Criteria
+- [ ] All endpoints documented
+- [ ] Schemas are complete
+- [ ] Error responses defined
+- [ ] Frontend team approved
+
+---
+
+## Phase 3: Backend Development
+
+### Sub-Phases
+
+#### 3A: Database Layer
+- Schema design
+- Migrations
+- Seed data
+
+**Test**: Migrations run successfully
+
+#### 3B: API Layer
+- Route definitions
+- Request validation
+- Response formatting
+
+**Test**: Swagger UI shows endpoints
+
+#### 3C: Business Logic
+- Service layer
+- Business rules
+- Data processing
+
+**Test**: Unit tests pass
+
+#### 3D: Integration
+- Connect all layers
+- API tests
+
+**Test**: Integration tests pass
+
+### Output
+- Working API endpoints
+- Swagger documentation live
+- All tests passing
+
+### Gate Criteria
+- [ ] All endpoints implemented
+- [ ] Unit tests pass (>80% coverage)
+- [ ] Integration tests pass
+- [ ] Swagger UI works
+- [ ] No security vulnerabilities
+
+---
+
+## Phase 4: Frontend Development
+
+### Sub-Phases
+
+#### 4A: Component Structure
+- Create component files
+- Define props/types
+- Basic rendering
+
+**Test**: Components render without errors
+
+#### 4B: Mock API Integration
+- Create mock data
+- Connect to mock API
+- Data flows correctly
+
+**Test**: Data displays from mocks
+
+#### 4C: UI Implementation
+- Styling
+- Layout
+- Responsiveness
+
+**Test**: Visual review passes
+
+→ If design needed: Invoke `frontend-design` or `canvas-design` skill
+
+#### 4D: Interactions
+- Event handlers
+- State management
+- User flows
+
+**Test**: All interactions work
+
+### Output
+- Complete UI with mock data
+- All states implemented
+- Responsive design
+
+### Gate Criteria
+- [ ] All components render
+- [ ] Mock data displays
+- [ ] All interactions work
+- [ ] Responsive on all breakpoints
+- [ ] No console errors
+
+---
+
+## Phase 5: Frontend-Backend Integration
+
+### Activities
+1. Replace mock with real API calls
+2. Verify data contract matches
+3. Test all endpoints
+4. Handle loading states
+5. Handle error states
+
+### Common Issues
+| Issue | Solution |
+|-------|----------|
+| Field name mismatch | Update frontend to match backend |
+| Missing error handling | Add try-catch, error UI |
+| Loading not shown | Add loading state |
+| Auth issues | Verify token handling |
+
+### Output
+- Fully integrated application
+- Real data flowing
+
+### Gate Criteria
+- [ ] All API calls work
+- [ ] Data matches between FE/BE
+- [ ] Loading states work
+- [ ] Error states work
+- [ ] Auth flows work
+
+---
+
+## Phase 6: Polish & Edge Cases
+
+### Activities
+1. Handle edge cases
+2. Improve UX
+3. Add animations
+4. Optimize performance
+5. Add analytics
+
+### Edge Cases to Test
+- Empty states
+- Maximum data
+- Network errors
+- Session timeout
+- Concurrent actions
+- Browser back button
+- Refresh behavior
+
+### Output
+- Production-ready feature
+- All edge cases handled
+
+### Gate Criteria
+- [ ] All edge cases handled
+- [ ] Performance acceptable
+- [ ] UX smooth
+- [ ] Analytics tracking
+
+---
+
+## Phase 7: Final Testing
+
+### Activities
+1. End-to-end tests
+2. Cross-browser testing
+3. Accessibility audit
+4. Security review
+5. Performance testing
+
+### Test Checklist
+
+#### Functional
+- [ ] All user flows work
+- [ ] All CRUD operations work
+- [ ] Validation works
+- [ ] Error handling works
+
+#### Non-Functional
+- [ ] Performance acceptable
+- [ ] Accessible (WCAG AA)
+- [ ] Secure (no vulnerabilities)
+- [ ] Cross-browser works
+
+### Output
+- Verified, production-ready feature
+
+### Gate Criteria
+- [ ] All tests pass
+- [ ] No critical bugs
+- [ ] Ready for deployment
+
+---
+
+## Bug Handling During Development
+
+```
+┌─────────────────────────────────────┐
+│  Bug Found During Development       │
+├─────────────────────────────────────┤
+│                                     │
+│  1. STOP current task               │
+│  2. Document the bug                │
+│  3. Assess severity                 │
+│     │                               │
+│     ├─► Minor: Fix inline           │
+│     │                               │
+│     └─► Complex: Invoke bug-fixing  │
+│                                     │
+│  4. Verify fix                      │
+│  5. Resume development              │
+│                                     │
+│  ❌ NEVER: Ignore and continue     │
+│  ❌ NEVER: "Fix later" pile-up     │
+└─────────────────────────────────────┘
+```
+
+---
+
+## Phase Gate Template
+
+```markdown
+## Phase [X] Gate Review
+
+### Completed Tasks
+| Task | Status | Notes |
+|------|--------|-------|
+| T1 | ✅ | |
+| T2 | ✅ | |
+
+### Tests Run
+| Test Type | Result | Coverage |
+|-----------|--------|----------|
+| Unit | ✅ Pass | 85% |
+| Integration | ✅ Pass | |
+| Manual | ✅ Pass | |
+
+### Issues Found
+| Issue | Severity | Resolution |
+|-------|----------|------------|
+| None | - | - |
+
+### Checklist
+- [ ] All tasks complete
+- [ ] All tests pass
+- [ ] No console errors
+- [ ] Code reviewed
+- [ ] Documentation updated
+
+### Decision
+- [ ] ✅ PASS - Proceed to next phase
+- [ ] ❌ FAIL - Fix issues first
+```
+