refactor: streamline Redis caching logic across services
- Implemented a unified `getAndSet` method in RedisService to handle caching for single, list, and paginated responses. - Removed redundant cache checks and writes in various services, simplifying the code and improving readability. - Updated GoodsService, StockKeepingUnitsService, PartnerActivatedLicensesService, and others to utilize the new caching mechanism. - Adjusted Prisma connection limit for better resource management.
This commit is contained in:
@@ -1,17 +1,162 @@
|
||||
# AGENT.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.
|
||||
@@ -19,6 +164,7 @@ Operational guide for AI/coding agents working in `consumer_api`.
|
||||
- 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).
|
||||
@@ -26,6 +172,7 @@ Operational guide for AI/coding agents working in `consumer_api`.
|
||||
- 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:
|
||||
@@ -34,12 +181,14 @@ Operational guide for AI/coding agents working in `consumer_api`.
|
||||
- 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`.
|
||||
@@ -47,12 +196,14 @@ Operational guide for AI/coding agents working in `consumer_api`.
|
||||
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.
|
||||
@@ -60,6 +211,7 @@ Operational guide for AI/coding agents working in `consumer_api`.
|
||||
## 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.
|
||||
@@ -67,6 +219,7 @@ Operational guide for AI/coding agents working in `consumer_api`.
|
||||
- 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.
|
||||
@@ -74,12 +227,14 @@ Operational guide for AI/coding agents working in `consumer_api`.
|
||||
- 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:
|
||||
@@ -94,6 +249,7 @@ Operational guide for AI/coding agents working in `consumer_api`.
|
||||
- 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.
|
||||
@@ -104,6 +260,7 @@ Operational guide for AI/coding agents working in `consumer_api`.
|
||||
- `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.
|
||||
|
||||
Reference in New Issue
Block a user