# 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.