Feature Specification: Approval Workflow

1. Overview & Vision

The Approval Workflow ensures that documents meet organizational quality and compliance standards before being finalized. It provides a formal cycle of submission, review, and publication, transforming a raw draft into a "Published" source of truth.

2. Personas & Stakeholders

Persona	Goal
Author	Submit work for review and address feedback.
Reviewer	Audit content, request changes, and provide final approval.
Admin	Monitor the publication pipeline and manage stuck reviews.

3. User Stories

• As an author, I want to submit my draft to the HR Manager so it can be officially published.
• As a reviewer, I want to request changes with a specific comment so the author knows what to fix.
• As a user, I want to be notified when my document has been approved or rejected.

4. Functional Requirements (FR)

• REQ-AP-001: 3-stage document status machine: draft, in_review, published.
• REQ-AP-002: Formal "Submit for Review" action with reviewer selection.
• REQ-AP-003: Review decisions: Approve, Request Changes.
• REQ-AP-004: Commenting system for review feedback.

5. Non-Functional Requirements (NFR)

• Consistency: Status transitions MUST be atomic and logged in the audit trail.
• Security: Documents MUST be locked for editing while in the in_review state.

6. Business Logic & Rules

• Editor Lock: Authors cannot edit a document while it is being reviewed by someone else.
• Auto-versioning: Requesting changes automatically returns the document to draft state.
• Finality: Once published, a document is read-only (until a new draft version is created).

7. User Interface (UI/UX)

• Workflow Toolbar: Prominent status badge and primary action button (e.g., "Submit Review").
• Review Panel: Side-drawer for reviewers to enter comments and toggle their decision.
• In-app Notifications: Toast and Bell notifications for workflow events.

8. Information Architecture

• Workflow status visible in all document lists and search results.

9. Data Model & Persistence

• Table: approval_requests.
• Table: documents (status column).

10. API & Service Layer

• POST /documents/:id/submit-review
• POST /approval-requests/:id/decide

11. Integration Patterns

• Notification Service: Triggers Shell-wide notifications upon status changes.
• AI Module: (Future) Auto-summarize changes for the reviewer.

12. Security & Permissions

• RBAC: documents:publish required to approve; documents:write to submit.
• Ownership: Authors can only submit their own work (unless Admin).

13. Error Handling & Resilience

• Invalid State: Prevent approving a document that has since been modified or deleted.
• Orphaned Review: Admins can re-assign reviewers if the original reviewer is unavailable.

14. Performance & Scalability

• Optimized status checking to ensure real-time editor locking.

15. Globalization & i18n

• Localized workflow status names (e.g., "Đang chờ duyệt").

16. Accessibility (a11y)

• Accessible workflow buttons with clear state labels.

17. Observability & Analytics

• Tracking of "Time in Review" to identify organizational bottlenecks.
• Analytics on "First-time Approval" rates.

18. Testing & Quality

• State machine unit tests covering all transition paths.
• Integration tests for permission-based locking logic.

19. Constraints & Assumptions

• Assumes a linear 1-step approval for v1 (Multi-stage is planned for v2).

20. Future Enhancements

• Multi-step approval chains (e.g., Peer -> Manager -> Legal).
• Mandatory checklists for reviewers before they can click "Approve".