first

2026-06-02 17:35:45 +08:00
commit 4ef99b1f81
148 changed files with 21134 additions and 0 deletions
--- a/TASK_PLAN.md
+++ b/TASK_PLAN.md
@@ -0,0 +1,342 @@
+# 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.