vibes
This commit is contained in:
androidlover5842
247
AGENTS.md
Normal file
247
AGENTS.md
Normal file
@@ -0,0 +1,247 @@
|
|||||||
|
PROJECT CONTEXT / SYSTEM BRIEF
|
||||||
|
|
||||||
|
This is a hotel-grade Property Management System (PMS) being rebuilt from scratch.
|
||||||
|
This AGENTS file captures both the product rules you gave and my current understanding of
|
||||||
|
the TrisolarisServer codebase as of the last read, so future sessions can resume accurately.
|
||||||
|
|
||||||
|
Tech stack
|
||||||
|
- Spring Boot monolith
|
||||||
|
- Kotlin only
|
||||||
|
- JPA / Hibernate
|
||||||
|
- PostgreSQL
|
||||||
|
- No Flyway for now, schema via JPA during development (Flyway is present in deps but disabled)
|
||||||
|
- Single API domain api.hoteltrisolaris.in
|
||||||
|
- Android app and future website consume the same APIs
|
||||||
|
|
||||||
|
This replaces a very old Firestore-based Android app. Old code exists only to understand behaviour. Do not reuse or mirror old models.
|
||||||
|
|
||||||
|
CORE DESIGN PRINCIPLES
|
||||||
|
|
||||||
|
Server is the only source of truth
|
||||||
|
Clients never calculate state
|
||||||
|
Clients send intent, server derives facts
|
||||||
|
|
||||||
|
Ledger-based design
|
||||||
|
Never store totals
|
||||||
|
Never overwrite money
|
||||||
|
Append rows and derive views
|
||||||
|
|
||||||
|
Three independent concerns
|
||||||
|
Occupancy handled by RoomStay
|
||||||
|
Charges handled by Charge
|
||||||
|
Payments handled by Payment
|
||||||
|
Invoices are derived views, not stored state
|
||||||
|
|
||||||
|
Room availability is by room number
|
||||||
|
Availability is derived from RoomStay
|
||||||
|
toAt = null means occupied
|
||||||
|
Category counts are only summaries
|
||||||
|
|
||||||
|
Room changes must never break billing
|
||||||
|
Changing rooms means closing one RoomStay and opening another
|
||||||
|
Charges are time-bound and linked to booking, optionally to room_stay
|
||||||
|
|
||||||
|
Multi-property from day one
|
||||||
|
Every domain object is scoped to property_id
|
||||||
|
Users belong to organization
|
||||||
|
Access is granted per property
|
||||||
|
|
||||||
|
Auth and access
|
||||||
|
User exists once as AppUser
|
||||||
|
Property access via PropertyUser
|
||||||
|
Roles are per property
|
||||||
|
Every API call must enforce property membership
|
||||||
|
|
||||||
|
CURRENT DOMAIN MODEL ALREADY CREATED
|
||||||
|
|
||||||
|
Organization
|
||||||
|
Property
|
||||||
|
AppUser
|
||||||
|
PropertyUser with roles
|
||||||
|
RoomType
|
||||||
|
Room
|
||||||
|
Booking
|
||||||
|
Guest
|
||||||
|
RoomStay
|
||||||
|
|
||||||
|
These entities already exist in Kotlin. Do not redesign unless explicitly asked.
|
||||||
|
|
||||||
|
WHAT THE SYSTEM MUST SUPPORT
|
||||||
|
|
||||||
|
Operational behaviour
|
||||||
|
- Staff sees exact room numbers free, occupied, checkout today
|
||||||
|
- Different rates for same room type
|
||||||
|
- Multiple rooms today and fewer tomorrow under the same booking
|
||||||
|
- Room changes without data loss
|
||||||
|
|
||||||
|
Financial behaviour
|
||||||
|
- Advance payments, partial payments, refunds
|
||||||
|
- PayU integration for QR and payment links
|
||||||
|
- Payment status via webhooks
|
||||||
|
- Clear source and destination of money
|
||||||
|
- Staff-wise collection tracking
|
||||||
|
|
||||||
|
Website integration
|
||||||
|
- Website reads live availability from PMS
|
||||||
|
- Website creates booking intents
|
||||||
|
- No inventory sync jobs
|
||||||
|
- Rate plans like DIRECT, WALKIN, OTA are snapshotted at booking time
|
||||||
|
|
||||||
|
Realtime
|
||||||
|
- Firestore-like realtime behaviour
|
||||||
|
- WebSocket or SSE for room board and payment updates
|
||||||
|
- Push notifications later via FCM
|
||||||
|
|
||||||
|
Infrastructure
|
||||||
|
- Nginx reverse proxy
|
||||||
|
- Single domain with multiple paths
|
||||||
|
- Database is never exposed publicly
|
||||||
|
|
||||||
|
IMPORTANT RULES FOR YOU
|
||||||
|
|
||||||
|
- Use Kotlin only
|
||||||
|
- Follow existing package structure
|
||||||
|
- No speculative features
|
||||||
|
- No premature microservices
|
||||||
|
- Flyway must remain disabled during development. Do not introduce or modify Flyway migrations unless explicitly instructed after schema stabilization.
|
||||||
|
- Propose schema or API changes before coding if unsure
|
||||||
|
- Money logic must be explicit and auditable
|
||||||
|
- Canonical staff roles for now are ADMIN, MANAGER, STAFF, HOUSEKEEPING, FINANCE. Other roles may exist later but must not be depended on unless asked.
|
||||||
|
- Booking is a lifecycle container only. Booking does not own rooms or money. Occupancy is only via RoomStay. Billing is only via Charge and Payment ledgers.
|
||||||
|
- Realtime features must emit derived domain events only. Clients must never subscribe to raw entity state or database changes.
|
||||||
|
|
||||||
|
HOW YOU SHOULD WORK
|
||||||
|
|
||||||
|
- Read the entire repository before making changes
|
||||||
|
- Work file by file
|
||||||
|
- Prefer small focused changes
|
||||||
|
- Ask before touching auth or payment logic
|
||||||
|
- Assume this will run in real production hotels
|
||||||
|
|
||||||
|
FIRST TASK
|
||||||
|
|
||||||
|
Do nothing until asked.
|
||||||
|
Likely upcoming tasks include room board API, charge ledger, payment and PayU webhook flow, booking check-in transaction.
|
||||||
|
|
||||||
|
===============================================================================
|
||||||
|
CURRENT CODEBASE UNDERSTANDING (TrisolarisServer)
|
||||||
|
===============================================================================
|
||||||
|
|
||||||
|
Repository
|
||||||
|
- Root: /home/androidlover5842/IdeaProjects/TrisolarisServer
|
||||||
|
- Language: Kotlin only (Spring Boot 4, JPA)
|
||||||
|
- Entry point: src/main/kotlin/com/android/trisolarisserver/TrisolarisServerApplication.kt
|
||||||
|
- Active controller layer is minimal (Rooms.kt is stubbed/commented)
|
||||||
|
|
||||||
|
Gradle
|
||||||
|
- build.gradle.kts uses:
|
||||||
|
- Spring Boot 4.0.1
|
||||||
|
- Kotlin 2.2.21 (kotlin("jvm"), kotlin("plugin.spring"), kotlin("plugin.jpa"))
|
||||||
|
- Java toolchain 19
|
||||||
|
- JPA, WebMVC, Validation, Security, WebSocket, Flyway (dep), Postgres
|
||||||
|
- Flyway is disabled in application.properties
|
||||||
|
|
||||||
|
Configuration
|
||||||
|
- src/main/resources/application.properties
|
||||||
|
- spring.jpa.hibernate.ddl-auto=update
|
||||||
|
- spring.jpa.open-in-view=false
|
||||||
|
- flyway.enabled=false
|
||||||
|
- application-dev.properties -> jdbc:postgresql://192.168.1.53:5432/trisolaris
|
||||||
|
- application-prod.properties -> jdbc:postgresql://localhost:5432/trisolaris
|
||||||
|
- DB password via env: DB_PASSWORD
|
||||||
|
|
||||||
|
Current packages and code
|
||||||
|
|
||||||
|
com.android.trisolarisserver.component
|
||||||
|
- PropertyAccess
|
||||||
|
- requireMember(propertyId, userId) -> checks PropertyUserRepo
|
||||||
|
- requireAnyRole(propertyId, userId, roles) -> checks roles
|
||||||
|
|
||||||
|
com.android.trisolarisserver.db.repo
|
||||||
|
- PropertyUserRepo
|
||||||
|
- existsByIdPropertyIdAndIdUserId(...)
|
||||||
|
- hasAnyRole(...) via JPQL joining property_user_role
|
||||||
|
- RoomRepo
|
||||||
|
- findFreeRooms(propertyId): active, not maintenance, no open RoomStay
|
||||||
|
- findOccupiedRooms(propertyId): rooms with active RoomStay
|
||||||
|
|
||||||
|
com.android.trisolarisserver.controller
|
||||||
|
- Rooms.kt: placeholder, no active endpoints yet
|
||||||
|
|
||||||
|
Entity model (current Kotlin entities)
|
||||||
|
- Organization
|
||||||
|
- id (uuid), name, createdAt
|
||||||
|
- Property
|
||||||
|
- id (uuid)
|
||||||
|
- org (Organization)
|
||||||
|
- code, name, timezone, currency
|
||||||
|
- active, createdAt
|
||||||
|
- AppUser
|
||||||
|
- id (uuid)
|
||||||
|
- org (Organization)
|
||||||
|
- firebaseUid, phoneE164, name
|
||||||
|
- disabled, createdAt
|
||||||
|
- PropertyUser
|
||||||
|
- composite key PropertyUserId (propertyId, userId)
|
||||||
|
- property (Property), user (AppUser)
|
||||||
|
- roles (ElementCollection of Role)
|
||||||
|
- Role enum
|
||||||
|
- ADMIN, MANAGER, STAFF, HOUSEKEEPING, FINANCE, GUIDE, SUPERVISOR, AGENT
|
||||||
|
- RoomType
|
||||||
|
- id (uuid)
|
||||||
|
- property (Property)
|
||||||
|
- code, name, baseOccupancy, maxOccupancy, createdAt
|
||||||
|
- Room
|
||||||
|
- id (uuid)
|
||||||
|
- property (Property)
|
||||||
|
- roomType (RoomType)
|
||||||
|
- roomNumber, floor
|
||||||
|
- hasNfc, active, maintenance, notes
|
||||||
|
- Booking
|
||||||
|
- id (uuid)
|
||||||
|
- property (Property)
|
||||||
|
- primaryGuest (Guest)
|
||||||
|
- status (BookingStatus)
|
||||||
|
- source, sourceBookingId
|
||||||
|
- checkinAt, checkoutAt
|
||||||
|
- expectedCheckinAt, expectedCheckoutAt
|
||||||
|
- notes
|
||||||
|
- createdBy (AppUser)
|
||||||
|
- createdAt, updatedAt
|
||||||
|
- BookingStatus enum
|
||||||
|
- OPEN, CHECKED_IN, CHECKED_OUT, CANCELLED, NO_SHOW
|
||||||
|
- Guest
|
||||||
|
- id (uuid)
|
||||||
|
- org (Organization)
|
||||||
|
- phoneE164, name, nationality
|
||||||
|
- addressText
|
||||||
|
- createdAt, updatedAt
|
||||||
|
- RoomStay
|
||||||
|
- id (uuid)
|
||||||
|
- property (Property)
|
||||||
|
- booking (Booking)
|
||||||
|
- room (Room)
|
||||||
|
- fromAt, toAt (null = active occupancy)
|
||||||
|
- createdBy (AppUser)
|
||||||
|
- createdAt
|
||||||
|
|
||||||
|
Notes on schema vs migration file
|
||||||
|
- There is a Flyway migration file at src/main/resources/db/migration/V1__core.sql,
|
||||||
|
but Flyway is disabled. The SQL file does NOT match current Kotlin entities in
|
||||||
|
multiple places (columns and tables differ). For now, JPA schema generation is
|
||||||
|
authoritative during development.
|
||||||
|
|
||||||
|
Gaps relative to target design (do not implement unless asked)
|
||||||
|
- No Charge entity yet
|
||||||
|
- No Payment entity yet
|
||||||
|
- No ledger/derived views
|
||||||
|
- No API controllers/services for bookings, rooms, payments
|
||||||
|
- No auth filter or principal model wired (PropertyAccess expects userId)
|
||||||
|
- No WebSocket/SSE endpoints yet
|
||||||
|
|
||||||
|
Behavioral requirements to keep in mind when coding
|
||||||
|
- Every domain object must include property scope
|
||||||
|
- Room availability derived from RoomStay toAt == null
|
||||||
|
- Room changes are new RoomStay + closing old
|
||||||
|
- Charges and payments are append-only (never overwrite totals)
|
||||||
|
- Clients send intent; server derives facts
|
||||||
Reference in New Issue
Block a user