speech2text/TASK_PLAN.md

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

# 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

# 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

# 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

# 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

# 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.