Projeto de TIC #631

Entidades foram modificadas e outras foram criadas. Essa migration resolverá essa parte

\[BE] Enum: AcaoPenaMulta em penamulta/ — valores: CALCULAR, SALVAR\_CALCULO, GERAR\_PDF, REIMPRIMIR\_PDF, RECALCULAR, BAIXA\_MANUAL, BAIXA\_LOTE, ALTERAR\_INDICE, AUTORIZAR\_INDICE\_DESATUALIZADO

Consolidando e padronizando os requisitos mapeados na planilha

Elaboração da Feature Spec da FT-PM-01 - Realizar Cálculo da Pena Multa. Descrição completa no projeto java em docs/penamulta/FT-PM-01-realizar-calculo.md

Elaboração da Feature Spec da \[EP-PM-01] - FT-PM-02 - Registrar e visualizar memória de cálculo Descrição completa no projeto java em `docs/penamulta/FT-PM-02-memoria-calculo.md`

Elaboração da Feature Spec da \[EP-PM-01] - FT-PM-03 - Recalcular pena multa Descrição completa no projeto java em `docs/penamulta/FT-PM-03-recalcular.md`

Elaboração da Feature Spec da \[EP-PM-02] - FT-PM-04 - Gerenciar salário mínimo. Descrição completa no projeto java em `docs/penamulta/FT-PM-04-salario-minimo.md`

Elaboração da Feature Spec da \[EP-PM-02] - FT-PM-05 - Gerenciar IPCA-E. Descrição completa no projeto java em docs/penamulta/FT-PM-05-ipca-e.md

Elaboração da Feature Spec da \[EP-PM-02] - FT-PM-06 - Gerenciar SELIC Descrição completa no projeto java em `docs/penamulta/FT-PM-06-selic.md`

Elaboração da Feature Spec da \[EP-PM-02] - FT-PM-07 - Controlar atualização de índices Descrição completa no projeto java em `docs/penamulta/FT-PM-07-controle-atualizacao.md`

Elaboração da Feature Spec da \[EP-PM-03] - FT-PM-08 - Emitir certidão de cálculo da pena multa Descrição completa no projeto java em docs/penamulta/FT-PM-08-emitir-certidao.md

Elaboração da Feature Spec da \[EP-PM-02] - FT-PM-09 - Consultar certidões geradas Descrição completa no projeto java em `docs/penamulta/FT-PM-09-consultar-certidoes.md`

Elaboração da Feature Spec da \[EP-PM-02] - FT-PM-10 - Registrar log de auditoria Descrição completa no projeto java em docs/penamulta/FT-PM-10-auditoria.md

**Objetivo:** Transformar o cálculo em cobrança judicial efetiva.   **EP-PM-04 — Gestão de Cobrança** | Feature | Nome | Observação | | -------- | -------------------------------- | ---------- | | FT-PM-11 | Registrar cobrança da pena multa | A detalhar | | FT-PM-12 | Controlar inadimplência | A detalhar | | FT-PM-13 | Emitir cobrança da pena multa | A detalhar | | FT-PM-14 | Processar retorno bancário | A detalhar | > Features, comportamentos e user stories deste marco serão detalhados após a conclusão e avaliação do Marco 1.

**Objetivo:** Integrar completamente o módulo ao fluxo judicial. **EP-PM-05 — Integração com PJe** > A busca de dados do processo no PJe é realizada no Marco 1 do COBJUD PRO (US-PM-10). Esse método busca em 1G e 2G automaticamente, valida acesso e trata segredo de justiça. As features deste marco cobrem o sentido inverso — o módulo alimentando o PJe — usando o (SOAP MNI) já existente no módulo `tjpi`, com suporte a assinatura digital via `AssinadorService`. | Feature | Nome | User Stories | Observação | | -------- | --------------------------------------------- | ------------ | -------------------------------------------------------------------------------- | | FT-PM-15 | Registrar movimentações no processo | A definir | Via `PjeClient.entregarManifestacaoProcessual()` — SOAP MNI | | FT-PM-16 | Enviar documentos ao processo | A definir | Via `PjeClient` + `AssinadorService` (assinatura ICP-Brasil) | | FT-PM-17 | Automatizar fluxo da pena multa | A definir | — | | FT-PM-18 | Registrar dados da pena multa no processo PJe | A definir | Alimentar o PJe com dados do cálculo e da cobrança; caminho natural após Marco 2 |

Esse guia foi elaborado pra auxiliar na compressão dos padrões do projeto. As atualizações serão colocadas no arquivo ".md" no projeto, que é o arquivo correto para consulta. O texto aqui é apenas para referência, não substitui o arquivo no projeto java.     # Guia de Desenvolvimento ## Projeto Cálculo Pena Multa ### Integrado ao sistema COBJUD PRO — TJPI --- ## 1. Objetivo deste documento Este guia orienta novos integrantes do projeto **Cálculo Pena Multa**, incluindo servidores da equipe técnica, desenvolvedores e estagiários. O documento explica: * como o projeto está organizado; * onde localizar cada tipo de informação; * como manter rastreabilidade entre backlog, documentação e código; * como contribuir com o desenvolvimento do sistema. Este projeto é parte integrante do sistema **COBJUD PRO** e segue a estrutura de desenvolvimento já utilizada pela equipe responsável. --- ## 2. Princípio fundamental: fonte única da informação Para evitar retrabalho, inconsistência e documentação duplicada, cada tipo de informação possui **uma fonte oficial**. > **Princípio adotado:** cada informação deve existir em apenas um local oficial. --- ## 3. Fonte oficial de cada tipo de informação | Tipo de informação | Fonte oficial | | ---------------------------- | ---------------------------------------------------- | | Planejamento do projeto | **Captei** (sistema interno TJPI) | | Marcos | Captei | | Épicos | Captei | | Features | Captei | | User Stories | Captei | | Tasks | Captei | | Fluxos de processo | Arquivos BPMN — `docs/penamulta/fluxos/` | | Protótipos de interface | Ferramenta de design ou `docs/penamulta/prototipos/` | | Regras de negócio detalhadas | Feature Specs — `docs/penamulta/features/` | | Modelo de dados (ERD) | `docs/penamulta/onboarding/erd-pena-multa.html` | | Arquitetura do sistema | `docs/penamulta/onboarding/arquitetura-geral.md` | | Estrutura de APIs | Feature Specs — `docs/penamulta/features/` | | Estrutura de banco de dados | Código-fonte e migrations | | Histórico de mudanças | Repositório Git | > **Captei** é o sistema de gerenciamento de portfólio e projetos de TIC do TJPI (PEGPTIC/GOVTIC). É a ferramenta equivalente ao que outros projetos chamam de "board" ou "backlog". Não replicar informações do Captei no repositório — apenas referenciar. --- ## 4. Estrutura de rastreabilidade ### 4.1 Visão geral ```plaintext Planejamento do Projeto Documentação do Sistema Implementação Técnica (Captei) (Repositório Git) (Repositório Git) ──────────────────────── ──────────────────────── ──────────────────────── Marco Feature Spec Código-fonte ↓ ↓ ↓ Épico Fluxos de processo Services / Controllers ↓ ↓ ↓ Feature Regras de negócio Banco de dados ↓ ↓ ↓ User Story Protótipos Commits ↓ ↓ ↓ Task APIs e arquitetura Deploy ``` ### 4.2 Rastreabilidade completa ```plaintext Captei (Feature) ↓ Feature Spec (docs/penamulta/features/FT-PM-XX-nome.md) ↓ User Stories (Captei) ↓ Tasks (Captei) ↓ Código-fonte ↓ Commit (com referência FT-PM-XX) ↓ Deploy ``` --- ## 5. Onde cada informação está localizada ### Captei Responsável por: * planejamento e priorização; * acompanhamento das sprints; * gestão das tarefas do time. Estrutura utilizada: ```plaintext Marco └── Épico (EP-PM-XX) └── Feature (FT-PM-XX) ├── User Story (US-PM-XX) │ └── Task └── (referência ao Feature Spec no repositório) ``` Para acessar o Captei: \[sistema interno TJPI — PEGPTIC/GOVTIC] ### Repositório Git Responsável por armazenar documentação técnica e funcional durável. **O repositório não deve replicar o backlog do Captei.** Em vez disso, deve referenciar os itens do backlog pelo ID da feature (ex.: `FT-PM-01`, `FT-PM-02`). --- ## 6. Por que utilizar Feature Spec Ferramentas de backlog como o Captei são voltadas principalmente para gestão de trabalho. Com o tempo podem ocorrer situações como: * reorganização ou arquivamento de projetos; * dificuldade para localizar funcionalidades mais antigas; * perda de contexto ao trocar membros da equipe. Por isso é necessário manter um **registro durável das funcionalidades** no repositório. O Feature Spec registra: * objetivo da funcionalidade; * contexto do negócio; * fluxo do processo; * regras de negócio; * APIs envolvidas; * estrutura de dados; * critérios de aceite. Esses documentos ficam versionados junto ao código, preservando o conhecimento do sistema independentemente do estado do backlog. --- ## 7. Estrutura de documentação no repositório ```plaintext docs/penamulta/ ├── onboarding/ │ ├── guia-desenvolvimento.md ← este arquivo │ ├── arquitetura-geral.md │ ├── mapa-rastreabilidade.md │ └── erd-pena-multa.html ← modelo de dados (ERD) ├── templates/ │ ├── feature-spec-template.md │ └── regra-negocio-template.md ├── features/ │ ├── FT-PM-01-realizar-calculo.md │ ├── FT-PM-02-memoria-calculo.md │ ├── FT-PM-03-recalcular.md │ ├── FT-PM-04-salario-minimo.md │ ├── FT-PM-05-ipca-e.md │ ├── FT-PM-06-selic.md │ ├── FT-PM-07-controle-atualizacao.md │ ├── FT-PM-08-emitir-certidao.md │ ├── FT-PM-09-consultar-certidoes.md │ └── FT-PM-10-auditoria.md ├── fluxos/ │ ├── fluxo-calculo-multa-isolada.bpmn │ └── fluxo-calculo-multa-cumulada.bpmn └── prototipos/ ├── FT-PM-01-wizard-calculo.png ├── FT-PM-08-certidao.png └── FT-PM-09-historico.png ``` ### Estrutura do pacote Java ```plaintext penamulta/ ├── controller/ │ ├── PenaMultaController.java │ └── PenaMultaAdminController.java ├── domain/ │ ├── dto/ │ │ ├── request/ │ │ └── response/ │ ├── entity/ │ │ ├── indice/ ← subpacote isolado — candidato a extração futura │ │ │ ├── IndiceIpcaE.java ← tabela: indice_ipca_e │ │ │ ├── IndiceSelic.java ← tabela: indice_selic │ │ │ └── IndiceSalarioMinimo.java ← tabela: indice_salario_minimo │ │ ├── PenaMulta.java │ │ ├── PenaMultaCalculo.java │ │ ├── PenaMultaCertidao.java │ │ ├── PenaMultaBaixa.java │ │ ├── PenaMultaRecalculo.java │ │ └── PenaMultaAuditoria.java │ └── enums/ │ ├── StatusCalculo.java │ ├── TipoMulta.java │ ├── ModoEntrada.java │ └── OrigemBaixa.java ├── repository/ │ └── indice/ ← subpacote isolado │ ├── IndiceIpcaERepository.java │ ├── IndiceSelicRepository.java │ └── IndiceSalarioMinimoRepository.java └── service/ ├── indice/ ← subpacote isolado │ ├── IpcaEService.java │ ├── SelicService.java │ └── SalarioMinimoService.java ├── PenaMultaCalculoService.java ├── PenaMultaPdfService.java └── PenaMultaPjeService.java ``` > **Por que o subpacote **`indice/`**?** O COBJUD PRO (COBranças JUDiciais) prevê outros tipos de cálculo judicial que usarão os mesmos índices econômicos (IPCA-E, SELIC, salário mínimo). Quando isso ocorrer, o subpacote `indice/` será extraído para um módulo próprio `indices/` — a operação se resume a mover arquivos e atualizar imports. As tabelas já têm nomes genéricos (`indice_ipca_e`, não `pena_multa_ipca_e`) para facilitar essa migração. --- ## 8. Template padrão de Feature Spec **Arquivo:** `docs/penamulta/templates/feature-spec-template.md` ```plaintext # FEATURE [FT-PM-XX] — [Nome da funcionalidade] ## Referência no backlog Captei — Sistema de Gerenciamento de Projetos de TIC (PEGPTIC/GOVTIC — TJPI) Épico: [EP-PM-XX — Nome do épico] Feature ID: FT-PM-XX Documentação técnica: docs/penamulta/features/FT-PM-XX-nome.md --- ## 1. Objetivo Descrever o objetivo principal da funcionalidade. --- ## 2. Contexto do Negócio Descrever brevemente o processo de negócio envolvido. --- ## 3. Fluxo do Processo ### 3.1 Fluxo simplificado 1. 2. 3. ### 3.2 Fluxo detalhado docs/penamulta/fluxos/[arquivo].bpmn --- ## 4. Regras de Negócio | ID | Regra | |---|---| | RN-PM-01 | Descrição da regra. | | RN-PM-02 | Descrição da regra. | --- ## 5. Protótipo docs/penamulta/prototipos/FT-PM-XX-nome.png --- ## 6. User Stories As stories permanecem no Captei. Referência: [FT-PM-XX — Lista de US no Captei] | US | Título | Classificação | |---|---|---| | US-PM-01 | ... | Must / Should / Could | --- ## 7. Tasks técnicas As tasks permanecem no Captei, vinculadas às User Stories. Principais tasks previstas: - [ ] ... - [ ] ... --- ## 8. APIs envolvidas | Método | Endpoint | Descrição | |---|---|---| | POST | /recurso | ... | | GET | /recurso/{id} | ... | --- ## 9. Estrutura de dados Tabela principal: `nome_tabela` | Campo | Tipo | Obrigatório | Observação | |---|---|---|---| | id | BIGINT | Sim | Chave primária | | campo_a | VARCHAR | Sim | ... | | campo_b | DECIMAL | Não | ... | --- ## 10. Critérios de aceite | ID | Critério | |---|---| | CA-PM-01 | Descrição do critério. | | CA-PM-02 | Descrição do critério. | --- ## 12. Dependências - [FT-PM-YY] — motivo da dependência. --- ## 13. Observações técnicas Decisões técnicas importantes, restrições ou pontos de atenção. ``` --- ## 9. Relação entre Captei e Feature Spec A relação entre backlog e documentação ocorre por **referência cruzada**. **No Captei** (campo de descrição ou anexo da Feature): ```plaintext Feature: FT-PM-01 — Realizar cálculo da pena multa Documentação técnica: docs/penamulta/features/FT-PM-01-realizar-calculo.md ``` **No Feature Spec** (cabeçalho do arquivo): ```plaintext ## Referência no backlog Captei — PEGPTIC/GOVTIC — TJPI Feature ID: FT-PM-01 ``` --- ## 10. Regras para commits Os commits devem manter vínculo com a feature implementada, usando o prefixo `FT-PM-XX`. **Formato:** ```plaintext FT-PM-XX tipo: descrição curta do que foi implementado ``` **Tipos válidos:** | Tipo | Uso | | ---------- | --------------------------------------------- | | `feat` | Nova funcionalidade | | `fix` | Correção de bug | | `test` | Adição ou correção de testes | | `docs` | Alteração de documentação | | `refactor` | Refatoração sem alteração de comportamento | | `chore` | Tarefas de manutenção (configs, dependências) | **Siglas de prefixo válidas — Marco 1:** | Sigla | Feature | Área | | ---------- | ----------------------------------------- | ---------------------------------------------- | | `FT-PM-01` | Realizar cálculo da pena multa | Cálculo principal, wizard, integração PJe | | `FT-PM-02` | Registrar e visualizar memória de cálculo | Snapshot imutável do resultado | | `FT-PM-03` | Recalcular pena multa | Histórico de recálculos | | `FT-PM-04` | Gerenciar salário mínimo | Tabela histórica de SM | | `FT-PM-05` | Gerenciar IPCA-E | Índices de correção monetária | | `FT-PM-06` | Gerenciar SELIC | Taxas de juros de mora | | `FT-PM-07` | Controlar atualização de índices | Alerta de desatualização | | `FT-PM-08` | Emitir certidão de cálculo | Geração e rastreio de impressões | | `FT-PM-09` | Consultar certidões e baixas | Histórico e baixa manual de pagamento | | `FT-PM-10` | Registrar log de auditoria | Rastreabilidade transversal | | `DOC` | Documentação geral | Alterações em `docs/` sem feature específica | | `INFRA` | Infraestrutura | Configurações de ambiente, CI/CD, dependências | > Novas features recebem a próxima sigla `FT-PM-XX` disponível, definida no Captei no momento da criação. Não criar siglas ad hoc fora desse padrão. **Exemplos:** ```plaintext FT-PM-01 feat: busca de processo via JudicialService FT-PM-01 feat: cálculo de correção monetária pelo IPCA-E FT-PM-01 fix: precisão do fator SELIC acumulado FT-PM-01 test: validação dos limites legais de dias-multa FT-PM-04 feat: CRUD de salário mínimo histórico FT-PM-05 feat: CRUD de índices IPCA-E FT-PM-08 feat: geração de PDF da certidão de apuração de débito FT-PM-09 feat: baixa manual de pagamento individual e em lote DOC docs: atualização do ERD após separação PENA_MULTA/CALCULO ``` --- ## 12. Documentação da API (Swagger / OpenAPI) O COBJUD PRO usa **SpringDoc OpenAPI 2.1.0** (`springdoc-openapi-starter-webmvc-ui`). A UI do Swagger está disponível em `{host}/swagger-ui.html`. O módulo Pena Multa inaugura o padrão de documentação da API no COBJUD PRO. Os demais módulos devem adotar as mesmas convenções quando forem tocados. ### Configuração global Uma única classe `OpenApiConfig` em `common/config/` define o contrato global: ```java @Configuration public class OpenApiConfig { @Bean public OpenAPI openAPI() { return new OpenAPI() .info(new Info() .title("COBJUD PRO API") .description("COBranças JUDiciais — Tribunal de Justiça do Piauí") .version("1.0.0") .contact(new Contact() .name("STIC/TJPI — GOVTIC/PEGPTIC") .url("https://www.tjpi.jus.br"))) .addSecurityItem(new SecurityRequirement().addList("bearerAuth")) .components(new Components() .addSecuritySchemes("bearerAuth", new SecurityScheme() .name("bearerAuth") .type(SecurityScheme.Type.HTTP) .scheme("bearer") .bearerFormat("JWT"))); } } ``` ### Convenções por camada **Controllers — obrigatório:** ```java @Tag(name = "Pena Multa", description = "Cálculo e gestão de multas criminais – NT N011/2025") @SecurityRequirement(name = "bearerAuth") public class PenaMultaController { ... } @Operation( summary = "Calcular pena de multa", description = "Executa o cálculo sem persistir. Usar para pré-visualização no wizard." ) @ApiResponse(responseCode = "200", description = "Cálculo executado com sucesso") @ApiResponse(responseCode = "400", description = "Parâmetros inválidos") @ApiResponse(responseCode = "401", description = "Não autenticado") public ResponseEntity