pos-system/docs/en/guides/development.md

# Development Guide

Comprehensive standards and workflows for contributing to the GoodGo Microservices Platform.

## Table of Contents

1. [Project Structure](#project-structure)
2. [Code Standards](#code-standards)
3. [Git Workflow](#git-workflow)
4. [Backend Development](#backend-development)
5. [Testing Strategy](#testing-strategy)
6. [Database Workflow](#database-workflow)
7. [Kubernetes Deployment](#kubernetes-deployment)

---

## Project Structure

We follow a strict monorepo structure managed by PNPM Workspaces.

```
Base/
├── apps/                 # Frontend applications
│   ├── web-client/       # Next.js 14+ (App Router)
│   └── mobile-client/    # Flutter
├── services/             # Backend microservices
│   ├── _template/        # Template for new services
│   ├── iam-service/      # Identity & Access Management
│   └── ...
├── packages/             # Shared libraries
│   ├── logger/           # Structured logging (Winston)
│   ├── types/            # Shared DTOs & Interfaces
│   ├── http-client/      # Internal Service Client
│   └── tracing/          # OpenTelemetry configuration
├── infra/                # Infrastructure-as-Code
│   ├── traefik/          # API Gateway
│   └── databases/        # Database setup scripts
└── docs/                 # Documentation (EN & VI)
```

---

## Code Standards

### Naming Conventions

*   **Files**: `kebab-case.ts` (e.g., `user.controller.ts`, `app.config.ts`)
*   **Classes**: `PascalCase` (e.g., `UserController`, `AuthService`)
*   **Functions/Variables**: `camelCase` (e.g., `getUserById`, `isValid`)
*   **Constants**: `UPPER_SNAKE_CASE` (e.g., `MAX_RETRIES`, `DEFAULT_TIMEOUT`)
*   **Interfaces**: `PascalCase` (e.g., `User`, `CreateUserDto`) - *No 'I' prefix*

### Bilingual Comments

For core logic and public APIs, assume both international and Vietnamese developers reading the code.

```typescript
/**
 * EN: Validates user credentials and returns a token
 * VI: Xác thực thông tin người dùng và trả về token
 */
async login(dto: LoginDto): Promise<TokenResponse> { ... }
```

### TypeScript Usage

*   **Strict Mode**: Enabled in `tsconfig.json`. No `any` allowed (use `unknown` if needed).
*   **DTOs**: Use Zod for runtime validation and type inference.
*   **Return Types**: Explicitly declare return types for all public methods.

---

## Git Workflow

### Branching Strategy

*   `main`: Production-ready code.
*   `develop`: Integration branch for next release.
*   `feature/xyz`: New features (branch off `develop`).
*   `fix/xyz`: Bug fixes (branch off `develop`).
*   `hotfix/xyz`: Critical fixes (branch off `main`).

```mermaid
gitGraph
    commit id: "Initial"
    branch develop
    checkout develop
    commit id: "Setup"
    
    branch feature/login
    checkout feature/login
    commit id: "Add login form"
    commit id: "Add validation"
    checkout develop
    merge feature/login
    
    branch feature/dashboard
    checkout feature/dashboard
    commit id: "Create dashboard"
    checkout develop
    
    checkout main
    merge develop tag: "v1.0.0"
    
    checkout develop
    merge feature/dashboard
    
    checkout main
    branch hotfix/security
    commit id: "Fix security issue"
    checkout main
    merge hotfix/security tag: "v1.0.1"
    checkout develop
    merge hotfix/security
```

### Commit Messages

We follow [Conventional Commits](https://www.conventionalcommits.org/):

```
feat(iam): add multi-factor authentication
fix(db): correct unique constraint on email
docs(guide): update development setup
style: format code with prettier
refactor: simplify auth middleware
test: add unit tests for user service
chore: update dependencies
```

---

## Backend Development

```mermaid
graph TD
    Start([Start Creating New API]) --> DTO[1. Define DTO - Zod Schema]
    DTO --> Repo[2. Create Repository Method]
    Repo --> Service[3. Create Service Method - Business Logic]
    Service --> Controller[4. Create Controller - HTTP Handler]
    Controller --> Route[5. Register Route - Express Router]
    Route --> Middleware[6. Add Middlewares]
    Middleware --> Test[7. Write Tests]
    Test --> Done([API Complete])
    
    Service --> ErrorCheck{Has Error?}
    ErrorCheck -->|Yes| ThrowError[Throw HttpError]
    ThrowError --> ErrorHandler[Global Error Handler]
    ErrorHandler --> Response[Error Response]
    ErrorCheck -->|No| Success[Success Response]
    
    style Start fill:#1e3a2e,color:#4ade80,stroke:#4ade80,stroke-width:3px
    style Done fill:#1e3a2e,color:#4ade80,stroke:#4ade80,stroke-width:3px
    style DTO fill:#1e293b,color:#60a5fa
    style Repo fill:#1e293b,color:#3b82f6
    style Service fill:#2e1a47,color:#a78bfa
    style Controller fill:#2d1b0e,color:#fb923c
    style Route fill:#1e293b,color:#3b82f6
    style Middleware fill:#1e293b,color:#60a5fa
    style Test fill:#1e3a2e,color:#4ade80
    style ErrorCheck fill:#2d1b0e,color:#fb923c
    style ThrowError fill:#3f1a1a,color:#f87171
    style ErrorHandler fill:#3f1a1a,color:#f87171
    style Response fill:#27272a,color:#a1a1aa
    style Success fill:#1e3a2e,color:#4ade80
```

### Creating a New API Endpoint

1.  **Define DTO** (`modules/user/user.dto.ts`):
    ```typescript
    export const CreateUserDto = z.object({
      email: z.string().email(),
      name: z.string().min(2),
    });
    export type CreateUserDto = z.infer<typeof CreateUserDto>;
    ```

2.  **Create Service Method** (`modules/user/user.service.ts`):
    *   Implement business logic.
    *   Use `BaseRepository`.
    *   Throw `HttpError` (e.g., `NotFound`, `BadRequest`).

3.  **Create Controller** (`modules/user/user.controller.ts`):
    *   Parse body with DTO: `const dto = CreateUserDto.parse(req.body)`.
    *   Call service.
    *   Return success response: `res.json({ success: true, data: result })`.

4.  **Register Route** (`modules/user/index.ts`):
    *   Add to Express router with middlewares.

### Error Handling

Always use the custom error classes from `core/errors`:

```typescript
import { NotFoundError, ConflictError } from '../../core/errors';

if (!user) {
  throw new NotFoundError('User not found');
}
```

---

## Testing Strategy

```mermaid
graph TB
    subgraph "Testing Pyramid - Bottom to Top"
        Unit[Unit Tests - Most, Fastest]
        Integration[Integration Tests - Medium]
        E2E[E2E Tests - Least, Slowest]
    end
    
    Code[Code Changes] --> CheckLint{Lint Pass?}
    CheckLint -->|No| FixLint[Fix Linting Errors]
    FixLint --> CheckLint
    CheckLint -->|Yes| RunUnit[Run Unit Tests]
    
    RunUnit --> UnitPass{Unit Tests Pass?}
    UnitPass -->|No| FixUnit[Fix Unit Tests]
    FixUnit --> RunUnit
    UnitPass -->|Yes| RunIntegration[Run Integration Tests]
    
    RunIntegration --> IntPass{Integration Pass?}
    IntPass -->|No| FixIntegration[Fix Integration]
    FixIntegration --> RunIntegration
    IntPass -->|Yes| RunE2E[Run E2E Tests]
    
    RunE2E --> E2EPass{E2E Pass?}
    E2EPass -->|No| FixE2E[Fix E2E]
    FixE2E --> RunE2E
    E2EPass -->|Yes| Coverage{Coverage > 70%?}
    
    Coverage -->|No| AddTests[Add More Tests]
    AddTests --> RunUnit
    Coverage -->|Yes| ReadyMerge[Ready to Merge]
    
    style Unit fill:#1e3a2e,color:#4ade80
    style Integration fill:#1e293b,color:#60a5fa
    style E2E fill:#2e1a47,color:#a78bfa
    style Code fill:#1e293b,color:#3b82f6
    style CheckLint fill:#2d1b0e,color:#fb923c
    style UnitPass fill:#1e3a2e,color:#4ade80
    style IntPass fill:#1e293b,color:#60a5fa
    style E2EPass fill:#2e1a47,color:#a78bfa
    style Coverage fill:#2d1b0e,color:#fbbf24
    style RunUnit fill:#1e3a2e,color:#4ade80
    style RunIntegration fill:#1e293b,color:#60a5fa
    style RunE2E fill:#2e1a47,color:#a78bfa
    style ReadyMerge fill:#1e3a2e,color:#4ade80,stroke:#4ade80,stroke-width:3px
    style FixLint fill:#3f1a1a,color:#f87171
    style FixUnit fill:#3f1a1a,color:#f87171
    style FixIntegration fill:#3f1a1a,color:#f87171
    style FixE2E fill:#3f1a1a,color:#f87171
    style AddTests fill:#2d1b0e,color:#fbbf24
```

### Unit Tests (`*.test.ts`)

*   **Scope**: Individual classes/functions.
*   **Mocking**: Mock all external dependencies (DB, other services) using `jest-mock-extended`.
*   **Location**: Co-located with source files.
*   **Run**: `pnpm test`

### E2E Tests (`tests/**/*.e2e.ts`)

*   **Scope**: Full API flows (Controller -> Service -> DB).
*   **Database**: Use a separate test database (Dockerized).
*   **Run**: `pnpm test:e2e`

### Linting & Formatting

*   **Lint**: `pnpm lint` (ESLint)
*   **Format**: `pnpm format` (Prettier)
*   **Typecheck**: `pnpm typecheck` (TSC)

---

## Database Workflow

We use **Prisma** with **Neon PostgreSQL**.

### Migrations

1.  Modify `prisma/schema.prisma`.
2.  Create migration (Dev):
    ```bash
    ./scripts/db/migrate.sh iam-service dev --name add_user_profile
    ```
3.  Apply to Production (CI/CD):
    ```bash
    ./scripts/db/migrate.sh iam-service deploy
    ```

### Seed Data

Populate database with initial data:
```bash
./scripts/db/seed.sh iam-service
```

### Visualizing Data

Use Prisma Studio:
```bash
pnpm --filter @goodgo/iam-service prisma studio
```

---

## Kubernetes Deployment

For local Kubernetes testing (Docker Desktop / Minikube):

```bash
# 1. Build images
docker build -t goodgo/iam-service:latest -f services/iam-service/Dockerfile .

# 2. Deploy
cd deployments/local/kubernetes
./deploy.sh

# 3. Verify
kubectl get pods -n iam-local
kubectl logs -f -l app=iam-service -n iam-local
```

See [Kubernetes Guide](./kubernetes-local.md) for detailed setup.