Commit inicial - upload de todos os arquivos da pasta

2026-07-24 23:55:21 -03:00
commit 9d4d395881
88 changed files with 9484 additions and 0 deletions
@@ -0,0 +1,40 @@
+## ADDED Requirements
+
+### Requirement: Single AI Attempt Per Document
+The system SHALL make at most one AI categorization call per fiscal document per ingestion attempt and SHALL NOT automatically retry a failed AI categorization call.
+
+#### Scenario: AI categorization call fails
+- **WHEN** the AI categorization call for a document errors or times out
+- **THEN** the system does not retry the AI call for that document and proceeds directly to keyword fallback
+
+### Requirement: Supplier Categorization Cache
+The system SHALL cache the category determined for a given supplier name (in-memory or persisted) and SHALL reuse the cached category for subsequent documents from the same supplier instead of calling the AI again.
+
+#### Scenario: Second document from a known supplier
+- **WHEN** a fiscal document is processed for a supplier name that already has a cached category from a prior categorization
+- **THEN** the system uses the cached category and does not issue a new AI categorization call
+
+#### Scenario: Cache miss for a new supplier
+- **WHEN** a fiscal document is processed for a supplier name with no cached category
+- **THEN** the system proceeds with the normal AI-then-keyword categorization flow and stores the result in the cache
+
+### Requirement: Per-Batch AI Call Limit
+The system SHALL enforce a configurable maximum number of AI categorization calls within a single import batch (or time window). Once the limit is reached, remaining documents in that batch SHALL be categorized using only the keyword fallback, with no further AI calls, until the batch/window resets.
+
+#### Scenario: Limit reached mid-batch
+- **WHEN** the number of AI categorization calls in the current batch reaches the configured maximum
+- **THEN** subsequent documents in the same batch skip the AI call and go directly to keyword fallback (or "Sem categoria" if no keyword matches)
+
+### Requirement: Configurable Safety Limits
+The maximum AI calls per batch and cache behavior SHALL be configurable via application configuration/environment variables, not hardcoded in the categorization logic.
+
+#### Scenario: Operator changes the configured limit
+- **WHEN** the configured maximum AI calls per batch is changed
+- **THEN** the categorization flow honors the new limit on the next run without code changes
+
+### Requirement: Observability of Skipped AI Calls
+When an AI categorization call is skipped due to the cache or the per-batch limit, the system SHALL log the reason (cache hit or limit reached) so the behavior is observable and auditable.
+
+#### Scenario: Skip logged
+- **WHEN** the system skips an AI categorization call because of a cache hit or because the batch limit was reached
+- **THEN** a log entry is recorded indicating which reason caused the skip and for which document/supplier