gabogg
41fb0d0d75
- Add English/Spanish translation system for UI pages - Add bilingual AI audit notes using translation LLM chains in n8n - Support zero-trust Docker routing to dev stack via internal hostnames - Quiet down Next.js database query and middleware logging in test runs
10 KiB
10 KiB
Requirements and User Stories
Variable Remuneration, Compensation, and Commissions System - Hoteles Estelar
General Objective
Implement a centralized platform for the administration, calculation, validation, and monitoring of variable remuneration, compensations, and commercial incentives, replacing the current manual management in Excel sheets and enabling automated settlement, approval, and traceability processes.
Functional Scope
The system consists of 7 main features divided into 14 User Stories (US).
FEATURE 1 — Compensation Plan Administration
US-COM-001 — Create Compensation Plan
- Role: System Administrator
- Goal: Create compensation and commission plans
- Benefit: Define variable remuneration rules.
- Description:
The system must allow configuring plans associated with:
- Hotels
- Regions
- Commercial teams
- Roles
- Campaigns
- Seasons
- Business units
- Acceptance Criteria:
- Scenario 1 (Successful creation): Given that the administrator enters the compensation module, when they select "Create plan" and fill out the required fields, then the system must store the plan correctly.
- Scenario 2 (Mandatory validation): Given that mandatory fields exist, when the user tries to save without completing them, then the system must show validation messages.
- Suggested Fields:
- Plan Name, Code, Validity/Period, Compensation Type, Area, Role, Hotel, Region, Calculation Type, Formula, Goal/Quota, Percentage, Max Caps, Status.
- Operations (Sub-features):
- Create plan, Edit plan, Duplicate plan, Versioning, Inactivate plan.
US-COM-002 — Configure Calculation Rules
- Role: Administrator
- Goal: Parametrize business rules
- Benefit: Automate commission and incentive settlements.
- Description:
The system must support:
- Percentage calculations
- Tiers/Scales and Ranges
- Goal achievements
- Fixed and variable commissions
- Special bonuses
- Acceptance Criteria:
- Scenario 1 (Formula configuration): Given that a compensation plan exists, when the user defines the rules, then the system must store the configuration.
- Scenario 2 (Cap validation): Given that a maximum cap is defined, when the calculation exceeds the limit, then the system must apply the configured cap.
- Operations (Sub-features):
- Dynamic formulas, Commission scales, Max caps, Conditional rules, Special bonuses.
US-COM-003 — Configure Commercial Goals
- Role: Administrator
- Goal: Configure commercial goals/quotas
- Benefit: Measure achievement for variable calculations.
- Acceptance Criteria:
- Scenario 1 (Configure goal): Given that a collaborator or team exists, when the user assigns goals, then the system must store them by period.
- Operations (Sub-features):
- Monthly goals, quarterly goals, per-hotel goals, per-team goals, individual goals.
FEATURE 2 — Data Load & Integration
US-COM-004 — Import Commercial Results from Excel
- Role: User
- Goal: Import commercial results from Excel
- Benefit: Avoid manual data-entry processes.
- Acceptance Criteria:
- Scenario 1 (Valid import): Given that the user uploads a valid file, when the system processes the information, then it must update results automatically.
- Scenario 2 (Invalid file): Given that the file contains errors, when the system processes the file, then it must display validation inconsistencies.
- Operations (Sub-features):
- XLSX/CSV import, Column validation, Upload templates.
US-COM-005 — Automatic Integration with External Systems
- Role: Administrator
- Goal: Automatically integrate sales information
- Benefit: Automate commission calculation.
- Description:
The system must integrate with:
- ERP, Hotel PMS, CRM, Financial systems, Booking platforms, Revenue Management.
- Acceptance Criteria:
- Scenario 1 (Successful integration): Given that an integration is configured, when the automatic process runs, then the system must update the information automatically.
- Scenario 2 (Integration error): Given that a failure occurs, when the process does not finish successfully, then the system must log the errors and notify the administrator.
- Operations (Sub-features):
- API integrations, Automated Cron Jobs, Logs, Automatic retries.
FEATURE 3 — Automated Settlement
US-COM-006 — Calculate Commissions Automatically
- Role: System
- Goal: Automatically calculate commissions
- Benefit: Reduce manual errors.
- Acceptance Criteria:
- Scenario 1 (Individual calculation): Given that registered sales exist, when the system executes the settlement, then it must calculate automatically: Individual commission, Goal achievement percentage, Bonus, and Incentive.
- Scenario 2 (Group calculation): Given that group rules exist, when the system processes the calculation, then it must generate the group commission automatically.
- Operations (Sub-features):
- Calculation engine, Automatic settlement, Bulk calculations, Payment simulation.
US-COM-007 — Simulate Settlement Before Approval
- Role: Commercial Leader
- Goal: Simulate settlements
- Benefit: Validate results before approving payments.
- Acceptance Criteria:
- Scenario 1 (Simulation): Given that a settlement period exists, when the user runs the simulation, then the system must show preliminary results.
- Operations (Sub-features):
- Simulation, Pre-validation, Comparisons, Adjustments before closing.
FEATURE 4 — Approvals & Validation Flow
US-COM-008 — Approve Settlements
- Role: Commercial Leader
- Goal: Approve or reject settlements
- Benefit: Validate variable payments.
- Acceptance Criteria:
- Scenario 1 (Approve): Given that a settlement has been generated, when the leader reviews the information, then they can approve it.
- Scenario 2 (Reject): Given that inconsistencies exist, when the leader rejects the settlement, then they must record mandatory observations/comments.
- Operations (Sub-features):
- Approval workflow, Observations/Comments, Rejections, Settlement resubmission.
US-COM-009 — Notify Approval or Rejection
- Role: System
- Goal: Notify approval or rejection results
- Benefit: Inform responsible stakeholders.
- Acceptance Criteria:
- Scenario 1 (Approval notification): Given that the settlement was approved, when the process finishes, then the system must send an automatic notification.
- Operations (Sub-features):
- Auto-emails, Push notifications, Notification logs.
FEATURE 5 — Inquiry & Traceability
US-COM-010 — Consult Commission History
- Role: Collaborator
- Goal: Consult variable payment history
- Benefit: Validate settlements performed.
- Acceptance Criteria:
- Scenario 1 (Historical query): Given that settled periods exist, when the user queries the information, then the system must display: Period, Goal, Result, Commission, Status.
- Operations (Sub-features):
- Payment history, Filters, PDF download, Period queries.
US-COM-011 — Record Traceability and Auditing
- Role: System
- Goal: Record changes and approvals
- Benefit: Maintain historical audit trails.
- Acceptance Criteria:
- Scenario 1 (Automatic recording): Given that a user modifies rules or settlements, when they save changes, then the system must record: User, Date, Time, Action, Previous value, New value.
- Operations (Sub-features):
- Audit trails, Logs, History, Logbook.
FEATURE 6 — Reports & Analytics
US-COM-012 — Visualize Compensation Dashboard
- Role: Commercial Director
- Goal: View compensation dashboards
- Benefit: Analyze performance and variable costs.
- Acceptance Criteria:
- Scenario 1 (Executive Dashboard): Given that settlements have been generated, when the user views the dashboard, then the system must display: Paid commissions, Goal achievement, Sales ranking, Variable costs, Trends.
- Operations (Sub-features):
- Dashboards, Financial KPIs, Trends, Comparisons.
US-COM-013 — Export Financial Reports
- Role: Financial User
- Goal: Export reports
- Benefit: Perform budget and operational analysis.
- Acceptance Criteria:
- Scenario 1 (Export): Given that settled results exist, when the user selects export, then the system must generate: PDF, Excel, Consolidated reports by hotel, Consolidated reports by region.
- Operations (Sub-features):
- PDF export, Excel export, Consolidated reports, Automated report scheduling.
FEATURE 7 — Security & Permissions
US-COM-014 — Manage Roles and Permissions
- Role: Administrator
- Goal: Manage roles and accesses
- Benefit: Protect sensitive financial information.
- Suggested Roles:
- Administrator, Commercial Director, Hotel Manager, Commercial Leader, Financial Analyst, Inquiry (Consulta).
- Operations (Sub-features):
- Roles, Permissions, Restriction by hotel, Restriction by region, Restriction by area.
FEATURE 8 — Internationalization & Multi-language Support
US-COM-015 — Internationalization of UI and AI Audit Notes
- Role: User / Auditor
- Goal: Toggle application language and read AI audit observations in the active locale
- Benefit: Support bilingual corporate workflows (English and Spanish).
- Acceptance Criteria:
- Scenario 1 (UI Translation): Given that the user selects English/Spanish from the language picker, when the page renders, then all headers, buttons, form labels, and table cells must translate accordingly.
- Scenario 2 (Bilingual AI Notes): Given that n8n runs compliance audits or anomaly checks, when the workflow posts callback results, then the system must store bilingual notes and render the language matching the user's active locale.
- Operations (Sub-features):
- Language selector dropdown, Bilingual translation dictionaries, Localized AI translation nodes, JSONB database storage.