Requirements Traceability
Purpose
This page documents traceability between Maqsafy requirements, implementation areas, APIs, database entities, and test coverage.
The purpose is to ensure that every approved requirement is tracked from specification to implementation and validation.
Traceability Model
Each requirement should be tracked using the following structure:
| Field | Description |
|---|---|
| Requirement ID | Unique requirement reference from the SRS |
| Requirement Summary | Short description of the requirement |
| Module | Functional area or system module |
| Role | User role affected by the requirement |
| Screen / UI | Related dashboard or app screen |
| API Endpoint | Related backend API endpoint |
| Database Entities | Related tables or entities |
| Test Case | Related functional or security test |
| Status | Planned / In Progress / Implemented / Tested / Deferred |
| Notes | Additional clarification |
Status Definitions
| Status | Meaning |
|---|---|
| Planned | Requirement is approved but not implemented yet |
| In Progress | Implementation is currently active |
| Implemented | Feature exists but testing is not fully confirmed |
| Tested | Feature is implemented and validated |
| Deferred | Requirement is postponed |
| Needs Confirmation | Requirement requires product, technical, or business confirmation |
Common Requirements Traceability
Authentication and Authorization
| Requirement ID | Requirement Summary | Module | Role | Screen / UI | API Endpoint | Database Entities | Test Case | Status | Notes |
|---|---|---|---|---|---|---|---|---|---|
| FR-COM-001 | Secure login for dashboard users | Authentication | Admin / School Manager / Supplier / Operator | Login | TBD | users, roles | Login success and failure tests | Needs Confirmation | Confirm actual auth flow |
| FR-COM-002 | Enforce RBAC permissions | Authorization | All roles | All protected screens | TBD | users, roles, permissions | Unauthorized and cross-scope access tests | Needs Confirmation | Must be enforced in backend |
| FR-COM-003 | Password reset and account recovery | Authentication | Dashboard users | Password Reset | TBD | users, password_resets | Password reset flow test | Needs Confirmation | Confirm if enabled |
| FR-COM-004 | Optional MFA for Admin and sensitive financial actions | Authentication / Security | Admin | MFA / Sensitive Actions | TBD | users, mfa_settings | MFA verification test | Planned | Confirm MFA implementation |
| FR-COM-005 | Log authentication events | Audit Logging | All roles | N/A | TBD | audit_logs, login_events | Login audit test | Needs Confirmation | Confirm actual log table |
Audit Logging
| Requirement ID | Requirement Summary | Module | Role | Screen / UI | API Endpoint | Database Entities | Test Case | Status | Notes |
|---|---|---|---|---|---|---|---|---|---|
| FR-COM-030 | Maintain audit trail for critical actions | Audit Logging | Admin / System | Audit Logs | TBD | audit_logs | Critical action audit test | Needs Confirmation | Required for financial and admin actions |
| FR-COM-031 | Audit entries include actor, time, action, scope, before/after values | Audit Logging | Admin / System | Audit Logs | TBD | audit_logs | Audit field completeness test | Needs Confirmation | Must confirm stored fields |
Wallet and Ledger
| Requirement ID | Requirement Summary | Module | Role | Screen / UI | API Endpoint | Database Entities | Test Case | Status | Notes |
|---|---|---|---|---|---|---|---|---|---|
| FR-COM-040 | Display wallet balances based on permissions | Wallet | Authorized roles | Wallet Dashboard | TBD | wallets, transactions | Wallet visibility by role test | Needs Confirmation | Scope must be enforced |
| FR-COM-041 | Display immutable transaction ledger with filtering and export | Wallet / Ledger | Authorized roles | Ledger | TBD | transactions, ledger_entries | Ledger filtering and export test | Needs Confirmation | Confirm immutability design |
| FR-COM-042 | Reconciliation reports by school/branch and date range | Finance / Reports | Admin / School Manager | Reconciliation Reports | TBD | transactions, settlements | Reconciliation report test | Needs Confirmation | Confirm report source |
Credential Inventory
| Requirement ID | Requirement Summary | Module | Role | Screen / UI | API Endpoint | Database Entities | Test Case | Status | Notes |
|---|---|---|---|---|---|---|---|---|---|
| FR-COM-050 | Display credential inventory and statuses | Credentials | Admin / School Manager | Credential Inventory | TBD | credential_inventory | View inventory by scope test | Needs Confirmation | Statuses include Available, Assigned, Delivered, Disabled |
| FR-COM-051 | View credential identifier/code subject to privacy policy | Credentials | Admin / School Manager | Credential Details | TBD | credential_inventory, students | Sensitive field visibility test | Needs Confirmation | Must apply privacy policy |
| FR-COM-052 | Assign/link credential item to student wallet owner | Credentials | Admin / School Manager | Assign Credential | TBD | credential_inventory, students, wallets | Assignment test | Needs Confirmation | Must prevent duplicate active assignment |
| FR-COM-053 | Prevent same active credential from multiple wallet owners | Credentials | System | N/A | TBD | credential_inventory | Duplicate assignment prevention test | Needs Confirmation | Requires unique constraint or validation |
| FR-COM-054 | Dashboard must not provide NFC reader/scanner functionality | Credentials | All roles | Dashboard | N/A | N/A | UI and code review | Needs Confirmation | Dashboard display/manage only |
| FR-COM-055 | Restrict credential disabling/replacement to Admin | Credentials | Admin | Credential Lifecycle | TBD | credential_inventory, audit_logs | Admin-only deactivation test | Needs Confirmation | Critical RBAC rule |
Admin Requirements Traceability
| Requirement ID | Requirement Summary | Module | Role | Screen / UI | API Endpoint | Database Entities | Test Case | Status | Notes |
|---|---|---|---|---|---|---|---|---|---|
| FR-ADM-001 | Create, update, deactivate, and view schools | Schools | Admin | Schools Management | TBD | schools | School CRUD test | Needs Confirmation | Admin-only |
| FR-ADM-002 | Manage branches/cafeterias under schools | Cafeterias | Admin | Branch / Cafeteria Management | TBD | cafeterias, branches | Cafeteria CRUD test | Needs Confirmation | Confirm entity naming |
| FR-ADM-003 | Manage operating companies and link them to branches | Operating Companies | Admin | Operating Companies | TBD | operating_companies, branches | Linking test | Needs Confirmation | Confirm module exists |
| FR-ADM-010 | Manage dashboard user accounts | User Management | Admin | Users | TBD | users, roles | User management test | Needs Confirmation | Includes activate/deactivate/reset access |
| FR-ADM-011 | Assign roles and scopes | RBAC | Admin | Roles and Permissions | TBD | users, roles, permissions, scopes | Scope assignment test | Needs Confirmation | Critical security area |
| FR-ADM-012 | View permissions matrix and role summary | RBAC | Admin | Permissions Matrix | TBD | roles, permissions | Permission matrix visibility test | Needs Confirmation | Should match RBAC documentation |
| FR-ADM-020 | Manage product master list | Products | Admin | Product Catalog | TBD | products, categories | Product CRUD test | Needs Confirmation | Include SKU, category, allergens, images |
| FR-ADM-030 | View purchase orders across tenants | Procurement | Admin | Purchase Orders | TBD | purchase_orders | Admin PO visibility test | Needs Confirmation | Platform-wide scope |
| FR-ADM-031 | View and audit returns/refunds | Returns / Refunds | Admin | Returns / Refunds | TBD | refunds, returns, transactions | Refund audit test | Needs Confirmation | Must include reasons |
| FR-ADM-032 | Export invoices and settlement summaries | Finance | Admin | Finance Exports | TBD | invoices, settlements | Export test | Needs Confirmation | Must respect date range |
| FR-ADM-040 | Configure settlement rules | Finance Settings | Admin | Settlement Settings | TBD | settlement_rules | Settlement rule update test | Needs Confirmation | Sensitive financial setting |
| FR-ADM-041 | Approve or reject withdrawal requests above thresholds | Withdrawals | Admin | Withdrawal Approvals | TBD | withdrawals, audit_logs | Withdrawal approval test | Needs Confirmation | Must be audited |
| FR-ADM-042 | Access platform-wide finance dashboards | Finance Reports | Admin | Finance Dashboard | TBD | transactions, invoices, settlements | Admin finance dashboard test | Needs Confirmation | Platform-wide access |
| FR-ADM-060 | Disable/deactivate credential and record reason | Credentials | Admin | Credential Lifecycle | TBD | credential_inventory, audit_logs | Credential deactivation test | Needs Confirmation | Admin-only |
| FR-ADM-061 | Perform credential replacement workflow | Credentials | Admin | Credential Replacement | TBD | credential_inventory, audit_logs | Replacement workflow test | Needs Confirmation | Full audit trail required |
| FR-ADM-062 | View credential lifecycle history and export reports | Credentials | Admin | Credential History | TBD | credential_inventory, audit_logs | Lifecycle export test | Needs Confirmation | Confirm export format |
| FR-ADM-050 | Manage advertisement campaigns | Advertisements | Admin | Ads Management | TBD | advertisements | Campaign CRUD test | Needs Confirmation | If enabled |
| FR-ADM-051 | Configure dashboard settings and business rules | System Settings | Admin | Settings | TBD | settings | Settings update test | Needs Confirmation | Sensitive |
| FR-ADM-052 | Manage integration settings excluding NFC scanning | Integrations | Admin | Integration Settings | TBD | integrations | Integration setting test | Needs Confirmation | Do not expose secrets |
School Manager Requirements Traceability
| Requirement ID | Requirement Summary | Module | Role | Screen / UI | API Endpoint | Database Entities | Test Case | Status | Notes |
|---|---|---|---|---|---|---|---|---|---|
| FR-SCH-001 | Manage school profile data and operational settings | School Operations | School Manager | School Profile | TBD | schools, settings | Update within scope test | Needs Confirmation | School scope only |
| FR-SCH-002 | View/manage cafeterias under school | Cafeterias | School Manager | Cafeterias | TBD | cafeterias, branches | Scope visibility test | Needs Confirmation | Admin constraints apply |
| FR-SCH-010 | Create/manage School Staff Supervisor records | Supervisors | School Manager | Supervisors | TBD | supervisors | Supervisor CRUD test | Needs Confirmation | Non-login record |
| FR-SCH-011 | Import or sync student records | Students | School Manager | Student Roster | TBD | students | Student import test | Needs Confirmation | Confirm import method |
| FR-SCH-012 | Assign supervisors to cafeterias/branches | Supervisors | School Manager | Supervisor Assignment | TBD | supervisor_assignments | Assignment test | Needs Confirmation | School scope only |
| FR-SCH-013 | Define student spending policies | Student Policies | School Manager | Spending Policies | TBD | spending_policies | Policy update test | Needs Confirmation | If enabled |
| FR-SCH-015 | System does not require supervisors to have dashboard accounts | Supervisors | System | N/A | N/A | supervisors | No-login supervisor test | Needs Confirmation | Must not create user login |
| FR-SCH-020 | View credential inventory for school | Credentials | School Manager | Credential Inventory | TBD | credential_inventory | School scope inventory test | Needs Confirmation | School scope only |
| FR-SCH-021 | View credential identifiers/codes as permitted | Credentials | School Manager | Credential Details | TBD | credential_inventory | Privacy visibility test | Needs Confirmation | Subject to privacy policy |
| FR-SCH-022 | Assign credential to student and record delivery status | Credentials | School Manager | Assign / Deliver Credential | TBD | credential_inventory, students | Delivery status test | Needs Confirmation | No deactivation |
| FR-SCH-023 | School Manager cannot disable/deactivate or replace credentials | Credentials | School Manager | Credential Lifecycle | TBD | credential_inventory | Denied deactivation test | Needs Confirmation | Admin-only action |
| FR-SCH-030 | Approve products for sale at school | Products | School Manager | Product Approval | TBD | products, school_product_rules | Product allowlist/denylist test | Needs Confirmation | School scope |
| FR-SCH-031 | Manage menu availability schedules | Menu | School Manager | Menu Schedule | TBD | menu_schedules | Schedule update test | Needs Confirmation | School scope |
| FR-SCH-040 | View sales summaries by branch, category, and time | Reports | School Manager | Sales Reports | TBD | transactions, orders | Sales report test | Needs Confirmation | School scope |
| FR-SCH-041 | View student spending analytics as permitted | Reports | School Manager | Student Analytics | TBD | transactions, students | Privacy-safe analytics test | Needs Confirmation | Must minimize student data |
| FR-SCH-042 | View procurement performance where enabled | Reports | School Manager | Procurement Reports | TBD | purchase_orders | Procurement report test | Needs Confirmation | If enabled |
| FR-SCH-043 | Manage school-level advertisements where enabled | Advertisements | School Manager | Ads Management | TBD | advertisements | School ad test | Needs Confirmation | Admin-controlled enablement |
| FR-SCH-044 | Export credential distribution reports | Credentials / Reports | School Manager | Credential Reports | TBD | credential_inventory | School scope export test | Needs Confirmation | Assigned school only |
Supplier Requirements Traceability
| Requirement ID | Requirement Summary | Module | Role | Screen / UI | API Endpoint | Database Entities | Test Case | Status | Notes |
|---|---|---|---|---|---|---|---|---|---|
| FR-SUP-001 | Manage supplier products | Supplier Products | Supplier | Supplier Catalog | TBD | products, supplier_products | Supplier product test | Needs Confirmation | Supplier scope |
| FR-SUP-002 | Manage availability indicators and lead times | Supplier Products | Supplier | Availability | TBD | supplier_products | Availability update test | Needs Confirmation | If enabled |
| FR-SUP-010 | View incoming purchase orders and accept/reject | Procurement | Supplier | Purchase Orders | TBD | purchase_orders | Supplier PO access test | Needs Confirmation | Supplier scope |
| FR-SUP-011 | Update fulfillment statuses | Procurement | Supplier | Fulfillment | TBD | purchase_orders | Fulfillment update test | Needs Confirmation | With timestamps |
| FR-SUP-012 | Attach delivery notes and invoices | Invoices | Supplier | Invoices / Delivery Notes | TBD | invoices, attachments | Attachment upload test | Needs Confirmation | File restrictions required |
| FR-SUP-020 | Review return requests and approve/reject | Returns | Supplier | Returns | TBD | returns, refunds | Supplier return review test | Needs Confirmation | Supplier scope |
| FR-SUP-021 | Finalize refunds or credit notes according to policy | Refunds | Supplier | Refunds / Credit Notes | TBD | refunds, credit_notes | Refund finalization test | Needs Confirmation | Policy-dependent |
| FR-SUP-030 | View invoices and settlement statements | Finance | Supplier | Settlement Statements | TBD | invoices, settlements | Supplier settlement test | Needs Confirmation | Supplier scope |
| FR-SUP-031 | View wallet/ledger entries and payout statuses | Wallet | Supplier | Supplier Wallet | TBD | wallets, transactions, payouts | Supplier wallet scope test | Needs Confirmation | Supplier scope |
| FR-SUP-032 | Submit payout details and verification documents | Payouts | Supplier | Payout Details | TBD | payout_accounts, attachments | Payout details test | Needs Confirmation | Sensitive data |
Operator Requirements Traceability
| Requirement ID | Requirement Summary | Module | Role | Screen / UI | API Endpoint | Database Entities | Test Case | Status | Notes |
|---|---|---|---|---|---|---|---|---|---|
| FR-OPR-001 | Manage cafeteria profile and operational parameters | Cafeteria Operations | Operator | Cafeteria Profile | TBD | cafeterias | Operator scope update test | Needs Confirmation | Assigned scope only |
| FR-OPR-002 | Manage product availability when permitted | Products | Operator | Product Availability | TBD | products, cafeteria_products | Availability update test | Needs Confirmation | Permission-based |
| FR-OPR-003 | View recorded sales transactions | Sales | Operator | Sales Transactions | TBD | transactions, orders | Operator transaction scope test | Needs Confirmation | Customer credential details restricted |
| FR-OPR-010 | Initiate return/refund requests | Refunds | Operator | Refund Request | TBD | refunds, transactions | Refund request test | Needs Confirmation | Policy limits apply |
| FR-OPR-011 | Link refund requests to original transaction | Refunds | Operator / System | Refund Details | TBD | refunds, transactions | Refund traceability test | Needs Confirmation | Must be traceable |
| FR-OPR-012 | View refund request status | Refunds | Operator | Refund Status | TBD | refunds | Refund status visibility test | Needs Confirmation | Assigned scope only |
| FR-OPR-040 | Create purchase orders to suppliers when permitted | Procurement | Operator | Purchase Orders | TBD | purchase_orders | Operator PO creation test | Needs Confirmation | Permission-based |
| FR-OPR-041 | Confirm receiving and record discrepancies | Procurement | Operator | Receiving | TBD | purchase_orders, receiving_records | Receiving test | Needs Confirmation | Assigned cafeteria |
| FR-OPR-042 | View invoices related to cafeteria purchase orders | Invoices | Operator | Invoices | TBD | invoices | Operator invoice scope test | Needs Confirmation | Assigned cafeteria |
| FR-OPR-050 | View cafeteria wallet balance and transaction history | Wallet | Operator | Cafeteria Wallet | TBD | wallets, transactions | Operator wallet scope test | Needs Confirmation | Assigned cafeteria |
| FR-OPR-051 | Submit withdrawal requests subject to approval rules | Withdrawals | Operator | Withdrawal Request | TBD | withdrawals | Withdrawal request test | Needs Confirmation | Approval workflow required |
Non-Functional Requirements Traceability
| Requirement Area | Requirement Summary | Related Module | Validation Method | Status | Notes |
|---|---|---|---|---|---|
| Performance | Key dashboard pages render within target time | Dashboard / API / Database | Performance testing | Needs Confirmation | Target from SRS: 3 seconds under normal conditions |
| Export Performance | Exports complete within target time | Reports / Exports | Export load testing | Needs Confirmation | Target from SRS: one school, one month range within 60 seconds |
| Security | TLS 1.2+ | Infrastructure / Nginx | SSL/TLS scan | Needs Confirmation | Confirm production configuration |
| Security | Sensitive data encrypted at rest | Database / Storage | Architecture review | Needs Confirmation | Confirm implementation |
| Security | RBAC and tenant isolation | API / Database | Security testing | Needs Confirmation | Critical |
| Security | Rate limiting and brute-force protection | Authentication | Security testing | Needs Confirmation | Login and OTP endpoints |
| Usability | Arabic and English UI | Frontend / Dashboard | UI testing | Needs Confirmation | Confirm supported languages |
| Reliability | 99.5% monthly availability target | Infrastructure | Monitoring reports | Needs Confirmation | Excluding scheduled maintenance |
| Observability | Centralized logging, monitoring, and alerting | Infrastructure / Backend | Operations review | Needs Confirmation | Confirm tools |
| Maintainability | APIs documented and versioned | API | Documentation review | Needs Confirmation | OpenAPI recommended |
Testing Matrix
| Test Type | Purpose | Required |
|---|---|---|
| Functional Testing | Validate user workflows | Yes |
| RBAC Testing | Validate role and permission restrictions | Yes |
| Cross-Tenant Testing | Validate tenant isolation | Yes |
| API Testing | Validate endpoint behavior | Yes |
| Regression Testing | Validate existing features after changes | Yes |
| Security Testing | Validate authentication, authorization, and input handling | Yes |
| Performance Testing | Validate page and report response times | Yes |
| Backup / Restore Testing | Validate recovery capability | Yes |
| Audit Log Testing | Validate critical actions are recorded | Yes |
Required Negative Tests
| Scenario | Expected Result |
|---|---|
| Unauthenticated user accesses protected endpoint | 401 Unauthorized |
| School Manager accesses another school record | 403 Forbidden |
| Supplier accesses another supplier order | 403 Forbidden |
| Operator accesses another cafeteria record | 403 Forbidden |
| School Manager attempts credential deactivation | 403 Forbidden |
| User exports report outside scope | 403 Forbidden |
| User submits invalid input | Validation error |
| User retries financial action causing duplicate effect | Duplicate must be prevented |
Open Items
| Item | Owner | Status | Notes |
|---|---|---|---|
| Confirm actual API route names | TBD | Open | Replace all TBD endpoints |
| Confirm actual database table names | TBD | Open | Replace generic entities |
| Confirm RBAC middleware implementation | TBD | Open | Backend verification required |
| Confirm tenant isolation tests | TBD | Open | Required before production sign-off |
| Confirm audit log implementation | TBD | Open | Critical for financial and credential actions |
| Confirm OpenAPI availability | Draft Available | Open | /openapi.yaml exists; backend validation required before final approval |
| Confirm performance test results | TBD | Open | Required for page and export targets |
Rules
- Do not mark any requirement as tested unless validation evidence exists.
- Do not assume implementation details without confirming code, database, or environment.
- Use
TBDwhere details are unknown. - Use
Needs Confirmationwhere implementation may exist but has not been verified. - Link each implemented feature to at least one test case.