@tinkcarlos/skillora 0.2.0

package/.claude/skills/code-review/references/functional-completeness.md

@@ -0,0 +1,386 @@
+# Functional Completeness Verification Guide
+
+> **CRITICAL LESSON**: Code quality review ≠ Functional completeness verification. You MUST validate complete user flows from the end-user perspective!
+
+## 🔴 2024-12 Case Study: Why This Guide is Critical
+
+```
+Project: Agent Desktop Chat Application
+Bug Report: "401 Not authenticated" on all API calls
+
+Investigation Timeline:
+1. Code review started - reviewed chat service, API routes, auth endpoints
+2. Backend auth API was complete and working ✅
+3. Frontend Login route existed at /login ✅
+4. Frontend had token retrieval code: localStorage.getItem('token') ✅
+
+MISSED ISSUES (Found only after user report):
+5. Login component was: `const Login = () => <h1>登录页面</h1>` ❌
+   - No form, no inputs, no submit handler
+   - No API call to POST /auth/login
+   - No token storage (localStorage.setItem was never called!)
+6. No route guards - user could access /chat directly without login
+7. Request body mismatch: frontend sent {message}, backend expected {content}
+
+Root Cause: Code review focused on "code quality" not "does it work?"
+Impact: Complete application failure - no user could authenticate
+
+Lesson: Phase 0 MUST be a BLOCKING gate with ACTUAL APPLICATION TESTING
+```
+
+## Why This Guide Exists
+
+| Failure Case | What Was Missed | User Impact |
+|--------------|-----------------|-------------|
+| Login page is placeholder | No actual login form implemented | 401 errors on all protected routes |
+| No route guards | Protected routes accessible without auth | Security vulnerability |
+| API exists but not consumed | Backend ready, frontend not connected | Feature appears broken |
+| Placeholder components | `<div>Coming Soon</div>` in production | Incomplete product |
+| Field name mismatch | `{message}` vs `{content}` | 422 Validation Error |
+| SSE field mismatch | `data.tool` vs `data.tool_name` | Tool calls not displayed |
+| Token only GET, no SET | Token retrieval exists, storage doesn't | Auth always fails |
+
+---
+
+## Phase 0: Functional Completeness Verification (MANDATORY - BLOCKING)
+
+> ⛔ **BLOCKING GATE**: You CANNOT proceed to code quality review until Phase 0 passes!
+> This phase requires ACTUAL APPLICATION EXECUTION, not just code reading.
+
+**This phase MUST be executed BEFORE any code-level review.**
+
+### 0.1 Startup Test (MANDATORY - MUST ACTUALLY RUN)
+
+**You MUST actually start the application and test it:**
+
+```bash
+# Step 1: Start Backend
+cd backend
+pip install -r requirements.txt  # or: poetry install
+python -m uvicorn app.main:app --reload --port 8000
+
+# Step 2: Verify Backend
+curl http://localhost:8000/health
+curl http://localhost:8000/docs  # Should show Swagger UI
+
+# Step 3: Start Frontend
+cd frontend
+npm install
+npm run dev
+
+# Step 4: Open Browser
+open http://localhost:5173  # or xdg-open on Linux
+```
+
+```markdown
+## Startup Test Checklist (MUST PASTE EVIDENCE)
+
+### Backend Startup
+- [ ] Backend server starts without errors
+  Evidence: [paste terminal output]
+- [ ] Database connection successful
+- [ ] All migrations applied
+- [ ] Health check returns 200: `curl http://localhost:8000/health`
+  Evidence: [paste output]
+- [ ] API docs accessible: http://localhost:8000/docs
+
+### Frontend Startup
+- [ ] Frontend dev server starts without errors
+  Evidence: [paste terminal output]
+- [ ] No console errors on initial load
+  Evidence: [screenshot or "No errors"]
+- [ ] Can access root URL (e.g., http://localhost:5173)
+- [ ] Assets load correctly (no 404s in Network tab)
+
+### Critical Flow Test (MUST EXECUTE - NOT OPTIONAL)
+
+> 🔴 **BLOCKING**: If any of these fail, STOP review and report as P0 blocker!
+
+- [ ] **Authentication Flow**:
+  - Open DevTools → Network tab
+  - Navigate to /login
+  - Is there an actual login FORM? (not just text)
+  - Does form have username/email and password inputs?
+  - Does clicking login trigger POST /auth/login?
+  - Does success response contain access_token?
+  - Is token stored (check Application → localStorage)?
+  
+- [ ] **Protected Route Access**:
+  - Clear localStorage: `localStorage.clear()`
+  - Navigate to protected route (e.g., /chat)
+  - Does it redirect to /login? (It SHOULD if auth required)
+  - If no redirect → Route guards missing → P0 blocker
+  
+- [ ] **Core Feature E2E**:
+  - Login with valid credentials (or create test user)
+  - Navigate to main feature
+  - Perform primary action
+  - Check Network tab - all API calls succeed?
+  - Check response data displayed correctly?
+```
+
+---
+
+### 0.2 E2E User Journey Verification
+
+**Trace complete user journeys, not just code paths:**
+
+```markdown
+## User Journey: [Feature Name]
+
+### Journey Steps
+| Step | User Action | Expected Result | Actual Result | Status |
+|------|-------------|-----------------|---------------|--------|
+| 1 | Open app | See login page OR dashboard | | ⬜ |
+| 2 | Login (if required) | Redirected to dashboard | | ⬜ |
+| 3 | Navigate to feature | Feature page loads | | ⬜ |
+| 4 | Perform action | Action succeeds | | ⬜ |
+| 5 | See result | Correct feedback shown | | ⬜ |
+
+### Journey Verdict
+- [ ] Journey completes successfully
+- [ ] All steps have implemented UI
+- [ ] All API calls succeed
+- [ ] Error states handled gracefully
+```
+
+---
+
+### 0.3 Authentication Flow Completeness
+
+**CRITICAL for any app with protected routes:**
+
+```markdown
+## Auth Flow Verification
+
+### Frontend Auth Components
+| Component | Required | Exists | Functional | Location |
+|-----------|----------|--------|------------|----------|
+| Login Page | ✅ | ⬜ | ⬜ | |
+| Login Form | ✅ | ⬜ | ⬜ | |
+| Register Page | Optional | ⬜ | ⬜ | |
+| Logout Button | ✅ | ⬜ | ⬜ | |
+| Route Guard | ✅ | ⬜ | ⬜ | |
+| Token Storage | ✅ | ⬜ | ⬜ | |
+| Auth Context/Store | ✅ | ⬜ | ⬜ | |
+
+### Backend Auth APIs
+| Endpoint | Required | Exists | Tested | Notes |
+|----------|----------|--------|--------|-------|
+| POST /auth/login | ✅ | ⬜ | ⬜ | |
+| POST /auth/register | Optional | ⬜ | ⬜ | |
+| POST /auth/refresh | ✅ | ⬜ | ⬜ | |
+| GET /auth/me | ✅ | ⬜ | ⬜ | |
+
+### Auth Integration Check
+| Check | Status | Notes |
+|-------|--------|-------|
+| Frontend calls login API | ⬜ | |
+| Token stored after login | ⬜ | |
+| Token sent in API requests | ⬜ | |
+| 401 response triggers re-login | ⬜ | |
+| Protected routes check auth state | ⬜ | |
+```
+
+---
+
+### 0.4 Placeholder & Stub Detection
+
+**Find code that looks complete but isn't:**
+
+```bash
+# Detect placeholder components
+grep -rn "Coming Soon\|TODO\|FIXME\|Not Implemented\|Placeholder" --include="*.tsx" --include="*.vue"
+
+# Detect stub functions
+grep -rn "throw new Error.*not implemented\|console.log.*TODO\|pass  # TODO" --include="*.py" --include="*.ts"
+
+# Detect empty handlers
+grep -rn "onClick={() => {}}\|onChange={() => {}}\|onSubmit={() => {}}" --include="*.tsx"
+
+# Detect mock data in production code
+grep -rn "mock\|dummy\|fake\|test.*data" --include="*.ts" --include="*.tsx" | grep -v "__tests__\|\.test\.\|\.spec\."
+
+# Detect placeholder pages (single-line components)
+grep -rn "const.*Page.*=.*().*=>.*<div>.*</div>" --include="*.tsx"
+```
+
+### Common Placeholder Patterns
+
+| Pattern | Example | Risk Level |
+|---------|---------|------------|
+| Single-line component | `const Login = () => <div>Login</div>` | 🔴 Critical |
+| Empty handler | `onClick={() => {}}` | 🔴 Critical |
+| TODO in production | `// TODO: implement` | 🟠 High |
+| Mock data used | `const users = mockUsers` | 🟠 High |
+| Commented code | `// api.post('/login', data)` | 🟡 Medium |
+
+---
+
+### 0.5 Frontend-Backend Contract Verification (FIELD-LEVEL)
+
+> 🔴 **2024-12 LESSON**: Frontend sent `{ message: "hello" }`, backend expected `{ content: "hello" }` → 422 Error
+
+**Ensure frontend actually consumes backend APIs with CORRECT field names:**
+
+```bash
+# Step 1: Extract backend request schemas
+echo "=== Backend Request Models ==="
+grep -rn "class.*Request.*BaseModel" --include="*.py" -A 10
+
+# Step 2: Extract frontend request bodies
+echo "=== Frontend Request Bodies ==="
+grep -rn "JSON.stringify\|body:" --include="*.ts" --include="*.tsx" -B 2 -A 5
+
+# Step 3: MANUALLY COMPARE field names character by character!
+```
+
+```markdown
+## API Contract Status (FIELD-LEVEL VERIFICATION)
+
+### Request Body Field Matching (CRITICAL - 2024-12)
+| API Endpoint | Backend Expects | Frontend Sends | Match? | Issue |
+|--------------|-----------------|----------------|--------|-------|
+| POST /auth/login | `{ username, password }` | `{ email, password }` | ❌ | Field name! |
+| POST /api/v1/chat | `{ content, parent_id }` | `{ message }` | ❌ | Field name! |
+| POST /api/v1/sessions | `{ title }` | `{ title }` | ✅ | OK |
+
+### SSE/WebSocket Event Matching (CRITICAL)
+| Event Type | Backend Sends | Frontend Expects | Match? |
+|------------|---------------|------------------|--------|
+| tool_start | `{ tool_name, arguments }` | `{ tool, args }` | ❌ |
+| tool_result | `{ tool_name, result, duration_ms }` | `{ tool, result }` | ❌ |
+| token | `{ prompt_tokens, completion_tokens }` | | ⬜ |
+| done | `{ message_id }` | | ⬜ |
+
+### How to Verify
+1. List all backend endpoints (from routes/routers)
+2. Search frontend for each endpoint URL
+3. **CRITICAL**: Compare request payload fields CHARACTER BY CHARACTER
+4. **CRITICAL**: Compare SSE event names AND payload fields
+5. Verify response handling exists
+
+### Missing Integrations (CRITICAL)
+| Backend API | Purpose | Frontend Status | Action Needed |
+|-------------|---------|-----------------|---------------|
+| | | | |
+```
+
+### Contract Verification Evidence Template
+
+```markdown
+## Contract Verification Evidence
+
+### Endpoint: POST /api/v1/sessions/{id}/chat
+
+**Backend Schema** (app/api/v1/chat.py):
+```python
+class ChatRequest(BaseModel):
+    content: str          # <-- Backend expects 'content'
+    parent_id: str | None
+    llm_id: str | None
+```
+
+**Frontend Call** (hooks/useChatStream.ts):
+```typescript
+body: JSON.stringify({ 
+    message: content    // <-- Frontend sends 'message' ❌ MISMATCH!
+})
+```
+
+**Verdict**: ❌ Field name mismatch - will cause 422 Validation Error
+**Fix**: Change frontend to `{ content, parent_id, llm_id }`
+```
+
+---
+
+## Phase 0 Verdict Template
+
+```markdown
+## Phase 0 Summary
+
+| Check Category | Status | Blockers |
+|----------------|--------|----------|
+| Startup Test | ✅/❌ | |
+| Auth Flow Complete | ✅/❌ | |
+| Core Journey Works | ✅/❌ | |
+| No Placeholders in Critical Path | ✅/❌ | |
+| API Contracts Verified | ✅/❌ | |
+
+### Phase 0 Decision
+- [ ] **PASS** - Proceed to code quality review
+- [ ] **FAIL** - Fix functional gaps before code review
+
+### Critical Gaps Found
+1. [Gap description + file location]
+2. [Gap description + file location]
+```
+
+---
+
+## Automated Verification Script
+
+```bash
+#!/bin/bash
+# functional-check.sh - Run before code review
+
+echo "=== Phase 0: Functional Completeness Check ==="
+
+echo ""
+echo "--- Placeholder Detection ---"
+echo "Placeholder text:"
+grep -rn "Coming Soon\|TODO\|FIXME\|Not Implemented\|Placeholder" --include="*.tsx" --include="*.ts" --include="*.vue" 2>/dev/null | head -20
+
+echo ""
+echo "Empty handlers:"
+grep -rn "onClick={() => {}}\|onChange={() => {}}\|onSubmit={() => {}}" --include="*.tsx" 2>/dev/null | head -10
+
+echo ""
+echo "Single-line placeholder components:"
+grep -rn "const.*=.*().*=>.*<div>.*</div>;" --include="*.tsx" 2>/dev/null | head -10
+
+echo ""
+echo "--- Auth Flow Check ---"
+echo "Login page/component:"
+grep -rn "login\|Login" --include="*.tsx" -l 2>/dev/null
+
+echo ""
+echo "Route guard:"
+grep -rn "ProtectedRoute\|AuthGuard\|RequireAuth\|PrivateRoute" --include="*.tsx" -l 2>/dev/null
+
+echo ""
+echo "Token storage:"
+grep -rn "localStorage.*token\|sessionStorage.*token" --include="*.ts" --include="*.tsx" 2>/dev/null | head -5
+
+echo ""
+echo "--- API Integration Check ---"
+echo "Auth API calls:"
+grep -rn "/auth/login\|/api/v1/auth" --include="*.ts" --include="*.tsx" 2>/dev/null | head -10
+
+echo ""
+echo "=== Check Complete ==="
+```
+
+---
+
+## Review Completeness Checklist (Phase 0)
+
+```markdown
+### 🚨 Phase 0: Functional Completeness (MUST VERIFY FIRST)
+- [ ] **Startup test passed** - App runs without errors
+- [ ] **Auth flow complete** - Login page exists AND works (not placeholder)
+- [ ] **Route guards active** - Protected routes redirect unauthenticated users
+- [ ] **Core user journey works** - Main feature functional end-to-end
+- [ ] **No placeholder code in critical paths** - No "TODO", "Coming Soon" in production
+- [ ] **API contracts verified** - Frontend actually calls backend APIs
+- [ ] **Token flow working** - Stored, sent, refreshed correctly
+
+### Quality Metrics (Updated)
+| Metric | Target | Actual |
+|--------|--------|--------|
+| Functional completeness | 100% | __% |
+| Auth flow implemented | 100% | __% |
+| Placeholder count | 0 | __ |
+| API integration coverage | 100% | __% |
+```
+