Initial commit

2025-11-29 18:29:15 +08:00
commit be476a3fea
76 changed files with 12812 additions and 0 deletions
--- a/skills/code-style/checklists/python-review.md
+++ b/skills/code-style/checklists/python-review.md
@@ -0,0 +1,141 @@
+# Python/FastAPI Code Review Checklist
+
+Use this checklist when reviewing Python/FastAPI code or creating pull requests for Grey Haven projects.
+
+## Formatting & Style
+
+- [ ] **Line length**: Code lines do not exceed 130 characters (CRITICAL!)
+- [ ] **Indentation**: Uses 4 spaces (not tabs or 2 spaces)
+- [ ] **Quotes**: Uses double quotes for strings (Ruff default)
+- [ ] **Line endings**: Uses Unix-style line endings (\\n)
+- [ ] **Ruff formatted**: Code is formatted with Ruff (`ruff format .`)
+- [ ] **Ruff linting**: No Ruff linting errors (`ruff check .`)
+
+## Type Hints
+
+- [ ] **Function signatures**: ALL functions have type hints (CRITICAL!)
+  - Parameters: `def get_user(user_id: str) -> Optional[User]:`
+  - Return types: Always include return type annotation
+- [ ] **MyPy passing**: `mypy app/` has no type errors
+- [ ] **Optional types**: Uses `Optional[T]` or `T | None` for nullable values
+- [ ] **Generic types**: Uses proper generic types (`list[str]`, `dict[str, Any]`)
+- [ ] **Type imports**: Imports types from `typing` module
+
+## Database Models (SQLModel)
+
+- [ ] **snake_case fields**: ALL database column names use snake_case (CRITICAL!)
+  - ✅ `created_at`, `tenant_id`, `email_address`, `is_active`
+  - ❌ `createdAt`, `tenantId`, `emailAddress`, `isActive`
+- [ ] **Multi-tenant**: Models include `tenant_id` field
+- [ ] **Field descriptions**: All fields have `description` parameter
+- [ ] **Indexes**: Frequently queried fields have `index=True`
+- [ ] **Constraints**: Foreign keys, unique constraints properly defined
+- [ ] **Timestamps**: Uses UTC datetime (`UTCDateTime` type if available)
+- [ ] **Table names**: Uses `__tablename__` with lowercase plural names
+
+## Pydantic Schemas
+
+- [ ] **Schema hierarchy**: Follows Base/Create/Update/Response pattern
+- [ ] **Validators**: Uses `@field_validator` for custom validation
+- [ ] **ConfigDict**: Response schemas have `model_config = ConfigDict(from_attributes=True)`
+- [ ] **Field constraints**: Uses appropriate constraints (`ge`, `le`, `max_length`, etc.)
+- [ ] **Optional fields**: Update schemas use `| None` for optional fields
+- [ ] **Descriptions**: All fields have descriptions in `Field(..., description="...")`
+
+## FastAPI Endpoints
+
+- [ ] **Type hints**: ALL endpoint functions fully typed with `Annotated`
+- [ ] **Docstrings**: Endpoints have comprehensive docstrings (Args, Returns, Raises)
+- [ ] **Status codes**: Uses appropriate HTTP status codes from `status` module
+- [ ] **Response models**: Endpoints specify `response_model`
+- [ ] **Dependencies**: Uses Depends() for repository and auth dependencies
+- [ ] **Error handling**: Raises HTTPException with proper status codes and messages
+- [ ] **Router prefix**: Router has appropriate prefix and tags
+
+## Repository Pattern
+
+- [ ] **Tenant isolation**: ALL queries filter by `tenant_id` (CRITICAL!)
+- [ ] **Type hints**: Repository methods fully typed
+- [ ] **Async/await**: Uses async/await for database operations
+- [ ] **Session management**: Properly commits and refreshes after changes
+- [ ] **Error handling**: Handles database errors appropriately
+- [ ] **CRUD methods**: Implements standard create, read, update, delete methods
+
+## Multi-Tenant Architecture
+
+- [ ] **Tenant filtering**: All queries include tenant_id filter
+- [ ] **Repository methods**: Accept `tenant_id` parameter
+- [ ] **Validation**: Validates user has access to requested tenant
+- [ ] **Isolation**: No cross-tenant data leakage possible
+- [ ] **Foreign keys**: Multi-tenant relationships properly enforced
+
+## Imports Organization
+
+- [ ] **Import order**: Follows Ruff isort rules:
+  1. Standard library imports
+  2. Third-party imports
+  3. Local imports (app.*)
+- [ ] **Absolute imports**: Uses absolute imports (not relative)
+- [ ] **Grouped imports**: Related imports grouped together
+- [ ] **No unused imports**: All imports are used
+
+## Testing (Pytest)
+
+- [ ] **Tests exist**: Endpoints/functions have corresponding tests
+- [ ] **Test markers**: Uses pytest markers (@pytest.mark.unit, @pytest.mark.integration)
+- [ ] **Fixtures**: Uses pytest fixtures for setup
+- [ ] **Async tests**: Async tests decorated with `@pytest.mark.asyncio`
+- [ ] **Mocking**: Uses AsyncMock/MagicMock for external dependencies
+- [ ] **Coverage**: Maintains or improves test coverage (aim for >80%)
+- [ ] **Assertions**: Tests have clear, specific assertions
+
+## Security
+
+- [ ] **Input validation**: Uses Pydantic schemas for input validation
+- [ ] **SQL injection**: Uses parameterized queries (SQLModel handles this)
+- [ ] **Authentication**: Endpoints require authentication via dependencies
+- [ ] **Authorization**: Validates user has permission for actions
+- [ ] **Secrets**: Uses environment variables for secrets (never hardcode)
+- [ ] **Rate limiting**: Critical endpoints have rate limiting
+
+## Error Handling
+
+- [ ] **HTTPException**: Raises HTTPException with proper status codes
+- [ ] **Error messages**: Error messages are descriptive and user-friendly
+- [ ] **Logging**: Errors are logged appropriately
+- [ ] **Validation errors**: Pydantic validation errors return 422
+- [ ] **Not found**: Returns 404 for missing resources
+
+## Performance
+
+- [ ] **Database queries**: Queries are efficient (no N+1 problems)
+- [ ] **Indexes**: Frequently filtered columns have indexes
+- [ ] **Pagination**: List endpoints implement pagination (limit/offset)
+- [ ] **Async operations**: Uses async/await for I/O operations
+- [ ] **Connection pooling**: Database uses connection pooling
+
+## Documentation
+
+- [ ] **Docstrings**: All functions have comprehensive docstrings
+- [ ] **OpenAPI docs**: FastAPI auto-docs are accurate and complete
+- [ ] **Type annotations**: Type hints serve as documentation
+- [ ] **README updated**: README reflects any new features/changes
+- [ ] **API examples**: Complex endpoints have usage examples
+
+## Pre-commit Checks
+
+- [ ] **Virtual env active**: Ran commands with `source .venv/bin/activate`
+- [ ] **Ruff formatting**: `ruff format .` applied
+- [ ] **Ruff linting**: `ruff check --fix .` passing
+- [ ] **MyPy**: `mypy app/` passing with no type errors
+- [ ] **Tests passing**: `pytest` passes all tests
+- [ ] **Coverage**: Test coverage meets threshold (>80%)
+- [ ] **Pre-commit hooks**: All pre-commit hooks pass
+
+## API Design
+
+- [ ] **RESTful**: Endpoints follow REST principles
+- [ ] **Naming**: Endpoints use clear, descriptive names
+- [ ] **Versioning**: API versioned appropriately (`/v1/`)
+- [ ] **Consistency**: Similar endpoints have consistent patterns
+- [ ] **CRUD complete**: Resource has full CRUD operations if needed
--- a/skills/code-style/checklists/typescript-review.md
+++ b/skills/code-style/checklists/typescript-review.md
@@ -0,0 +1,113 @@
+# TypeScript/React Code Review Checklist
+
+Use this checklist when reviewing TypeScript/React code or creating pull requests for Grey Haven projects.
+
+## Formatting & Style
+
+- [ ] **Line width**: Code lines do not exceed 90 characters
+- [ ] **Indentation**: Uses 2 spaces (not tabs or 4 spaces)
+- [ ] **Semicolons**: All statements end with semicolons
+- [ ] **Quotes**: Uses double quotes for strings (not single quotes)
+- [ ] **Trailing commas**: Has trailing commas in objects, arrays, function parameters
+- [ ] **Prettier formatted**: Code is formatted with Prettier (`npm run format`)
+- [ ] **ESLint passing**: No ESLint errors (`npm run lint`)
+
+## TypeScript
+
+- [ ] **Type safety**: No `any` types used unnecessarily (but allowed when appropriate)
+- [ ] **Type annotations**: Complex types have proper interfaces/types defined
+- [ ] **Imports organized**: Imports are auto-sorted (external → internal → relative)
+- [ ] **Path aliases**: Uses `~/` path alias for src imports (not `../..`)
+- [ ] **tsconfig compliance**: Follows strict TypeScript configuration
+
+## Database Schema (Drizzle)
+
+- [ ] **snake_case fields**: ALL database column names use snake_case (CRITICAL!)
+  - ✅ `created_at`, `tenant_id`, `email_address`
+  - ❌ `createdAt`, `tenantId`, `emailAddress`
+- [ ] **Multi-tenant**: Tables include `tenant_id` or `tenantId` field
+- [ ] **Indexes**: Frequently queried fields have indexes
+- [ ] **RLS policies**: Row Level Security policies defined for multi-tenant isolation
+- [ ] **Foreign keys**: Relationships use proper foreign key constraints
+
+## React Components
+
+- [ ] **Component structure**: Follows Grey Haven component pattern:
+  1. Imports (auto-sorted)
+  2. Types/Interfaces
+  3. Component definition
+  4. State management (hooks first)
+  5. Queries/Mutations
+  6. Effects
+  7. Event handlers
+  8. Conditional renders
+  9. Main render
+- [ ] **Naming**: Components use PascalCase (`UserProfile.tsx`)
+- [ ] **Props typed**: Component props have TypeScript interfaces
+- [ ] **Hooks named**: Custom hooks start with `use-` prefix
+- [ ] **Default export**: Route components export default
+
+## TanStack Query
+
+- [ ] **Query keys**: Uses descriptive, unique query keys
+- [ ] **staleTime**: Sets appropriate staleTime (default: 60000ms / 1 minute)
+- [ ] **Error handling**: Handles loading and error states
+- [ ] **Mutations**: Uses useMutation for data updates
+- [ ] **Invalidation**: Invalidates queries after mutations
+
+## Environment Variables
+
+- [ ] **Validation**: Environment variables validated with @t3-oss/env-core and Zod
+- [ ] **VITE_ prefix**: Client variables prefixed with `VITE_`
+- [ ] **Types**: All env variables have proper Zod schemas
+- [ ] **Documentation**: Env variables have JSDoc comments
+
+## Multi-Tenant Architecture
+
+- [ ] **Tenant isolation**: All queries filter by `tenant_id` / `tenantId`
+- [ ] **RLS enabled**: Row Level Security policies enforce tenant boundaries
+- [ ] **Context usage**: Uses tenant context from auth provider
+- [ ] **API calls**: Includes tenant ID in API requests
+
+## Testing
+
+- [ ] **Tests exist**: Components/functions have corresponding tests
+- [ ] **Coverage**: Maintains or improves test coverage (aim for >80%)
+- [ ] **Test structure**: Tests follow Arrange-Act-Assert pattern
+- [ ] **Mocking**: External dependencies are properly mocked
+
+## Security
+
+- [ ] **Input validation**: User inputs are validated (Zod schemas)
+- [ ] **XSS prevention**: No dangerouslySetInnerHTML without sanitization
+- [ ] **API security**: API endpoints require authentication
+- [ ] **Secrets**: No secrets or API keys in code (use env variables)
+
+## Accessibility
+
+- [ ] **Semantic HTML**: Uses appropriate HTML elements
+- [ ] **ARIA labels**: Interactive elements have accessible labels
+- [ ] **Keyboard nav**: Interactive elements are keyboard accessible
+- [ ] **Color contrast**: Text has sufficient color contrast
+
+## Performance
+
+- [ ] **Code splitting**: Large components use lazy loading if appropriate
+- [ ] **Memoization**: Expensive calculations use useMemo/useCallback
+- [ ] **Query optimization**: Database queries are efficient (no N+1)
+- [ ] **Bundle size**: No unnecessary dependencies added
+
+## Documentation
+
+- [ ] **JSDoc comments**: Complex functions have JSDoc comments
+- [ ] **README updated**: README reflects any new features/changes
+- [ ] **Type exports**: Exported types are documented
+- [ ] **Examples**: Complex patterns have usage examples
+
+## Pre-commit Checks
+
+- [ ] **Build passes**: `npm run build` completes without errors
+- [ ] **Linting passes**: `npm run lint` has no errors
+- [ ] **Type checking**: `npx tsc --noEmit` has no errors
+- [ ] **Tests passing**: `npm test` passes all tests
+- [ ] **Pre-commit hooks**: Husky pre-commit hooks all pass