@tinkcarlos/skillora 0.2.0

package/.claude/skills/code-review/references/report-template.md

@@ -0,0 +1,430 @@
+# Code Review Report Template
+
+Comprehensive report format for thorough code reviews.
+
+---
+
+# Code Review Report
+
+## Review Metadata
+
+| Field | Value |
+|-------|-------|
+| **Review ID** | CR-YYYY-MM-DD-XXX |
+| **PR/MR** | #XXX |
+| **Title** | [PR Title] |
+| **Author** | @username |
+| **Reviewer** | @reviewer |
+| **Branch** | `feature/xxx` → `main` |
+| **Review Date** | YYYY-MM-DD |
+| **Review Duration** | X hours |
+
+---
+
+## Executive Summary
+
+### Verdict
+
+| Status | Meaning |
+|--------|---------|
+| 🚫 **BLOCKED** | Critical security/correctness issues. Cannot merge. |
+| 🔴 **CHANGES REQUESTED** | Significant issues must be addressed. |
+| 🟠 **APPROVED WITH COMMENTS** | Minor issues, can merge after addressing. |
+| ✅ **APPROVED** | Ready to merge. |
+
+**Current Status**: [VERDICT]
+
+### Quick Stats
+
+| Metric | Count |
+|--------|-------|
+| Files Changed | X |
+| Files Reviewed | X / X (100%) |
+| Lines Added | +XXX |
+| Lines Removed | -XXX |
+| Functions Changed | XX |
+| Tests Added/Modified | XX |
+
+### Issue Summary
+
+| Severity | Count | Must Fix |
+|----------|-------|----------|
+| 🚫 Blocker | X | Yes |
+| 🔴 Critical | X | Yes |
+| 🟠 Major | X | Recommended |
+| 🟡 Minor | X | Optional |
+| 🔵 Info | X | Optional |
+| **Total** | **XX** | |
+
+### Key Findings
+
+1. **[Most important finding]** - [Brief description]
+2. **[Second finding]** - [Brief description]
+3. **[Third finding]** - [Brief description]
+
+---
+
+## Review Plan Executed
+
+### Files Reviewed (In Order)
+
+| # | File | Type | Status | Issues | Time |
+|---|------|------|--------|--------|------|
+| 1 | `src/services/auth.ts` | Service | ✅ Complete | 3 | 15min |
+| 2 | `src/api/users.ts` | API | ✅ Complete | 2 | 10min |
+| 3 | `src/components/Login.tsx` | Component | ✅ Complete | 5 | 20min |
+| 4 | `src/utils/validation.ts` | Utility | ✅ Complete | 1 | 5min |
+| 5 | `tests/auth.test.ts` | Test | ✅ Complete | 0 | 5min |
+
+### Review Coverage
+
+```
+Total Lines Changed: 500
+Lines Reviewed: 500 (100%)
+Lines with Issues: 45 (9%)
+```
+
+---
+
+## Detailed Findings
+
+### 🚫 Blockers (Must Fix Before Merge)
+
+These issues MUST be resolved. PR cannot be merged with blockers.
+
+---
+
+#### B1: [Issue Title]
+
+| Property | Value |
+|----------|-------|
+| **File** | `src/services/auth.ts` |
+| **Line(s)** | 45-48 |
+| **Category** | Security |
+| **Severity** | 🚫 Blocker |
+
+**Current Code**:
+```typescript
+const token = jwt.sign(payload, "hardcoded-secret-key");
+```
+
+**Problem**:
+JWT secret is hardcoded in source code. This is a critical security vulnerability:
+- Secret is visible in version control
+- Cannot rotate without code change
+- Exposed in any leak of source code
+
+**Required Fix**:
+```typescript
+const token = jwt.sign(payload, process.env.JWT_SECRET);
+```
+
+**Additional Steps**:
+1. Add `JWT_SECRET` to environment variables
+2. Add to `.env.example` as placeholder
+3. Update deployment configuration
+
+---
+
+#### B2: [Next Blocker]
+[Same format]
+
+---
+
+### 🔴 Critical Issues (Must Fix)
+
+High-severity issues that should be fixed before merge.
+
+---
+
+#### C1: [Issue Title]
+
+| Property | Value |
+|----------|-------|
+| **File** | `src/api/users.ts` |
+| **Line(s)** | 23-30 |
+| **Category** | Correctness |
+| **Severity** | 🔴 Critical |
+
+**Current Code**:
+```typescript
+async function getUser(id: string) {
+  const user = await db.users.find(id);
+  return user.profile; // Can crash if user is null
+}
+```
+
+**Problem**:
+No null check on database result. Will throw TypeError if user not found.
+
+**Impact**:
+- API returns 500 instead of 404
+- Error logs filled with noise
+- Poor user experience
+
+**Recommended Fix**:
+```typescript
+async function getUser(id: string) {
+  const user = await db.users.find(id);
+  if (!user) {
+    throw new NotFoundError(`User ${id} not found`);
+  }
+  return user.profile;
+}
+```
+
+---
+
+#### C2: [Next Critical Issue]
+[Same format]
+
+---
+
+### 🟠 Major Issues (Should Fix)
+
+Significant issues that should be addressed, but won't block merge if justified.
+
+---
+
+#### M1: [Issue Title]
+
+| Property | Value |
+|----------|-------|
+| **File** | `src/components/Login.tsx` |
+| **Line(s)** | 67 |
+| **Category** | Performance |
+| **Severity** | 🟠 Major |
+
+**Current Code**:
+```tsx
+<Button onClick={() => handleSubmit(formData)} />
+```
+
+**Problem**:
+Inline arrow function creates new function reference on every render, causing unnecessary re-renders of child components.
+
+**Recommended Fix**:
+```tsx
+const handleClick = useCallback(() => handleSubmit(formData), [formData]);
+<Button onClick={handleClick} />
+```
+
+---
+
+### 🟡 Minor Issues (Nice to Have)
+
+Small improvements that would enhance code quality.
+
+| # | File | Line | Issue | Suggestion |
+|---|------|------|-------|------------|
+| m1 | auth.ts | 12 | Unused import | Remove `lodash` |
+| m2 | users.ts | 45 | Magic number | Extract to constant `MAX_RETRIES = 3` |
+| m3 | Login.tsx | 23 | Generic variable name | Rename `data` to `formData` |
+| m4 | validation.ts | 8 | Missing JSDoc | Add function documentation |
+
+---
+
+### 🔵 Suggestions (Optional)
+
+Ideas for improvement, not required.
+
+| # | File | Suggestion |
+|---|------|------------|
+| s1 | auth.ts | Consider using `zod` for runtime validation |
+| s2 | users.ts | Could benefit from caching frequent queries |
+| s3 | Login.tsx | Consider splitting into smaller components |
+
+---
+
+## File-by-File Summary
+
+### 1. `src/services/auth.ts`
+
+| Metric | Value |
+|--------|-------|
+| Lines Reviewed | 140/140 |
+| Functions Reviewed | 4/4 |
+| Issues Found | 3 |
+| Status | 🔴 Has Critical Issues |
+
+**Functions Reviewed**:
+| Function | Lines | Status | Issues |
+|----------|-------|--------|--------|
+| `login()` | 36-78 | 🔴 | 2 issues |
+| `logout()` | 79-95 | ✅ | 0 issues |
+| `validateToken()` | 96-120 | 🟡 | 1 issue |
+| `refreshToken()` | 121-140 | ✅ | 0 issues |
+
+**Key Issues**:
+- B1: Hardcoded JWT secret (Line 52)
+- C1: No rate limiting on login (Lines 36-78)
+- M1: Inconsistent error messages (Lines 41, 65)
+
+---
+
+### 2. `src/api/users.ts`
+
+| Metric | Value |
+|--------|-------|
+| Lines Reviewed | 89/89 |
+| Functions Reviewed | 5/5 |
+| Issues Found | 2 |
+| Status | 🟠 Has Major Issues |
+
+**Functions Reviewed**:
+| Function | Lines | Status | Issues |
+|----------|-------|--------|--------|
+| `getUser()` | 10-25 | 🔴 | 1 issue |
+| `createUser()` | 26-50 | ✅ | 0 issues |
+| `updateUser()` | 51-70 | 🟡 | 1 issue |
+| `deleteUser()` | 71-85 | ✅ | 0 issues |
+| `listUsers()` | 86-89 | ✅ | 0 issues |
+
+---
+
+### 3. `src/components/Login.tsx`
+
+[Same format for each file]
+
+---
+
+## Cross-Cutting Concerns
+
+### Consistency Analysis
+
+| Aspect | Status | Notes |
+|--------|--------|-------|
+| Error handling | ⚠️ Inconsistent | auth.ts uses custom errors, users.ts uses generic |
+| Logging | ✅ Consistent | All use logger service |
+| Naming | ⚠️ Minor issues | Some generic names (data, result) |
+| Types | ✅ Consistent | All functions typed |
+
+### Dependency Analysis
+
+| Changed File | Dependents | Impact |
+|--------------|------------|--------|
+| auth.ts | 5 files | All auth flows affected |
+| users.ts | 3 files | User display affected |
+
+### Test Coverage
+
+| File | Tests Exist | Coverage | New Tests Needed |
+|------|-------------|----------|------------------|
+| auth.ts | ✅ | 78% | Add rate limit test |
+| users.ts | ✅ | 65% | Add null user test |
+| Login.tsx | ❌ | 0% | Add component tests |
+
+---
+
+## Checklists Completed
+
+### Security Checklist
+
+| Check | Status | Notes |
+|-------|--------|-------|
+| No hardcoded secrets | ❌ | B1: JWT secret hardcoded |
+| Input validation | ⚠️ | Missing in some endpoints |
+| SQL injection prevention | ✅ | ORM used correctly |
+| XSS prevention | ✅ | React escapes by default |
+| CSRF protection | ✅ | Tokens implemented |
+| Auth on protected routes | ✅ | Middleware in place |
+
+### Performance Checklist
+
+| Check | Status | Notes |
+|-------|--------|-------|
+| No N+1 queries | ✅ | |
+| Proper indexes | ✅ | |
+| Memoization used | ⚠️ | M1: Missing useCallback |
+| No memory leaks | ✅ | |
+| Bundle size | ✅ | No heavy additions |
+
+### Maintainability Checklist
+
+| Check | Status | Notes |
+|-------|--------|-------|
+| Functions <50 lines | ✅ | |
+| Clear naming | ⚠️ | Some generic names |
+| No magic numbers | ⚠️ | m2: MAX_RETRIES |
+| Comments present | ✅ | |
+| Tests updated | ⚠️ | Login.tsx needs tests |
+
+---
+
+## Recommended Actions
+
+### Before Merge (Required)
+
+1. **[B1]** Replace hardcoded JWT secret with environment variable
+2. **[C1]** Add null check in `getUser()` function
+3. Run security scan to verify no other hardcoded secrets
+
+### Before Deploy (Recommended)
+
+1. **[M1]** Add `useCallback` to Login component handlers
+2. Add tests for Login.tsx component
+3. Update API documentation for changed endpoints
+
+### Follow-up (After Merge)
+
+1. Consider implementing rate limiting on auth endpoints
+2. Refactor error handling for consistency
+3. Add monitoring for new endpoints
+
+---
+
+## Discussion Points
+
+Questions or items needing author clarification:
+
+1. **Line 45 auth.ts**: Is the 30-minute token expiry intentional? Seems short for some use cases.
+2. **Line 67 users.ts**: Should soft-deleted users be included in `listUsers()`?
+3. **Login.tsx**: Any reason for not using React Hook Form for this form?
+
+---
+
+## Appendix
+
+### A. All Issues by File
+
+| File | Blockers | Critical | Major | Minor | Info |
+|------|----------|----------|-------|-------|------|
+| auth.ts | 1 | 1 | 1 | 0 | 0 |
+| users.ts | 0 | 1 | 0 | 1 | 1 |
+| Login.tsx | 0 | 0 | 1 | 2 | 1 |
+| validation.ts | 0 | 0 | 0 | 1 | 0 |
+| **Total** | **1** | **2** | **2** | **4** | **2** |
+
+### B. Lines of Code Reviewed
+
+| File | Total Lines | Changed Lines | Reviewed |
+|------|-------------|---------------|----------|
+| auth.ts | 140 | +45/-12 | 140 (100%) |
+| users.ts | 89 | +23/-5 | 89 (100%) |
+| Login.tsx | 156 | +67/-20 | 156 (100%) |
+| validation.ts | 45 | +15/-3 | 45 (100%) |
+| auth.test.ts | 89 | +34/-10 | 89 (100%) |
+| **Total** | **519** | **+184/-50** | **519 (100%)** |
+
+### C. Review Timeline
+
+| Phase | Duration | Notes |
+|-------|----------|-------|
+| Review Plan | 10 min | Created file list, prioritized |
+| Dependency Mapping | 15 min | Traced 5 layers |
+| File Reviews | 55 min | 5 files analyzed |
+| Cross-File Analysis | 10 min | Consistency check |
+| Report Generation | 15 min | This document |
+| **Total** | **~1.5 hours** | |
+
+---
+
+## Signatures
+
+**Reviewer**: @reviewer
+**Date**: YYYY-MM-DD
+**Status**: [VERDICT]
+
+---
+
+*This review was conducted following the comprehensive file-by-file review process. All files were read in their entirety and analyzed across all dimensions.*

package/.claude/skills/code-review/references/resource-limits-and-degradation.md

@@ -0,0 +1,137 @@
+# Resource Limits & Graceful Degradation (资源限制与优雅降级)
+
+**核心问题**：当系统资源受限时（内存、Token、时间），代码是否有降级策略而不是直接失败？
+
+## 🔴 必检场景
+
+### 1. LLM Token 限制
+
+**问题模式**：
+```python
+if current_tokens > max_tokens:
+    logger.warning("Token limit exceeded")
+    return  # ❌ 直接返回，用户收不到任何回复
+```
+
+**正确模式**：
+```python
+if current_tokens > max_tokens:
+    logger.warning("Token limit exceeded, applying degradation")
+    
+    # ✅ 降级策略 1: 压缩上下文
+    context = truncate_context(context, max_length=available_tokens)
+    
+    # ✅ 降级策略 2: 禁用非必要功能
+    disable_tools = True
+    
+    # ✅ 降级策略 3: 使用更小的模型
+    model = fallback_model
+    
+    # ✅ 无论如何都要尝试生成回复
+    response = generate_with_constraints(prompt, context)
+    if not response:
+        response = "抱歉，由于资源限制，无法完整处理您的请求。请尝试简化问题或清理对话历史。"
+    return response
+```
+
+### 2. 内存/连接限制
+
+**问题模式**：
+```python
+if len(items) > MAX_ITEMS:
+    raise ValueError("Too many items")  # ❌ 直接失败
+```
+
+**正确模式**：
+```python
+if len(items) > MAX_ITEMS:
+    logger.warning(f"Items exceed limit ({len(items)} > {MAX_ITEMS}), processing in batches")
+    # ✅ 分批处理
+    results = []
+    for batch in chunked(items, MAX_ITEMS):
+        results.extend(process_batch(batch))
+    return results
+```
+
+### 3. 超时限制
+
+**问题模式**：
+```python
+try:
+    result = await asyncio.wait_for(operation(), timeout=30)
+except asyncio.TimeoutError:
+    pass  # ❌ 静默失败
+```
+
+**正确模式**：
+```python
+try:
+    result = await asyncio.wait_for(operation(), timeout=30)
+except asyncio.TimeoutError:
+    logger.warning("Operation timed out, using cached/fallback result")
+    # ✅ 使用缓存或默认值
+    result = get_cached_result() or create_fallback_result()
+    # ✅ 通知用户
+    result.add_warning("操作超时，结果可能不完整")
+```
+
+## 边界条件测试清单
+
+| 场景 | 测试问题 | 期望行为 |
+|------|---------|---------|
+| 小上下文模型 | 8K token 模型 + 10K 上下文 | 压缩上下文，仍生成回复 |
+| 大数据量 | 100万条记录 | 分页/分批处理 |
+| 网络超时 | 外部 API 无响应 | 使用缓存或返回友好错误 |
+| 空输入 | 用户发送空消息 | 返回提示而非崩溃 |
+| 并发高峰 | 1000 并发请求 | 队列排队或限流提示 |
+
+## 降级策略模板
+
+```python
+class GracefulDegradation:
+    """降级策略模板"""
+    
+    STRATEGIES = [
+        ("compress_context", "压缩上下文"),
+        ("disable_features", "禁用非必要功能"),
+        ("use_fallback_model", "使用备用模型"),
+        ("use_cached_result", "使用缓存结果"),
+        ("return_partial_result", "返回部分结果"),
+        ("return_error_message", "返回友好错误"),
+    ]
+    
+    @staticmethod
+    def apply(context, limit_type):
+        """按优先级尝试降级策略"""
+        for strategy, description in GracefulDegradation.STRATEGIES:
+            try:
+                result = getattr(GracefulDegradation, strategy)(context)
+                if result.is_acceptable():
+                    logger.info(f"Degradation applied: {description}")
+                    return result
+            except Exception as e:
+                logger.warning(f"Strategy {strategy} failed: {e}")
+                continue
+        
+        # 最后兜底：确保有输出
+        return GracefulDegradation.return_error_message(context)
+```
+
+## 检查清单
+
+| # | 检查项 | Severity |
+|---|-------|----------|
+| 1 | 资源限制触发时，是否有降级策略而非直接失败？ | P0 |
+| 2 | 超时异常是否被捕获并有合理处理？ | P1 |
+| 3 | 是否测试了"最小资源"边界场景？ | P1 |
+| 4 | 用户是否能收到有意义的反馈（非空回复）？ | P0 |
+| 5 | 是否有分批/分页处理大数据量的逻辑？ | P1 |
+
+## 典型 Bug 模式
+
+| 模式 | 问题 | 解决方案 |
+|------|------|---------|
+| Hard Limit Fail | 超限直接失败 | 添加降级策略链 |
+| Silent Timeout | 超时静默失败 | 捕获并使用缓存/默认值 |
+| No User Feedback | 失败时用户无感知 | 确保返回友好错误信息 |
+| Single Path | 只有成功路径 | 添加失败路径处理 |