superport_v2/doc/ApprovalFlow_System_Integration_and_ChangePlan.md

Approval Step Creation and Management System – Full Revision Plan

---

🎯 Objective

Add an Approval Step Configuration feature to the Inbound, Outbound, and Rental Registration screens, and expand the existing “Approval Management” and “Approval History” menus into a unified, fully functional approval workflow.

Both backend and frontend modifications are permitted as needed, but all changes must be designed and deployed carefully to avoid any side effects and ensure system stability.

---

1. Core Principles

• Existing data structures, responses, and UI may be changed if necessary. However, every change must be controlled and validated to ensure compatibility and prevent unintended side effects.
• Prefer append-only design, but allow structural refactoring when the current design causes inefficiency or redundancy.
• Every change must include test coverage, rollback strategy, and observability before release.
• Draft approvals must persist across browser sessions so submitters can resume from Approval Management, and pending transactions remain hidden from the primary lists until final approval.

---

2. Approval Step Logic and Workflow

1. Approval Flow

   • The submitter is automatically set as the logged-in user (not editable).
   • Intermediate approvers must be other users (the submitter cannot approve their own request).
   • Up to 98 approval steps can be added dynamically.
   • Final approver is mandatory and always visible.
   • Admins (highest privilege users) can designate themselves as the final approver.

2. Status Transitions

   • SUBMIT → IN_PROGRESS → APPROVED / REJECTED / RECALLED
   • Rejection immediately terminates the process.
   • The submitter can recall a request only if the first approver has not acted yet.
   • Recalled requests can be edited and resubmitted (RESUBMIT).
   • All state transitions must be logged in an Audit Table with timestamp, actor, and action.

3. User Roles & Permissions

   • Each approver can approve/reject only their assigned step.
   • Earlier steps are visible for reference but cannot be modified.
   • Notes or memos visibility follows permission tiers (own, higher-level, or approvers only).
   • Submitters and approvers who have already completed their step retain read access; future-step approvers (including the final approver before their turn) cannot see the document in lists or detail views and receive a 403 when attempting access.
   • terabits (Super Admin) can view all approvals and logs but cannot modify them.

---

3. Frontend Revision Plan

1. UI Additions

   • Add an Approval Step Configuration section (or modal) to the existing Inbound / Outbound / Rental registration forms.

   • Default fields:

     • Submitter (auto-filled, read-only)
     • Final Approver (search/dropdown input)

   • Intermediate approvers added dynamically via “+ Add Approver” button (max 98).

   • Each row displays: Order, Approver, Role, Delete(X).

   • Include Template Selector to load previously saved approval configurations.

   • On save, send both registration data and approval configuration together.

   • Draft submissions must be saved server-side and restorable from the Approval Management menu even after the browser window is closed.

   • Persist drafts through /approval-drafts (GET /approval-drafts?requester_id=<user>, POST /approval-drafts, POST /approval-drafts/{id}/restore) so the client can resume unfinished configurations across devices.

   • The draft payload mirrors the final submission contract (title, summary, note, transaction_id, optional template_id, steps[]) and accepts an optional session_key that lets browsers overwrite the current draft without creating duplicates.

   • Drafts expire automatically; pass include_expired=true when the recovery UI needs to surface recently expired drafts for troubleshooting.

2. Approval Management Menu

   • Show user-created approval templates with step summaries (e.g., “1: Team Lead → 2: Director → Final: Executive”).
   • Allow template creation, modification, and deletion.
   • During submission, a user can choose a template to auto-populate steps.
   • Provide Draft/Pending filters so submitters can reopen saved approvals while restricting visibility for future-step approvers.

3. Approval History Menu

   • Display list of submitted approvals with current state, responsible approver, and timestamp.
   • In detail view, show all steps with status, timestamp, and memo timeline.
   • If eligible, show Recall button; after recall, allow Resubmit.
   • terabits (Super Admin) can view all approvals globally (read-only).
   • Enforce visibility so only the submitter and already-acting approvers can open pending documents; final approvers gain access only when their step is activated.

4. Validation & Integration

   • Validation must match the current frontend logic and framework conventions.

   • Reuse existing UI components (dropdowns, toasts, validation rules).

   • Enforce constraints:

     • No duplicate approvers
     • Submitter cannot self-approve
     • Final approver is mandatory
     • Default inventory lists surface only fully approved transactions; drafts and submitted items live in dedicated "Pending Approvals" views.

---

4. Backend Revision Plan

1. Data Model

   • Existing schemas and API responses can be modified when justified, but every change must maintain backward compatibility and prevent side effects.

   • Key entities (if not already present):

     • approval_requests: Approval request header
     • approval_steps: Per-step status tracking
     • approval_templates: Saved approval flow templates
     • approval_template_steps: Template step definitions
     • approval_audits: Activity and state transition logs

2. Core Logic

   • Enforce strict sequential flow between steps.
   • Each approval/rejection triggers a state change and audit log entry.
   • Recall allowed only if step 1 approver has not acted.
   • Resubmission allowed only from recalled/rejected states.
   • All transitions must be atomic and transaction-safe.

3. API Design

   • Existing endpoints may be extended with new parameters or response fields if needed.

   • Main APIs:

     • POST /approval/submit
     • POST /approval/approve
     • POST /approval/reject
     • POST /approval/recall
     • POST /approval/resubmit
     • GET /approval/history
     • GET /approval/templates

   • Responses should remain backward-compatible while exposing additional fields (e.g., approvalStatus, currentStep).

4. Auditing and Monitoring

   • Log all actions (create, submit, approve, reject, recall, resubmit) in approval_audits.
   • Each entry records user ID, timestamp, action type, and metadata.
   • Emit state-change events (e.g., Kafka or WebSocket) for real-time tracking.

---

5. Change Control and Stability

1. Side-Effect Prevention

   • Schema updates must include pre-migration validation, backup, and rollback scripts.
   • Deploy via staging → production, with feature toggles for controlled rollout.
   • Critical operations (approval/rejection) must be idempotent and transaction-safe.

2. Consistency and Concurrency

   • Prevent duplicate approvers or skipped steps.
   • Apply optimistic locking/version control for step updates.
   • Centralize all approval state changes in a single service (e.g., ApprovalService).

3. Testing Criteria

   • Existing modules (inbound/outbound/rental) must work with or without approval data.
   • Verify all state transitions: submit → approve → final approve, reject, recall, resubmit.
   • terabits can view all but not modify.
   • Audit log integrity check for every state transition.

---

6. Operations and Collaboration

• Frontend and Backend may both be modified if agreed upon during design review.

  • All changes must be documented and version-controlled.
  • Updated response specs must be reflected in OpenAPI/Swagger documentation.

• Feature Toggles must allow enabling/disabling approval features per environment.

• Monitoring and Alerts:

  • Track approval error rates, delays, and recall/resubmission frequency.

---

7. Deliverables

• Frontend:

  • ApprovalStepUI Component
  • ApprovalTemplateManager, ApprovalHistoryViewer Modules

• Backend:

  • ApprovalController, ApprovalService, ApprovalAuditService
  • Migration + Rollback Scripts
  • Updated OpenAPI Documentation

• Task Plans:

  • Backend 세부 작업 계획 — ../superport_api_v2/doc/approval_flow_backend_task_plan.md
  • Frontend 세부 작업 계획 — doc/approval_flow_frontend_task_plan.md

---

8. Final Directive

• Backend and frontend may be modified freely when necessary, but every modification must be safely designed to prevent side effects.
• The approval system must support real workflow tracking — including role-based visibility, note sharing, audit logging, recall/resubmission, and seamless integration with existing registration processes.
• The guiding principles are: Controlled Change, Traceability, and Operational Safety.