# HACKER DIVERGENTS — CHECKPOINT FASE 21

**Checkpoint:** FASE 21 — NPC SYSTEM
**Estado geral estimado:** 91% concluído
**Última fase concluída:** 21D8B4
**Próxima fase:** 21D8C1 — NpcShopSaleId
**Banco:** `hacker_divergents`
**PHP:** 8.2.12
**MariaDB:** 10.4.32

---

## 1. ESTADO GERAL DA FASE 21

A Fase 21 implementa a fundação dos NPCs do Hacker Divergents e sua integração com:

* facções;
* reputação;
* relacionamento;
* lojas;
* estoque;
* restock;
* economia;
* hardware;
* fragmentos;
* blueprints;
* conhecimento;
* compras;
* vendas;
* progressão;
* rede virtual por rodada.

Estado estimado:

**91% concluído.**

Restante aproximado:

**9%.**

---

# 2. NPC FOUNDATION — CONCLUÍDO

NPC-1 está fechado.

Estruturas implementadas:

* `npc_factions`
* `npcs`
* `player_faction_reputation`
* `player_npc_relationships`

Estados de relacionamento oficiais:

* unknown
* known
* trusted
* respected
* hostile
* blacklisted

Estados oficiais de NPC:

* active
* offline
* hidden
* missing
* arrested
* retired

Facções iniciais:

1. BlackWire Collective
2. NetCore Industries
3. IronGrid Systems
4. Cipher Labs
5. SafeNet
6. Independent

NPCs iniciais:

* ZeroByte
* Cipher
* Patch
* GridMaster
* Volt
* Nexus
* Sentinel
* Hex
* Vector
* Ghost
* Null
* Agent Orion

NPC Foundation:

**100% CONCLUÍDO**

---

# 3. NPC SHOPS — CONCLUÍDO

Lojas iniciais:

* Cipher Code Exchange
* Patch Hardware
* Volt Hardware

Migrations:

* `000140_create_npc_shops.sql`
* `000141_seed_initial_npc_shops.sql`

Contrato:

* uma loja principal por NPC;
* loja pode ser ativada/desativada;
* NPC precisa existir;
* loja referencia NPC permanentemente.

Estado:

**100% CONCLUÍDO**

---

# 4. NPC SHOP INVENTORY — CONCLUÍDO

Migration:

* `000142_create_npc_shop_inventory.sql`

Tipos de produto:

* item
* fragment
* software_blueprint
* knowledge_artifact

Características:

* estoque finito;
* quantidade máxima;
* quantidade de restock;
* preço unitário;
* condição física;
* nível mínimo;
* reputação mínima;
* intervalo de restock;
* próxima data de restock;
* ativação individual da oferta.

Migration complementar:

* `000143_add_player_level_requirement_to_npc_shop_inventory.sql`

Seed inicial:

* `000144_seed_initial_npc_shop_inventory.sql`

Total inicial:

**19 ofertas.**

Estado:

**100% CONCLUÍDO**

---

# 5. PROGRESSÃO E RARIDADE — CONTRATO OFICIAL

Faixas:

* nível 0 — onboarding/tutorial
* níveis 1–3 — COMMON
* níveis 4–6 — UNCOMMON
* níveis 7–10 — RARE
* níveis 11–14 — EPIC
* nível 15 — LEGENDARY

Princípio oficial:

> Progressão aumenta poder, oportunidade e risco. Nenhuma vantagem econômica ou de nível pode tornar um jogador inalcançável durante a rodada.

Dinheiro sozinho não compra progressão.

Legendary não é estoque comum de loja.

Nível 15 apenas habilita oportunidades lendárias.

---

# 6. NPC STOCK EVENTS — CONCLUÍDO

Migration:

* `000145_create_npc_stock_events.sql`

Eventos:

* seed
* purchase
* restock
* manual_restock
* event_restock
* sale_to_npc
* adjustment

Migration:

* `000146_seed_initial_npc_stock_events.sql`

Um evento inicial foi registrado para cada oferta.

Estado:

**100% CONCLUÍDO**

---

# 7. NPC RESTOCK — CONCLUÍDO

Implementado:

* `NpcStockEventId`
* `NpcStockRestockService`
* `NpcStockRestockBatchService`
* runner CLI de restock

Runner:

* `bin\npc-stock-restock.php`

Contrato:

* lock da oferta;
* respeita intervalo;
* respeita quantidade máxima;
* ofertas controladas não fazem restock temporal;
* registra evento de estoque;
* preserva transações externas.

Estado:

**100% CONCLUÍDO**

---

# 8. NPC SHOP READ / ACCESS — CONCLUÍDO

Implementado:

* `NpcShopCatalogService`
* `NpcShopOfferAccessService`

Valida:

* loja ativa;
* NPC ativo;
* oferta ativa;
* estoque;
* nível;
* reputação.

Browsing não altera progressão.

Estado:

**100% CONCLUÍDO**

---

# 9. DELIVERY CONTRACTS — CONCLUÍDO

## Fragmentos

Usa:

`player_code_fragments`

Incremento de quantidade idempotente.

## Hardware

Usa:

`player_inventory`

Cada hardware físico é uma instância própria:

* `inv_...`
* quantity = 1
* condition_percent individual
* equipped = 0
* equipped_machine_public_id = NULL
* market_locked = 0

Serviço:

`InventoryAcquisitionService`

## Software Blueprint

Migration:

`000147_create_player_software_blueprints.sql`

Serviço:

`SoftwareBlueprintOwnershipService`

Origem NPC suportada:

`npc_shop`

## Knowledge Artifact

`SoftwareKnowledgeService`

Migration:

`000149_extend_software_knowledge_discovery_method_npc_shop.sql`

Método:

`npc_shop`

Estado dos delivery contracts:

**100% CONCLUÍDO**

---

# 10. JOGADOR COMPRA DO NPC — CONCLUÍDO

Migration:

`000148_create_npc_shop_transactions.sql`

Transaction ID:

`nst_...`

Serviço:

`NpcShopPurchaseService`

Fluxo atômico:

1. valida jogador;
2. valida quantidade;
3. valida idempotência;
4. trava jogador;
5. trava oferta;
6. valida loja/NPC/oferta;
7. valida estoque;
8. valida nível;
9. valida reputação;
10. valida ownership exclusivo;
11. calcula preço;
12. cria transação;
13. debita `CreditLedgerService`;
14. entrega produto;
15. reduz estoque;
16. registra `npc_stock_events.purchase`;
17. conclui transação.

Tipos operacionais:

* fragment
* hardware
* software blueprint
* knowledge artifact

Testes concluídos:

* compra atômica;
* debit;
* estoque;
* entrega;
* auditoria;
* replay idempotente;
* conflito de idempotência;
* hardware;
* blueprint;
* knowledge;
* guards;
* rollback;
* external transaction.

Suíte oficial:

`scripts\phase21d7b5-npc-shop-purchase-suite.ps1`

Resultado:

**PASS**

Estado jogador → NPC purchase:

**100% CONCLUÍDO**

---

# 11. JOGADOR VENDE PARA NPC — EM IMPLEMENTAÇÃO

## 21D8A — INSPEÇÃO

Concluída.

Nenhum dado alterado.

Contrato observado:

`player_inventory` possui:

* public_id
* player_public_id
* item_public_id
* quantity
* condition_percent
* equipped
* equipped_machine_public_id
* market_locked

Hardware atual:

* físico;
* não stackable;
* max_stack = 1.

Regras oficiais para venda:

* somente hardware inicialmente;
* venda por instância `inv_`;
* equipado não pode ser vendido;
* item vinculado a máquina não pode ser vendido;
* `market_locked = 1` não pode ser vendido;
* condição <= 0 não pode ser vendida;
* NPC precisa aceitar vendas;
* NPC precisa possuir oferta daquele item;
* oferta precisa possuir espaço;
* estoque NPC não pode ultrapassar `max_quantity`.

---

# 12. POLÍTICA DE RECOMPRA NPC — CONCLUÍDA

Migration:

`000150_add_player_sale_policy_to_npc_shops.sql`

Campos:

* `accepts_player_sales`
* `buyback_rate_percent`

Configuração inicial:

### Patch Hardware

* aceita vendas: SIM
* buyback: 50%

### Volt Hardware

* aceita vendas: NÃO

### Cipher Code Exchange

* aceita vendas: NÃO

Auditoria:

`phase21d8b2-npc-player-sale-policy-check.php`

Resultado:

**PASS**

Migration `000150`:

**IMUTÁVEL**

---

# 13. NPC SHOP SALES — DATABASE FOUNDATION CONCLUÍDA

Migration:

`000151_create_npc_shop_sales.sql`

Tabela:

`npc_shop_sales`

Campos principais:

* public_id
* idempotency_key
* player_public_id
* shop_public_id
* shop_inventory_public_id
* player_inventory_public_id
* item_public_id
* quantity
* condition_percent
* base_value
* buyback_rate_percent
* payout_amount
* status
* completed_at
* timestamps

Status:

* processing
* completed
* failed

Quantidade física:

`quantity = 1`

A tabela registra:

* jogador vendedor;
* loja compradora;
* oferta NPC receptora;
* instância física vendida;
* item;
* condição;
* valor base;
* taxa aplicada;
* payout final;
* idempotência;
* lifecycle comercial.

Auditoria:

`phase21d8b4-npc-shop-sales-database-check.php`

Resultado:

**PASS**

Migration `000151`:

**IMUTÁVEL**

---

# 14. PREÇO DE RECOMPRA

Contrato inicial:

`payout = base_value × condition_percent × buyback_rate_percent`

Percentuais são convertidos corretamente antes do cálculo.

Patch:

`50%`

A condição física reduz o payout.

O payout será calculado server-side.

O cliente nunca poderá informar o valor final.

---

# 15. CREDIT LEDGER NA VENDA

NPC pagando o jogador introduz créditos na economia.

Portanto é obrigatório usar:

`CreditLedgerService::credit()`

Nunca alterar diretamente:

`players.credits`

Categoria planejada:

`npc_shop_sale`

Source type planejado:

`npc_shop_sale`

Source public ID:

ID da operação `npc_shop_sales`.

A operação inteira deverá possuir idempotência própria.

---

# 16. PRÓXIMA ETAPA EXATA

## FASE 21D8C1

Criar:

`NpcShopSaleId`

Prefixo planejado:

`nss_`

Formato:

`nss_` + 32 caracteres hexadecimais minúsculos.

Depois:

## 21D8C2

Criar serviço atômico:

`NpcShopSaleService`

Fluxo previsto:

1. validar IDs;
2. validar idempotency key;
3. travar jogador;
4. travar instância `player_inventory`;
5. validar ownership;
6. validar equipamento;
7. validar machine attachment;
8. validar market lock;
9. validar condição;
10. travar loja;
11. validar accepts_player_sales;
12. localizar/travar oferta NPC;
13. validar espaço;
14. calcular payout server-side;
15. criar `npc_shop_sales`;
16. creditar jogador via ledger;
17. remover instância do inventário;
18. aumentar estoque NPC;
19. registrar `npc_stock_events.sale_to_npc`;
20. completar venda;
21. commit somente se o serviço possuir a transação.

Depois serão necessários:

* teste de venda atômica;
* teste de payout;
* teste do ledger;
* teste de stock increment;
* teste do `sale_to_npc`;
* teste de equipped guard;
* teste de machine guard;
* teste de market_locked;
* teste de condição;
* teste de estoque cheio;
* teste de loja sem recompra;
* teste de idempotência;
* teste de rollback;
* suíte permanente.

---

# 17. FASE 21R — AINDA PENDENTE

Após fechamento da economia NPC:

**FASE 21R — Round Network Rotation**

Regra oficial:

Cada nova rodada muda os IPs virtuais.

Identidade do servidor permanece.

Endpoint operacional muda.

Jogador precisa redescobrir o IP em cada rodada.

Descoberta antiga não revela automaticamente o novo endpoint.

Histórico pode permanecer.

Integração planejada:

* `virtual_network_endpoints`
* `player_server_discoveries`

NPCs não armazenarão IP operacional diretamente.

---

# 18. ESTADO FINAL DESTE CHECKPOINT

NPC Foundation........................ 100%

NPC Factions/Reputation............... 100%

NPC Shops............................. 100%

NPC Stock............................. 100%

NPC Restock........................... 100%

NPC Shop Read/Eligibility............. 100%

NPC Purchase.......................... 100%

NPC Player Sale....................... ~45%

Round Network Rotation................ PENDENTE

FASE 21 TOTAL......................... ~91%

RESTANTE.............................. ~9%

---

## PONTO DE RETOMADA

Retomar exatamente em:

**FASE 21D8C1 — NpcShopSaleId**

Não alterar migrations:

`000140` até `000151`.

Todas são consideradas aplicadas e imutáveis.

Última validação:

**PHASE 21D8B4 NPC SHOP SALES DATABASE: PASS**
