Incident Management — Khái niệm cốt lõi
Aggregate: IncidentFormInstance
Incident Management dùng shared Forms infrastructure, nhưng domain boundary rõ ràng:
| Thành phần | Nghĩa |
|---|---|
| IncidentFormInstance | Tên đọc của aggregate; implementation là FormInstance có FormCategoryId = IncidentManagement. |
| FormTypeId | Phân loại Incident (101), Accident (102), Illness (103). |
| StatusId | Trạng thái workflow của incident. |
| BusinessUnitId | Ranh giới dữ liệu và cấu hình. |
| OrgId / Site | Site nơi sự việc xảy ra. |
Aggregate root là incident. Attendee links, acknowledgements, generated documents, notification flags và history đều xoay quanh incident id/guid.
Vòng trạng thái
| Status | Ý nghĩa | Ai thường xử lý |
|---|---|---|
| Draft | Đang soạn, chưa gửi review. | Creator |
| Submitted | Đã submit, chờ review. | Manager/full-control |
| Under Review | Đang được review. | Manager/full-control |
| Changes Requested | Bị yêu cầu sửa. | Creator |
| Approved | Đã được approve, có thể gửi customer. | Manager/full-control |
| Sent To Customer | Đã tạo acknowledgement và enqueue notification. | System/customer |
| Partially Acknowledged | Một phần acknowledgement đã xong. | Customer |
| Acknowledged | Tất cả acknowledgement hành động đã xong. | Customer/system |
| Closed | Kết thúc. | Manager/full-control |
| Reopened | Mở lại sau khi close. | Manager/full-control |
| Cancelled | Hủy trước khi hoàn tất. | Manager/full-control |
Permission levels
| Quyền | Hành vi |
|---|---|
INCIDENT_MANAGEMENT | Chỉ điều khiển hiển thị menu/entry point; tự nó không cho create/view/full-control. |
INCIDENT_MANAGEMENT_CREATE | Tạo, save draft, update, submit, delete incident do chính user tạo (khi status cho phép). |
INCIDENT_MANAGEMENT_VIEW | Xem list/detail theo Business Unit + Org access scope, read-only. |
INCIDENT_MANAGEMENT_FULL_CONTROL | Toàn quyền: review, request changes, approve, send, close, reopen, cancel, settings. |
Quy tắc quan trọng:
- Create-only user chỉ thấy/sửa incident của chính mình; không làm governance action.
- View và full-control bị giới hạn bởi Business Unit hiện tại + Org access scope; filter ra ngoài scope không lộ record.
- Không có quyền operational nào (
CREATE/VIEW/FULL_CONTROL) ⇒ bị từ chối cả list/detail/mutation lẫn settings. - Settings icon và API settings chỉ mở cho
INCIDENT_MANAGEMENT_FULL_CONTROL.
Attendee và body marker
Một incident có thể liên quan nhiều attendee. Mỗi attendee record có thể có:
| Trường | Dùng để |
|---|---|
| Account / Attendee | Định danh customer account và attendee bị ảnh hưởng. |
| Role | Vai trò của attendee trong sự việc. |
| Staff description | Ghi chú nội bộ. |
| Customer-visible note | Nội dung customer được thấy. |
| Body marker JSON | Đánh dấu vị trí trên body map nếu cần báo cáo y tế/tai nạn. |
Customer detail chỉ hiện attendee/ghi chú liên quan đến acknowledgement của customer, không cần lộ toàn bộ attendee khác.
Attachment và generated PDF
| Loại file | Nguồn | Lưu ở đâu | Dùng khi nào |
|---|---|---|---|
| Attachment | Staff upload | Blob + attachment record | Ảnh, PDF, tài liệu nội bộ hoặc gắn với attendee. |
| Generated PDF | Reporting service | Generated document Blob + GeneratedAttachment | Report để xem nội bộ hoặc gửi customer. |
| Signature | Customer submit | Blob signature | Khi acknowledgement yêu cầu ký. |
Generate PDF popup điều hướng output bằng một lựa chọn visibility duy nhất:
- Checkbox Internal Use Only mặc định bỏ chọn ⇒ report customer-visible, luôn sinh một PDF cho mỗi attendee (không hỏi combined/per-attendee).
- Khi chọn Internal Use Only ⇒ hiện lựa chọn thứ hai: gộp tất cả attendee vào một report (mặc định) hoặc một PDF mỗi attendee, đều đánh dấu internal-use-only.
PDF chứa acknowledgement status và signature theo từng attendee tùy visibility mode:
- Internal report: gồm mọi acknowledgement active của attendee (loại notification-only) — contact name, account name, status, thời điểm acknowledge, signature (base64) nếu có.
- Customer-visible report: chỉ gồm acknowledgement có
AccountIdtrùng account của attendee; không lộ acknowledgement của account khác. - Không có signature ⇒ entry vẫn hiện status + thời gian, signature field null, template không render khối chữ ký.
Acknowledgement
FormAcknowledgement là cầu nối giữa incident và customer contact.
| Loại acknowledgement | Nghĩa |
|---|---|
| Acknowledged | Primary contact cần xác nhận đã đọc/chấp nhận. |
| Signed | Primary contact cần ký xác nhận. |
| NotificationOnly | Contact được thông báo nhưng không phải người submit acknowledgement. |
Khi customer acknowledge/sign, incident status được cập nhật thành PartiallyAcknowledged hoặc Acknowledged dựa trên tất cả acknowledgement có hành động.
Customer visibility của field
Mỗi field incident được phân loại customer-visible hoặc internal-only, có label rõ trên form staff:
| Nhóm | Customer-visible | Internal-only |
|---|---|---|
| Incident | Title, Description, Action Taken | Created By, Internal Notes |
| Attendee | Role, Customer Visible Notes | Description |
| Body marker | Body Part, Injury Type, Note, Diagram | — |
- Internal Notes: field internal-only nằm ngay dưới Action Taken; lưu cùng incident, trả về admin/staff nhưng không trả về customer.
- Customer Portal và customer-use PDF chỉ phơi field customer-visible; admin/staff và internal-use PDF thấy cả hai.
Description template & materialize
| Khái niệm | Là gì |
|---|---|
| Description template | Mẫu Description mặc định cho mỗi incident type (Incident/Accident/Illness), edit trong settings (full-control). |
| PrefillBlobName | Trỏ tới form-config-json blob (field-prefill format) lưu template trên active FormTemplateVersion của type, theo Business Unit. |
| Materialize | Khi tạo/edit, Description được prefill thành text editable thuần — placeholder đã resolve, không hiện token thô. |
- Type chưa lưu template ⇒ dùng built-in default cho type đó.
- Placeholder:
,,,,; giá trị chưa có ⇒ thay bằng text đọc được, không để token thô. - Description auto-refresh khi đổi type/date/time/site/attendee chỉ khi user chưa sửa tay; đã sửa tay ⇒ giữ nguyên, không ghi đè.
Truy cập từ Onsite App
Incident Management mở được từ Onsite App (webview tablet/mobile):
- Entry "Incident" trên landing page chỉ hiện khi có quyền incident; không có thì ẩn (không "coming soon").
- List bị giới hạn theo site identifier do wrapper cung cấp: một site ⇒ ẩn site selector; nhiều site ⇒ selector chỉ liệt kê các site được cấp.
- Xem/tải/upload attachment (PDF, ảnh) hoạt động ngay trong webview; list và form thích ứng viewport tablet/mobile.
Notification và history
- IncidentSubmitted: job bất đồng bộ khi staff submit; gửi email cho staff/manager recipient cấu hình cho Business Unit (không tạo acknowledgement/portal message). Không có recipient ⇒ job hoàn tất, không gửi gì.
- IncidentSentToCustomer: job khi gửi report cho customer contact; tạo email/SMS theo channel chọn và portal user message nếu contact có portal user id.
- Template fallback: Business Unit chưa cấu hình template cho event type ⇒ worker dùng built-in default template, không bỏ qua/fail job.
- Unified customer template: một template duy nhất cho Incident/Accident/Illness; loại cụ thể render qua placeholder incident type.
- Sau khi xử lý xong recipient, acknowledgement chuyển status Sent.
- EntityHistory: audit timeline theo incident guid; snapshot ghi ở milestone lớn (submit, approve, send, close).
- Notification history: staff xem lại notification jobs, event type, recipient và delivery method.
Tiếp theo: Kiến trúc & dữ liệu.