101 lines
3.4 KiB
Markdown
101 lines
3.4 KiB
Markdown
# ADR-001: User-Employee Domain Boundary
|
|
|
|
## Status
|
|
|
|
Accepted
|
|
|
|
## Context
|
|
|
|
The application already uses `users` for authentication and permissions, while training, reporting, and HR master data still rely on `employees`. The repo also has two linkage seams:
|
|
|
|
- `users.employeeId`
|
|
- `user_employee_maps`
|
|
|
|
Phase 1 remediation needs a stable, documented boundary before more invasive schema work begins.
|
|
|
|
## Problem
|
|
|
|
Without an explicit boundary, new work can:
|
|
|
|
- create dual source-of-truth behavior
|
|
- put audit actors on `employees`
|
|
- put training ownership on `users`
|
|
- expand both linking strategies at the same time
|
|
|
|
## Definitions
|
|
|
|
- `users`: authenticated system identity
|
|
- `employees`: HR-owned worker profile
|
|
|
|
## Decision
|
|
|
|
Adopt this boundary for the current remediation phase:
|
|
|
|
- `users` own authentication, login identity, session context, permissions, organization membership, notifications, and audit actor fields.
|
|
- `employees` own employee code, employee profile, department/position assignment, training ownership, training targets, matrix applicability, and compliance reporting subject.
|
|
|
|
## Data Ownership
|
|
|
|
| Data | Owner |
|
|
|---|---|
|
|
| login email, username, password, account status | `users` |
|
|
| active organization, membership, permissions | `users` + membership tables |
|
|
| audit actor, created by, approved by, published by | `users` |
|
|
| employee code, employee name, company, department, position, employment status | `employees` |
|
|
| training owner, target, matrix applicability, compliance subject | `employees` |
|
|
|
|
## Relationship Cardinality
|
|
|
|
Canonical relationship during remediation:
|
|
|
|
- `User 0..1 <-> 0..1 Employee`
|
|
|
|
This supports:
|
|
|
|
- super admins or service identities without employee records
|
|
- employees that exist before a user account is provisioned
|
|
|
|
## Linking Strategy
|
|
|
|
Short term:
|
|
|
|
- preserve both current compatibility seams
|
|
- treat `user_employee_maps` as the explicit linkage record
|
|
- treat `users.employeeId` as a compatibility pointer that must stay synchronized
|
|
|
|
## Mapping Strategy
|
|
|
|
- New query logic should prefer explicit linkage semantics and document fallback behavior.
|
|
- New features must not introduce additional user-employee link columns or tables.
|
|
|
|
## Non-Employee User Handling
|
|
|
|
Allowed. A user may authenticate and operate without an employee profile when their work is administrative or service-oriented.
|
|
|
|
## Employee Without User Handling
|
|
|
|
Allowed. Employee master data may exist before a user account is provisioned.
|
|
|
|
## Migration Strategy
|
|
|
|
1. Inventory all current user/employee joins and ownership assumptions.
|
|
2. Standardize docs and runtime guards around the split boundary.
|
|
3. Add automated checks for route and guard drift.
|
|
4. Reconcile the dual-linking seam in a later schema-focused slice with backfill and verification.
|
|
|
|
## Compatibility Strategy
|
|
|
|
- Keep `users.employeeId` readable during the transition.
|
|
- Keep `user_employee_maps` operational until reconciliation is complete.
|
|
- Do not expand either seam without a follow-up ADR.
|
|
|
|
## Consequences
|
|
|
|
- Documentation now matches the current transitional implementation more honestly.
|
|
- Training and reporting code may continue using `employees` as owner scope for now.
|
|
- Future migration work must explicitly retire one linking seam instead of letting both continue to grow.
|
|
|
|
## Rollback Strategy
|
|
|
|
Rollback is documentation-only for this ADR. Runtime rollback is not required unless a later schema migration changes persisted data.
|