Place ticket list (ticketService)

The ticketService is the sole source of place ticket history for reports and accounts (RN-TLC-18). It is the single gateway for historical ticket rows via GET place/ticketlst. Features must not call adhoc.DoRequest('place/ticketlst', …) directly.

Implementation: libs/upp-data/src/modules/tickets.ts
Contract: libs/upp-data/src/frontlib/tickets.mdc
Backend: server/src/App/Services/place/Ticketlst.php

Purpose

Problem (before)	Solution
Income report and pay-account each cached ticketlst separately	One RAM cache per active place in ticketService
Repeated full-place fetches per account	Shared cache + incremental sync on cache hit
Live TPV tickets missing from API list	_MergeLiveTickets from PlaceView.tickets before hit/miss

Public API

Symbol	Role
ticketService.Query(place, ini, end, mode?)	Rows for period; mode 'CREATED' (default) or 'UPDATED'. Throws when offline — callers must guard with view.IsOnline.
TicketInfo	Lightweight row DTO (objid, created, updated, status, payment, price, account, invceac, …)
TICKET_LIST_CACHE_MAX	10000 — max rows per place in RAM

There is no public Sync or Invalidate. Incremental sync runs inside Query on cache hit (RN-TLC-13).

Hit vs miss

Path	HTTP	Response source
Miss (RN-TLC-01)	One place/ticketlst with timestamp: 0 for the full requested period	Merged cache after API + live tickets. Miss when cache is empty or dateini is before the oldest row still stored (evicted history is not covered).
Hit (RN-TLC-03)	Optional incremental with stored watermark	RAM only (live merge applied first)

Mixing partial API responses with historical cache rows to fill period gaps in a single Query is forbidden (RN-TLC-04). Live TPV tickets are not an exception — they are merged before the hit/miss decision (RN-TLC-11).

Limits

Limit	Value	Rule
RAM per place	10 000 rows	RN-TLC-05 — session cache evicts stalest by updated; current Query response is not truncated
Scope per Query	~1 year (product)	RN-TLC-06 — not enforced in ticketService. Reports: max step YEAR in upp-report-period, history up to 4 years back by changing period and reloading. Accounts: last natural year via accountService (rolling window). Wider history = several Query calls, not one request.
Places in RAM	1 active	RN-TLC-10 — new place.objid discards previous cache
In-flight sync dedup	place.objid + calendar-day period	RN-TLC-16 — dateini start of day, dateend start of next day; response filter uses caller bounds

HTTP fetch and response mode

HTTP query params: place, dateini, dateend, timestamp (epoch seconds). There is no updated request flag; the server matches rows whose created OR updated falls within the requested period (incremental uses the same OR rule from max(timestamp, dateini)).

Consumer	Query mode	Response filter (client)
Income report (upp-report-income)	CREATED	Rows with created in period
Pay account (accountService)	UPDATED	Rows with updated in period, then row.account === account.objid
Future monthly / clients reports	CREATED	Report-specific

mode only selects which timestamp column filters the client response from RAM; HTTP contract is shared.

Materialization to TicketView (volatile ObjectFactory + data.alives.get) is accountService responsibility for accounts; income maps to IncomeTicket locally.

Consumers (v4)

Module	Usage
libs/feature/reports/.../upp-report-income.ts	ticketService.Query(..., 'CREATED')
libs/feature/account/src/modules/account.ts	ticketService.Query(..., 'UPDATED') → filter by account + materialize
upp-account-thumb / upp-account-edit / upp-account-view	AccountInfo.Tickets / Pending / Settled via accountService.bind (no ticketService in components)

Architecture check: rg "DoRequest('place/ticketlst'" libs/feature must return 0 (REG-TLC-05).

Offline

Query throws when !view.IsOnline (RN-TLC-14). accountService.Tickets / Pending / Settled return [] without calling Query (RN-PAC-12, RV-PAC-04, CA-PAC-OFF-01). Account ticket lists require connectivity.

Tests

Spec	Coverage
libs/upp-data/src/specs/tickets.spec.ts	Hit/miss, eviction, live merge, offline, place switch
libs/feature/account/src/specs/account-service.spec.ts	Per-account materialization, grouping, dedup sync (UT-PAC-20, REG-TLC-03)
libs/feature/account/src/specs/account-service-group.spec.ts	Pending grouping rules (RN-PAC-05…08)
libs/feature/reports/src/specs/upp-report-income.spec.ts	Delegates to ticketService.Query
libs/feature/account/src/specs/upp-account-thumb.spec.ts	AccountInfo.Tickets / offline thumb

Backend (PHP)

Test	Role
server/tests/Unit/place/TicketlstActionTest.php	SQL period uses TICKET.created OR TICKET.updated (replaces former integration case for updated=1 only)

Related

• Sync and Cache — syncService / cacheService (persistent session data; not ticket list RAM)
• Ticket System — ticket lifecycle, commit, print
• Data service — dataService, storage, alives
• Functional contracts: libs/upp-data/src/frontlib/tickets.mdc, libs/upp-data/src/modules/model/views/payaccount.mdc
• Future consumers (monthly / clients reports): must use ticketService.Query only — no parallel DoRequest('place/ticketlst') in features