Lesson 1.3: Definition of Done cho Standards

"Tất cả APIs nên return consistent errors"
   → "Nên" nghĩa là gì? "Consistent" như thế nào?

"Tất cả APIs PHẢI return error theo schema này:
   {code: string, message: string}
   Enforced by: lint rule #E001
   Examples: Xem error-examples.md"

Errors should be descriptive and helpful.

## Error Response Specification

### MUST (Required)
- Error responses MUST include `code` field (string, SCREAMING_SNAKE_CASE)
- Error responses MUST include `message` field (string, user-readable)
- Error codes MUST be registered in error-catalog.md

### SHOULD (Recommended)
- Errors SHOULD include `details` object for field-level errors
- Errors SHOULD include `traceId` for debugging

### MAY (Optional)
- Errors MAY include `documentation` URL

// Example 1: Validation Error (400)
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": {
      "email": "Must be a valid email address",
      "password": "Must be at least 8 characters"
    }
  }
}

// Example 2: Not Found Error (404)
{
  "success": false,
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "The requested user does not exist"
  }
}

// Example 3: Internal Error (500)
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred",
    "traceId": "abc-123-def-456"
  }
}

// eslint-plugin-backend-ds/rules/error-format.js

module.exports = {
  meta: {
    type: "problem",
    docs: {
      description: "Enforce standard error format"
    }
  },
  create(context) {
    return {
      // Check all throw statements
      ThrowStatement(node) {
        // Validate error has required fields
        if (!hasRequiredFields(node)) {
          context.report({
            node,
            message: "Error must have 'code' and 'message' fields"
          });
        }
      }
    };
  }
};

# .spectral.yaml
rules:
  error-response-schema:
    description: All 4xx/5xx responses must use standard error schema
    given: "$.paths.*.*.responses[?(@property >= 400)]"
    then:
      field: content.application/json.schema.$ref
      function: pattern
      functionOptions:
        match: "#/components/schemas/ErrorResponse"

// tests/error-format.test.ts

describe('Error Response Format', () => {
  it('should return correct format for validation error', async () => {
    const response = await request(app)
      .post('/users')
      .send({ email: 'invalid' });
    
    expect(response.status).toBe(400);
    expect(response.body).toMatchObject({
      success: false,
      error: {
        code: expect.stringMatching(/^[A-Z_]+$/),
        message: expect.any(String)
      }
    });
  });

  it('should include traceId for 5xx errors', async () => {
    // Force internal error
    const response = await request(app)
      .get('/trigger-error');
    
    expect(response.status).toBe(500);
    expect(response.body.error).toHaveProperty('traceId');
  });
});

# Migration Guide: Error Format v1 → v2

## Overview
- **Breaking change:** Yes
- **Estimated effort:** 2-4 hours per service
- **Deadline:** 2026-02-15

## Step-by-step

### Step 1: Update error-handler middleware (15 min)
Replace your current error handler with the new one:

```typescript
// OLD
catch(err) {
  res.status(500).json({ message: err.message });
}

// NEW
import { formatError } from '@company/error-handler';
catch(err) {
  res.status(getStatusCode(err)).json(formatError(err));
}

---

## Nguyên tắc then chốt

> *"No examples = Developers interpret differently = Standard fails"*

Áp dụng:
1. **Mỗi rule cần ≥3 examples**
2. **Examples phải là real code**, không phải pseudo-code
3. **Include edge cases**, không chỉ happy path

```markdown
"Xem API spec để biết format"
Actual JSON response right in the doc

# Definition of Done Checklists

## API Changes
- [ ] OpenAPI spec updated
- [ ] At least 3 request/response examples
- [ ] Breaking change analysis documented
- [ ] Migration guide (if breaking)
- [ ] Contract tests added
- [ ] Lint rules pass
- [ ] Reviewed by 2 team members

## Database Changes
- [ ] Migration script (up + down)
- [ ] Rollback plan documented
- [ ] Index analysis for new queries
- [ ] Data backfill strategy (if needed)
- [ ] Tested with production-like data volume
- [ ] DBA review (if > 1M rows affected)

## Event/Message Changes
- [ ] Schema version bumped
- [ ] Backward compatibility verified
- [ ] Consumer impact analyzed
- [ ] Deprecation timeline (if breaking)
- [ ] Example messages documented
- [ ] Dead letter queue handling defined