# Tambak API Documentation

Sistem Manajemen Tambak Udang - RESTful API untuk Flutter Mobile App

## Base URL
```
http://your-domain.com/api
```

## Authentication

Semua endpoint (kecuali `/api/auth/login` dan `/api/health`) memerlukan authentication token.

### Login
**POST** `/api/auth/login`

**Request Body:**
```json
{
  "username": "aliong",
  "password": "password123",
  "device_info": "iPhone 13 - iOS 16"
}
```

**Response:**
```json
{
  "success": true,
  "message": "Login successful",
  "data": {
    "user": {
      "id": 1,
      "name": "Aliong",
      "username": "aliong",
      "divisi": "PUSAT",
      "roles": ["super-admin"],
      "permissions": ["kolam.view", "pakan.create", ...],
      "last_login_at": "2026-04-12T10:30:00.000000Z"
    },
    "token": "1|aBcDeFgHiJkLmNoPqRsTuVwXyZ",
    "token_type": "Bearer"
  }
}
```

### Using the Token
Include the token in the Authorization header:
```
Authorization: Bearer 1|aBcDeFgHiJkLmNoPqRsTuVwXyZ
```

---

## Main Modules

### 1. Dashboard

#### Get Dashboard Summary
**GET** `/api/dashboard`

**Query Parameters:**
- `kolam` (optional): Filter by pond name
- `start_date` (optional): Start date (default: start of month)
- `end_date` (optional): End date (default: today)

**Response:**
```json
{
  "success": true,
  "data": {
    "summary": {
      "total_kolam": 10,
      "active_kolam": 8,
      "today_feed": 150.5,
      "today_anco_checks": 5,
      "mortality_this_month": 1250,
      "panen_this_month": {
        "total_value": 85000000,
        "total_qty": 1250.5
      }
    },
    "latest_sampling": [...],
    "latest_water_quality": [...],
    "recent_activities": {...}
  }
}
```

---

### 2. Kolam (Ponds)

#### List Ponds
**GET** `/api/kolam`

**Query Parameters:**
- `status` (optional): active, inactive, maintenance
- `lokasi` (optional): Filter by location
- `search` (optional): Search by name
- `per_page` (optional): Items per page (default: 20)

**Create Pond**
**POST** `/api/kolam`

**Request Body:**
```json
{
  "nama": "A01",
  "luas": 1000,
  "satuan": "M2",
  "lokasi": "Blok A",
  "status": "active",
  "kapasitas": 300000,
  "keterangan": "Kolam udang vaname"
}
```

#### Get Pond Details
**GET** `/api/kolam/{id}`

**Response:**
```json
{
  "success": true,
  "data": {
    "kolam": {
      "id": 1,
      "nama": "A01",
      "luas": 1000,
      "satuan": "M2",
      "lokasi": "Blok A",
      "status": "active",
      "kapasitas": 300000,
      "is_active": true,
      "current_cycle": {...},
      "latest_sampling": {...},
      "mbw": 20.5,
      "adg": 0.15
    }
  }
}
```

---

### 3. Sampling

#### List Sampling
**GET** `/api/sampling`

**Query Parameters:**
- `kolam` (optional): Filter by pond
- `start_date` (optional): Start date
- `end_date` (optional): End date
- `per_page` (optional): Items per page

**Create Sampling**
**POST** `/api/sampling`

**Request Body:**
```json
{
  "kolam": "A01",
  "tanggal": "2026-04-12",
  "mbw": 20.5,
  "adg": 0.15,
  "umur": 45,
  "qty_sample": 30,
  "keterangan": "Sampling minggu ke-6"
}
```

**Response:**
```json
{
  "success": true,
  "message": "Sampling data created successfully",
  "data": {
    "sampling": {
      "id": 1,
      "kolam": "A01",
      "tanggal": "2026-04-12",
      "mbw": 20.5,
      "adg": 0.15,
      "umur": 45,
      "qty_sample": 30
    }
  }
}
```

#### Get Latest Sampling by Pond
**GET** `/api/sampling/latest`

---

### 4. Pakan (Feed)

#### List Feed Records
**GET** `/api/pakan`

**Query Parameters:**
- `kolam` (optional): Filter by pond
- `start_date` (optional): Start date
- `end_date` (optional): End date
- `jenis_pakan` (optional): Filter by feed type
- `today` (optional): Set to "true" for today's records only
- `per_page` (optional): Items per page

**Create Feed Record**
**POST** `/api/pakan`

**Request Body:**
```json
{
  "kolam": "A01",
  "tanggal": "2026-04-12",
  "waktu_pemberian": "08:30",
  "jenis_pakan": "SATWA BOGA KODE 2A",
  "jumlah": 10.5,
  "satuan": "KG",
  "keterangan": "Pakan pagi"
}
```

**Get Today's Feed**
**GET** `/api/pakan/today`

**Get Feed Summary**
**GET** `/api/pakan/summary`

---

### 5. Cek Anco (Feed Tray Check)

#### List Anco Checks
**GET** `/api/cek-anco`

**Query Parameters:**
- `kolam` (optional): Filter by pond
- `start_date` (optional): Start date
- `end_date` (optional): End date
- `today` (optional): Set to "true" for today's records
- `per_page` (optional): Items per page

**Create Anco Check**
**POST** `/api/cek-anco`

**Request Body:**
```json
{
  "kolam": "A01",
  "tanggal": "2026-04-12",
  "waktu_pemberian": "08:30",
  "waktu_cek": "08:50",
  "jumlah_pakan": 10,
  "anco_1_status": "sedikit",
  "anco_2_status": "habis",
  "keterangan": "Konsumsi baik"
}
```

**Anco Status Values:**
- `habis`: Empty (< 10%)
- `sedikit`: Little left (10% - 50%)
- `banyak`: A lot left (> 50%)

**Get Today's Checks**
**GET** `/api/cek-anco/today`

---

### 6. Cek Air (Water Quality)

#### List Water Checks
**GET** `/api/cek-air`

**Query Parameters:**
- `kolam` (optional): Filter by pond
- `start_date` (optional): Start date
- `end_date` (optional): End date
- `today` (optional): Set to "true" for today's records
- `per_page` (optional): Items per page

**Create Water Check**
**POST** `/api/cek-air`

**Request Body:**
```json
{
  "kolam": "A01",
  "tanggal": "2026-04-12",
  "jam": "06:00",
  "ph": 8.2,
  "do": 5.5,
  "salinitas": 25,
  "suhu": 30,
  "alkalinitas": 150,
  "kecerahan": 40,
  "keterangan": "Kualitas air optimal"
}
```

**Get Today's Checks**
**GET** `/api/cek-air/today`

**Get Latest by Pond**
**GET** `/api/cek-air/latest`

---

### 7. Panen (Harvest)

#### List Harvest
**GET** `/api/panen`

**Query Parameters:**
- `kolam` (optional): Filter by pond
- `customer` (optional): Filter by customer
- `start_date` (optional): Start date
- `end_date` (optional): End date
- `status` (optional): PARTIAL, AKHIR
- `per_page` (optional): Items per page

**Create Harvest**
**POST** `/api/panen`

**Request Body:**
```json
{
  "tanggal": "2026-04-12",
  "jam": "08:00",
  "customer": "PT. DISANATA",
  "keterangan": "PARTIAL",
  "no_polisi": "BE 9362 YV",
  "supir": "SONI",
  "satuan": "KG",
  "items": [
    {
      "kolam": "A01",
      "qty": 783.7,
      "size": 49,
      "grade": "FS",
      "harga": 60900
    },
    {
      "kolam": "A02",
      "qty": 789.2,
      "size": 45.4,
      "grade": "FS",
      "harga": 64120
    }
  ]
}
```

**Get Harvest Details**
**GET** `/api/panen/{no_bukti}`

**Get Harvest Summary**
**GET** `/api/panen/summary`

---

## Error Handling

### Error Response Format
```json
{
  "success": false,
  "message": "Error message here",
  "data": {
    "errors": {
      "field_name": ["Error message 1", "Error message 2"]
    }
  }
}
```

### HTTP Status Codes
- `200`: Success
- `201`: Created
- `401`: Unauthorized (not logged in)
- `403`: Forbidden (no permission)
- `404`: Not Found
- `422`: Validation Error
- `500`: Server Error

---

## Pagination

All list endpoints support pagination:

**Request:**
```
GET /api/kolam?per_page=10&page=2
```

**Response:**
```json
{
  "success": true,
  "data": {
    "kolam": [...],
    "pagination": {
      "total": 100,
      "per_page": 10,
      "current_page": 2,
      "last_page": 10,
      "from": 11,
      "to": 20
    }
  }
}
```

---

## RBAC Permissions

### Permission Format
`{module}.{action}`

Examples:
- `kolam.view` - View ponds
- `pakan.create` - Create feed records
- `panen.edit` - Edit harvest data
- `sampling.delete` - Delete sampling data

### Modules
- `users` - User management
- `roles` - Role management
- `kolam` - Pond management
- `tebar` - Stocking
- `panen` - Harvest
- `sampling` - Sampling
- `pakan` - Feed
- `cek-anco` - Anco check
- `cek-air` - Water quality
- `kematian` - Mortality
- `stok` - Stock
- `mutasi-stok` - Stock mutation
- `pembelian` - Purchasing
- `keuangan` - Finance
- `laporan` - Reports
- `logs` - Activity logs

### Actions
- `view` - View data
- `create` - Create new data
- `edit` - Update data
- `delete` - Delete data
- `approve` - Approve data
- `export` - Export data
- `print` - Print data

---

## Flutter Integration

### Setup HTTP Client
```dart
class ApiClient {
  final String baseUrl = 'http://your-domain.com/api';
  String? token;

  Future<void> login(String username, String password) async {
    final response = await http.post(
      Uri.parse('$baseUrl/auth/login'),
      body: {
        'username': username,
        'password': password,
      },
    );

    if (response.statusCode == 200) {
      final data = json.decode(response.body);
      token = data['data']['token'];
    }
  }

  Future<Map<String, String>> getHeaders() async {
    return {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer $token',
    };
  }
}
```

### Example: Get Kolam List
```dart
Future<List<Kolam>> getKolamList() async {
  final headers = await apiClient.getHeaders();
  final response = await http.get(
    Uri.parse('${apiClient.baseUrl}/kolam'),
    headers: headers,
  );

  if (response.statusCode == 200) {
    final data = json.decode(response.body);
    return (data['data']['kolam'] as List)
        .map((e) => Kolam.fromJson(e))
        .toList();
  }
  throw Exception('Failed to load kolam');
}
```

---

## Best Practices

1. **Always use HTTPS in production**
2. **Store tokens securely** (use flutter_secure_storage)
3. **Handle token expiration** - use refresh endpoint
4. **Implement offline support** - cache important data
5. **Use pagination** for list endpoints
6. **Filter by date ranges** for better performance
7. **Check permissions** before showing UI elements
8. **Handle errors gracefully** with user-friendly messages
9. **Log activities** for audit trail
10. **Optimize images** if uploading photos

---

## Health Check

**GET** `/api/health`

**Response:**
```json
{
  "success": true,
  "message": "API is running",
  "data": {
    "version": "1.0.0",
    "timestamp": "2026-04-12T10:30:00.000000Z",
    "timezone": "Asia/Jakarta"
  }
}
```