Feature Specification: Employee Profile Management

1. Overview & Vision

The Employee Profile is the central source of truth for all employment-related data. It provides visibility into a person's role, reporting line, and employment status, serving as the foundational building block for all other HRM features like Leave and Org Charts.

2. Personas & Stakeholders

Persona	Goal
Employee	View own data, update personal contact info, and track employment history.
Manager	View team skills, job titles, and direct reporting lines.
HR Admin	Full lifecycle management of employee data (hiring to offboarding).

3. User Stories

• As an employee, I want to update my emergency contact so HR knows who to call in a crisis.
• As an HR Admin, I want to change an employee's department when they are promoted.
• As a manager, I want to see the start date of my direct reports to plan work anniversaries.

4. Functional Requirements (FR)

• REQ-EP-001: Profile must include: Name, Job Title, Department, Manager, Start Date, Status.
• REQ-EP-002: Organization-wide searchable employee directory (text search + advanced filters).
• REQ-EP-003: Self-service editing for personal contact fields (Phone, Emergency).
• REQ-EP-004: Employee lifecycle state machine: Candidate → Active → Probation → Terminated with guarded transitions.
• REQ-EP-005: Sensitive field encryption at rest — SSN, IBAN, bank account stored with AES-256-GCM; masked on read for non-HR roles.
• REQ-EP-006: Permanent Employee UUID generated on promotion from Candidate to Active; immutable legal identifier.
• REQ-EP-007: Legal Document Vault — contract and ID uploads with seal guard (sealed docs cannot be deleted).
• REQ-EP-008: CV management and versioning — multiple CV versions with upload date and active flag.
• REQ-EP-009: AI-assisted CV parsing — upload PDF/DOCX → extract fields → human confirms → create candidate.
• REQ-EP-010: Natural language search for employees (semantic query support).
• REQ-EP-011: Quick View popup — profile summary without navigating away from directory.
• REQ-EP-012: Export employee profiles to PDF.
• REQ-EP-013: Automated Skill Matrix updates.
• REQ-EP-014: Salary and title change audit ledger (time-travel record — view profile as of any date).
• REQ-EP-015: Shell User Provisioner — outbound sync to Shell on employee create/terminate.
• REQ-EP-016: Shell Role & Attribute Mapper — sync HRM job title / department to Shell user attributes.

5. Non-Functional Requirements (NFR)

• Performance: Profile load time < 300ms.
• Privacy: Personal fields MUST be hidden from non-HR/non-managers.

6. Business Logic & Rules

• Reporting Line: Every employee (except the CEO) MUST have exactly one managerId.
• Lifecycle Guards: Status transitions are strictly gated — e.g., a Candidate cannot skip to Terminated; Probation employees cannot submit leave.
• Data Integrity: Employee ID in HRM must map to a valid user_id in the Shell.
• Encryption: Sensitive fields (SSN, IBAN, salary) are encrypted before persistence; decrypted only for HR Admin role; masked (***-1234) for others.
• Four-Eyes Salary: Salary changes require a second HR approver before taking effect.
• Seal Guard: Once a legal document is sealed, the delete endpoint returns 403 Forbidden.
• Shell Sync: On EMPLOYEE_ACTIVATED event, Shell Provisioner creates/updates the Shell user account; on termination it triggers the kill-switch (revokes all tokens).

7. User Interface (UI/UX)

• Header: Avatar, Name, Job Title, and Department badge.
• Tabs: Personal Info, Employment, Leave Balance, Onboarding Status.
• Directory: Grid/List toggle with multi-attribute filtering.

8. Information Architecture

• Primary module landing page.
• Direct links from the Shell top-bar "My Profile".

9. Data Model & Persistence

• Table: employees (Main profile).
• Table: departments (Metadata).
• Storage: Profile photos stored in MinIO/S3 via the Drive driver.

10. API & Service Layer

• GET /employees/:id
• PUT /employees/:id
• EmployeeService handles cross-table coordination.

11. Integration Patterns

• Shell Sync: Ingests new users from Shell when they first log in.
• Drive: Uses Drive's storage engine for file attachments (CVs, Contracts).

12. Security & Permissions

• RBAC: employees:read for directory; employees:write for HR Admin.
• Isolation: Users can only see profiles within their own organization.

13. Error Handling & Resilience

• Graceful handling of "Missing Manager" errors.
• Validation for circular reporting lines (A reports to B, B reports to A).

14. Performance & Scalability

• Profile data is cached at the API level.
• Search uses PostgreSQL ILIKE indexing for fast directory lookups.

15. Globalization & i18n

• Support for Vietnamese and International name formats.
• Localized job titles and department names.

16. Accessibility (a11y)

• Accessible directory tables with proper ARIA scopes.
• High-contrast status badges (Active = Green, On Leave = Blue).

17. Observability & Analytics

• Tracking of "Turnover Rate" based on status transitions.
• Audit logging of all profile modifications.

18. Testing & Quality

• Integration tests for status transition logic.
• UI tests for the Org Chart tree rendering.

19. Constraints & Assumptions

• Assumes every employee has a valid Shell user account.

20. Future Enhancements

• Automated birthday and work anniversary notifications.
• Matrix management (dotted-line reporting).
• Biometric identity verification for legal document signing.