feat(analytics-trust): real per-connection earliest-order-date read

[jakubretajczykBD]

Summary

• Adds OrderRecordRepositoryPort.findEarliestPlacedAtByConnection — one batched GROUP BY query (MIN(COALESCE(placedAt, createdAt)) per connection), not a per-connection fan-out.
• Adds the IOrderRecordService.getEarliestOrderDateByConnection cross-context seam analytics-trust consumes it through (mirrors the existing getFailedSyncValueSummary pattern).
• AnalyticsTrustService.getIngestionTrustSnapshot calls it exactly once, batched across every enumerated connection, before the existing per-connection job-lookup fan-out.
• New ConnectionIngestionTrust.earliestOrderDate field, threaded through GET /analytics/trust's DTO/controller.
• docs/architecture-overview.md dependency map gains the analytics-trust --> orders edge.

Implements #2083. Full implementation plan: docs/plans/implementation-plan-analytics-trust-earliest-order-date.md.

Base branch note: targets 1985-order-analytics-read-model, not main — #2083 is explicitly blocked by #1985 (needs order_records.placedAt, which only exists on that branch today). Rebase onto main once #1985 merges.

Test plan

• pnpm --filter @openlinker/core type-check — clean
• pnpm --filter @openlinker/api type-check — clean
• pnpm --filter @openlinker/worker type-check — clean
• Targeted unit tests (repository, service, AnalyticsTrustService, controller DTO mapping) — green
• ESLint on all changed files — 0 errors/warnings
• check-cross-context-imports, check-service-interfaces, check-workspace-dep-declarations — pass
• pnpm test:integration — not run in this environment; no int-spec added per plan's rationale (matches getFailedSyncValueSummary/countByHealth, unit-tested only)

Known pre-existing issue, not introduced here: pnpm lint's check:invariants chain currently fails on a migration-timestamp collision already present on 1985-order-analytics-read-model (1833000000004-add-order-analytics-read-model.ts vs. main's 1833000000004-add-identifier-mappings-offer-created-index.ts), confirmed via git stash to exist independent of this PR's changes. Also pre-existing and unrelated: OrdersController › listOrders › should serialize cancelledAt as an ISO string fails on the base branch too.

[piotrswierzy]

Tech-lead review — 🔄 Close; one behavioural regression to fix first

Scope assessed: diffed against 1985-order-analytics-read-model — this PR's own base, not main. That isolates 21 files: the findEarliestPlacedAtByConnection port/repo/service chain, its consumption in analytics-trust, the DTO/controller field, specs and a plan doc. The 1985 read-model work itself isn't assessed here.

Two things I went in expecting to find aren't there. This is not a stub replacement — it's purely additive; on the base branch ConnectionIngestionTrust had no earliest-order-date field at all, and connectionCreatedAt was already documented as explicitly not a coverage claim. So no caller depended on an old shape. And the N+1 across connections isn't present — it's actively defended against.

IMPORTANT

1. The batched lookup sits outside the per-connection isolation boundary. analytics-trust.service.ts:88-90

This service's own file header states the contract: "a single connection's build failure is caught and degraded to an 'unknown' entry rather than failing the whole snapshot." The new getEarliestOrderDateByConnection call sits before the Promise.all, unguarded — so a transient DB error on this one supplementary field now throws out of getIngestionTrustSnapshot and 500s the entire /analytics/trust endpoint.

Before this PR, no single data read could do that. That's a real regression in the availability posture of a page whose whole job is to still tell you something when things are broken — and it's the read #2115 gates its page render on, so the blast radius is the analytics page going blank rather than degrading.

The fix matches the design already in the file: wrap it, log, fall back to an empty Map. Every connection then reports earliestOrderDate: null, which the type and DTO already model as unknown. Note the existing comment at :181 reasons carefully about this lookup being independent of the job lookup's failure — it just doesn't consider the lookup itself failing.

2. No integration test for the actual SQL. order-record.repository.spec.ts:190-261 asserts where/groupBy/addSelect were called with the right strings — a change-detector, not a correctness check. MIN(COALESCE("placedAt", "createdAt")) with GROUP BY over a mixed null/non-null placedAt population is exactly what one Testcontainers assertion is for, including that the pg driver hands back a Date for the raw earliest_at alias (the code types it Date at :102 on faith). Confirmed nothing under apps/api/test or apps/worker/test touches earliestOrderDate.

Suggestions

• Index support is adequate, not ideal. @Index(['sourceConnectionId']) and the separate placedAt index mean the IN (...) filter is index-supported and this isn't a seq scan — correctly, no migration was needed. But neither index covers the aggregate, so Postgres still heap-fetches every matching row to evaluate the MIN(COALESCE(...)). On a connection with hundreds of thousands of orders that's a real cost on a page-load-blocking read. A composite (sourceConnectionId, placedAt) would let it index-scan, though COALESCE defeats a pure index-only min. Not worth a migration today — worth a note if this endpoint ever shows up slow.
• :88 computes connectionIds even when entries is empty — harmless, since the repository short-circuits [] without querying, which is the right call and is tested.

Worth calling out

• One aggregate, not N queries — a single GROUP BY hoisted above the Promise.all fan-out, with a spec asserting toHaveBeenCalledTimes(1) and pinning the exact id array, so a future refactor pushing it into buildTrustEntry fails the build. That's the defect being pre-empted rather than shipped and then found in review.
• Absent data is reported as unknown, never defaulted to healthy — verified end to end: a connection with zero orders is omitted from the Map rather than defaulted, the service resolves ?? null, the type is Date | null, the DTO is nullable: true, and the controller null-guards the toISOString(). Three specs cover present / absent / degraded. The DTO description even warns "do not confuse with connectionCreatedAt" — the exact conflation #2037 was blocked on.
• The recordStatus non-filter is a documented decision, not an omission — the port JSDoc argues it against getFailedSyncValueSummary's NOT_MAPPING_OR_DELETED gate (coverage fact vs value figure), and a spec asserts andWhere is never called so nobody "helpfully" adds a filter later. Encoding the decision as a test is the right move.
• Cross-context contract holds: only IOrderRecordService + its token cross the boundary, OrdersModule for imports: only, no repository port leaking. No any; the raw row shape is typed via getRawMany<{…}>.

CI: only Scaffolded Adapter Builds has reported (success) on 71706cf6; everything else is pending with total_count: 0. Nothing red, nothing meaningful run.

Merge readiness: 🔄 Close. Finding 1 is a ~5-line fix to a resilience property this service documents about itself, and I'd want it before merge; 2 is cheap now and expensive later. Everything else is advisory. Targets 1985-order-analytics-read-model, so it lands after that.

[jakubretajczykBD]

Summary

This is a tightly-scoped, well-executed PR that adds a real MIN(COALESCE(placedAt, createdAt)) earliest-order-date read to the analytics-trust snapshot, replacing the misleading connectionCreatedAt proxy. It follows the getFailedSyncValueSummary port→service→cross-context-consumer precedent almost verbatim, respects the cross-context contract (IOrderRecordService, never the repository port), batches the query correctly (no N+1), and — across its three commits — proactively fixed two review findings itself (documenting the unfiltered recordStatus scope, and isolating the batch-lookup failure so one bad read doesn't kill the whole /analytics/trust snapshot). Test coverage is thorough at every layer including a new Testcontainers int-spec for the aggregate query. No blocking issues found.

Issues

[SUGGESTION] — libs/core/src/analytics-trust/analytics-trust.module.ts

Importing the full OrdersModule pulls in its entire provider graph (IntegrationsModule, IdentifierMappingModule, SyncModule, ProductsModule, MappingsModule, OrderSyncService, OrderIngestionService, etc.) just to obtain IOrderRecordService. This is explicitly flagged and accepted in the PR's own implementation plan as a pre-existing NestJS all-or-nothing-module cost, not a new problem — no narrower "orders read-only" sub-module exists today. Not asking for a fix here, just flagging for anyone auditing module-boot cost later.

[SUGGESTION] — libs/core/src/orders/infrastructure/persistence/repositories/order-record.repository.ts:87

The raw MIN(COALESCE(rec."placedAt", rec."createdAt")) fragment hardcodes quoted column names rather than using TypeORM's own identifier resolution (as .select/.groupBy do via rec.sourceConnectionId). No injection risk (no interpolated user input) and it matches the existing getFailedSyncValueSummary raw-aggregate style in the same file, so this is consistent with house style — just noting it as the one place a future column rename could silently drift from the entity's @Column mapping without a compile error.

[SUGGESTION] — apps/api/src/orders/http/refunds.controller.spec.ts / shipping/*.spec.ts

The new getEarliestOrderDateByConnection: jest.fn() mock entries were inserted at slightly different positions across the five updated spec files relative to their sibling mock properties. Purely cosmetic — TS/jest don't care about property order — but worth a quick pass if these files get touched again.

None of the above block merge.

Verdict

✅ Approve — architecture-compliant (cross-context seam via IOrderRecordService, batched query, no repository-port leakage), correctly threaded through domain type → DTO → controller, comprehensive unit + integration test coverage, and the PR history shows the two most important correctness concerns (unfiltered recordStatus semantics, batch-failure isolation) were already caught and fixed pre-review.

---

🤖 Generated with Claude Code tech-review