Manual Book StaraTrace¶

Versi dokumen: 1.2
Tanggal: 7 Juli 2026
Target pembaca: pengguna operasional, project manager, document controller, dan administrator StaraTrace.

1. Tujuan dan ruang lingkup¶

Manual ini menjelaskan penggunaan antarmuka StaraTrace sampai tingkat pengisian field, contoh nilai, status, dan tindakan pada setiap menu utama.

Screenshot dibuat dari database demo terpisah. Nama project, email, URL, dan dokumen pada screenshot adalah contoh dan bukan data produksi.

1.1 Membuka Manual Book¶

Manual Book dipublikasikan sebagai situs MkDocs dan dapat dibuka tanpa memelihara salinan konten terpisah:

• sebelum login, klik Lihat Manual Book pada panel promo;
• setelah login, klik menu Manual pada navbar;
• akses langsung melalui /manual/ pada domain StaraTrace.

Aturan keamanan yang harus dipatuhi:

• Jangan menulis password dokumen, password mailbox, access token, atau secret lain di tiket, catatan, screenshot, maupun dokumen ini.
• Isi password hanya pada field password yang tersedia. StaraTrace menyimpan password dokumen dan credential mailbox dalam bentuk terenkripsi menggunakan DOCUMENT_SECRET_KEY.
• Body email tidak disimpan di database. Database hanya menyimpan metadata header dan path raw file.
• Jangan menyalin isi attachment ke log.
• Gunakan doc_key sebagai identitas dokumen; nama file upload hanya atribut sumber.

2. Daftar isi menu¶

Menu	Fungsi utama
Dashboard	Ringkasan project, dokumen, versi, email, dan aktivitas terakhir
Projects	Membuat project, module, routing email, melihat timeline project, dan membuka Tanya AI per project
Documents	Mencari dokumen, upload, versioning, compare, diff, approval, dan external upload
Inbox	Intake email, review email, attachment, mapping, dan timeline percakapan
Sync	Local Outlook Sync, Outlook Add-in, IMAP Sync, staging, review, dan import
History	Audit timeline dan filter aktivitas
Upload	Shortcut ke upload dokumen manual
Search	Pencarian email, dokumen, dan case
Admin	User, group, membership, konfigurasi, dan inspeksi data sistem
Profil	Theme, Admin, dan Logout

3. Akses dan hak pengguna¶

3.1 Login¶

1. Buka URL StaraTrace dari administrator, misalnya https://dms.example.com/.
2. Jika belum login, aplikasi mengarahkan ke halaman login.
3. Isi Username dan Password akun StaraTrace.
4. Klik Log in.

Jangan memakai credential demo yang terlihat pada lingkungan pengembangan. Untuk reset password, hubungi administrator.

3.2 Role project¶

Role	Akses umum
Viewer	Melihat project dan artefak yang diizinkan
Editor	Viewer + intake, mapping, link case, dan perubahan operasional
Manager	Editor + mengelola konfigurasi project/module
Superuser	Semua project dan seluruh Django Admin

Menu atau tombol dapat tidak muncul jika role tidak memenuhi syarat. Akses efektif juga dapat dipengaruhi status staff/superuser dan kepemilikan email.

4. Dashboard¶

Dashboard menampilkan:

• jumlah project, dokumen, versi, dan email yang dapat diakses;
• versi terbaru beserta source dan status;
• email terbaru dan dokumen yang sudah terhubung;
• Quick Actions untuk upload dokumen, upload email, membuat project, dan membuka daftar dokumen;
• ringkasan project beserta shortcut upload.

Tidak ada field input pada Dashboard. Klik angka, nama project, doc key, atau tombol shortcut untuk masuk ke detail terkait.

5. Projects¶

5.1 Daftar project¶

Menu Projects menampilkan project yang dapat diakses. Setiap kartu berisi nama, project_key, jumlah module, jumlah dokumen, serta shortcut upload dokumen dan email.

Tindakan:

• New Project: membuat project.
• Klik kartu project: membuka detail project.
• Ikon cloud: upload dokumen langsung ke project.
• Ikon email: upload email ke project.

5.2 Membuat atau mengedit project¶

Buka Projects > New Project. Untuk mengedit, buka detail project lalu klik Edit Project.

Field	Wajib	Cara isi	Contoh
Name	Ya	Nama bisnis project	ERP Modernization 2026
Project key	Ya	ID stabil berbentuk slug; gunakan huruf kecil, angka, dan tanda minus	erp-modernization
Description	Tidak	Ringkasan scope project	Implementasi ERP untuk finance, procurement, dan inventory.
Email from patterns	Tidak	Satu pola sender per baris; mendukung email penuh, @domain, atau prefix*	@vendor.co.id lalu consultant*
Email to patterns	Tidak	Pola alamat pada header To	dms@example.com
Email cc patterns	Tidak	Pola alamat pada header Cc	pm@example.com
External source policy	Ya	Kebijakan link source eksternal	Local DMS + optional external link
External upload mode	Ya	Aktifkan antrean external upload hanya jika worker sudah siap	No external upload worker
External upload provider	Ya	Provider yang digunakan jika queue aktif	SharePoint / Teams via RPA

Pilihan External source policy:

• Local DMS only: source lokal saja; field link eksternal tidak digunakan.
• Local DMS + optional external link: link eksternal boleh ditambahkan.
• Local DMS + required external link: link diwajibkan sebagai tindak lanjut, tetapi intake lokal tetap dapat dilakukan lebih dulu.

Klik Save. project_key harus unik dan sebaiknya tidak diubah setelah dipakai oleh dokumen.

5.3 Detail project¶

Detail project menyediakan:

• edit dan soft delete project;
• upload dokumen/email dengan project terpilih;
• membuat case dan module;
• membuka Tanya AI untuk bertanya berdasarkan artefak project yang berhasil dibaca sistem;
• daftar module, dokumen, email, dan case;
• story timeline dengan filter flow/all, inbound/outbound, dan email/document;
• filter daftar melalui menu Documents atau Search.

Gunakan Delete Project hanya setelah memastikan tidak ada pekerjaan aktif. Penghapusan adalah soft delete dan tunduk pada retention/legal hold.

5.4 Tanya AI project¶

Dari detail project, klik Tanya AI. Fitur ini tersedia untuk user dengan akses minimal Viewer pada project tersebut.

Tanya AI dipakai untuk mengajukan pertanyaan natural-language terhadap isi project. Jawaban hanya dibangun dari sumber yang lolos akses project dan berhasil dibaca sistem. Secara default sumber utamanya adalah dokumen hasil extract. Jika administrator mengaktifkan cakupan email untuk environment ini, email project yang terindeks juga dapat ikut dipakai sebagai konteks.

Area	Fungsi	Catatan
Pertanyaan	Kalimat tanya atau instruksi analitis singkat	Contoh: Apa saja validasi currency pada modul portofolio?
Tanyakan	Menjalankan pencarian kandidat lalu meminta AI menyusun jawaban	Pertanyaan yang lebih spesifik biasanya memberi sumber yang lebih tepat
Jawaban	Respons AI berbasis konteks yang ditemukan	Selalu verifikasi isi jawaban ke sumber
Sumber dokumen yang dipertimbangkan	Daftar sumber yang ditemukan AI	Entri yang benar-benar dipakai akan ditandai dikutip
Dokumen relevan	Ditampilkan ketika AI belum dapat menjawab	Menunjukkan kandidat terdekat yang tetap perlu dicek manual

Alur singkat fitur ini:

1. Sistem mencari dokumen dan, bila diaktifkan, email yang relevan dalam project yang sama.
2. Sistem mengambil potongan isi yang paling relevan dari sumber tersebut.
3. AI menyusun jawaban ringkas dan wajib menyebut sumber yang dipakai.
4. Jika konteks tidak cukup, aplikasi akan menyatakan bahwa jawaban tidak ditemukan pada project ini.

Gunakan Tanya AI untuk pertanyaan seperti keputusan rapat, validasi field, istilah bisnis, perubahan versi, atau ringkasan topik tertentu. Hindari memasukkan secret, password dokumen, atau instruksi yang meminta AI mengabaikan sumber, karena fitur ini memang dibatasi agar hanya menjawab dari konteks project.

6. Modules¶

Module adalah scope di dalam project, misalnya Finance, Procurement, atau Inventory. Module digunakan untuk routing email, pengelompokan dokumen, dan target external upload.

6.1 Membuat atau mengedit module¶

Dari detail project, klik Add Module. Untuk edit, buka detail module lalu klik Edit Module.

Field	Wajib	Cara isi	Contoh
Name	Ya	Nama module	Finance & Accounting
Module key	Ya	Slug unik di dalam project	finance
Description	Tidak	Ringkasan scope module	Scope finance, budget, dan general ledger.
Email hosts	Tidak	Domain internal untuk menentukan arah email; pisahkan per baris atau koma	example.com, vendor.co.id
Email subject patterns	Tidak	Satu pola subject per baris	[ERP] && Finance atau FSD Finance*
External source policy override	Tidak	Kosong untuk mengikuti project; pilih nilai jika module perlu pengecualian	Use project default
External upload target URL	Tidak	Folder default SharePoint/Teams	https://contoso.sharepoint.com/sites/erp/Shared%20Documents/Finance
External Upload Target (FILE)	Tidak	Override folder untuk standalone file	https://.../Finance/Files
External Upload Target (FSD)	Tidak	Override folder FSD	https://.../Finance/FSD
External Upload Target (MOM)	Tidak	Override folder MOM	https://.../Finance/MOM
External Upload Target (SOP)	Tidak	Override folder SOP	https://.../Finance/SOP
External Upload Target (RFC)	Tidak	Override folder RFC	https://.../Finance/RFC

Sintaks subject pattern:

• FSD Finance*: subject harus diawali pola tersebut.
• [ERP] && Finance: kedua token harus ada.
• Teks biasa: pencocokan teks subject.

Target per doc type mengambil prioritas di atas target default. Queue external upload baru efektif jika mode project aktif, kebijakan external source mengizinkan, dan target module tersedia.

6.2 Detail module¶

Halaman ini menampilkan konfigurasi routing, kebijakan external source, target upload, dokumen, email, dan timeline module. Tombol Recalculate Email Directions menghitung ulang arah email memakai konfigurasi host terbaru; gunakan setelah perubahan domain internal.

7. Documents¶

7.1 Daftar dokumen¶

Filter yang tersedia:

Filter	Contoh
Project	ERP Modernization 2026
Module	finance
Doc Type	Functional Specification Document
Direction	Inbound
Extension	.docx
Updated From / To	2026-06-01 sampai 2026-06-30

Kolom utama: Doc Key, title, type, direction, kind, project, module, jumlah version, dan waktu update.

Upload Ulang Selected mengantrekan external upload. Untuk dokumen versioned, versi terbaru yang digunakan. Tombol ini hanya berguna jika external upload project/module telah dikonfigurasi.

7.2 Upload dokumen¶

Buka Upload atau Documents > Upload Document.

Format versioned: .csv, .docx, .odt, .pdf, .rtf, .txt, .xlsx.
Format standalone: .7z, .bmp, .doc, .gif, .heic, .jpeg, .jpg, .ods, .png, .ppt, .pptx, .rar, .tif, .tiff, .webp, .xls, .zip.

Field	Wajib	Cara isi	Contoh
Document File	Ya	Pilih satu atau beberapa file yang didukung	FSD_Finance_Closing_v1.1.docx
External Source Link	Tergantung kebijakan	URL Teams, SharePoint, Drive, atau source resmi	https://contoso.sharepoint.com/.../FSD
Document Password	Tidak	Isi hanya untuk Office file terenkripsi; jangan catat nilainya di tempat lain	Isi langsung pada UI
Project	Ya	Project pemilik dokumen	ERP Modernization 2026
Module	Tidak	Module scope	Finance & Accounting
Document Type	Jika tidak terdeteksi	FSD, FILE, MOM, SOP, atau RFC	FSD
Direction	Ya untuk dokumen baru	Inbound atau Outbound	Inbound
Action	Ya	Create new atau add version ke dokumen existing	Create new Document
Title	Ya untuk dokumen baru single-file	Judul logis, bukan sekadar nama file	FSD Finance - Monthly Closing
Meeting Date	Untuk MOM	Tanggal occurrence	2026-06-24
Doc Key Override	Tidak	Kosongkan agar otomatis; hanya single-file	fsd-erp-modernization-finance-closing
Existing Document	Ya untuk action existing	Dokumen target dengan project/module/type yang sama	FSD Finance - Monthly Closing
Version Override	Tidak	Kosongkan untuk auto-next; hanya single-file	v1.2
Change Summary	Disarankan	Ringkas perubahan bisnis	Menambahkan approval matrix dan SLA closing.
Force new version	Tidak	Centang hanya jika hash sama tetap harus menjadi versi baru	Tidak dicentang
Ignore conversion confidence threshold	Tidak	Override manual jika hasil konversi ber-confidence rendah tetapi sudah diverifikasi	Tidak dicentang
Allow failed conversion	Tidak	Simpan versi walau konversi gagal; diff belum tersedia	Tidak dicentang

Catatan batch upload:

• Doc Key Override, Version Override, dan Document Password hanya didukung untuk single-file.
• Batch diproses satu per satu.
• Hash SHA-256 digunakan untuk dedupe. Jangan memakai Force new version tanpa alasan audit yang jelas.

7.3 Detail dokumen¶

Informasi dan tindakan pada detail dokumen:

• metadata project/module, type, kind, direction, status, dan doc_key;
• daftar versi dan status conversion;
• Add Version;
• Compare dengan dokumen sejenis;
• Move Module untuk editor/manager;
• link document ke case;
• edit external source link pada document atau versi terbaru;
• queue/requeue external upload jika aktif;
• password management untuk sumber terenkripsi;
• promote standalone document menjadi versioned document;
• soft delete document.

7.4 Menambah versi¶

Field	Wajib	Contoh / ketentuan
Document File	Ya	Satu atau beberapa file; batch memakai nomor versi otomatis
External Source Link	Tergantung policy	https://contoso.sharepoint.com/.../FSD_Finance_v1.2.docx
Document Password	Tidak	Isi melalui UI hanya untuk single-file Office terenkripsi
Version Override	Tidak	v1.2; kosong berarti nomor berikutnya
Change Summary	Disarankan	Perbaikan approval matrix hasil UAT.
Force new version	Tidak	Hanya jika hash identik tetap perlu version baru
Ignore conversion confidence threshold	Tidak	Override terkontrol setelah review manual
Allow failed conversion	Tidak	Versi tersimpan dengan status conversion failed

Jika konversi gagal, source file tetap disimpan, status menjadi failed, dan error dicatat tanpa membuat aplikasi crash.

7.5 Detail versi¶

Tombol yang dapat muncul:

• Approve: mengubah Draft menjadi Approved jika fitur publish aktif.
• Download Source: mengunduh file sumber.
• Open External Source: membuka link eksternal.
• Download Markdown: mengunduh canonical Markdown jika tersedia.
• View Diff: membandingkan dengan versi sebelumnya.
• Retry Conversion: mencoba konversi ulang.
• Set Password / Clear Password: mengelola password terenkripsi.
• Delete Version: soft delete versi sesuai hak akses.
• External Upload: mengantrekan upload versi ke target module.

7.6 Diff versi¶

Diff menunjukkan baris ditambah, dihapus, atau berubah antara versi saat ini dan versi sebelumnya. Klik Generate pada panel AI hanya jika ringkasan AI diperlukan. Ringkasan disimpan sebagai artifact dan dapat di-generate ulang.

Ringkasan AI pada diff¶

Panel AI di bagian atas halaman diff membantu reviewer membaca inti perubahan tanpa harus menelusuri seluruh diff terlebih dahulu.

Status panel	Arti	Tindakan user
Belum Dibuat	Belum ada ringkasan tersimpan	Klik Generate Ringkasan Diff
Diproses	Permintaan sudah diterima layanan AI	Tunggu hasil muncul atau generate ulang bila proses macet
Siap	Ringkasan, poin perubahan, dan catatan review sudah tersedia	Baca hasil lalu buka diff jika perlu verifikasi detail
Tertahan	Prasyarat belum siap	Pastikan kedua versi sudah punya canonical Markdown
Gagal	Layanan AI gagal mengembalikan hasil	Klik Coba Lagi atau cek provider/worker
Perlu Update	Sumber berubah setelah ringkasan terakhir dibuat	Klik Generate Ulang agar hasil sinkron lagi

Isi panel AI diff umumnya mencakup:

• ringkasan singkat perubahan antar versi;
• daftar Poin Perubahan yang dianggap paling penting;
• Catatan Review untuk membantu reviewer menentukan area yang perlu diperiksa ulang.

Jika diff kosong, periksa:

• kedua versi memiliki canonical Markdown;
• conversion status OK;
• password dokumen terenkripsi sudah diisi jika diperlukan;
• source memang memiliki perubahan konten.

7.7 Compare dokumen serupa¶

Pilih Other Document, lalu klik Lihat Diff. Fitur ini dipakai untuk membandingkan dokumen logis yang berbeda tetapi serupa; untuk versi dalam dokumen yang sama gunakan View Diff.

8. Inbox¶

8.1 Daftar email¶

Inbox menyediakan tampilan Timeline dan Table. KPI menunjukkan total email, unparsed, needs review, dan conversion failed.

Filter	Contoh
Project	erp-modernization
Module	finance
Direction	inbound
Parsed	parsed atau unparsed
Process	needs_review, ready_for_mapping, archived_only, atau extraction_failed
From Date / To Date	2026-06-01 sampai 2026-06-30
Search	subject, sender, filename, Message-ID, atau hash

Tanggal filter memakai tanggal header email; jika kosong, aplikasi memakai waktu upload.

8.2 Upload email manual¶

File yang diterima: .eml dan .msg. Beberapa file dapat dipilih sekaligus.

Field	Wajib	Cara isi	Contoh
Email Files	Ya	Pilih satu atau beberapa .eml/.msg	RE_FSD_Finance_Closing.eml
Intake Mode	Ya	Automatic routing atau Manual project/module	Automatic routing
Project	Untuk manual	Project tujuan	ERP Modernization 2026
Module	Untuk manual	Module tujuan	Finance & Accounting
Document Type	Tidak	Override tipe attachment versioned	FSD
Direction	Tidak	Kosong berarti mengikuti direction email	Inbound
External Source Link	Tergantung policy	Folder/link source untuk batch	https://contoso.sharepoint.com/.../Finance

Pada Automatic routing, aplikasi menggunakan From/To/Cc pattern project dan subject pattern module. Jika project dan module tidak dapat ditentukan, email masuk staging untuk direview pada Sync.

Hasil intake:

• raw email disimpan ke storage;
• hanya header metadata dan path raw file disimpan di database;
• attachment diekstrak dan didedupe dengan SHA-256;
• jika parsing gagal, raw file tetap disimpan dan status menjadi unparsed;
• ZIP dapat diekstrak; entry yang didukung tampil sebagai attachment turunan.

8.3 Detail email¶

Detail email menampilkan From, To, Cc, Subject, Date, Message-ID, thread, direction, project/module, raw preview, attachment, dokumen terkait, case, dan AI summary.

Ringkasan AI pada email¶

Panel AI summary di bagian atas halaman email merangkum percakapan email, attachment, case terkait, dan dokumen yang sudah ditautkan.

Area panel	Fungsi
Ringkasan	Inti percakapan atau konteks email
Poin Penting	Butir utama yang perlu diketahui user
Tindak Lanjut / Catatan	Hal yang masih terbuka atau perlu dicek
Dokumen Terkait	Shortcut ke dokumen atau diff yang berhubungan

Perilaku cakupan:

• secara default, ringkasan mengikuti thread email ini;
• jika aplikasi menawarkan tombol Gunakan percakapan terkait, user dapat memperlebar cakupan ke email lain dengan subject yang sama dalam project yang sama;
• pada staged email, ringkasan hanya membaca staged email tersebut sampai email diimport ke Inbox.

Tindakan:

• Download Raw untuk mengambil .eml/.msg asli;
• Move Module untuk memperbaiki scope;
• Create/Link Case;
• Map attachment ke dokumen;
• Generate ringkasan AI;
• Delete untuk soft delete email.

8.4 Mapping attachment ke dokumen¶

Field mapping sama dengan upload dokumen, dengan source file berasal dari attachment email:

Field	Wajib	Contoh
Project	Ya	ERP Modernization 2026
Module	Tidak	Finance & Accounting
Document Type	Jika auto-detect gagal	FSD
Direction	Jika tidak dapat diwarisi	Inbound
Action	Ya	Create new Document atau Update existing Document
External Source Link	Tergantung policy	URL source resmi
Document Password	Tidak	Isi melalui UI untuk Office file terenkripsi
Title	Untuk dokumen baru	FSD Finance - Monthly Closing
Meeting Date	Untuk MOM	2026-06-24
Doc Key Override	Tidak	fsd-erp-modernization-finance-closing
Existing Document	Untuk update	Dokumen yang project/module/type-nya sesuai
Version Override	Tidak	v1.1
Change Summary	Disarankan	Revisi setelah review Finance.
Force/Confidence/Failed override	Tidak	Centang hanya setelah review manual

Mapping berhasil akan membuat DocumentVersion, menghubungkan attachment dan email, menjalankan conversion, serta menyediakan diff jika ada versi sebelumnya.

8.5 Review Queue¶

Review Queue berfokus pada attachment yang perlu keputusan manual. Pilih project/module jika diminta, lalu buka Map. Jangan memaksa mapping jika attachment hanya bukti pendukung dan bukan document version.

9. Sync¶

9.1 Local Outlook Sync¶

Gunakan Local Outlook Sync ketika IMAP/Graph/Exchange API tidak tersedia dan pengguna memakai Classic Outlook di Windows.

Field	Wajib	Cara isi	Contoh
Label	Ya	Nama perangkat/agent yang mudah dikenali	Outlook Finance Laptop
Source mailbox	Tidak	Identitas mailbox untuk audit	user@example.com
Source folder	Ya	Folder Outlook yang dipantau worker	DMS Sync
Import mode	Ya	Auto-route, fixed scope, atau stage only	Auto-route, stage if unmatched
Project	Wajib untuk fixed scope	Project tetap	ERP Modernization 2026
Module	Wajib untuk fixed scope	Module tetap	Finance & Accounting

Setelah klik Generate Agent Token:

1. Salin token saat ditampilkan; token hanya ditampilkan sekali.
2. Jangan menyimpan token di dokumen umum atau source code.
3. Pasang worker memakai command installer yang ditampilkan.
4. Buat Outlook Rule untuk memindahkan email relevan ke folder yang sama dengan Source folder.
5. Jika service tidak dapat mengakses profil Outlook, jalankan worker melalui Task Scheduler pada saat user login.

Revoke menonaktifkan token agent. Buat token baru jika perangkat diganti atau token diduga bocor.

9.2 Outlook Add-in¶

Pada halaman Local Outlook Sync tersedia URL manifest Add-in. Gunakan untuk New Outlook atau Outlook Web:

1. Buat agent token.
2. Install manifest sebagai custom add-in atau melalui Microsoft 365 admin center.
3. Pilih satu atau beberapa email.
4. Klik Upload to DMS.
5. Tempel token dmsls_... pada taskpane.
6. Klik Upload Current Email atau Upload Selected Emails.

Production memerlukan URL HTTPS publik yang benar pada OUTLOOK_ADDIN_BASE_URL.

9.3 IMAP Sync¶

IMAP Sync membuka folder mailbox dalam mode read-only. Aplikasi tidak memindahkan, menghapus, atau expunge email pada server.

Field	Wajib	Cara isi	Contoh
Saved credential	Tidak	Pilih credential tersimpan atau Manual entry	Manual entry
Host	Ya untuk manual	Host IMAP	outlook.office365.com
Port	Ya	Umumnya SSL IMAP	993
Username	Ya	Username login mailbox	user@example.com
Password	Untuk password auth	Password/app password; isi hanya di UI	Tidak ditampilkan
Access token	Untuk OAuth2	Bearer token sementara	Tidak ditampilkan
Source mailbox	Tidak	Mailbox untuk menentukan perspektif sender/To/Cc	user@example.com
Folder	Ya	Folder yang dibuka read-only	INBOX, Sent Items, atau [Gmail]/Sent Mail
Auth method	Ya	Password/App Password atau OAuth2 Access Token	Password / App Password
Use SSL	Tidak	Biasanya dicentang pada port 993	Dicentang
Since date	Tidak	Batas tanggal awal	2026-06-01
Subject filter	Tidak	Filter server-side subject	[ERP]
Max messages	Ya	1–500 pesan terbaru	100
Save credential	Tidak	Simpan secret terenkripsi untuk user ini	Tidak dicentang untuk uji awal
Credential label	Saat save baru	Nama credential	Outlook Inbox - Finance

Klik Sync Read-Only. Periksa bagian Recent Runs untuk jumlah fetched, duplicate, dan error.

9.4 Staged Email dan bulk action¶

Daftar staged pada IMAP Sync hanya menampilkan evidence milik user aktif.

Bulk action:

• Import Selected to Inbox: import staged email atau hubungkan ke email yang sudah ada.
• Apply Routing Selected: hitung ulang project/module berdasarkan pattern terbaru.
• Delete Selected from My Queue: hapus evidence dari queue user; gunakan hati-hati.
• Filter status: All, Perlu Dicek, Ditandai OK, Rahasia, Tidak Relevan.

9.5 Detail staged email dan review evidence¶

Field review:

Field	Wajib	Pilihan / contoh
Review decision	Ya	Not Reviewed, My Evidence Is OK, Not Relevant, Secret / Restricted
Review note	Tidak	Header dan attachment sesuai scope Finance.
Project	Saat import manual	ERP Modernization 2026
Module	Saat import manual	Finance & Accounting
Direction	Tidak	Kosong untuk derived direction

Status canonical staged email:

• Waiting Review: masih menunggu keputusan.
• Ready for Import: dapat diimport.
• Restricted - Secret: tidak boleh diproses sebagai email biasa.
• Not Relevant: ditolak dari scope DMS.
• Imported to Inbox: sudah menjadi/terhubung ke EmailMessage.

User hanya boleh mereview evidence miliknya. Gunakan Reroute setelah admin/manager memperbaiki routing pattern.

Panel AI summary juga tersedia pada detail staged email. Ringkasan ini berguna untuk menilai konteks email sebelum email diimport ke Inbox, terutama saat reviewer perlu memastikan evidence memang relevan terhadap project/module tujuan.

9.6 Maintenance Sync¶

Tombol Sync Semua Maintenance hanya untuk staff dan muncul jika scheduler tidak aktif. Proses mencakup reroute staged email, pemeriksaan external link, dan purge yang jatuh tempo. Jalankan setelah memastikan tidak ada scheduler lain yang mengerjakan proses sama.

9.7 Matriks integrasi email¶

Kanal	Status	Cara kerja	Kapan digunakan
Classic/Old Outlook di Windows	Tersedia	Local Sync Agent memakai Outlook COM pada PC user, mengekspor email, lalu mengirim raw email ke endpoint DMS dengan scoped device token	IMAP/Graph/Exchange API diblokir tetapi profil Classic Outlook tersedia
Outlook Add-in	Tersedia	User memilih email pada New Outlook/Outlook Web lalu mengunggahnya melalui taskpane	Background scanning tidak memungkinkan
IMAP	Tersedia	Server membuka folder mailbox secara read-only, mengambil raw message, dedupe, lalu menaruhnya di staging	Provider mengizinkan IMAP password/app password/OAuth2
POP3	Belum tersedia	Belum ada form, client, management command, atau worker POP3 pada versi ini	Jangan memasukkan credential POP3 ke form IMAP

Integrasi langsung Classic/Old Outlook¶

Alur aktual:

1. Outlook Rule memindahkan email relevan ke folder, misalnya DMS Sync.
2. Local Sync Agent berjalan dalam konteks Windows user yang memiliki profil Outlook.
3. Agent membaca item melalui Outlook COM dan menghasilkan file email untuk intake.
4. Agent mengirim file ke endpoint /inbox/sync/api/upload/ memakai token dmsls_....
5. DMS melakukan dedupe, parsing, routing, lalu memilih import langsung atau staging sesuai Import mode.
6. Database hanya menyimpan metadata header dan path raw file; body tidak disimpan di database.

Ini merupakan integrasi langsung melalui agent lokal, bukan koneksi server ke file cache internal Outlook. Jangan membaca atau memodifikasi OST/PST secara langsung.

Integrasi IMAP¶

IMAP memakai folder dan perspektif mailbox yang dipilih user. Sync bersifat read-only dan tidak menghapus/memindahkan pesan server. Gunakan staging untuk review evidence sebelum import ketika routing atau klasifikasi belum pasti.

Rencana guardrail POP3¶

POP3 belum dapat dioperasikan dari UI saat ini. Jika dikembangkan, implementasi minimum harus:

• menggunakan koneksi TLS dan secret terenkripsi dari environment/credential store;
• mengambil raw email tanpa menyimpan body ke database;
• menggunakan UIDL, Message-ID, raw SHA-256, dan header fingerprint untuk dedupe;
• tidak menjalankan DELE atau menghapus pesan dari server;
• menyimpan raw file walau parsing gagal dan menandai status unparsed;
• mengirim hasil ke staging/review flow yang sama dengan IMAP;
• mencatat status/error tanpa membuat aplikasi crash;
• menyediakan unit test untuk dedupe, kegagalan parsing, dan perilaku non-delete.

Karena POP3 tidak memiliki konsep folder seperti IMAP, scope mailbox/folder dan direction tidak boleh diasumsikan sama. Gunakan source_mailbox serta konfigurasi routing project/module untuk menentukan konteks.

10. History¶

History menampilkan event inbound, outbound, dan internal. Filter:

Field	Contoh
Direction	inbound
Action	document_version_created
Status	success, error, atau denied
Object Type	DocumentVersion
From / To	rentang tanggal audit
Actor	manualadmin
Search	doc_key, object ID, metadata, atau action

Gunakan History untuk investigasi siapa melakukan tindakan, objek yang berubah, status, waktu, IP, dan metadata yang aman. Isi attachment dan secret tidak boleh ada di metadata audit.

11. Search¶

Search dapat dibuka dari kotak pencarian navbar atau menu project.

Field	Wajib	Contoh
Query	Ya	closing, subject, doc key, filename, atau note
Type	Tidak	All, Email, Document, atau Case
Project	Tidak	erp-modernization

Klik ikon refresh untuk force rebuild index jika hasil belum mengikuti perubahan terbaru. Untuk rebuild operasional penuh gunakan python manage.py rebuild_search_index.

12. Cases¶

Case menggabungkan email, dokumen, dan link eksternal dalam satu konteks bisnis.

12.1 Membuat case¶

Case dapat dibuat dari detail project, email, atau dokumen.

Field	Wajib	Contoh
Project	Ya	ERP Modernization 2026
Module	Tidak	Finance & Accounting
Title	Ya	Closing Approval Gap
Description	Tidak	Pelacakan keputusan approval matrix dan SLA closing.

case_key dibuat otomatis dan unik. Jika case dibuat dari email/dokumen, artefak sumber dapat langsung terhubung.

12.2 Detail case dan external link¶

Bagian detail menampilkan email, dokumen, dan external link. Form external link:

Field	Wajib	Contoh
Source	Ya	Teams, Ticket, atau External Link
Label	Ya	JIRA ERP-142
URL	Ya	https://jira.example.com/browse/ERP-142
Note	Tidak	Change request approval matrix

URL harus menuju sumber resmi yang dapat diakses sesuai kebijakan organisasi.

13. Admin¶

Admin hanya untuk staff/superuser. Hindari mengedit record sistem secara langsung jika tindakan yang sama tersedia di UI operasional.

13.1 Authentication and Authorization¶

Menu	Penggunaan
Users	Membuat user, mengaktifkan staff/superuser, group, dan permission
Groups	Mengelompokkan permission Django

Field user yang umum: username, password hash/reset form, first name, last name, email, active, staff, superuser, groups, dan permissions. Jangan pernah memasukkan password user ke catatan admin.

13.2 Core¶

Menu	Penggunaan	Catatan
Projects	Konfigurasi project dan soft-delete/legal hold	Lebih aman melalui menu Projects
Modules	Routing dan target external upload	Pastikan module milik project benar
Project memberships	User, project, role, active	Cara utama memberi akses project
Documents	Metadata document dan version inline	doc_key adalah identitas stabil
Document versions	Inspeksi version, conversion, approval	Jangan mengubah hash/path sembarangan
External upload jobs	Monitoring queue, attempt, error, target	Field runtime umumnya read-only
AI summary artifacts	Monitoring status, model, error, summary	Artifact dapat di-generate ulang dari UI
Document artifact links	Relasi document/version/attachment	Untuk audit traceability
Conversation cases	Administrasi case	Gunakan UI Cases untuk aktivitas normal
Conversation external/email/document links	Relasi case	Hindari duplikasi relasi
Audit logs	Inspeksi audit	Read-only; tidak dapat add/edit

13.3 Ingest¶

Menu	Penggunaan	Catatan
Email messages	Metadata raw email dan scope	Body tidak ada di database
Email attachments	Hash, path, class, mapping	Jangan log atau salin isi attachment
Email document links	Relasi email ke version	Dibuat otomatis saat mapping
IMAP sync runs	Statistik dan error sync	Secret tidak ditampilkan
Mailbox sync credentials	Credential per user	Secret tersimpan terenkripsi
Local sync agents	Device, scope, status, revoke	Token asli tidak disimpan, hanya hash
Local sync uploads	Audit file yang diterima agent	Cek status/error
Synced emails	Canonical staged email	Cek trust dan review status
Synced email evidences	Copy/evidence per user	Review hanya oleh pemilik melalui UI

13.4 Project Membership¶

Field:

Field	Wajib	Contoh
Project	Ya	ERP Modernization 2026
User	Ya	finance.controller
Role	Ya	Viewer, Editor, atau Manager
Is active	Ya	Dicentang

Satu user hanya memiliki satu membership per project. Nonaktifkan membership untuk mencabut akses tanpa menghapus histori.

14. Profil, theme, dan logout¶

Klik nama user di kanan atas:

• Switch to light/dark mode: mengubah tema di browser saat ini.
• Admin: membuka Django Admin jika diizinkan.
• Logout: mengakhiri session.

Selalu logout pada perangkat bersama.

15. Alur kerja harian yang disarankan¶

15.1 Intake email dan membuat versi dokumen¶

1. Upload .eml/.msg atau jalankan Sync.
2. Jika staged, review evidence dan import ke Inbox.
3. Buka detail email.
4. Periksa metadata dan attachment.
5. Klik Map pada attachment yang merupakan dokumen versioned.
6. Pilih create new atau existing document.
7. Isi change summary dan submit.
8. Periksa conversion status dan diff.
9. Link email/dokumen ke case jika ada isu bisnis.

15.2 Upload revisi tanpa email¶

1. Buka detail dokumen.
2. Klik Add Version.
3. Upload source revisi.
4. Biarkan version override kosong kecuali ada nomor versi resmi.
5. Isi change summary.
6. Periksa SHA-256 dedupe dan conversion.
7. Buka diff dan generate AI summary jika diperlukan.

15.3 Menangani conversion failed¶

1. Pastikan file sumber dapat dibuka.
2. Jika Office file terenkripsi, isi password melalui Set Password.
3. Klik Retry Conversion.
4. Jika tetap gagal, source tetap tersimpan dan conversion_error dicatat.
5. Gunakan Allow failed conversion hanya jika penyimpanan versi diperlukan dan alasan sudah direview.

16. Status penting¶

Area	Status	Arti
Email parsing	parsed	Header berhasil diparse
Email parsing	unparsed	Raw tersimpan, parsing gagal
Attachment	ready_for_mapping	Dapat dipetakan ke dokumen
Attachment	archived_only	Disimpan sebagai bukti, bukan versioned document
Attachment	extraction_failed	Ekstraksi gagal
Mapping	unmapped	Belum dipetakan
Mapping	needs_review	Perlu keputusan user
Mapping	auto_mapped	Dipetakan otomatis
Mapping	manually_mapped	Dipetakan user
Conversion	pending	Belum selesai
Conversion	ok	Canonical Markdown tersedia/berhasil
Conversion	failed	Source tersimpan, conversion gagal
Version	draft	Belum approved
Version	approved	Sudah disetujui
External upload	pending/processing	Sedang antre/diproses
External upload	succeeded	Upload eksternal berhasil
External upload	failed	Gagal; cek last error dan requeue

17. Troubleshooting singkat¶

Email .msg tidak terbaca¶

Pastikan dependency extract-msg terpasang melalui pip install -r requirements.txt. Raw file harus tetap tersimpan dan status menjadi unparsed bila parsing gagal.

Attachment tidak muncul untuk mapping¶

Periksa processing_status, extension, hasil ekstraksi ZIP, dan apakah attachment sudah soft-deleted atau sudah mapped.

Dokumen tidak muncul pada Existing Document¶

Pilihan difilter berdasarkan project, module, doc type, status tidak terhapus, dan sifat versioned. Samakan scope/type terlebih dahulu.

Diff tidak tersedia¶

Periksa conversion status kedua versi, canonical Markdown, password sumber, dan confidence threshold.

AI summary tidak berjalan¶

Periksa provider, model, endpoint, mode direct/worker queue, dan status worker. Jangan menempel API key ke screenshot atau log.

Tanya AI menjawab "jawaban tidak ditemukan"¶

Periksa apakah:

• istilah pada pertanyaan sama atau cukup dekat dengan istilah yang benar-benar tertulis pada dokumen/email;
• dokumen relevan sudah berhasil di-extract dan dapat dicari;
• email memang sudah termasuk cakupan Tanya AI pada environment ini;
• user memiliki akses ke project yang berisi sumber tersebut.

Staged email tidak dapat diimport¶

Pastikan review status sudah Ready for Import, user memiliki akses editor pada project, dan project/module routing valid.

Search belum mengikuti data terbaru¶

Klik ikon rebuild pada Search atau jalankan:

python manage.py rebuild_search_index

External upload gagal¶

Periksa mode project, policy external source, target URL module/doc type, storage state RPA, browser Playwright, dan worker. Lihat last_error tanpa mencetak isi attachment.

18. Catatan screenshot¶

Seluruh screenshot manual tersedia di folder docs/assets/manual-book/. Screenshot form menggunakan contoh isian tetapi tidak disubmit, sehingga tidak mengubah data demo setelah pengambilan gambar.