---
name: fluig-process-reader
description: Leitura e interpretacao de arquivos .process (XML/XMI) exportados do TOTVS Fluig. Use quando precisar mapear atividades de um processo existente, extrair activityId para displayFields/enableFields, ou gerar diagramas Mermaid de fluxos BPM.
license: MIT
metadata:
  version: "1.0.0"
  author: Nevoa
  category: development
  platform: totvs-fluig
---

# Skill: fluig-process-reader

> Leitura e interpretacao de arquivos `.process` (XML/XMI) exportados do TOTVS Fluig.
> Extrai atividades BPMN, gateways, swimlanes, sequenceFlows e gera esqueletos de `displayFields` e diagramas Mermaid.

## Quando Usar

- Antes de criar eventos (`displayFields`, `enableFields`, `validateForm`) para um processo existente
- Quando o usuario fornece um `.process` e pede "leia o fluxo" ou "mapeie as atividades"
- Para gerar documentacao visual (Mermaid) de um processo Fluig

## Formato do Arquivo `.process`

Arquivo XML com namespace XMI (`http://www.omg.org/XMI`) e BPMN2 (`http://www.omg.org/spec/BPMN/20100524/MODEL-XMI`).

### Estrutura Principal

```xml
<?xml version="1.0" encoding="UTF-8"?>
<xmi:XMI xmlns:xmi="http://www.omg.org/XMI"
          xmlns:bpmn2="http://www.omg.org/spec/BPMN/20100524/MODEL-XMI"
          xmlns:pi="http://eclipse.org/graphiti/mm/pictograms"
          xmi:version="2.0">

  <!-- Secao 1: pi:Diagram â€” layout visual (posicoes, cores, estilos) -->
  <pi:Diagram diagramTypeId="BPMNdiagram" name="NomeProcesso" ...>
    <!-- children com link businessObjects="taskN", "starteventN", etc. -->
    <!-- connections com link para sequenceFlows -->
  </pi:Diagram>

  <!-- Secao 2: bpmn2:* â€” modelo BPMN semantico (IMPORTANTE) -->
  <bpmn2:BpmnPool id="pool1" name="Nome do Pool"/>
  <bpmn2:BpmnSwimLane id="swimlane2" name="Solicitante"/>
  <bpmn2:BpmnSwimLane id="swimlane3" name="Aprovador"/>

  <bpmn2:BpmnStartEvent id="startevent4" name="Inicio" outgoing="flow6" type="10"/>
  <bpmn2:BpmnTask id="task5" name="Aprovacao" incoming="flow6" outgoing="flow8" type="80"/>
  <bpmn2:BpmnExclusiveGateway id="exclusivegateway7" incoming="flow8" outgoing="flow10 flow12"/>
  <bpmn2:BpmnEndEvent id="endevent14" incoming="flow15" name="Cancelado" type="60"/>

  <bpmn2:SequenceFlow id="flow6" sourceRef="startevent4" targetRef="task5"/>
  <bpmn2:SequenceFlow id="flow8" sourceRef="task5" targetRef="exclusivegateway7"/>

  <bpmn2:BpmnProcess id="NomeProcesso" name="NomeProcesso"
                      cardIndex="259" version="2" formSource="server"/>
</xmi:XMI>
```

## Regra de Extracao do `activityId`

O `activityId` (usado em `getValue("WKNumState")`) e o **sufixo numerico** do atributo `id`:

| Elemento XML | id no XML | activityId | WKNumState |
|---|---|---|---|
| `bpmn2:BpmnStartEvent` | `startevent4` | 4 | 0 (inicio) |
| `bpmn2:BpmnTask` | `task5` | 5 | 5 |
| `bpmn2:BpmnTask` | `task9` | 9 | 9 |
| `bpmn2:BpmnExclusiveGateway` | `exclusivegateway7` | 7 | â€” (automatico) |
| `bpmn2:BpmnEndEvent` | `endevent14` | 14 | -1 (fim) |

### Regex para Extrair

```python
import re
match = re.search(r'(\d+)$', element_id)
activity_id = int(match.group(1)) if match else None
```

## Elementos BPMN Reconhecidos

| Tag XML | Tipo | Descricao |
|---|---|---|
| `bpmn2:BpmnStartEvent` | Start | Inicio do processo (type="10" = none, "20" = timer, "30" = message) |
| `bpmn2:BpmnTask` | Task | Atividade humana (type="80" = user task) |
| `bpmn2:BpmnServiceTask` | Service | Atividade automatica/servico |
| `bpmn2:BpmnExclusiveGateway` | Gateway | Decisao exclusiva (XOR) |
| `bpmn2:BpmnParallelGateway` | Gateway | Execucao paralela (AND) |
| `bpmn2:BpmnEndEvent` | End | Fim do processo (type="60" = none, "70" = terminate) |
| `bpmn2:SequenceFlow` | Flow | Conexao entre elementos (`sourceRef` â†’ `targetRef`) |
| `bpmn2:BpmnPool` | Pool | Container principal do processo |
| `bpmn2:BpmnSwimLane` | Lane | Raia/papel (Solicitante, Aprovador, etc.) |
| `bpmn2:BpmnProcess` | Process | Metadados (cardIndex, version, formSource) |

Atributos principais: `id` (sufixo = activityId), `name`, `incoming`, `outgoing`, `type`, `sourceRef`, `targetRef`.

> Detalhes completos de atributos de BpmnTask, SequenceFlow e BpmnProcess: [references/formato-process-xml.md](./references/formato-process-xml.md)

## Saida Esperada

### 1. Tabela de Atividades

```
activityId | Tipo            | Nome                    | Swimlane
-----------|-----------------|-------------------------|------------
0 (start)  | StartEvent      | Inicio                  | Solicitante
5          | Task            | Aprovacao Gestor         | Gestor
9          | Task            | TOTVS Sustentacao        | TI
7          | ExclusiveGW     | (decisao)               | â€”
14         | EndEvent        | Cancelado                | â€”
18         | EndEvent        | Finalizado               | â€”
```

### 2. Esqueleto `displayFields.js`

```javascript
function displayFields(form, customHTML, logger) {
    var numState = parseInt(getValue("WKNumState"));

    // Atividade 0 â€” Inicio (StartEvent)
    // Atividade 5 â€” Aprovacao Gestor
    if (numState == 5) {
        // TODO: configurar campos visiveis/ocultos
    }

    // Atividade 9 â€” TOTVS Sustentacao
    if (numState == 9) {
        // TODO: configurar campos visiveis/ocultos
    }
}
```

### 3. Diagrama Mermaid

```mermaid
graph TD
    Start((Inicio)) -->|flow6| Task5[Aprovacao]
    Task5 -->|flow8| GW7{Decisao}
    GW7 -->|flow10| Task9[TOTVS Sustentacao]
    GW7 -->|flow12| Task11[Notificar]
    Task9 -->|flow17| Task16[Validacao]
    Task11 -->|flow15| End14((Cancelado))
    Task16 -->|flow19| End18((Finalizado))
    Task11 -.->|flow22| Task5
```

## Swimlane â†” Atividade (Mapeamento via Layout)

A associacao entre atividade e swimlane e feita pelo **layout visual** na secao `pi:Diagram`:
- Cada `<children>` com `link businessObjects="taskN"` tem coordenadas `x`, `y`
- As swimlanes tem `y` (posicao vertical) e `height`
- A atividade pertence a swimlane cuja faixa vertical contem o `y` da atividade

O parser Python automatiza essa associacao.

## Parser Automatizado

Disponivel em `scripts/parse_process.py`:

```bash
# Uso basico
python scripts/parse_process.py caminho/para/processo.process

# Com diagrama Mermaid
python scripts/parse_process.py caminho/para/processo.process --mermaid

# Gerar esqueleto displayFields
python scripts/parse_process.py caminho/para/processo.process --display-fields

# Saida completa (tabela + mermaid + displayFields)
python scripts/parse_process.py caminho/para/processo.process --all
```

## Fluxo de Trabalho Recomendado

1. Usuario fornece arquivo `.process`
2. Executar parser: `python scripts/parse_process.py arquivo.process --all`
3. Revisar tabela de atividades e Mermaid com o usuario
4. Usar activityIds mapeados nos eventos:
   - `displayFields.js` â€” visibilidade por atividade
   - `enableFields.js` â€” habilitacao por atividade
   - `validateForm.js` â€” validacao condicional por atividade
   - `inputFields.js` â€” valores iniciais por atividade

## Prompts Estrategicos Disponiveis

- `ler-process-gerar-mapa-tecnico-mermaid-skeletons.md` - Leitura de `.process` com tabela, Mermaid e skeletons.
- `comparar-versoes-process-impacto-scripts.md` - Comparacao entre versoes de `.process` e impactos nos scripts.
- `auditar-scripts-contra-process-wknumstate.md` - Auditoria de `WKNumState` do codigo contra o fluxo real.
- `gerar-pacote-inicial-implementacao-a-partir-process.md` - Pacote inicial de implementacao a partir do `.process`.

Use estes prompts para transformar BPMN exportado em insumo tecnico para desenvolvimento e manutencao.
## Skills Relacionadas

- [fluig-formularios](../fluig-formularios/SKILL.md) — Gerar displayFields/enableFields a partir dos activityIds mapeados
- [fluig-eventos-processo](../fluig-eventos-processo/SKILL.md) — Scripts de workflow por atividade
- [fluig-eventos-formulario](../fluig-eventos-formulario/SKILL.md) — inputFields e validacao por atividade

## Checklist

- [ ] Arquivo `.process` lido e parseado sem erros
- [ ] Todos os `bpmn2:BpmnTask` extraidos com activityId correto
- [ ] StartEvent e EndEvent(s) identificados
- [ ] Gateways mapeados (exclusive, parallel)
- [ ] SequenceFlows conectando todos os elementos
- [ ] Swimlanes associadas as atividades (quando possivel)
- [ ] Esqueleto displayFields gerado com todos os numState
- [ ] Diagrama Mermaid valido e legivel

## Recursos Adicionais

- Para o parser Python, consulte [scripts/parse_process.py](./scripts/parse_process.py)
- Para exemplos de saida do parser, consulte [examples/](./examples/)
### Exemplos recomendados
- [exemplo_01_aprovacao_pedido_compra_process](./examples/exemplo_01_aprovacao_pedido_compra_process/): `.process` compacto com saidas `--all`, Mermaid e skeleton de `displayFields`.
- [exemplo_02_wf0035_pesquisa_desenvolvimento_process](./examples/exemplo_02_wf0035_pesquisa_desenvolvimento_process/): `.process` mais complexo para validar parser e cobertura de fluxo.
- Para referencia do formato XML .process, consulte [references/formato-process-xml.md](./references/formato-process-xml.md)
- Para prompts de uso, consulte [prompts/](./prompts/)

---

## Curadoria de Contexto Local

Para buscar exemplos reais no acervo local `Contexto`, consulte [references/contexto-curadoria.md](./references/contexto-curadoria.md).
Abra essa referencia quando a tarefa exigir aderencia a legado/producao ou comparacao com implementacoes existentes.
