androidlover5842/TrisolarisServer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

more codes

Browse Source
This commit is contained in:
androidlover5842
2026-01-24 22:22:37 +05:30
parent 0d3472c60e
commit 6b6d84e40a
12 changed files with 614 additions and 228 deletions
Download Patch File Download Diff File Expand all files Collapse all files

251
AGENTS.md
View File

@@ -1,19 +1,19 @@
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.
This AGENTS file captures the product rules + current codebase state.
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)
- No Flyway for now, schema via JPA during development (Flyway deps present 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.
Legacy note
Old Firestore Android app exists only to understand behavior. Do not reuse old models.
CORE DESIGN PRINCIPLES
@@ -52,76 +52,16 @@ 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
IMMUTABLE RULES
- 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
- Canonical staff roles: ADMIN, MANAGER, STAFF, HOUSEKEEPING, FINANCE (other roles may exist but must not be depended on)
- Booking is a lifecycle container only. Booking does not own rooms or money. Occupancy via RoomStay. Billing via Charge/Payment ledgers.
- Realtime must emit derived events only (no raw entity subscriptions)
- 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)
@@ -129,119 +69,76 @@ 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)
- Entry: src/main/kotlin/com/android/trisolarisserver/TrisolarisServerApplication.kt
- Scheduling enabled (@EnableScheduling)
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
Security/Auth
- Firebase Admin auth for every request, Firebase UID required.
- Security filter verifies token and maps to MyPrincipal(userId, firebaseUid).
- Endpoints: /auth/verify and /auth/me.
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
Domain entities
- Organization: id, name, emailAliases
- Property: org, code, name, addressText, timezone, currency, active, emailAddresses, otaAliases
- AppUser: org, firebaseUid, phoneE164, name, disabled
- PropertyUser: roles per property
- Role enum includes ADMIN, MANAGER, STAFF, HOUSEKEEPING, FINANCE, GUIDE, SUPERVISOR, AGENT (but only canonical roles should be used)
- RoomType: code/name/occupancy + otaAliases
- Room: roomNumber, floor, hasNfc, active, maintenance, notes
- Booking: status, source/sourceBookingId, expected check-in/out, emailAuditPdfUrl
- 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
- GuestDocument: files for guest/booking with AI-extracted data
- InboundEmail: inbound mail audit (PDF + raw eml), extractedData, status
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.
Repos
- Repos are under com.android.trisolarisserver.repo (note: not db.repo).
- Added repos for Booking, Guest, GuestDocument, InboundEmail.
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
Key modules
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
Rooms / inventory
- /properties/{propertyId}/rooms
- /properties/{propertyId}/rooms/board
- /properties/{propertyId}/rooms/availability
- /properties/{propertyId}/rooms/availability-range?from=YYYY-MM-DD&to=YYYY-MM-DD
Availability derived from RoomStay. Date range uses overlap [from, to).
Room types
- CRUD with otaAliases in DTOs.
Properties/Orgs
- Property create/update accept addressText, otaAliases, emailAddresses.
- Org create/get returns emailAliases.
Guest documents (files)
- POST /properties/{propertyId}/guests/{guestId}/documents (multipart + bookingId)
- GET list
- GET file (token or auth)
- Files stored under /home/androidlover5842/docs/{propertyId}/{guestId}/{bookingId}/
- AI extraction via llama.cpp with strict system prompt
Inbound email ingestion
- IMAP poller (1 min) with enable flag.
- Saves audit PDF + raw .eml to /home/androidlover5842/docs/emails
- Matches property via To/CC email first, then text aliases (name/code/address/otaAliases)
- AI extracts booking fields and creates/cancels Booking
- Booking gets emailAuditPdfUrl that points to /properties/{propertyId}/inbound-emails/{emailId}/file
AI integration
- Base URL configured per profile:
- dev: https://ai.hoteltrisolaris.in/v1/chat/completions
- prod: http://localhost:8089/v1/chat/completions
- LlamaClient uses strict system prompt: only visible text, no guessing.
- Read timeout 5 minutes.
Config
- application.properties: flyway disabled, storage paths, IMAP config, token secrets.
- storage.documents.publicBaseUrl + token secret/ttl.
- storage.emails.publicBaseUrl used for booking audit URL.
- mail.imap.enabled=false by default.
Notes / constraints
- API user creation removed; users are created by app; API only manages roles.
- Admin can assign ADMIN/MANAGER/STAFF/AGENT; Manager can assign STAFF/AGENT.
- Agents can only see free rooms.