psp_api/Agents.md

# GapCode Agent Instructions

# AGENTS.md

Operational guide for AI/coding agents working in `consumer_api`.

---

# ⚡ RTK LOW-TOKEN EXECUTION POLICY (MANDATORY)

This repository uses **RTK (Rust Token Killer)**.

All shell interactions MUST prefer RTK wrappers to reduce token usage.

If an RTK equivalent exists, **never use the raw command**.

This repository can be large; uncontrolled shell output will quickly exhaust model context.

---

# ✅ COMMAND REWRITE RULES (STRICT)

Always rewrite commands using RTK:

git status → rtk git status
git diff → rtk git diff
git log → rtk git log
ls → rtk ls
tree → rtk ls
cat <file> → rtk read <file>
grep <pattern> → rtk grep <pattern>
rg <pattern> → rtk grep <pattern>
find → rtk find

Never run:

- raw git commands for inspection
- raw cat
- raw grep
- raw ls
- raw tree

---

# 📂 CODE NAVIGATION WORKFLOW (MANDATORY)

When working in this repository follow this order:

1️⃣ Discover structure

rtk ls

2️⃣ Search before opening files

rtk grep <symbol | class | function | DTO | service>

3️⃣ Read only the necessary files

rtk read <file>

4️⃣ For large files (>300 lines)

rtk read <file> -l aggressive

5️⃣ For quick understanding

rtk smart <file>

Never open many files blindly.

Never read entire modules without searching first.

---

# 🧠 DIFF INSPECTION RULES

For reviewing repository changes:

Use:

rtk git diff

For large diffs:

rtk git diff -l aggressive

Never run raw `git diff`.

---

# 📁 FORBIDDEN PATHS

Never inspect or read these directories unless explicitly required:

node_modules/
dist/
build/
coverage/
.prisma/
prisma/migrations/

These folders produce extremely large outputs and waste tokens.

---

# 📄 FILE READING POLICY

Preferred:

rtk read file.ts

Large file:

rtk read file.ts -l aggressive

Quick overview:

rtk smart file.ts

Never use `cat` for source code inspection.

---

# 🔎 SEARCH POLICY

Always search before opening files.

Use:

rtk grep <pattern>

Avoid raw recursive searches.

---

# 🎯 TOKEN SAFETY RULES

- Never scan the entire repository.
- Never dump full logs.
- Never output entire large files.
- Prefer targeted inspection.

Token preservation is mandatory for this project.

---

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

## Thread Notes (May 2026)

- Shared sale-invoice creation was introduced and must be injected/exported correctly in consuming modules (example failure: `UnknownDependenciesException` for `SharedSaleInvoiceCreateService`).
- In `SalesInvoiceTspService.revoke`, prepare all creation/update data from `relatedInvoice` (no external `dataToUpdate` argument expected).
- Prisma client is generated to `src/generated/prisma` via:
  - `provider = "prisma-client"`
  - `output = "../../src/generated/prisma"`
  - `moduleFormat = "cjs"`
- Docker/runtime must include generated Prisma artifacts and `@prisma/client` runtime; missing `@prisma/client/runtime/client` indicates build/copy/install mismatch.
- Seeder commands that use `tsx` require dev dependencies/runtime tools; if running in slim production container, use a dedicated seed target/container or run seed from build/dev image.
- `pnpm` invocation in containers should use executable form (`pnpm ...`), not `node /app/pnpm`.
- Added SQL/Prisma error normalization utility: `src/common/utils/prisma-error.util.ts`; prefer mapping duplicate/constraint DB errors to domain-friendly messages.
- Partner-module list endpoints were standardized toward `ResponseMapper.paginate` where pagination response contract is expected.
- For heavy license provisioning (100+), request path should not synchronously insert all licenses; queue/background + batching is required.

## Migration Drift Playbook (Prisma/MySQL)

- If Prisma reports `modified after applied`, never edit an already-applied migration in-place for shared environments; create a new forward migration instead.
- If migration history and DB drift mismatch:
  1. Verify local migration folders are complete and ordered.
  2. Check `_prisma_migrations` for missing/applied names.
  3. Use `prisma migrate resolve` only to reconcile history state, then apply a forward fix migration.
- Duplicate FK error seen in this repo: `sales_invoices_ref_id_fkey` (MySQL 1826). Recheck migration SQL for repeated `ADD CONSTRAINT` statements before rerun.
- Drift that repeatedly showed in this project: missing FK/unique on `sale_invoice_tsp_attempts.invoice_id`. Validate both schema and migration SQL produce the same final state.
- `prisma migrate status` may show up-to-date while `migrate dev` still detects drift (shadow DB/application history issue); treat `migrate dev` output as source of truth for fixing local history.

## Redis Cache Conventions (May 2026)

- Use `RedisKeyMaker` in `src/common/utils/redis-key-maker.util.ts` for all cache keys and wildcard patterns; do not inline key strings in services.
- Keep invalidation domain-based (for example `src/modules/admin/guilds/cache/*`, `src/modules/admin/partners/cache/*`, `src/modules/pos/cache/*`) and avoid duplicating delete logic across modules.
- For list APIs that are expensive or frequently read, prefer read-through cache with TTL and invalidation on every related write path.
- For entity endpoints, use list + detail split:
  - list key(s): invalidated broadly on writes,
  - detail key(s): invalidated per entity id.
- Partner domain rules:
  - Shared partner cache namespace is `partners:*` (not admin-prefixed) because writes occur in both `admin/partners` and `partners` modules.
  - Use shared invalidation service `src/modules/partners/cache/partners-cache-invalidation.service.ts` from both admin and partner write paths.
  - Invalidate `partners:list` and `partners:{id}:detail` on partner create/update/delete and license-affecting writes.
  - Invalidate partner license caches (activated-licenses list, charge-transactions list/detail) via the shared invalidation service.
- POS goods rules:
  - Cache key shape is BA + guild scoped (`pos:ba:{businessActivityId}:guild:{guildId}:goods:list`) because results combine guild-default and BA-owned goods.
  - Invalidate POS goods cache by guild when admin guild goods/category/sku changes.
  - Invalidate POS goods cache by business activity when consumer BA goods create/update/delete.
- Consumer/Partner hierarchy rules:
  - Consumer profile cache key: `consumers:{consumerId}:info`.
  - Partner-consumer profile cache key: `partners:{partnerId}:consumers:{consumerId}:info`.
  - On partner-consumer single read, write both keys when practical to share warm cache across modules.
  - On consumer info update or partner-consumer update, invalidate both consumer and partner-consumer profile keys.
  - For business activities, invalidate both list and detail layers; child updates may invalidate parent single cache when parent aggregates depend on child state.
- Wildcard invalidation implementation:
  - Use `RedisService.deleteByPattern` / `RedisService.deleteByPatterns` for all pattern deletes.
  - Do not implement ad-hoc scan/delete loops inside domain services.
  - Pattern deletion uses `SCAN` + pipelined `DEL`; multi-pattern deletes run in parallel.