Z8MB1E
a8e147e52a
Add domain-specific AGENTS.md files for collections, components, lib, utils, and bot. Add login-return-url case study documenting the return-URL flow design decisions and debugging lessons learned.
85 lines
4.6 KiB
Markdown
85 lines
4.6 KiB
Markdown
# AGENTS.md — Shared Business Logic
|
|
|
|
> **Parent**: `../../AGENTS.md` — Payload config, server actions pattern, env vars.
|
|
|
|
## Overview
|
|
|
|
23 files across 8 domain subdirectories. Contains pure business logic and Payload-dependent service modules. Server actions in route directories delegate here; these modules hold the actual domain rules.
|
|
|
|
## Structure
|
|
|
|
```
|
|
lib/
|
|
utils.ts # cn() class merger (Tailwind)
|
|
storageRules.ts # Storage validation (prohibited → whitelist → per-item cap)
|
|
shipping.ts # Fuel cost, transit time, vehicle effective speed
|
|
distance.ts # Haversine distance calculation
|
|
logistics.ts # Shared logistics helpers
|
|
versionInfo.ts # Build version display
|
|
|
|
attendance/ # Mission attendance service (single write path)
|
|
banking/ # Transaction engine, account creation, formatting
|
|
locker/ # Grid logic, placement validation, loadouts
|
|
market/ # Buy/sell, NPC negotiation, dialogue, vendor resolution
|
|
notifications/ # User notification helper + muteable types
|
|
realtime/ # In-process SSE bus (single-instance only)
|
|
tickets/ # Ticket vocabulary, Lexical helpers, staff resolution
|
|
```
|
|
|
|
## Dependency graph
|
|
|
|
```
|
|
Server actions ──┬── storageRules.ts
|
|
├── lib/banking/index.ts ──┬── format.ts
|
|
│ └── ui.ts
|
|
├── lib/market/index.ts ──┬── negotiations.ts
|
|
│ ├── npcs.ts
|
|
│ ├── npcDialogue.ts (pure, client-safe)
|
|
│ └── chatBubbles.ts (pure, client-safe)
|
|
├── lib/locker/index.ts ── search.ts
|
|
├── lib/attendance/index.ts
|
|
├── lib/notifications/index.ts
|
|
└── lib/tickets/
|
|
|
|
game-tick script ── shipping.ts, distance.ts, storageRules.ts
|
|
market-tick script ── lib/market/index.ts (autoPrice, autoQuantity, npc vendor logic)
|
|
```
|
|
|
|
## Pure vs Payload-dependent
|
|
|
|
- **Pure modules** (no Payload import, safe for client + server): `npcDialogue.ts`, `chatBubbles.ts`, `ticketMeta.ts`, `distance.ts`, `storageRules.ts` (logic only)
|
|
- **Payload-dependent** (import `@payload-config`, server-only): everything else
|
|
|
|
## Key modules
|
|
|
|
### `storageRules.ts`
|
|
Enforcement order: **prohibited → whitelist → per-item cap**. Functions: `checkStorageDeposit`, `isResourceProhibited`, `isResourceWhitelisted`, `getResourceStorageCap`, `storageViolationMessage`. Used in structure actions, shipment creation, and arrival processing.
|
|
|
|
### `banking/index.ts`
|
|
`applyTransaction()` — single source of truth for balance math. Validates accounts, creates transaction + ledger entries, updates balances. `ensurePersonalAccount()` — dedup find-or-create. `getMainCurrencyId()` — resolves Game Rules main currency.
|
|
|
|
### `market/index.ts`
|
|
`buyListing()` — validates, debits buyer, credits locker, marks sold. Supports partial buys via `quantity` parameter. `creditLockerQuantity()` — merges stackables or fills empty grid spots; throws if no space.
|
|
|
|
### `market/negotiations.ts`
|
|
NPC vendor pricing engine: stance starts at asking price, only moves down. Offers ≥ stance accepted; within 2% with 85% chance; well-below draw concession (30% of gap). Patience meter increments per round, closes at cap.
|
|
|
|
### `realtime/bus.ts`
|
|
Module-level subscriber Set. SSE endpoint `GET /api/realtime` subscribes; game tick POST `/api/game-tick/notify` broadcasts. **Single-instance only** — will not work across multiple server processes.
|
|
|
|
## Where to look
|
|
|
|
| Task | Path |
|
|
|------|------|
|
|
| Add storage rule logic | `storageRules.ts` (pure functions) |
|
|
| Modify transaction flow | `lib/banking/index.ts` — `applyTransaction()` |
|
|
| Change NPC pricing | `lib/market/negotiations.ts` — NPC_ACCEPT constants |
|
|
| Add notification type | `lib/notifications/notificationTypes.ts` |
|
|
| Add pure client+server logic | Verify no Payload import; place in appropriate domain dir |
|
|
|
|
## Anti-patterns
|
|
|
|
- **NEVER** import `@payload-config` in files under `market/npcDialogue.ts` or `market/chatBubbles.ts` — they must stay client-safe
|
|
- **NEVER** duplicate business logic in server actions — always delegate to `lib/{domain}/`
|
|
- **NEVER** use module-level state in `realtime/bus.ts` for cross-instance scenarios — use external pub/sub (Redis) instead
|
|
- **NEVER** mutate `storageRules.ts` enforcement order without updating all 3 call sites (structure actions, shipment creation, arrival processing)
|