commit

plans/audit-employee-training-history.md

@@ -0,0 +1,493 @@
+# Employee Training History Audit (Read Only)
+
+## Role
+
+You are a Senior Full Stack Engineer, Software Architect, QA Engineer, UX/UI Reviewer, Security Reviewer, and Product Analyst.
+
+Your responsibility is to perform a comprehensive READ-ONLY audit of the Employee Training History flow.
+
+Do NOT modify any source code.
+
+Do NOT generate implementation code.
+
+Do NOT create pull requests.
+
+Only inspect the project and produce documentation.
+
+---
+
+# Before Starting
+
+Read and understand the existing project before reviewing.
+
+Review these documents first (follow project priority):
+
+1. AGENTS.md
+2. docs/AI_DEVELOPMENT_GUIDE.md
+3. docs/PROJECT_ARCHITECTURE.md
+
+Then inspect the existing implementation and reuse patterns already used throughout the project.
+
+---
+
+# Scope
+
+Review everything related to Employee Training History.
+
+Including but not limited to:
+
+- Route
+- Page
+- Listing
+- Detail / edit flow
+- Data table
+- Filters
+- Sorting
+- Search
+- Empty state
+- Loading UI
+- Error UI
+- Responsive design
+- Action menu
+- Create / update / delete affordances
+- Review status visibility
+- Certificate preview and download visibility
+- API
+- Queries
+- Mutations
+- Validation
+- Server Components
+- Client Components
+- Route handlers
+- Access control
+
+---
+
+# Functional Review
+
+Verify every feature.
+
+Examples
+
+## Training History Listing
+
+- List own training records
+- Search by employee/course text
+- Filter by status
+- Filter by type
+- Sort by date and visible columns
+- Pagination
+- Empty state
+
+Verify
+
+- Is the displayed data correct?
+- Does sorting reflect the visible field?
+- Does status/type filtering work correctly?
+- Are old records separated correctly by year if required by business rules?
+
+---
+
+## Record Detail / Edit
+
+Review
+
+- Open detail
+- Open edit
+- Read-only behavior
+- Pending record update/delete behavior
+- Certificate management visibility
+
+Verify
+
+- Employees can edit only what business rules allow
+- HRD / admin actions are separated correctly
+- UI affordances match server-side permission outcomes
+
+---
+
+## Submission Flow
+
+Verify
+
+- Create new training history
+- Validation messages
+- Upload certificate after create
+- Redirect and refresh behavior
+- Cache invalidation
+
+---
+
+# Business Rule Review
+
+Verify the training history flow follows project requirements.
+
+Examples
+
+- Employee only sees their own training history
+- HRD / admin can see organization-scoped records
+- Pending / approved / rejected / needs revision statuses are shown correctly
+- Training duration values are displayed correctly
+- Certificate preview/download is scoped correctly
+- Calendar year behavior is handled correctly
+
+Document any inconsistencies.
+
+---
+
+# Role Review
+
+Review every permission.
+
+Employee
+
+Verify the employee can
+
+- View own training history
+- View own record detail
+- Create own training history
+- Edit only records that should remain editable
+- Delete only records that should remain deletable
+- View own certificates
+
+Verify the employee cannot
+
+- View other employees' records
+- Edit approved records
+- Review records
+- Access HRD-only review flows
+
+Check
+
+- UI permission
+- API permission
+- Route protection
+- Hidden navigation
+- Direct URL access
+
+Report every permission issue.
+
+---
+
+# UI Review
+
+Review
+
+- Layout consistency
+- Table readability
+- Card spacing
+- Typography
+- Status badges
+- Action menu labels
+- Empty state clarity
+- Mobile layout
+- Tablet layout
+- Desktop layout
+
+Identify inconsistent UI.
+
+---
+
+# UX Review
+
+Evaluate
+
+- Information hierarchy
+- Discoverability of filters
+- Readability of record statuses
+- Feedback after create/update/delete
+- Clarity of detail vs edit flow
+- Error message quality
+- Empty state quality
+
+Suggest improvements without implementing them.
+
+---
+
+# Accessibility Review
+
+Inspect
+
+- Keyboard navigation
+- Focus indicators
+- Color contrast
+- Screen reader labels
+- Button accessibility
+- Table accessibility
+
+Report accessibility issues.
+
+---
+
+# Code Review
+
+Inspect
+
+## Architecture
+
+- Folder structure
+- Feature separation
+- Component organization
+
+## React
+
+- Hooks usage
+- State management
+- Client vs Server Components
+
+## TypeScript
+
+- Strong typing
+- Reusable interfaces
+- Nullable handling
+
+## Code Quality
+
+- Duplicate logic
+- Dead code
+- Naming consistency
+- File organization
+
+Do NOT change anything.
+
+---
+
+# API Review
+
+Review
+
+- Query structure
+- Response types
+- Error handling
+- Retry behavior
+- Cache
+- Query invalidation
+- Contract consistency between page, service, and route handler
+
+---
+
+# Performance Review
+
+Inspect
+
+- Query optimization
+- Loading strategy
+- Suspense usage
+- Large table rendering
+- Unnecessary payload in listing responses
+
+---
+
+# Security Review
+
+Review
+
+- Authentication
+- Authorization
+- Route Guard
+- Role Guard
+- Server validation
+- API validation
+- Sensitive information exposure
+
+---
+
+# Data Validation Review
+
+Inspect
+
+- Missing values
+- Incorrect defaults
+- Null handling
+- Incorrect formatting
+- Date formatting
+- Duration calculations
+- Status handling
+
+---
+
+# Consistency Review
+
+Compare the training history flow with the rest of the project.
+
+Verify
+
+- Shared DataTable stack
+- Shared page layout
+- Shared form stack
+- Shared dialogs
+- Shared badges
+- Shared loading UI
+- Shared spacing and typography
+
+Document inconsistencies.
+
+---
+
+# Edge Case Review
+
+Check
+
+- New employee with no history
+- Employee without linked profile
+- Pending record without linked `user_id`
+- No certificate
+- Unsupported certificate type
+- Approved record
+- Rejected record
+- Needs revision record
+- API failure
+- Slow network
+
+---
+
+# Deliverables
+
+Create
+
+docs/review/employee-training-history-audit.md
+
+---
+
+# Report Structure
+
+# Employee Training History Audit Report
+
+## Summary
+
+Overall Status
+
+- Excellent
+- Good
+- Needs Improvement
+- Critical
+
+Brief summary of findings.
+
+---
+
+## Architecture Review
+
+---
+
+## Functional Review
+
+| Feature | Status | Notes |
+
+---
+
+## Business Rule Review
+
+---
+
+## Role & Permission Review
+
+---
+
+## UI Review
+
+---
+
+## UX Review
+
+---
+
+## Accessibility Review
+
+---
+
+## Code Quality Review
+
+---
+
+## API Review
+
+---
+
+## Performance Review
+
+---
+
+## Security Review
+
+---
+
+## Consistency Review
+
+---
+
+## Edge Case Review
+
+---
+
+## Problems Found
+
+Categorize issues into
+
+### Critical
+
+### High
+
+### Medium
+
+### Low
+
+Each issue should include
+
+- Description
+- File
+- Component
+- Severity
+- Impact
+- Recommendation
+
+Do NOT fix the issue.
+
+---
+
+## Missing Features
+
+List missing functionality compared to project requirements.
+
+---
+
+## Improvement Opportunities
+
+Suggest improvements only.
+
+Do NOT implement them.
+
+---
+
+## Final Assessment
+
+Architecture: /10
+
+Functionality: /10
+
+UI: /10
+
+UX: /10
+
+Accessibility: /10
+
+Performance: /10
+
+Security: /10
+
+Maintainability: /10
+
+Overall Score: /10
+
+---
+
+# Important Rules
+
+- READ ONLY
+- No code changes
+- No refactoring
+- No formatting changes
+- No new files except the audit report
+- Do not modify existing documentation
+- Do not implement recommendations
+- Only inspect, analyze, and document findings with evidence where possible.