hamid
2f2aec61a2
Lay the cross-cutting platform backbone every later phase reads from. Adds the first marketplace EF migration baseline (new `ops` schema) and the mechanisms b2..b15 reuse: typed runtime config, an append-only audit trail, an analytics event log, the holiday/bank-closure calendar, in-app notifications, and the internal support-alert worklist. Schema & migration - New `ops` schema + migration InitialMarketplaceBaseline with 6 tables: PlatformConfigs (IAuditable), AuditLogs (append-only), SystemEvents, IranianHolidays, Notifications, SupportAlerts — with indexes/uniques and FKs to usr.Users. Seeded 12 config keys + 7 sample holidays via HasData. Domain / Application - IAuditable marker + [AuditRedacted] attribute; entities + string-code constant holders (config data_type, holiday type, alert type/severity/status). - Facade contracts: IPlatformConfig, IHolidayCalendar, IAnalyticsSink, IAuditLogger, INotificationService, ISupportAlertService; DTOs + PagedResult<T>; evolved the INotificationDispatcher.Notification record to carry Type + DataJson; Pagination helper. - 14 CQRS commands/queries (+ validators) wiring the endpoints to the facades. Infrastructure - DB-backed facade implementations in Persistence/Services/; real in-app INotificationDispatcher (removes the b0 log stub); notification-retention hosted service (purge is_read=1 AND age>90d). - Extended AuditFieldInterceptor to also append an old/new-diff audit_logs row for every IAuditable change in the same transaction (PII redacted). - Registered all facades + hosted service in AddPersistenceServices; removed the dispatcher registration from AddCrossCuttingSeams. API - 5 controllers: admin PlatformConfig/Holidays/Audit/SupportAlerts ([Authorize(DynamicPermission)]) + current-user Notifications ([Authorize]), all tenant-scoped and paginated. 16 Swagger paths total. Money-correctness & safety rules honoured - Config read at compute time (cached, parsed by data_type), never hardcoded; every config change is audited in the same transaction; audit_logs is append-only (no update/delete path); support alerts are admin-only; notifications are tenant-scoped; analytics is fire-and-forget. Tests & docs - 18 new foundation tests over in-memory SQLite (config typing + audit, holidays, notifications + tenancy + retention, support alerts, analytics); build clean (0 new code warnings), 22 tests green; migration applied to the dev DB and swagger.v1.json refreshed. - Updated server Project map + CONVENTIONS, product data-model doc 12 (seeded config defaults), config-reference contract, mock registry, backend handoff/ STATUS/report. Follow-ups: add FK constraints for SupportAlerts.BookingId (b9) and ReviewId (b14) when those tables land. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contracts — the shared interface between client/ and server/
The two projects are independent (no shared build). This folder is their single shared source of truth for everything that crosses the wire: API routes, request/response shapes, status codes, enums, shared flows, and money/format conventions. It lets a frontend agent build against a stable contract before, during, and after the matching backend phase, and it lets the two run in parallel.
Ownership (this is what makes parallel work safe)
- Backend owns and writes
contracts/domains/*andcontracts/openapi/*. A backend phase that ships an API writes/updates the contract in the same change. - Frontend reads contracts and derives its TypeScript types from them. The frontend never edits
files here. If a contract is missing or wrong, the frontend appends a request to
../shared-working-context/frontend/requests/for-backend.md; the backend delivers the fix in a later change.
What's here
| Path | What it is |
|---|---|
conventions/api-conventions.md |
The envelope, routing, pagination, errors, auth, locale — read first. |
conventions/money-and-types.md |
How money, dates, enums, gender, IDs are represented on the wire. |
domains/_TEMPLATE.md |
The shape every per-domain contract doc follows. |
domains/<domain>.md |
One file per domain (identity, catalog, booking, payments, …), added by the backend phase that ships it. |
openapi/ |
The published swagger.json snapshot(s) — the machine-readable contract for type generation. |
How a contract is produced (backend)
- Build the endpoints following
server/CONVENTIONS.md. - Write/extend
domains/<domain>.mdfromdomains/_TEMPLATE.md: every route, its method + snake_case path, auth/policy, request and response JSON (with a real example), the enums it uses, and the error cases. Reference, don't restate,conventions/*. - Publish the OpenAPI snapshot per
openapi/README.md. - Note in your handoff (
shared-working-context/backend/handoff/after-backend-phase-N.md) that the contract is live.
How a contract is consumed (frontend)
- Read
domains/<domain>.md+conventions/*. Derive types insrc/services/{domain}/types.ts(or generate fromopenapi/swagger.json) — keep names aligned with the contract. - If something is missing/ambiguous, request it (don't guess) and mock behind the
services/{domain}seam meanwhile.
Keep contracts versioned by being honest: when a shipped shape changes, update its
domains/*doc and the OpenAPI snapshot in the same change, and call it out in the handoff so the frontend re-syncs.