📂 Fail MD
📄 api-spec.md
📄 architecture.md
📄 compound-rules.md
📄 council-sync.md
📄 data-model.md
📄 money-ledger.md
📄 parking-rules.md
Sedang mengedit: data-model.md
# Smart Parking — Data Model Conceptual data model for the backend. Final column types/indexes will be refined during implementation (MySQL). The focus here is entities, `tenant_id` placement, and relationships. ## Tenancy Rules | Entity | `tenant_id`? | Notes | |---|---|---| | tenants | (is the tenant) | MBPP, MBSP, and Company A as operator | | users (public) | ❌ none | Global account; tenant set per transaction | | vehicles | ❌ none | Global; tenant inferred from session/compound | | user_vehicles | ❌ none | Many-to-many link | | staff | ✅ fixed | Belongs to one tenant | | admins (Company A) | operator scope | Can see all tenants | | zones | ✅ | Parking area belongs to a tenant | | bays | ✅ | Individual bay within a zone | | devices (sensors) | ✅ | Sensor assigned to a bay/zone | | rates (parking) | ✅ | Per tenant | | charging_windows | ✅ | Per tenant (and day type) | | public_holidays | ✅ (or global list + per-tenant opt) | Free all day | | parking_sessions | ✅ | Set at creation by location | | compounds | ✅ | Set by issuing staff's tenant | | compound_types | ✅ or global catalog | Extensible | | compound_rates | ✅ | Per tenant, per type | | wallets | ❌ none | Global liability per user | | ledger_entries | ✅ when spent | Movement-level tenant tag | | payments / topups | ✅ when recognized | | | refunds | ❌ (wallet) | Wallet balance only | | settlements / payouts | ✅ | Per tenant | | reserves | operator | Company A rolling reserve | ## Entities (key fields) ### tenants - `id`, `name` (MBPP / MBSP), `type` (council / operator), `status` - `commission_rate` (per tenant, differs), settings JSON - limits: `max_vehicles_per_user`, `max_users_per_vehicle`, `topup_min`, `topup_max` ### users (public) - `id`, `name`, `phone`, `email`, `password_hash`, `status` - **No `tenant_id`** (global) ### vehicles - `id`, `plate_no` (normalized/uppercase), `type` (car/motor/lorry), `status` - **No `tenant_id`** ### user_vehicles (M:N) - `id`, `user_id`, `vehicle_id`, `created_at` - Enforced against tenant limits at the point of action ### staff - `id`, `tenant_id` (fixed), `name`, `login_id`, `password_hash`, `role`, `status` ### zones - `id`, `tenant_id`, `name`, `geo` (lat/lng/polygon), `bay_count`, `status` ### bays - `id`, `tenant_id`, `zone_id`, `label`, `geo`, `current_status` (empty/occupied), `last_uplink_at` ### devices (sensors) - `id`, `tenant_id`, `bay_id`, `dev_eui`, `model`, `geo`, `battery`, `rssi`, `last_seen_at`, `status` ### rates (parking) - `id`, `tenant_id`, `name`, `vehicle_type`, `price_per_hour` (or block), `effective_from` ### charging_windows - `id`, `tenant_id`, `day_type` (weekday/weekend/holiday), `start_time`, `end_time` - Rest periods are the gaps between windows. ### public_holidays - `id`, `tenant_id` (or global), `date`, `name` → free all day, paying blocked ### parking_sessions - `id`, `tenant_id`, `vehicle_id`, `user_id`, `zone_id?` (informational) - `start_at`, `end_at` (computed with rest skipping), `paid_hours` - `amount`, `pay_method` (wallet/fpx/card), `status` (active/expired/cancelled) - Valid while `now < end_at` AND `tenant_id` matches scanning staff. ### compound_types - `id`, `code` (UNPAID_PARKING / ILLEGAL_PARKING / ...), `label`, `description` ### compound_rates - `id`, `tenant_id`, `compound_type_id`, `amount`, `effective_from` ### compounds - `id`, `tenant_id` (issuing staff tenant), `compound_type_id` - `vehicle_id`, `plate_no`, `issued_by_staff_id`, `issued_at` - `amount`, `evidence` (photos), `location/geo`, `status` (unpaid/paid/cancelled) ### wallets - `id`, `user_id`, **no `tenant_id`** (global) - Balance is computed from ledger, not stored as mutable number. ### ledger_entries (immutable) - `id`, `created_at`, `type`, `amount` (+/-), `tenant_id?` (set when recognized as revenue), `user_id?`, `reference` (session/compound/payout/etc.) - Types: `TOPUP`, `PAYMENT_PARK`, `PAYMENT_COMPOUND`, `COMMISSION`, `RESERVE_HOLD`, `RESERVE_RELEASE`, `PAYOUT`, `REFUND`, `GATEWAY_FEE` - Append-only; never edited or deleted. ### settlements / payouts - `id`, `tenant_id`, `period`, `gross`, `commission`, `reserve_held`, `reserve_released`, `net_payout`, `status`, `gateway_ref` ## Relationship Overview (Mermaid ER) ```mermaid erDiagram TENANTS ||--o{ STAFF : has TENANTS ||--o{ ZONES : has TENANTS ||--o{ RATES : sets TENANTS ||--o{ CHARGING_WINDOWS : sets TENANTS ||--o{ COMPOUND_RATES : sets TENANTS ||--o{ SETTLEMENTS : receives ZONES ||--o{ BAYS : contains BAYS ||--o| DEVICES : has USERS ||--o{ USER_VEHICLES : owns VEHICLES ||--o{ USER_VEHICLES : linked USERS ||--|| WALLETS : has VEHICLES ||--o{ PARKING_SESSIONS : parks USERS ||--o{ PARKING_SESSIONS : pays TENANTS ||--o{ PARKING_SESSIONS : scopes VEHICLES ||--o{ COMPOUNDS : receives STAFF ||--o{ COMPOUNDS : issues COMPOUND_TYPES ||--o{ COMPOUNDS : classifies TENANTS ||--o{ COMPOUNDS : scopes WALLETS ||--o{ LEDGER_ENTRIES : moves PARKING_SESSIONS ||--o{ LEDGER_ENTRIES : generates COMPOUNDS ||--o{ LEDGER_ENTRIES : generates ``` ## Notes - Plate numbers normalized (uppercase, no spaces) for reliable matching. - All money queries derive from `ledger_entries`; balances are never authoritative when stored — the ledger is. - Read-after-write sensitive checks (scanner verifying a just-paid session) should hit Primary to avoid replication lag.
Simpan Perubahan