LOTS PMS Season Synchronisation

Document Type: Technical + Business Integration Specification

Audience: PMS Vendors, Backend Engineers, Product Owners, QA Teams

1. Executive Summary

The LOTS PMS Season Synchronisation module ensures that Season records created in the Vendor system are accurately reflected in the PMS system.

Key Capabilities:

Automatic creation of new season records in PMS.
Automatic renewal of existing season records.
Support for continuous and non-continuous season logic.
Deduplication and idempotency handling.
Batch processing for scalability.
Full audit logging and error tracking.

2. System Architecture

Vendor System (Orders & Seasons)
        |
        v
+---------------------+
| LOTS Integration API|
+---------------------+
        |
        v
+---------------------+
| PMS System          |
| (Season Database)   |
+---------------------+

2.1 Key Components

Component	Responsibility
Vendor Database	Stores season orders and status.
LOTS Sync Service	Business logic, filtering, transformation, and orchestration.
PMS API	Create and update season records.
PMS Sync Log	Audit trail for all sync operations.

3. Terminology & Glossary

Term	Description
Season	A valid parking subscription period.
IU No	Unique Season Identifier (season_no in PMS).
Continuous Season	Season that extends from a previous season without gap.
Non-Continuous Season	Season that starts without continuity.
Complimentary Season	Season granted without charge.
PMS	Parking Management System.
Vendor System	External system managing orders.

4. Season Classification Logic

4.1 Active Season Status

Only seasons with the following statuses are processed:

ACTIVE
ACTIVE_COMPLIMENTARY

4.2 Non-Continuous Season

A season is classified as non-continuous if:

hasPreviousContinuosSeason = false
seasonStartDate ≤ current UTC time

4.3 Continuous Season

A season is classified as continuous if:

hasPreviousContinuosSeason = true
Only the earliest season per vehicle is processed (deduplication).

5. Data Selection & Filtering Rules

Rule	Description
Active Carpark	Only seasons belonging to active carparks are processed.
Batch Limit	Records are processed in limited batches.
Time Constraint	Start date must be ≤ current time.
Status Constraint	Season must be active.

6. High-Level Workflow

Fetch eligible seasons from Vendor DB.
Convert dates from UTC → SGT.
Group seasons by carpark and IU number.
Fetch existing seasons from PMS.
For each season:
- Check if season exists in PMS.
- Decide create or renew.
- Execute PMS API call.
Update Vendor DB sync status.
Write audit logs.

7. Decision Matrix

Scenario	Action
PMS season exists	Renew season
PMS season does not exist	Create season
PMS end date = null	Always renew
New end date < PMS end date	Skip renewal
Carpark group detected	Skip season

8. PMS API Payload Mapping

Vendor Field	PMS Field
IUNo	season_no
seasonStartDate	date_from
seasonEndDate	date_to
buyerName	holder_name
vehicleNo	vehicle_no
buyerCompany	full_company
rateType	rate_type

9. Vendor Database Update Logic

If complimentary season → update Preferential Rate table.
If normal season → update Order Item table.
Set hasSyncPms = 1.

10. Logging & Audit Trail

Log Type	Description
Create	Season created in PMS.
Renew	Season renewed in PMS.
Skip	Season ignored due to rules.
Error	Failed PMS operation.

11. Error Handling Strategy

Errors are logged without stopping the entire batch.
Failed seasons can be retried.
Detailed error messages are recorded.

12. Performance & Scalability

Batch processing limits DB and PMS load.
Parallel PMS queries using Promise.allSettled.
Deduplication reduces redundant updates.

13. Idempotency & Deduplication

Same IU No is processed only once per batch.
Continuous seasons are deduplicated by vehicle number.
Renewal only happens when necessary.

14. Pseudo-Code Overview

FOR each eligible season:
  IF season exists in PMS:
      IF shouldUpdate:
          renew season
      ELSE:
          skip
  ELSE:
      create season
  UPDATE vendor sync status
  LOG result

15. Vendor Responsibilities

Ensure IU No uniqueness.
Ensure accurate season start/end dates.
Provide reliable PMS API endpoints.
Support retry and reconciliation.

16. Future Enhancements

Webhook-based sync.
Real-time sync instead of batch.
Conflict resolution rules.
Monitoring dashboard.

17. Final Summary

The LOTS PMS Season Sync module provides a robust, scalable, and auditable integration between Vendor and PMS systems, ensuring accurate season lifecycle management across multiple carparks with advanced business logic for continuous and non-continuous seasons.