psp_api/AGENT.md

AGENT.md

Operational guide for AI/coding agents working in consumer_api.

Scope

• Applies to the whole repository.
• Stack: NestJS + Prisma + TypeScript.

Primary Goals

• Deliver minimal, safe, and focused changes.
• Preserve existing API behavior unless explicitly requested.
• Keep Prisma schema/data operations forward-safe.

Project Conventions

• Keep module layering consistent: controller -> service -> prisma/shared service.
• Reuse shared services for cross-module business logic (for example, sales invoice create flow).
• Keep DTO validation at API boundaries; avoid unchecked any in new code.
• Keep response shaping aligned with existing ResponseMapper usage.
• Prefer explicit Prisma select/include to control payload shape.

Sales Invoice / TSP Rules

• originalSend, correctionSend, and revoke flows should be consistent and auditable.
• For correction/revoke creation, prepare data from the related invoice when required.
• Persist attempt records with clear status transitions (QUEUED -> final status).
• Store request/response payloads for traceability.
• Avoid changing fiscal/tax status semantics without explicit approval.

Prisma and Migration Safety

• Treat committed migrations as immutable history.
• Prefer forward migrations; avoid destructive resets unless explicitly requested.
• For data-affecting changes:
  • use transactions,
  • verify expected row scope,
  • keep logic idempotent where possible.

Editing Principles

• Do not modify unrelated files.
• Do not revert user changes unless asked.
• Keep functions cohesive; extract shared logic when duplication appears.
• Remove debug leftovers (console.log, dead code) before finishing unless explicitly needed.

Validation Checklist (before handoff)

1. Read target module/service/DTO end-to-end before edits.
2. Apply minimal patch with consistent naming.
3. Run typecheck: pnpm -s tsc --noEmit.
4. If behavior changed, run targeted checks/tests where possible.
5. Summarize changed files and behavior impact clearly.

Useful Commands

• Typecheck: pnpm -s tsc --noEmit
• Migration status: pnpm prisma migrate status
• Create migration: pnpm prisma migrate dev --name <name>
• Deploy migrations: pnpm prisma migrate deploy

Communication Style

• Be concise and implementation-focused.
• Call out assumptions/risk before risky steps.
• Provide practical next actions after task completion.

Do / Don't (Repo-Specific)

Do

• Do derive correction/revoke invoice creation data from relatedInvoice when the flow requires historical consistency.
• Do keep TSP attempt lifecycle explicit (QUEUED, then update with provider result and timestamps).
• Do use shared invoice-creation service instead of duplicating create logic across modules.
• Do normalize numeric DB values (Decimal) with Number(...) before DTO/payload composition.
• Do keep Prisma queries tight with select/include only for fields you actually use.

Don't

• Don't pass undefined/out-of-scope variables in TSP flows (common regressions: invoice_id, attemptId, pos_id mismatches).
• Don't leave placeholder query blocks (for example empty select: {}) in production code.
• Don't mix method semantics (send vs originalSend) across services without verifying signatures.
• Don't leave debug logs (console.log) in critical invoice/tax paths unless explicitly requested.
• Don't change invoice type semantics (ORIGINAL, CORRECTION, REVOKE) implicitly.

Common Pitfalls To Recheck

• Incorrect relation field names (tax_id on wrong model, missing relation selects).
• Building payloads from the wrong invoice (must match the expected new/ref invoice in each flow).
• Creating attempts without persisting request payload and final response payload.
• Mismatch between DTO shapes and shared service input contracts.