feat: Add comprehensive BMAD agent, workflow, and documentation framework.

_bmad-output/developer-guide.md

@@ -0,0 +1,444 @@
+# Hướng Dẫn Developer SurfSense
+
+**Dành cho Nhà Phát Triển**
+
+---
+
+## 📖 Giới Thiệu
+
+Tài liệu này hướng dẫn developers cách setup, develop, và extend hệ thống SurfSense.
+
+---
+
+## 🏗️ Kiến Trúc Tổng Quan
+
+SurfSense bao gồm 3 components chính:
+
+1. **Backend** (`surfsense_backend`) - Python/FastAPI
+2. **Web** (`surfsense_web`) - Next.js 16
+3. **Extension** (`surfsense_browser_extension`) - Plasmo/React
+
+Xem chi tiết:
+- [Kiến Trúc Backend](./architecture-backend.md)
+- [Kiến Trúc Web](./architecture-web.md)
+- [Kiến Trúc Extension](./architecture-extension.md)
+- [Kiến Trúc Tích Hợp](./integration-architecture.md)
+
+---
+
+## 🚀 Setup Development Environment
+
+### Prerequisites
+
+- Python 3.11+
+- Node.js 18+
+- PostgreSQL 15+
+- Redis
+- Git
+
+### Clone Repository
+
+```bash
+git clone https://github.com/your-org/surfsense.git
+cd surfsense
+```
+
+### Backend Setup
+
+```bash
+cd surfsense_backend
+
+# Create virtual environment
+python -m venv venv
+source venv/bin/activate  # Windows: venv\Scripts\activate
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Setup environment
+cp .env.example .env
+# Edit .env với database credentials, API keys
+
+# Run migrations
+alembic upgrade head
+
+# Start server
+uvicorn app.main:app --reload
+```
+
+**Backend chạy tại:** `http://localhost:8000`
+
+### Web Setup
+
+```bash
+cd surfsense_web
+
+# Install dependencies
+npm install
+
+# Setup environment
+cp .env.example .env.local
+# Edit NEXT_PUBLIC_API_URL=http://localhost:8000
+
+# Start dev server
+npm run dev
+```
+
+**Web chạy tại:** `http://localhost:3000`
+
+### Extension Setup
+
+```bash
+cd surfsense_browser_extension
+
+# Install dependencies
+npm install
+
+# Build extension
+npm run dev
+
+# Load extension trong Chrome:
+# 1. Vào chrome://extensions/
+# 2. Enable "Developer mode"
+# 3. Click "Load unpacked"
+# 4. Chọn folder build/chrome-mv3-dev
+```
+
+---
+
+## 🗂️ Cấu Trúc Dự Án
+
+### Backend Structure
+
+```
+surfsense_backend/
+├── app/
+│   ├── api/          # API routes
+│   ├── core/         # Core logic (auth, config)
+│   ├── db/           # Database models
+│   ├── services/     # Business logic
+│   └── main.py       # FastAPI app
+├── alembic/          # Database migrations
+├── tests/            # Unit tests
+└── requirements.txt
+```
+
+### Web Structure
+
+```
+surfsense_web/
+├── app/              # Next.js App Router
+│   ├── (auth)/       # Auth pages
+│   ├── (dashboard)/  # Dashboard pages
+│   └── api/          # API routes
+├── components/       # React components
+├── lib/              # Utilities
+└── public/           # Static assets
+```
+
+### Extension Structure
+
+```
+surfsense_browser_extension/
+├── src/
+│   ├── background/   # Background service
+│   ├── popup/        # Popup UI
+│   ├── content/      # Content scripts
+│   └── components/   # Shared components
+└── manifest.json     # Extension manifest
+```
+
+---
+
+## 🔌 API Reference
+
+### Authentication
+
+**Login:**
+
+```bash
+POST /api/auth/login
+Content-Type: application/json
+
+{
+  "email": "user@example.com",
+  "password": "password123"
+}
+
+# Response:
+{
+  "access_token": "eyJ...",
+  "token_type": "bearer"
+}
+```
+
+**Sử dụng token:**
+
+```bash
+GET /api/content
+Authorization: Bearer eyJ...
+```
+
+### Content Management
+
+**Capture content:**
+
+```bash
+POST /api/content
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "url": "https://example.com",
+  "title": "Example Page",
+  "body": "Content text...",
+  "tags": ["research", "ai"]
+}
+```
+
+**Search:**
+
+```bash
+GET /api/search?q=machine+learning&limit=10
+Authorization: Bearer <token>
+```
+
+### AI Chat
+
+**Send message:**
+
+```bash
+POST /api/ai/chat
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "message": "Summarize my AI research",
+  "mode": "research"  # "chat" | "research"
+}
+```
+
+Xem chi tiết: [API Contracts](./api-contracts-backend.md)
+
+---
+
+## 🗄️ Database Schema
+
+### Core Tables
+
+**users:**
+- `id` (UUID, PK)
+- `email` (unique)
+- `hashed_password`
+- `role` (user | admin | superadmin)
+- `plan` (free | pro | enterprise)
+
+**content:**
+- `id` (UUID, PK)
+- `user_id` (FK → users)
+- `url`, `title`, `body`
+- `tags` (JSONB)
+- `created_at`
+
+**collections:**
+- `id` (UUID, PK)
+- `user_id` (FK → users)
+- `name`, `description`
+
+Xem chi tiết: [Data Models](./data-models-backend.md)
+
+---
+
+## 🧪 Testing
+
+### Backend Tests
+
+```bash
+cd surfsense_backend
+
+# Run all tests
+pytest
+
+# Run specific test
+pytest tests/test_auth.py
+
+# With coverage
+pytest --cov=app tests/
+```
+
+### Web Tests
+
+```bash
+cd surfsense_web
+
+# Run unit tests
+npm test
+
+# Run E2E tests
+npm run test:e2e
+```
+
+### Extension Tests
+
+```bash
+cd surfsense_browser_extension
+
+# Run tests
+npm test
+```
+
+---
+
+## 🔧 Common Development Tasks
+
+### Tạo API Endpoint Mới
+
+**1. Tạo route (`app/api/routes/example.py`):**
+
+```python
+from fastapi import APIRouter, Depends
+from app.core.auth import get_current_user
+
+router = APIRouter()
+
+@router.get("/example")
+async def get_example(user = Depends(get_current_user)):
+    return {"message": "Hello", "user_id": user.id}
+```
+
+**2. Register route (`app/api/__init__.py`):**
+
+```python
+from app.api.routes import example
+
+api_router.include_router(example.router, prefix="/example", tags=["example"])
+```
+
+### Tạo Database Migration
+
+```bash
+cd surfsense_backend
+
+# Auto-generate migration
+alembic revision --autogenerate -m "Add new_column to users"
+
+# Review migration file in alembic/versions/
+
+# Apply migration
+alembic upgrade head
+```
+
+### Thêm React Component Mới
+
+**1. Tạo component (`components/MyComponent.tsx`):**
+
+```tsx
+export function MyComponent({ title }: { title: string }) {
+  return <div>{title}</div>
+}
+```
+
+**2. Sử dụng:**
+
+```tsx
+import { MyComponent } from '@/components/MyComponent'
+
+export default function Page() {
+  return <MyComponent title="Hello" />
+}
+```
+
+---
+
+## 🚢 Deployment
+
+### Build Production
+
+**Backend:**
+
+```bash
+cd surfsense_backend
+pip install -r requirements.txt
+uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4
+```
+
+**Web:**
+
+```bash
+cd surfsense_web
+npm run build
+npm start
+```
+
+**Extension:**
+
+```bash
+cd surfsense_browser_extension
+npm run build
+# Upload build/chrome-mv3-prod to Chrome Web Store
+```
+
+### Docker Deployment
+
+```bash
+docker-compose up -d
+```
+
+Xem chi tiết deployment trong [Admin Guide](./admin-guide.md).
+
+---
+
+## 🐛 Debugging
+
+### Backend Debugging
+
+**Enable debug logs:**
+
+```bash
+# .env
+LOG_LEVEL=DEBUG
+```
+
+**Use debugger:**
+
+```python
+import pdb; pdb.set_trace()
+```
+
+### Web Debugging
+
+**Next.js debug mode:**
+
+```bash
+NODE_OPTIONS='--inspect' npm run dev
+```
+
+**React DevTools:** Install extension
+
+### Extension Debugging
+
+1. Vào `chrome://extensions/`
+2. Click **"Inspect views: background page"**
+3. Sử dụng Chrome DevTools
+
+---
+
+## 📚 Tài Nguyên Bổ Sung
+
+### Documentation
+- [FastAPI Docs](https://fastapi.tiangolo.com/)
+- [Next.js Docs](https://nextjs.org/docs)
+- [Plasmo Docs](https://docs.plasmo.com/)
+
+### Code Style
+- Backend: PEP 8, Black formatter
+- Web/Extension: ESLint, Prettier
+
+### Git Workflow
+- Branch naming: `feature/`, `bugfix/`, `hotfix/`
+- Commit messages: Conventional Commits
+- PR template: Mô tả changes, testing done
+
+---
+
+**Cập nhật:** 2026-01-31 | **Version:** 1.0