fengling-activity/docs/NAMING_CONVENTION.md

# Service Naming Convention

## Overview

This document defines the naming convention for all microservices in the Fengling platform.

## URL Structure

```
{ServicePrefix}/{Version}/{Resource}/{Action}
```

### Components

| Component | Description | Examples |
|-----------|-------------|----------|
| ServicePrefix | Unique service identifier | `activity`, `member`, `order` |
| Version | API version | `v1`, `v2` |
| Resource | Domain entity or resource | `campaigns`, `users`, `orders` |
| Action | Optional action endpoint | `publish`, `cancel` |

## Service Registry

| Service | Prefix | Port | Health Endpoint |
|---------|--------|------|-----------------|
| Activity | `activity` | 5001 | `/health` |
| Member | `member` | 5002 | `/health` |
| Order | `order` | 5003 | `/health` |
| Payment | `payment` | 5004 | `/health` |
| RiskControl | `risk` | 5005 | `/health` |

## Cluster Naming Convention

```
{ServicePrefix}-service
```

Examples:
- `activity-service`
- `member-service`
- `order-service`
- `payment-service`
- `risk-service`

## Gateway Route Configuration

### Global Route Pattern
```
/{ServicePrefix}/{**path} -> {ServicePrefix}-service
```

### Examples

**Activity Service:**
```yaml
Route:
  PathPattern: /activity/v1/{**path}
  ClusterId: activity-service

Endpoints:
  GET    /activity/v1/campaigns          # List campaigns
  POST   /activity/v1/campaigns           # Create campaign
  GET    /activity/v1/campaigns/{id}    # Get campaign
  POST   /activity/v1/campaigns/{id}/publish  # Publish campaign
```

**Member Service:**
```yaml
Route:
  PathPattern: /member/v1/{**path}
  ClusterId: member-service

Endpoints:
  GET    /member/v1/users               # List users
  POST   /member/v1/users               # Create user
  GET    /member/v1/users/{id}          # Get user
  PUT    /member/v1/users/{id}          # Update user
```

**Order Service:**
```yaml
Route:
  PathPattern: /order/v1/{**path}
  ClusterId: order-service

Endpoints:
  GET    /order/v1/orders               # List orders
  POST   /order/v1/orders               # Create order
  GET    /order/v1/orders/{id}          # Get order
  PUT    /order/v1/orders/{id}/cancel   # Cancel order
```

## Gateway Registration

### Activity Service Registration Script

```bash
# Register Activity Service
./scripts/gateway/register-service.sh \
    --service-prefix "activity" \
    --gateway-url "http://localhost:5000" \
    --address "http://localhost:5001"

# After registration, access endpoints at:
# GET http://localhost:5000/activity/v1/campaigns
# POST http://localhost:5000/activity/v1/campaigns
```

## Versioning Strategy

### Version Lifecycle

| Version | Status | Description |
|---------|--------|-------------|
| v1 | Active | Current stable API |
| v2 | Planning | Next major version |
| beta | Testing | Beta releases |

### Versioning Rules

1. **Major Version** (`v1`, `v2`): Breaking changes require version bump
2. **Minor Updates**: Backward-compatible additions don't require version change
3. **Deprecation**: Old versions should be supported for at least 6 months

## Multi-Tenancy Support

### Tenant-Specific Routes

For dedicated tenant instances:
```
/tenant/{tenantCode}/{ServicePrefix}/{Version}/{**path}
```

Example:
```
/tenant/acme/activity/v1/campaigns
```

## Health Check Endpoints

| Service | Health Path |
|---------|-------------|
| Activity | `/health` |
| Member | `/health` |
| Order | `/health` |
| Payment | `/health` |
| Risk | `/health` |

## Monitoring & Metrics

### Service Labels

| Label | Value |
|-------|-------|
| service | `activity` |
| version | `v1` |
| tenant | `{tenantCode}` |

## Best Practices

### 1. Consistent Naming
- Use lowercase for all components
- Use hyphens for multi-word names: `risk-control` NOT `riskControl`
- Avoid abbreviations: `campaigns` NOT `cmps`

### 2. Resource Naming
- Use plural nouns for collections: `campaigns` NOT `campaignList`
- Use singular for single resources: `campaign/{id}` NOT `campaigns/{id}`

### 3. Action Endpoints
- Use HTTP verbs for CRUD: `GET`, `POST`, `PUT`, `DELETE`
- Use specific verbs for actions: `publish`, `cancel`, `activate`

### 4. Path Parameters
- Use descriptive names: `/campaigns/{campaignId}` NOT `/campaigns/{id}`
- Consistent parameter naming across services

## Migration Guide

### Updating Existing Routes

**Before:**
```
/api/campaigns
/api/orders
```

**After:**
```
/activity/v1/campaigns
/order/v1/orders
```

**Migration Strategy:**
1. Register new routes with v1
2. Keep old routes active (alias)
3. Update clients to use new format
4. Remove old routes after transition period