@haposoft/cafekit 0.8.15 → 0.8.17

package/src/antigravity/workflows/docs-update.md

@@ -1,245 +0,0 @@
----
-description: Update existing documentation to match current codebase. Use when code has changed and docs are out of sync, or after adding new features.
----
-
-# /docs-update - Update Project Documentation
-
-## Overview
-
-This workflow updates all documentation to reflect the current state of the codebase:
-- Re-analyzes project structure
-- Updates all 7 documentation files
-- Syncs AGENTS.md with latest changes
-- Creates backup before updating
-
-## ⚠️ IMPORTANT: Execute Immediately
-
-**DO NOT create an implementation plan.** This workflow should be executed directly without planning mode.
-- Run all steps sequentially
-- Update files immediately as described
-- No approval needed between steps
-
----
-
-## Step 1: Verify Prerequisites
-
-**Check if docs/ exists:**
-```bash
-ls docs/ 2>/dev/null || echo "ERROR: Run '/docs-init' first"
-```
-
-**If docs/ not found:**
-- Stop and prompt: "❌ docs/ not found. Run `/docs-init` first to create documentation."
-
----
-
-## Step 2: Create Backup
-
-// turbo
-```bash
-cp -r docs docs.backup.$(date +%Y%m%d_%H%M%S)
-echo "Backup created: docs.backup.{timestamp}"
-```
-
----
-
-## Step 3: Ensure Repomix Available
-
-**Check if repomix is installed:**
-```bash
-which repomix 2>/dev/null || npm list -g repomix 2>/dev/null
-```
-
-**If repomix not found:**
-- Detect package manager:
-  ```bash
-  test -f pnpm-lock.yaml && PM="pnpm"
-  test -f yarn.lock && PM="yarn"
-  test -f bun.lockb && PM="bun"
-  PM="${PM:-npm}"
-  ```
-
-// turbo
-- Run `$PM install -g repomix`
-
----
-
-## Step 4: Re-analyze Codebase
-
-// turbo
-```bash
-repomix
-ls -la ./repomix-output.xml
-```
-
-**Detect recent changes:**
-```bash
-git diff --stat HEAD~5..HEAD 2>/dev/null || echo "No git history"
-```
-
----
-
-## Step 5: Read Current Documentation
-
-Read all existing docs to understand what needs updating:
-- `docs/codebase-summary.md`
-- `docs/project-overview-pdr.md`
-- `docs/code-standards.md`
-- `docs/system-architecture.md`
-- `docs/design-guidelines.md`
-- `docs/deployment-guide.md`
-- `docs/project-roadmap.md`
-- `.agent/rules/AGENTS.md` (if exists)
-
----
-
-## Step 6: Detect Updated Project Info
-
-**Re-read config files:**
-- `package.json` - check for new scripts, dependencies, version changes
-- `pyproject.toml`, `go.mod`, etc. - based on project type
-- Check for new directories or removed ones
-
-**Detect changes:**
-- New frameworks/libraries added
-- Version updates
-- New scripts
-- Structure changes
-- New deployment configs
-- New database schemas
-
----
-
-## Step 7: Update Documentation Files
-
-### 7.1 Update docs/codebase-summary.md
-
-**Refresh:**
-- File count and token count from repomix
-- Tech stack versions (from package.json)
-- Directory structure if changed
-- Timestamp
-
-### 7.2 Update docs/project-overview-pdr.md
-
-**Add:**
-- New features detected in codebase
-- Updated description if changed
-- Any new capabilities
-
-### 7.3 Update docs/code-standards.md
-
-**Sync:**
-- New patterns detected in code
-- Updated conventions
-- New linting rules if config changed
-
-### 7.4 Update docs/system-architecture.md
-
-**Update:**
-- New components or services
-- Changed data flows
-- New API endpoints
-- Database schema changes
-
-### 7.5 Update docs/design-guidelines.md
-
-**Refresh:**
-- New UI components
-- Updated styling patterns
-- Theme changes
-
-### 7.6 Update docs/deployment-guide.md
-
-**Update:**
-- New environment variables
-- Changed deployment commands
-- Platform updates
-
-### 7.7 Update docs/project-roadmap.md
-
-**Progress tracking:**
-- Mark completed items
-- Add new tasks based on TODOs found
-- Update technical debt section
-
----
-
-## Step 8: Update .agent/rules/AGENTS.md
-
-**Check if .agent/rules/AGENTS.md exists:**
-```bash
-test -f .agent/rules/AGENTS.md && cat .agent/rules/AGENTS.md || echo "NOT_FOUND"
-```
-
-**If exists - Update sections:**
-- **Tech Stack** - Update versions, add new dependencies
-- **Key Directories** - Add new directories
-- **Quick Commands** - Sync with package.json scripts
-- **Last Updated** - Refresh timestamp
-
-**If not exists - Create new:**
-- Use same template as in `/docs-init`
-- Or skip if user không muốn tạo
-
-**Note:** `.agent/rules/AGENTS.md` với `activation: always_on` sẽ luôn active trong Antigravity.
-
----
-
-## Step 9: Clean Up
-
-// turbo
-**Remove old repomix if needed:**
-```bash
-# Keep repomix-output.xml for AI context
-ls -la repomix-output.xml
-```
-
----
-
-## Step 10: Generate Report
-
-**Output success message:**
-
-```
-🔄 Documentation updated!
-
-💾 Backup: docs.backup.{timestamp}/
-
-📊 Changes:
-   - Files: {old_count} → {new_count}
-   - Tokens: {old_tokens} → {new_tokens}
-
-📝 Updated:
-   ✓ codebase-summary.md
-   ✓ project-overview-pdr.md
-   ✓ code-standards.md
-   ✓ system-architecture.md
-   ✓ design-guidelines.md
-   ✓ deployment-guide.md
-   ✓ project-roadmap.md
-   ✓ .agent/rules/AGENTS.md (if exists)
-
-💡 Review docs/ for any manual adjustments needed
-```
-
----
-
-## Error Handling
-
-| Scenario | Action |
-|----------|--------|
-| docs/ not found | Prompt to run `/docs-init` |
-| repomix fails | Continue with manual analysis |
-| Permission denied | Report path, suggest sudo/fix |
-| Conflicts detected | Ask user which version to keep |
-
----
-
-## Notes
-
-- Always create backup before updating
-- Merge existing content with new analysis
-- Preserve manual edits when possible
-- Update timestamp on all modified files
-- Keep repomix-output.xml for AI context

package/src/antigravity/workflows/impact-analysis-output-example.md

@@ -1,313 +0,0 @@
-# Ví Dụ Output: Phân Tích Impact - Thêm Xác Thực Sinh Trắc Học
-
-> Đây là ví dụ output mẫu từ workflow Impact Analysis cho một thay đổi code thực tế.
-> 
-> **Thay đổi**: Thêm tính năng xác thực sinh trắc học (Face ID/Touch ID) vào app React Native
-> 
-> **Files thay đổi**: 5 files (auth service, login screen, biometric helper, profile settings, token storage)
-
----
-
-## 📋 Tóm Tắt Nhanh
-
-**Mức độ rủi ro**: CAO ⚠️⚠️⚠️
-
-**Tác động chính**:
-- 🆕 Tính năng mới: Đăng nhập bằng Face ID/Touch ID
-- ⚠️ Breaking change: Format lưu token đã thay đổi
-- 🔄 Migration cần thiết: User hiện tại có thể phải đăng nhập lại
-
-**Thời gian ước tính**:
-- Sửa bugs: ~2 giờ
-- Testing: ~45 phút
-- Production-ready: 3-4 giờ
-
-**Vấn đề nghiêm trọng**: 3 bugs cần sửa trước khi deploy
-
----
-
-## 🎯 Tính Năng Bị Ảnh Hưởng
-
-### 1. Đăng Nhập (NGHIÊM TRỌNG) ⚠️⚠️⚠️
-
-**Hành động người dùng:**
-- ✓ Đăng nhập email/password (vẫn hoạt động)
-- 🆕 Đăng nhập bằng Face ID/Touch ID (tính năng mới)
-- ⚠️ Phiên hiện tại có thể bị mất (breaking change)
-
-**Tác động:**
-Thêm option đăng nhập bằng sinh trắc học. Đăng nhập email/password vẫn hoạt động nhưng cách lưu token đã thay đổi, có thể làm mất phiên hiện tại. User có thể phải đăng nhập lại sau khi update.
-
-**Người dùng sẽ thấy:**
-- Nút "Đăng nhập bằng Face ID" mới trên màn hình login
-- Prompt sinh trắc học khi tap nút
-- Đăng nhập nhanh hơn (không cần gõ password)
-- Có thể phải đăng nhập lại sau update app
-
-**Breaking changes:**
-- Format lưu token đã thay đổi
-- Phiên hiện tại có thể bị vô hiệu
-- User cần bật lại sinh trắc học sau update
-
----
-
-### 2. Hồ Sơ Người Dùng (TRUNG BÌNH) ⚠️
-
-**Hành động người dùng:**
-- ✓ Xem hồ sơ (không đổi)
-- ✓ Sửa hồ sơ (không đổi)
-- 🆕 Bật/Tắt sinh trắc học (setting mới)
-
-**Tác động:**
-Thêm setting mới để bật/tắt xác thực sinh trắc học trong cài đặt hồ sơ.
-
-**Người dùng sẽ thấy:**
-- Toggle mới trong Settings: "Đăng nhập bằng sinh trắc học"
-- Prompt xin permission khi bật lần đầu
-- Có thể tắt bất cứ lúc nào
-
----
-
-## 🎬 Scenarios Người Dùng
-
-### Scenario 1: Đăng Nhập Bằng Face ID (Flow Mới)
-**Khi người dùng:**
-1. Mở app
-2. Tap nút "Đăng nhập bằng Face ID"
-3. Nhìn vào camera (Face ID) hoặc đặt ngón tay (Touch ID)
-
-**Sẽ thấy:**
-- iOS: Prompt Face ID xuất hiện
-- Android: Prompt vân tay xuất hiện
-- Xác thực thành công → Đăng nhập
-- Xác thực thất bại → Hiện lỗi, cho thử lại hoặc dùng password
-
-**Cần test:** NGHIÊM TRỌNG ⚠️⚠️⚠️
-- Test trên cả iOS và Android
-- Test khi thành công
-- Test khi thất bại
-- Test khi chưa đăng ký sinh trắc học
-- Test khi từ chối permission
-
----
-
-### Scenario 2: User Hiện Tại Mở App Sau Update
-**Khi người dùng:**
-1. Đã đăng nhập trên app cũ
-2. Update lên version mới (có sinh trắc học)
-3. Mở app
-
-**Có thể thấy:**
-- Phiên bị mất → Phải đăng nhập lại
-- Hoặc: Phiên vẫn còn → Thấy option sinh trắc học mới
-
-**Cần test:** NGHIÊM TRỌNG ⚠️⚠️⚠️
-- Test migration phiên
-- Test user không bị logout
-- Test hiển thị option mới
-
----
-
-### Scenario 3: Bật Sinh Trắc Học Trong Settings
-**Khi người dùng:**
-1. Vào Profile > Settings
-2. Tap toggle "Đăng nhập bằng sinh trắc học"
-
-**Sẽ thấy:**
-- iOS: Prompt xin permission (nếu chưa cho)
-- Android: Kiểm tra đã đăng ký vân tay chưa
-- Thành công: Sinh trắc học được bật
-- Thất bại: Hiện lỗi rõ ràng
-
-**Cần test:** QUAN TRỌNG ⚠️
-- Test permission flow
-- Test khi chưa đăng ký sinh trắc học
-- Test khi từ chối permission
-
----
-
-### Scenario 4: Sinh Trắc Học Thất Bại
-**Khi người dùng:**
-1. Tap "Đăng nhập bằng Face ID"
-2. Xác thực thất bại (sai mặt/ngón tay)
-
-**Sẽ thấy:**
-- Thông báo lỗi
-- Option "Thử lại" hoặc "Dùng Password"
-- Không bị kẹt màn hình
-
-**Cần test:** QUAN TRỌNG ⚠️
-
----
-
-### Scenario 5: Thiết Bị Không Hỗ Trợ
-**Khi người dùng:**
-1. Mở app trên thiết bị không có sinh trắc học
-
-**Sẽ thấy:**
-- Nút sinh trắc học bị ẩn
-- Chỉ có option đăng nhập password
-- Thông báo: "Bật Face ID trong Settings để dùng tính năng này"
-
-**Cần test:** BÌNH THƯỜNG
-
----
-
-## ⚠️ Vấn Đề Cần Sửa
-
-### Nghiêm Trọng (3)
-
-**1. iOS Chưa Xin Permission Đúng Cách**
-- **Vị trí**: `src/utils/biometric/biometricHelper.ts:45`
-- **Vấn đề**: iOS cần xin permission trong Info.plist và runtime, nhưng code chỉ check availability
-- **Tác động**: Sinh trắc học sẽ fail trên iOS với lỗi "Permission denied"
-- **Cách sửa**: Thêm flow xin permission cho iOS
-
-```typescript
-// Sửa:
-if (Platform.OS === 'ios') {
-  const permission = await Biometrics.requestPermission();
-  if (permission !== 'granted') {
-    throw new Error('Cần cấp quyền sinh trắc học');
-  }
-}
-```
-
----
-
-**2. Thiếu Migration Token Storage**
-- **Vị trí**: `src/services/auth/authService.ts:89`
-- **Vấn đề**: Format lưu token đã đổi từ plain sang encrypted, nhưng không có logic migration
-- **Tác động**: User hiện tại sẽ bị logout sau update
-- **Cách sửa**: Thêm logic migration khi app start
-
-```typescript
-// Thêm migration:
-async function migrateTokenStorage() {
-  const oldToken = await AsyncStorage.getItem('auth_token');
-  if (oldToken && !await SecureStore.getItemAsync('auth_token_encrypted')) {
-    await SecureStore.setItemAsync('auth_token_encrypted', oldToken);
-    await AsyncStorage.removeItem('auth_token');
-  }
-}
-```
-
----
-
-**3. Không Có Fallback Khi Sinh Trắc Học Thất Bại**
-- **Vị trí**: `src/screens/Auth/LoginScreen.tsx:123`
-- **Vấn đề**: Nếu sinh trắc học fail, không có option dùng password
-- **Tác động**: User bị kẹt màn hình login
-- **Cách sửa**: Thêm nút "Dùng Password" sau khi fail
-
-```typescript
-// Thêm fallback:
-try {
-  await authenticateWithBiometric();
-} catch (error) {
-  Alert.alert(
-    'Sinh trắc học thất bại',
-    'Bạn muốn dùng password thay thế?',
-    [
-      { text: 'Thử lại', onPress: () => retry() },
-      { text: 'Dùng Password', onPress: () => showPasswordLogin() }
-    ]
-  );
-}
-```
-
----
-
-### Quan Trọng (2)
-
-**4. Android Chưa Check Đăng Ký Vân Tay**
-- Có thể crash nếu user chưa đăng ký vân tay
-
-**5. Nút Chưa Có Debouncing**
-- Tap nhiều lần → Nhiều prompts
-
----
-
-### Nhỏ (1)
-
-**6. Thiếu Loading State**
-- Màn hình trắng 1-2 giây khi check availability
-
----
-
-## ✅ Checklist Trước Khi Deploy
-
-### Code (NGHIÊM TRỌNG)
-- [ ] Sửa iOS permission (30 phút) ⚠️⚠️⚠️
-- [ ] Thêm token migration (45 phút) ⚠️⚠️⚠️
-- [ ] Thêm fallback UI (20 phút) ⚠️⚠️⚠️
-- [ ] Sửa Android enrollment check (15 phút)
-- [ ] Thêm debouncing (10 phút)
-
-### Test
-- [ ] Test trên iPhone (iOS 15+)
-- [ ] Test trên Android (Android 10+)
-- [ ] Test với mạng yếu
-- [ ] Test offline
-- [ ] Test permission flows
-- [ ] Test ảnh lớn (> 5MB)
-
-### Regression
-- [ ] Password login vẫn hoạt động
-- [ ] Logout hoạt động
-- [ ] Session persistence hoạt động
-
----
-
-## 📊 Thống Kê
-
-- Files: 5 thay đổi
-- Rủi ro: CAO ⚠️⚠️⚠️
-- Vấn đề: 6 (3 nghiêm trọng)
-- Tests cần: 8 scenarios
-- Thời gian sửa: ~2 giờ
-- Thời gian test: ~45 phút
-
----
-
-## 🚀 Bước Tiếp Theo
-
-1. ✅ Đọc báo cáo đầy đủ
-2. ⚠️ Sửa 3 vấn đề nghiêm trọng (~2 giờ)
-3. ✅ Chạy tests (~45 phút)
-4. ✅ Test trên thiết bị thật
-5. ✅ Tạo PR với báo cáo này đính kèm
-
-**Ước tính production-ready**: 3-4 giờ
-
----
-
-**💡 Lưu ý**: Đây là thay đổi HIGH RISK. Cần test kỹ trước khi deploy!
-```
-
----
-
-## Key Changes
-
-### 1. Ngôn Ngữ
-- ✅ Toàn bộ tiếng Việt
-- ✅ Thuật ngữ tech giữ nguyên (Face ID, Touch ID, etc.)
-- ✅ Dễ hiểu cho developer Việt Nam
-
-### 2. Structure
-- ✅ **Tính năng trước** (🎯 Tính Năng Bị Ảnh Hưởng)
-- ✅ **Scenarios người dùng** (🎬 Scenarios Người Dùng)
-- ✅ **Vấn đề cần sửa** (⚠️ Vấn Đề Cần Sửa)
-- ✅ **Chi tiết kỹ thuật sau** (📝 Files Đã Sửa)
-
-### 3. Focus
-- ✅ Tính năng và tác động lên user
-- ✅ Hành động cụ thể cần làm
-- ✅ Ước tính thời gian
-- ✅ Priority rõ ràng
-
-### 4. Tone
-- ✅ Thân thiện, dễ hiểu
-- ✅ Actionable (có thể hành động ngay)
-- ✅ Emoji để dễ scan
-- ✅ Checklist để track progress