Lesson 1.2: Xác định phạm vi MVP

Sai: "Chúng ta cần 6 tháng để build Design System hoàn chỉnh"
Đúng: "Chúng ta cần 2 tuần để có version 0.1 usable"

// Standard Response Envelope
interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: {
    code: string;
    message: string;
    details?: Record<string, string>;
  };
  meta?: {
    page?: number;
    limit?: number;
    total?: number;
  };
}

// Error Codes Catalog (MVP)
const ERROR_CODES = {
  // 400 Bad Request
  'VALIDATION_ERROR': 400,
  'INVALID_INPUT': 400,
  'MISSING_FIELD': 400,
  
  // 401 Unauthorized
  'UNAUTHORIZED': 401,
  'TOKEN_EXPIRED': 401,
  
  // 403 Forbidden
  'FORBIDDEN': 403,
  'INSUFFICIENT_PERMISSIONS': 403,
  
  // 404 Not Found
  'RESOURCE_NOT_FOUND': 404,
  'USER_NOT_FOUND': 404,
  
  // 500 Internal
  'INTERNAL_ERROR': 500,
  'DATABASE_ERROR': 500,
} as const;

// JWT Payload Standard
interface JwtPayload {
  sub: string;       // User ID
  email: string;
  roles: string[];
  iat: number;       // Issued at
  exp: number;       // Expires at
  iss: string;       // Issuer
}

// Middleware example
function authMiddleware(req, res, next) {
  const token = req.headers.authorization?.replace('Bearer ', '');
  if (!token) {
    return res.status(401).json({
      success: false,
      error: { code: 'UNAUTHORIZED', message: 'Missing token' }
    });
  }
  // Verify and attach user...
}

// Standard Log Format
interface LogEntry {
  timestamp: string;      // ISO 8601
  level: 'debug' | 'info' | 'warn' | 'error';
  message: string;
  traceId: string;        // For distributed tracing
  spanId?: string;
  service: string;
  environment: string;
  data?: Record<string, any>;
}

// Usage
logger.info('User created', {
  userId: user.id,
  email: user.email
});

// Output
{
  "timestamp": "2026-01-15T09:00:00.000Z",
  "level": "info",
  "message": "User created",
  "traceId": "abc-123-def",
  "service": "user-service",
  "environment": "production",
  "data": { "userId": "123", "email": "user@example.com" }
}

# Cấu trúc Starter Template
my-service-template/
├── src/
│   ├── index.ts              # Entry point
│   ├── config/
│   │   └── index.ts          # Environment config
│   ├── middleware/
│   │   ├── auth.ts           # Auth middleware
│   │   ├── error-handler.ts  # Error handler
│   │   └── logger.ts         # Request logging
│   ├── routes/
│   │   └── health.ts         # GET /health
│   └── utils/
│       ├── logger.ts         # Logger wrapper
│       └── response.ts       # Response helpers
├── Dockerfile
├── docker-compose.yml
├── package.json
├── tsconfig.json
└── README.md                  # QUAN TRỌNG: Quick start guide

# Backend Design System MVP Roadmap

## Week 1

### Day 1-2: API Guidelines
- [ ] Define response envelope schema
- [ ] Document versioning strategy
- [ ] Write 5 example endpoints

### Day 3: Error Handling
- [ ] Define error schema
- [ ] Create error codes catalog (20 codes)
- [ ] Document error → HTTP status mapping

### Day 4-5: Auth & Logging
- [ ] Decide JWT vs Session (document decision)
- [ ] Define JWT payload schema
- [ ] Define log format
- [ ] Choose logging library

## Week 2

### Day 1-3: Starter Template
- [ ] Create repo từ scratch
- [ ] Implement health endpoint
- [ ] Add auth middleware
- [ ] Add error handler middleware
- [ ] Add logging middleware

### Day 4: Documentation
- [ ] Write README with quick start
- [ ] Document folder structure
- [ ] Add code examples

### Day 5: Validation
- [ ] Time "new developer" flow (target: 15 min)
- [ ] Fix friction points
- [ ] Get feedback từ 2-3 team members