690504:1641 Update specs [skip ci]
This commit is contained in:
@@ -0,0 +1,162 @@
|
||||
# Feature Specification: Integrated Workflow Context & Step-specific Attachments
|
||||
|
||||
**Feature Branch**: `200-fullstacks/202-adr-021-integrated-workflow-context`
|
||||
**Created**: 2026-05-03
|
||||
**Status**: Draft
|
||||
**Input**: ADR-021 Integrated Workflow Context & Step-specific Attachments
|
||||
**Location**: `specs/200-fullstacks/202-adr-021-integrated-workflow-context/`
|
||||
|
||||
---
|
||||
|
||||
## Clarifications
|
||||
|
||||
### Session 2026-04-12 (from ADR-021)
|
||||
|
||||
- **Q:** What are the file size and attachment count limits per workflow step? → **A:** No explicit limit (controlled by infrastructure only)
|
||||
- **Q:** What are the specific values and storage format for the "Priority" field in the Integrated Banner? → **A:** Enum "URGENT", "HIGH", "MEDIUM", "LOW" — 4-tier system with visual indicators
|
||||
- **Q:** How should the system handle virus/malware detection during step-specific file upload? → **A:** Block upload immediately, delete temp file, show error "File rejected" to user
|
||||
- **Q:** What is the cache TTL for Workflow History data to reduce join query overhead? → **A:** 1 hour — balanced cache duration for workflow history data
|
||||
- **Q:** Who is authorized to upload step-specific attachments during a workflow transition? → **A:** Only assigned handler can upload; superadmin and organization admin can upload on behalf (impersonation)
|
||||
|
||||
### Session 2026-04-19 (from ADR-021)
|
||||
|
||||
- **Q:** Which workflow states allow step-specific attachment upload? → **A:** Only Active-decision states (`PENDING_REVIEW`, `PENDING_APPROVAL`) — Terminal states (`APPROVED`, `REJECTED`, `CLOSED`) are not allowed
|
||||
- **Q:** What happens if Redis Redlock fails during transition? → **A:** Fail-closed — Retry 3 times (500ms exponential backoff) then throw HTTP 503 "Service temporarily unavailable" to preserve data integrity
|
||||
- **Q:** Which modules must support step-specific attachments in v1.8.6? → **A:** **All 4 modules** — RFA, Transmittal, Circulation, and Correspondence
|
||||
- **Q:** Performance target for Upload + Transition API? → **A:** P95 ≤ 5 seconds for files ≤10MB (ClamAV scan + Redlock + DB transaction included)
|
||||
|
||||
---
|
||||
|
||||
## User Scenarios & Testing
|
||||
|
||||
### User Story 1 - Integrated Banner (Priority: P1) 🎯 MVP
|
||||
|
||||
As a Reviewer/Approver, I want to see all critical document information (Doc No, Subject, Status, Priority) and available actions in a single header bar without scrolling or switching screens, so I can make approval decisions quickly with full context.
|
||||
|
||||
**Why this priority**: This is the core UX improvement of ADR-021. Without the Integrated Banner, users waste time scrolling and switching between document content and workflow controls.
|
||||
|
||||
**Independent Test**: The IntegratedBanner component can be rendered with mock RFA/Transmittal/Circulation/Correspondence data, verifying Priority badge colors, Status display, and Action button visibility. Buttons must be disabled when workflow is in terminal states.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** an RFA in `PENDING_APPROVAL` state with `URGENT` priority, **When** I open the detail page, **Then** I see the Doc No, Subject, red URGENT badge, status badge, and Approve/Reject/Return buttons in a sticky header
|
||||
2. **Given** a Transmittal in `APPROVED` state, **When** I view the detail page, **Then** action buttons are disabled and the status shows as completed
|
||||
3. **Given** a Correspondence in `PENDING_REVIEW` state with `MEDIUM` priority, **When** I open the detail page, **Then** the priority badge shows yellow and all workflow actions are available
|
||||
|
||||
---
|
||||
|
||||
### User Story 2 - Workflow Lifecycle Visualization (Priority: P1) 🎯 MVP
|
||||
|
||||
As a document participant, I want to see a vertical timeline showing all workflow steps with the current step highlighted, so I understand where the document is in the approval process and what steps remain.
|
||||
|
||||
**Why this priority**: Users currently lack visibility into workflow progress. The vertical timeline provides immediate orientation and reduces confusion about approval status.
|
||||
|
||||
**Independent Test**: The WorkflowLifecycle component can be rendered with mock workflow history data containing completed, current, and pending steps. Verify current step has Indigo (#6366f1) color with pulse animation.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** a 4-step RFA workflow where step 2 is current, **When** I view the Workflow tab, **Then** step 1 shows as completed (with actor/date), step 2 shows Indigo with pulse, steps 3-4 are muted/pending
|
||||
2. **Given** a Circulation workflow with comments on completed steps, **When** I view the timeline, **Then** each completed step shows the handler name, action date, and any comments
|
||||
3. **Given** a Transmittal in terminal state, **When** I view the timeline, **Then** the final step is marked complete and no pulse animation is shown
|
||||
|
||||
---
|
||||
|
||||
### User Story 3 - Step-specific Attachments (Priority: P2)
|
||||
|
||||
As a Reviewer, I want to upload supporting documents (images, PDFs) that are specifically linked to the current workflow step, so reviewers can see exactly which evidence was provided for each approval decision.
|
||||
|
||||
**Why this priority**: Currently all attachments are mixed at the document level. Step-specific attachments provide audit trail clarity and improve compliance tracking.
|
||||
|
||||
**Independent Test**: Upload files during a workflow transition in `PENDING_REVIEW` state, then verify via API that `attachments.workflow_history_id` is set correctly. Files uploaded in terminal states must be rejected with HTTP 409.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** an RFA in `PENDING_REVIEW` state, **When** I drag-drop 2 PDF files and click Approve, **Then** the files are linked to that workflow history step and visible in the timeline
|
||||
2. **Given** a Transmittal in `APPROVED` state, **When** I attempt to upload a file, **Then** the system rejects with "Upload not allowed in terminal state" error
|
||||
3. **Given** a Circulation in `PENDING_APPROVAL` state, **When** I upload a file and the approver rejects, **Then** the attachment remains linked to that rejection step for audit purposes
|
||||
|
||||
---
|
||||
|
||||
### User Story 4 - Internal File Preview (Priority: P2)
|
||||
|
||||
As a Reviewer, I want to click on any attachment and preview it in a modal without leaving the document page, so I can review evidence while maintaining workflow context.
|
||||
|
||||
**Why this priority**: Current workflow requires downloading or opening files in new tabs, breaking user flow and reducing productivity.
|
||||
|
||||
**Independent Test**: Click on PDF and Image attachments in the workflow timeline, verify FilePreviewModal opens with correct content type rendering (iframe for PDF, img for images).
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** a step with 3 attachments (2 PDFs, 1 PNG), **When** I click the first PDF, **Then** a modal opens showing the PDF in an inline viewer
|
||||
2. **Given** the preview modal is open, **When** I press Escape or click the X button, **Then** the modal closes and I remain on the document page
|
||||
3. **Given** a large PDF attachment, **When** I open the preview, **Then** the modal loads within 2 seconds with proper scroll controls
|
||||
|
||||
---
|
||||
|
||||
### User Story 5 - i18n Support (Priority: P3)
|
||||
|
||||
As a Thai or English speaking user, I want all workflow UI text to display in my selected language, so I can use the system effectively regardless of my preferred language.
|
||||
|
||||
**Why this priority**: LCBP3-DMS must support bilingual operations. All new UI components must follow i18n standards from project inception.
|
||||
|
||||
**Independent Test**: Switch language between TH and EN, verify all IntegratedBanner labels, WorkflowLifecycle step labels, and FilePreviewModal controls display correctly in each language.
|
||||
|
||||
**Acceptance Scenarios**:
|
||||
|
||||
1. **Given** my language is set to Thai, **When** I view an RFA detail page, **Then** all workflow action buttons show Thai text (อนุมัติ, ปฏิเสธ, ส่งกลับ)
|
||||
2. **Given** my language is set to English, **When** I view the Workflow tab, **Then** step labels show English text (Review, Approval, etc.)
|
||||
3. **Given** I switch language while viewing a document, **When** the page refreshes, **Then** all ADR-021 components show the newly selected language immediately
|
||||
|
||||
---
|
||||
|
||||
### Edge Cases
|
||||
|
||||
- What happens when a user attempts transition with concurrent upload from another user? (Redis Redlock handles serialization)
|
||||
- How does system handle ClamAV detecting malware during step upload? (Block immediately, delete temp file, show "File rejected")
|
||||
- What happens when Redis is unavailable during transition? (Retry 3x with exponential backoff, then HTTP 503 fail-closed)
|
||||
- How does system handle duplicate Idempotency-Key? (Return cached response, no re-processing)
|
||||
- What happens when attachment file is deleted from storage after linking? (Show "File unavailable" in UI, preserve metadata)
|
||||
- How does system handle unauthorized upload attempt? (CASL Guard blocks with 403 Forbidden)
|
||||
|
||||
---
|
||||
|
||||
## Requirements
|
||||
|
||||
### Functional Requirements
|
||||
|
||||
- **FR-001**: System MUST display Integrated Banner on RFA, Transmittal, Circulation, and Correspondence detail pages showing Doc No, Subject, Status, Priority, and available actions
|
||||
- **FR-002**: Priority badge MUST support 4 levels: URGENT (red), HIGH (orange), MEDIUM (yellow), LOW (green) with visual indicators
|
||||
- **FR-003**: Action buttons (Approve/Reject/Return) MUST be disabled when workflow is in terminal states (APPROVED, REJECTED, CLOSED)
|
||||
- **FR-004**: System MUST display Workflow Lifecycle as vertical timeline with current step highlighted in Indigo (#6366f1) with pulse animation
|
||||
- **FR-005**: System MUST support drag-drop file upload linked to workflow history steps, only allowed in PENDING_REVIEW or PENDING_APPROVAL states
|
||||
- **FR-006**: Upload attempts in terminal states MUST be rejected with HTTP 409 Conflict
|
||||
- **FR-007**: System MUST enforce 4-Level RBAC for workflow transitions: Superadmin > Org Admin > Assigned Handler > Read-only
|
||||
- **FR-008**: System MUST validate Idempotency-Key header on all transition requests to prevent duplicate processing
|
||||
- **FR-009**: File uploads MUST use Two-Phase pattern (Temp → ClamAV scan → Permanent)
|
||||
- **FR-010**: System MUST provide internal File Preview Modal for PDF and Image attachments without page navigation
|
||||
- **FR-011**: All UI text MUST use i18n keys supporting Thai and English languages
|
||||
- **FR-012**: Workflow transitions MUST use optimistic locking (version_no) to prevent race conditions
|
||||
- **FR-013**: Redis Redlock MUST serialize concurrent transitions on the same workflow instance
|
||||
- **FR-014**: Attachment linking to workflow history MUST occur in same database transaction as state transition
|
||||
|
||||
### Key Entities
|
||||
|
||||
- **WorkflowInstance**: Represents a running workflow tied to a document (RFA/Transmittal/Circulation/Correspondence). Tracks current state, definition reference, and context data.
|
||||
- **WorkflowHistory**: Audit record of each workflow transition. Contains from_state, to_state, action, actor, timestamp, and (ADR-021) linked attachments.
|
||||
- **Attachment** (Extended): File entity with new `workflow_history_id` FK linking to specific workflow step. NULL value indicates main document attachment (pre-ADR-021 behavior).
|
||||
- **IntegratedBanner**: UI component combining document metadata, workflow status, priority indicator, and action controls.
|
||||
- **WorkflowLifecycle**: UI component displaying vertical timeline of all workflow steps with visual highlighting.
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
### Measurable Outcomes
|
||||
|
||||
- **SC-001**: Users can approve/reject documents 40% faster due to Integrated Banner reducing screen navigation
|
||||
- **SC-002**: 100% of workflow attachments are traceable to specific approval steps via `workflow_history_id` linkage
|
||||
- **SC-003**: File preview modal loads and displays PDF/Image files within 2 seconds (P95)
|
||||
- **SC-004**: Zero duplicate workflow transitions occur due to Idempotency-Key enforcement (verified via audit logs)
|
||||
- **SC-005**: System handles 50 concurrent workflow transitions per minute without data inconsistency (optimistic lock + Redlock)
|
||||
- **SC-006**: 100% of UI text in ADR-021 components is translatable (verified by language switch testing)
|
||||
- **SC-007**: Users can complete workflow transition with file upload within 5 seconds for files ≤10MB (P95, including ClamAV scan)
|
||||
Reference in New Issue
Block a user