# TASK_PLAN.md — Speech2Text MBIP

## Ringkasan Fasa

| Fasa | Fokus | Anggaran |
|---|---|---|
| Fasa 1 | Auth, Role, User Management, Docker | Asas wajib |
| Fasa 2 | Project CRUD, Upload Audio, Collaborator, Policies | Storage + RBAC |
| Fasa 3 | Queue, Transcription Worker, Status, Retry | AI Integration |
| Fasa 4 | Transcript Editor, Version History, Comments | Content Features |
| Fasa 5 | Admin Dashboard, Audit Log, Transfer Ownership | Admin Tools |
| Fasa 6 | Security Hardening, Tests, README, Production Checklist | Quality |

---

## FASA 1: Asas — Auth, Role, User Management, Docker

### Objektif
Sistem boleh login, admin boleh urus pengguna, Docker berjalan.

### Checklist Fasa 1

#### 1.1 Struktur Projek Laravel
- [ ] `laravel new speech2text-mbip` dengan PHP 8.3+
- [ ] Konfigurasi `.env.example`
- [ ] Setup `config/filesystems.php` — tambah private disk
- [ ] Setup `config/auth.php`
- [ ] Konfigurasi Laravel untuk UUID

#### 1.2 Docker Setup
- [ ] `Dockerfile` untuk Laravel app (php:8.3-fpm)
- [ ] `docker-compose.yml` dengan services: app, nginx, mysql, redis, queue-worker, scheduler
- [ ] `docker/nginx/default.conf`
- [ ] `docker/php/php.ini`
- [ ] `.dockerignore`
- [ ] Test: `docker compose up -d --build`

#### 1.3 Database — Migration Awal
- [ ] Migration: `departments`
- [ ] Migration: `users` (dengan `role`, `is_active`, `department_id`, `deleted_at`)
- [ ] Migration: `audit_logs`
- [ ] Migration: `sessions` (jika guna database session)

#### 1.4 Models
- [ ] `User` model (dengan SoftDeletes, role check methods)
- [ ] `Department` model
- [ ] `AuditLog` model

#### 1.5 Authentication
- [ ] Login form (Bootstrap 5)
- [ ] Logout
- [ ] Middleware `EnsureUserIsActive` — check `is_active` selepas login
- [ ] Rate limit login (5 attempts/minute)
- [ ] Redirect admin ke `/admin/dashboard`, user ke `/dashboard`

#### 1.6 Role Middleware
- [ ] Middleware `EnsureAdmin` — untuk route `/admin/*`
- [ ] Middleware `EnsureUser` — untuk route `/dashboard/*`, `/projects/*`
- [ ] Register middleware dalam `bootstrap/app.php`

#### 1.7 Admin — User Management
- [ ] `UserPolicy` — CRUD user oleh admin sahaja
- [ ] `UserController` (Admin) dengan actions:
  - `index` — senarai semua pengguna
  - `create` / `store` — daftar pengguna baru
  - `edit` / `update` — tukar emel pengguna
  - `activate` — aktifkan pengguna
  - `deactivate` — deactivate pengguna
  - `destroy` — delete pengguna (hanya jika tiada usage)
- [ ] Form Request: `CreateUserRequest`, `UpdateUserEmailRequest`
- [ ] Views (Bootstrap 5): senarai pengguna, form cipta, form edit emel
- [ ] Action classes: `CreateUserAction`, `DeactivateUserAction`, `ActivateUserAction`, `DeleteUserAction`, `ChangeUserEmailAction`

#### 1.8 Audit Log Service
- [ ] `AuditLogService` dengan method `log()`
- [ ] Panggil AuditLogService dalam setiap action yang relevan
- [ ] Rekodkan: actor, action, target, old_values, new_values, ip, user_agent, justification

#### 1.9 Seeder
- [ ] `DepartmentSeeder` — beberapa jabatan contoh
- [ ] `AdminUserSeeder` — admin dari `.env` variables
- [ ] `DatabaseSeeder` — panggil semua seeders

#### 1.10 Admin Dashboard (Asas)
- [ ] Dashboard route `/admin/dashboard`
- [ ] Layout admin (Bootstrap 5 sidebar)
- [ ] Papar: jumlah pengguna aktif, jumlah pengguna deactive

### Arahan Test Fasa 1

```bash
# Build dan jalankan
cd /svr/speech2text
docker compose up -d --build

# Setup
docker compose exec app php artisan key:generate
docker compose exec app php artisan migrate --seed

# Semak
docker compose exec app php artisan migrate:status
docker compose exec app php artisan route:list

# Test manual:
# 1. Buka browser http://localhost
# 2. Login sebagai admin (dari .env)
# 3. Admin redirect ke /admin/dashboard
# 4. Admin boleh lihat senarai pengguna
# 5. Admin boleh daftar pengguna baru
# 6. Admin boleh deactivate pengguna
# 7. Pengguna deactivated tidak boleh login
# 8. Admin boleh activate semula
# 9. Admin boleh tukar emel
# 10. Semak audit_logs ada rekod untuk setiap tindakan
# 11. Login sebagai pengguna biasa -> redirect /dashboard
# 12. Pengguna biasa tidak boleh akses /admin/*
```

---

## FASA 2: Project CRUD, Upload Audio, Collaborator, Policies

### Checklist Fasa 2

#### 2.1 Migration
- [ ] `transcription_projects`
- [ ] `project_collaborators`

#### 2.2 Models & Relationships
- [ ] `TranscriptionProject` (dengan UUID, SoftDeletes)
- [ ] `ProjectCollaborator`
- [ ] Relationships dalam `User` model

#### 2.3 Policies
- [ ] `TranscriptionProjectPolicy` — view, create, update, delete, viewAudio, manageCollaborators
- [ ] Register policies dalam `AuthServiceProvider`

#### 2.4 File Upload
- [ ] Konfigurasi private disk dalam `config/filesystems.php`
- [ ] Form Request: `UploadAudioRequest` (validate MIME, size)
- [ ] `StorageService` — handle private file storage
- [ ] AudioController — stream audio melalui policy check

#### 2.5 Project Controllers
- [ ] `ProjectController` (User) — CRUD projek
- [ ] `AudioController` (User) — stream/download audio
- [ ] `CollaboratorController` (User) — tambah/buang collaborator

#### 2.6 Views
- [ ] Project list (dashboard)
- [ ] Create project + upload audio form
- [ ] Project detail (placeholder transcript area)
- [ ] Collaborator management panel

### Arahan Test Fasa 2

```bash
# Test manual:
# 1. Login sebagai user biasa
# 2. Cipta projek baru dengan upload audio
# 3. Semak fail ada dalam storage/app/private/ (bukan public/)
# 4. Dengar audio dalam browser (via controller stream)
# 5. Tambah collaborator
# 6. Login sebagai collaborator — boleh lihat projek
# 7. Login sebagai user lain (bukan collaborator) — 403
# 8. Login sebagai admin — tidak boleh dengar audio (403)
# 9. Admin hanya boleh lihat metadata projek
```

---

## FASA 3: Queue, Transcription Worker, Status, Retry

### Checklist Fasa 3

#### 3.1 Transcription Worker (Python)
- [ ] `docker/transcription-worker/Dockerfile` (Python 3.11 + faster-whisper)
- [ ] `docker/transcription-worker/main.py` (FastAPI endpoint `/transcribe`)
- [ ] `/health` endpoint untuk monitoring
- [ ] Tambah service ke `docker-compose.yml`

#### 3.2 Laravel Queue Job
- [ ] `TranscribeAudioJob` — baca audio, hantar ke Python worker, simpan result
- [ ] Handle timeout dan retry
- [ ] Update `transcription_status` di database

#### 3.3 Ollama Integration (Optional)
- [ ] `OllamaService` — panggil Ollama API untuk post-processing
- [ ] `OllamaPostProcessJob` — dispatch selepas transcription selesai
- [ ] Config via `.env`: `OLLAMA_ENABLED`, `OLLAMA_BASE_URL`, `OLLAMA_MODEL`

#### 3.4 UI Status
- [ ] Status badge dalam project detail (pending/processing/completed/failed)
- [ ] Auto-refresh status menggunakan polling atau SSE
- [ ] Retry button untuk failed transcription (owner sahaja)

### Arahan Test Fasa 3

```bash
# Semak transcription worker
docker compose logs -f transcription-worker
docker compose exec app curl http://transcription-worker:8000/health

# Upload audio dan monitor
docker compose logs -f queue-worker
docker compose exec app php artisan queue:work --once

# Semak result dalam database
docker compose exec mysql mysql -u root -p speech2text \
    -e "SELECT id, title, transcription_status, transcript_text FROM transcription_projects LIMIT 5;"
```

---

## FASA 4: Transcript Editor, Version History, Comments

### Checklist Fasa 4

#### 4.1 Migration
- [ ] `transcript_versions`
- [ ] `project_comments`

#### 4.2 Models
- [ ] `TranscriptVersion`
- [ ] `ProjectComment` (dengan SoftDeletes)

#### 4.3 Policies
- [ ] `TranscriptVersionPolicy`
- [ ] `CommentPolicy`

#### 4.4 Controllers & Actions
- [ ] `TranscriptController` — view dan update transcript
- [ ] `TranscriptVersionController` — lihat history, restore
- [ ] `CommentController` — CRUD komen

#### 4.5 Views
- [ ] Transcript editor (textarea, save button)
- [ ] Version history timeline
- [ ] Restore version button
- [ ] Comment/chat panel (sidebar atau bawah transcript)

### Arahan Test Fasa 4

```bash
# Test:
# 1. Edit transcript — semak transcript_versions ada rekod baru
# 2. Edit kedua kali — semak version_number bertambah
# 3. Restore version lama — semak transcript_text dikemaskini
# 4. Collaborator boleh edit transcript
# 5. Admin tidak boleh akses transcript editor (403)
# 6. Buat komen
# 7. Admin tidak boleh lihat komen (403)
```

---

## FASA 5: Admin Dashboard, Audit Log, Transfer Ownership

### Checklist Fasa 5

#### 5.1 Admin Dashboard Lengkap
- [ ] Statistik pengguna (aktif/deactivate)
- [ ] Statistik projek (pending/processing/completed/failed)
- [ ] Statistik storage
- [ ] Top users by usage
- [ ] Chart harian/bulanan (jQuery chart library)

#### 5.2 Admin Project Metadata List
- [ ] Senarai projek dengan metadata sahaja (TANPA transcript_text)
- [ ] Filter: status, tarikh, owner
- [ ] Pagination

#### 5.3 Transfer Ownership
- [ ] Form transfer ownership dengan justification field
- [ ] `TransferProjectOwnerAction`
- [ ] Option: jadikan owner lama sebagai collaborator
- [ ] Audit log untuk transfer

#### 5.4 Audit Log Browser
- [ ] Senarai audit log dengan filter
- [ ] Filter: action, actor, tarikh, projek
- [ ] Pagination
- [ ] Export CSV (admin sahaja)

### Arahan Test Fasa 5

```bash
# Test:
# 1. Admin lihat dashboard dengan statistik
# 2. Admin transfer ownership — semak audit log ada justifikasi
# 3. Selepas transfer, owner baru boleh akses projek
# 4. Owner lama (jika dijadikan collaborator) boleh akses
# 5. Admin browse audit log — semak semua rekod ada
```

---

## FASA 6: Security Hardening, Tests, README, Production

### Checklist Fasa 6

#### 6.1 Feature Tests
- [ ] `AdminCannotViewTranscriptTest`
- [ ] `AdminCannotDownloadAudioTest`
- [ ] `OwnerCanAccessOwnProjectTest`
- [ ] `CollaboratorCanAccessSharedProjectTest`
- [ ] `NonCollaboratorCannotAccessProjectTest`
- [ ] `OnlyOwnerCanDeleteProjectTest`
- [ ] `CollaboratorCanEditTranscriptTest`
- [ ] `TranscriptEditCreatesVersionHistoryTest`
- [ ] `AdminTransferOwnershipRequiresJustificationTest`
- [ ] `DeactivateUserPreventsLoginTest`
- [ ] `DeleteUnusedUserOnlyAllowedTest`
- [ ] `EmailChangeCreatesAuditLogTest`

#### 6.2 Security Hardening
- [ ] Security headers middleware
- [ ] Rate limiting semua endpoint sensitif
- [ ] Validate MIME type dari magic bytes
- [ ] Semak semua `{{ }}` dalam Blade (bukan `{!! !!}`)
- [ ] Semak CSRF token semua form
- [ ] Remove debug routes

#### 6.3 Production Checklist
- [ ] Semua item dalam `DEPLOYMENT.md` production checklist
- [ ] `APP_DEBUG=false` di production
- [ ] Config cache, route cache, view cache
- [ ] Queue supervisor setup

#### 6.4 Documentation
- [ ] README.md utama
- [ ] Arahan deployment
- [ ] Arahan development local

---

## Peringatan Penting

> **Prinsip Privasi:**
> Admin = pentadbir AKAUN, bukan pentadbir KANDUNGAN.
> Setiap fasa mesti pastikan admin tidak boleh akses audio, transcript, atau komen.
> Semak dengan feature test sebelum anggap selesai.