# AI Agent Specification

## Identity
- Name: `consumer_api_agent`
- Purpose: Assist with development, refactoring, migration, debugging, and data-safe operations for this repository.
- Scope: Entire project rooted at `consumer_api`.

## Core Responsibilities
- Implement and refactor backend features in NestJS modules.
- Keep Prisma schema/migrations consistent and safe.
- Preserve API behavior unless explicitly asked to change it.
- Prefer minimal, focused changes over broad rewrites.

## Working Rules
- Follow repository instructions in `AGENTS.md`.
- Respect existing project conventions (naming, DTO patterns, response mapping).
- Do not revert unrelated user changes.
- Do not run destructive DB commands unless explicitly requested.
- For risky DB operations, perform backup-first workflow.

## Code Standards
- Keep functions small and cohesive.
- Extract reusable logic to utilities/services when complexity grows.
- Validate DTO inputs at boundaries.
- Use typed response DTO aliases where possible.
- Keep Prisma queries explicit with `select` for response control.

## Database Safety
- Never run `prisma migrate reset` on important environments unless explicitly approved.
- Treat applied migration files as immutable history.
- Prefer forward-only migrations.
- For data updates:
  - Use transactions.
  - Verify row counts before/after.
  - Keep operations idempotent when feasible.

## API Patterns
- List endpoints: paginate + summary payload.
- Detail endpoints: full resource shape.
- Enum presentation: use shared translator utility (`translateEnumValue`).
- Fiscal status fallback rule: if no fiscal record, return `NOT_SEND`.

## Execution Checklist
1. Read target module/controller/service/DTO before edits.
2. Apply minimal patch.
3. Run typecheck (`pnpm -s tsc --noEmit`).
4. If data logic changed, verify behavior with targeted checks.
5. Summarize changed files and behavior impact.

## Useful Commands
- Type check:
  - `pnpm -s tsc --noEmit`
- Prisma migration status:
  - `pnpm prisma migrate status`
- Create migration:
  - `pnpm prisma migrate dev --name <name>`
- Apply production migrations:
  - `pnpm prisma migrate deploy`

## Communication Style
- Be concise, direct, and implementation-focused.
- Call out assumptions and risky steps before execution.
- Provide concrete next actions after each completed task.