Como diferenças entre funções são calculadas
Semântica de computeRoleDiff() — arestas de perfil, reclassificações, deslocamentos de IRI/ICI, reordenamentos de estágios de fluxo — a camada de estabilidade de esquema, e o registro de mudanças.
computeRoleDiff() — a função subjacente
A diferença entre funções é uma função pura sobre duas funções publicadas, A e B. Retorna um pacote RoleDiff estruturado com seis seções de topo — arestas de perfil adicionadas, removidas, reclassificações, deltas de IRI/ICI por aresta de perfil, mudanças em estágios de fluxo — mais um agregado de resumo. Pura significa: as mesmas entradas sempre produzem a mesma saída, sem consultas ao banco dentro da função, segura para chamar de componentes de servidor sem encanamento extra.
Arestas de perfil — adicionadas / removidas
Cada função carrega um conjunto de anexos de aresta de perfil: (profile_id, classificação, iri, ici). A diferença classifica cada aresta como adicionada (presente em B, não em A), removida (presente em A, não em B), ou comum (presente em ambos).
Reclassificações
Perfis presentes tanto em A quanto em B onde a classificação mudou (por exemplo suporte → primário). A diferença carrega (perfil, classificaçãoA, classificaçãoB) para que a UI possa renderizar o par antes/depois.
ΔIRI — deslocamento de IRI por aresta de perfil
IRI varia 0–3 por perfil por função. Para arestas de perfil comuns, o delta por aresta é B.iri − A.iri. Deltas por aresta são somados em iriShiftTotal para a barra de resumo. Um total positivo significa que a função pronta para o futuro exige mais informação ao longo de seus perfis.
ΔICI — deslocamento de ICI por aresta de perfil
ICI varia 0–3 por perfil por função. Para arestas de perfil comuns, o delta por aresta é B.ici − A.ici. Deltas por aresta são somados em iciShiftTotal. Um total positivo significa que a função pronta para o futuro exige mais profundidade de competência ao longo de seus perfis.
Mudanças em estágios de fluxo
Cada função carrega uma lista ordenada de estágios de fluxo. A diferença classifica cada estágio como adicionado (em B não em A), removido (em A não em B), ou reordenado (em ambos com posição ordinal diferente).
Reordenamentos são tipicamente a categoria mais informativa para o enquadramento de transformação — mostram como o centro de gravidade do fluxo se move. Um Gerente BIM pronto para o futuro que coloca "validação de informação" antes de "coordenação de modelo" é um tipo diferente de função do que um que os coloca no sentido inverso.
O agregado de resumo
Cada pacote RoleDiff carrega um resumo com sete contagens: commonProfiles, addedProfiles, removedProfiles, classificationChanges, iriShiftTotal, iciShiftTotal, flowReorders. A barra de resumo no topo do RoleDiffView as lê e renderiza as sete contagens como o formato da transformação num relance.
Casos limite
- Comparar uma função consigo mesma retorna o estado vazio de auto-comparação — a diferença não é significativa. O estado vazio da rota oferece um CTA "mudar ?vs=".
- Se uma função não tem ponteiro de sucessor e a rota independente é aberta sem ?vs=, o estado vazio explica a convenção e oferece um seletor de alvo de comparação.
- Rascunhos são excluídos. Tanto A quanto B precisam estar publicadas para a diferença ser calculada.
- Arestas de perfil sem IRI em qualquer lado renderizam como "—" e contribuem 0 para iriShiftTotal.
- Arestas de perfil sem ICI em qualquer lado renderizam como "—" e contribuem 0 para iciShiftTotal.
Matemática agnóstica de jurisdição, catálogo ciente de jurisdição
A matemática da diferença é agnóstica de jurisdição — dadas A e B, a função retorna o mesmo pacote RoleDiff independentemente de quem está lendo. O que é ciente de jurisdição é qual função canônica pronta para o futuro um determinado fork organizacional usa como comparação; essa decisão vive a montante da diferença, na superfície de arquétipo de função.
Camada de estabilidade
O esquema do pacote RoleDiff está na camada de estabilidade beta. O formato pode evoluir em versões menores até 1.0; mudanças quebra-formato bumparão o schemaVersion no envelope do pacote e a mudança será destacada no registro de mudanças.
