[Feature Name]

Status: 🚧 Draft | ✅ Active | 🔄 In Progress | ⚠️ Deprecated
Version: 1.0.0
Last Updated: 2024-01-01
Owner: @team-name

📋 Overview

Deskripsi singkat tentang fitur ini, tujuan bisnis, dan value yang diberikan kepada user.

Key Features

✅ Feature point 1
✅ Feature point 2
✅ Feature point 3

User Stories

As a [user type], I want to [action], so that [benefit]
As a [user type], I want to [action], so that [benefit]

🎯 Business Logic

Business Rules

Rule 1: [Rule Name]

Description: Penjelasan detail rule bisnisConditions:

Kondisi 1
Kondisi 2

Actions:

Action yang dilakukan jika kondisi terpenuhi

Example:

IF user.role == "admin" AND order.status == "pending"
THEN allow_cancel = true

Rule 2: [Rule Name]

Description: Penjelasan detail rule bisnisValidation:

Validasi 1: amount > 0
Validasi 2: user.verified == true

Error Handling:

Error code: INVALID_AMOUNT
Error message: “Amount must be greater than 0”

State Machine

Business Flow

🗄️ Data Model (ERD)

Entity Relationship Diagram

Table Specifications

users
orders
order_items

Column	Type	Constraints	Description
id	UUID	PK	Primary key
email	VARCHAR(255)	UNIQUE, NOT NULL	User email
name	VARCHAR(255)	NOT NULL	Full name
phone	VARCHAR(20)		Phone number
role	ENUM	NOT NULL	admin, user, guest
verified	BOOLEAN	DEFAULT false	Email verified
created_at	TIMESTAMP	NOT NULL	Created timestamp
updated_at	TIMESTAMP	NOT NULL	Updated timestamp

Indexes:

idx_users_email on email
idx_users_role on role

Column	Type	Constraints	Description
id	UUID	PK	Primary key
user_id	UUID	FK, NOT NULL	Reference to users
order_number	VARCHAR(50)	UNIQUE, NOT NULL	Order number
total_amount	DECIMAL(10,2)	NOT NULL	Total amount
status	ENUM	NOT NULL	pending, paid, completed, cancelled
ordered_at	TIMESTAMP	NOT NULL	Order timestamp
completed_at	TIMESTAMP		Completion timestamp

Indexes:

idx_orders_user_id on user_id
idx_orders_status on status
idx_orders_ordered_at on ordered_at

Column	Type	Constraints	Description
id	UUID	PK	Primary key
order_id	UUID	FK, NOT NULL	Reference to orders
product_id	UUID	FK, NOT NULL	Reference to products
quantity	INT	NOT NULL	Quantity
unit_price	DECIMAL(10,2)	NOT NULL	Price per unit
subtotal	DECIMAL(10,2)	NOT NULL	Subtotal

Indexes:

idx_order_items_order_id on order_id
idx_order_items_product_id on product_id

🔌 API Specification

Endpoints Overview

Method	Endpoint	Description	Auth
GET	`/api/v1/orders`	List orders	✅ Required
GET	`/api/v1/orders/:id`	Get order detail	✅ Required
POST	`/api/v1/orders`	Create order	✅ Required
PUT	`/api/v1/orders/:id`	Update order	✅ Required
DELETE	`/api/v1/orders/:id`	Cancel order	✅ Required

1. List Orders

GET /api/v1/orders?page=1&limit=20&status=pending
Authorization: Bearer <token>

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "orderNumber": "ORD-2024-0001",
      "userId": "660e8400-e29b-41d4-a716-446655440000",
      "totalAmount": 150000,
      "status": "pending",
      "orderedAt": "2024-01-01T10:00:00Z",
      "items": [
        {
          "productId": "770e8400-e29b-41d4-a716-446655440000",
          "productName": "Product A",
          "quantity": 2,
          "unitPrice": 50000,
          "subtotal": 100000
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "totalPages": 5
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired token",
    "traceId": "abc123"
  }
}

Query Parameters:

page (integer, optional): Page number, default 1
limit (integer, optional): Items per page, default 20, max 100
status (string, optional): Filter by status (pending, paid, completed, cancelled)
startDate (string, optional): Filter by start date (ISO 8601)
endDate (string, optional): Filter by end date (ISO 8601)

Response Codes:

200 OK: Success
401 Unauthorized: Invalid token
403 Forbidden: Insufficient permissions
500 Internal Server Error: Server error

2. Create Order

POST /api/v1/orders
Authorization: Bearer <token>
Content-Type: application/json

{
  "items": [
    {
      "productId": "770e8400-e29b-41d4-a716-446655440000",
      "quantity": 2
    },
    {
      "productId": "880e8400-e29b-41d4-a716-446655440000",
      "quantity": 1
    }
  ],
  "notes": "Please deliver before 5 PM"
}

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "orderNumber": "ORD-2024-0001",
    "userId": "660e8400-e29b-41d4-a716-446655440000",
    "totalAmount": 150000,
    "status": "pending",
    "orderedAt": "2024-01-01T10:00:00Z",
    "items": [
      {
        "productId": "770e8400-e29b-41d4-a716-446655440000",
        "productName": "Product A",
        "quantity": 2,
        "unitPrice": 50000,
        "subtotal": 100000
      }
    ]
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": [
      {
        "field": "items",
        "message": "items is required and must be an array"
      },
      {
        "field": "items[0].quantity",
        "message": "quantity must be greater than 0"
      }
    ],
    "traceId": "abc123"
  }
}

Request Body:

items (array, required): Array of order items
- productId (string, required): Product UUID
- quantity (integer, required): Quantity, must be > 0
notes (string, optional): Order notes, max 500 characters

Validation Rules:

Items array tidak boleh kosong
Product ID harus valid dan product harus active
Quantity harus lebih dari 0 dan tidak melebihi stock available
Total amount harus lebih dari 0

Response Codes:

201 Created: Order created successfully
400 Bad Request: Validation error
401 Unauthorized: Invalid token
404 Not Found: Product not found
409 Conflict: Insufficient stock
500 Internal Server Error: Server error

3. Get Order Detail

GET /api/v1/orders/550e8400-e29b-41d4-a716-446655440000
Authorization: Bearer <token>

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "orderNumber": "ORD-2024-0001",
    "user": {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "name": "John Doe",
      "email": "[email protected]"
    },
    "items": [
      {
        "id": "990e8400-e29b-41d4-a716-446655440000",
        "product": {
          "id": "770e8400-e29b-41d4-a716-446655440000",
          "name": "Product A",
          "sku": "SKU-001"
        },
        "quantity": 2,
        "unitPrice": 50000,
        "subtotal": 100000
      }
    ],
    "totalAmount": 150000,
    "status": "pending",
    "orderedAt": "2024-01-01T10:00:00Z",
    "completedAt": null,
    "payment": {
      "id": "aa0e8400-e29b-41d4-a716-446655440000",
      "method": "credit_card",
      "status": "pending",
      "amount": 150000
    }
  }
}

{
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "Order with ID 550e8400-e29b-41d4-a716-446655440000 not found",
    "traceId": "abc123"
  }
}

🔄 Sequence Diagram

Create Order Flow

🎨 UI/UX Flow

User Journey

🧪 Testing

Test Cases

Unit Tests
Integration Tests
Load Tests

func TestCreateOrder_Success(t *testing.T) {
    // Arrange
    req := &CreateOrderRequest{
        Items: []OrderItem{
            {ProductID: "prod-1", Quantity: 2},
        },
    }
    
    // Act
    order, err := orderService.CreateOrder(ctx, req)
    
    // Assert
    assert.NoError(t, err)
    assert.NotNil(t, order)
    assert.Equal(t, "pending", order.Status)
}

func TestCreateOrder_InsufficientStock(t *testing.T) {
    // Test insufficient stock scenario
}

func TestOrderAPI_CreateOrder_E2E(t *testing.T) {
    // Setup test database
    db := setupTestDB()
    defer db.Close()
    
    // Create test user
    user := createTestUser(db)
    token := generateTestToken(user)
    
    // Create test product
    product := createTestProduct(db, 10) // stock: 10
    
    // Make API request
    resp := makeRequest(t, "POST", "/api/v1/orders", 
        map[string]interface{}{
            "items": []map[string]interface{}{
                {"productId": product.ID, "quantity": 2},
            },
        },
        token,
    )
    
    // Assert
    assert.Equal(t, 201, resp.StatusCode)
    
    // Verify database
    order := getOrderFromDB(db, resp.Data.ID)
    assert.Equal(t, "pending", order.Status)
    
    // Verify stock updated
    updatedProduct := getProductFromDB(db, product.ID)
    assert.Equal(t, 8, updatedProduct.Stock)
}

// k6 load test
import http from 'k6/http';
import { check } from 'k6';

export let options = {
  stages: [
    { duration: '1m', target: 100 },
    { duration: '3m', target: 100 },
    { duration: '1m', target: 0 },
  ],
};

export default function() {
  let payload = JSON.stringify({
    items: [
      { productId: 'prod-1', quantity: 1 }
    ]
  });
  
  let params = {
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer ' + __ENV.TOKEN,
    },
  };
  
  let res = http.post('http://localhost:8080/api/v1/orders', payload, params);
  
  check(res, {
    'status is 201': (r) => r.status === 201,
    'response time < 500ms': (r) => r.timings.duration < 500,
  });
}

📊 Monitoring & Observability

Metrics

# Prometheus metrics
- order_created_total (counter)
  labels: [status, user_role]
  
- order_processing_duration_seconds (histogram)
  labels: [status]
  buckets: [0.1, 0.5, 1, 2, 5]
  
- order_total_amount (histogram)
  labels: [payment_method]
  buckets: [10000, 50000, 100000, 500000, 1000000]
  
- active_orders_count (gauge)
  labels: [status]

Logs

{
  "timestamp": "2024-01-01T10:00:00Z",
  "level": "info",
  "service": "order-service",
  "traceId": "abc123",
  "spanId": "def456",
  "message": "Order created successfully",
  "order": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "userId": "660e8400-e29b-41d4-a716-446655440000",
    "totalAmount": 150000,
    "status": "pending"
  }
}

Alerts

# Grafana alerts
- name: HighOrderFailureRate
  condition: rate(order_created_total{status="failed"}[5m]) > 0.1
  severity: critical
  notification: slack, pagerduty
  
- name: SlowOrderProcessing
  condition: histogram_quantile(0.95, order_processing_duration_seconds) > 5
  severity: warning
  notification: slack

🚀 Deployment

Environment Variables

# Order Service
ORDER_SERVICE_PORT=8080
ORDER_SERVICE_DB_DSN=mysql://user:pass@localhost:3306/orders
ORDER_SERVICE_REDIS_URL=redis://localhost:6379
ORDER_SERVICE_QUEUE_URL=amqp://localhost:5672

# Feature Flags
FEATURE_ORDER_AUTO_CONFIRM=true
FEATURE_ORDER_PAYMENT_RETRY=true

Deployment Checklist

API Styleguide

Panduan API design patterns

Database Schema

Schema database lengkap

Testing Guide

Panduan testing backend

Observability

Setup monitoring & logging

🔄 Changelog

Version	Date	Changes	Author
1.0.0	2024-01-01	Initial release	@team
1.1.0	2024-01-15	Add payment retry	@team

Template Usage: Copy file ini dan rename sesuai nama fitur. Isi semua section yang relevan. Hapus section yang tidak digunakan.

Business Features

Offline-First Architecture

Real-time Sync

[Feature Name] - Template

[Feature Name]

📋 Overview

Key Features

User Stories

🎯 Business Logic

Business Rules

State Machine

Business Flow

🗄️ Data Model (ERD)

Entity Relationship Diagram

Table Specifications

🔌 API Specification

Endpoints Overview

1. List Orders

2. Create Order

3. Get Order Detail

🔄 Sequence Diagram

Create Order Flow

🎨 UI/UX Flow

User Journey

🧪 Testing

Test Cases

📊 Monitoring & Observability

Metrics

Logs

Alerts

🚀 Deployment

Environment Variables

Deployment Checklist

API Styleguide

Database Schema

Testing Guide

Observability

🔄 Changelog

​[Feature Name]

​📋 Overview

​Key Features

​User Stories

​🎯 Business Logic

​Business Rules

​State Machine

​Business Flow

​🗄️ Data Model (ERD)

​Entity Relationship Diagram

​Table Specifications

​🔌 API Specification

​Endpoints Overview

​1. List Orders

​2. Create Order

​3. Get Order Detail

​🔄 Sequence Diagram

​Create Order Flow

​🎨 UI/UX Flow

​User Journey

​🧪 Testing

​Test Cases

​📊 Monitoring & Observability

​Metrics

​Logs

​Alerts

​🚀 Deployment

​Environment Variables

​Deployment Checklist

​📚 Related Documentation

API Styleguide

Database Schema

Testing Guide

Observability

​🔄 Changelog

[Feature Name]

📋 Overview

Key Features

User Stories

🎯 Business Logic

Business Rules

State Machine

Business Flow

🗄️ Data Model (ERD)

Entity Relationship Diagram

Table Specifications

🔌 API Specification

Endpoints Overview

1. List Orders

2. Create Order

3. Get Order Detail

🔄 Sequence Diagram

Create Order Flow

🎨 UI/UX Flow

User Journey

🧪 Testing

Test Cases

📊 Monitoring & Observability

Metrics

Logs

Alerts

🚀 Deployment

Environment Variables

Deployment Checklist

📚 Related Documentation

🔄 Changelog