Auditoria Detalhada de Funcionalidades e Documentação — HDT-AF¶
Data: 2026-11-18
Escopo: Inspeção estática integral de código-fonte, build/POM/Gradle/npm, infraestrutura Docker/Fabric/scripts e especificações OpenAPI em todo o workspace (modules/, research/experiments/, deploy/, docker/, pom.xml, docs/), com identificação de funcionalidades implementadas, divergências entre código e documentação e achados de engenharia.
Limite de verificação: Auditoria estática conduzida sobre os arquivos reais do workspace em 2026-11-18 (incluindo alterações locais não commitadas referentes ao
BL-334). A suíte Java/Maven não foi executada por ausência demvne JDK 25 no ambiente local.
1. Inventário Quantitativo Real do Workspace¶
| Camada | Localização | Composição real observada |
|---|---|---|
| Reator Maven (Java 25) | pom.xml |
15 módulos de plataforma + 5 módulos de experimento + 2 módulos de benchmark = 22 módulos (exp-har-smartphones-001 entra via build-helper-maven-plugin, sem pom.xml próprio) |
| Aplicação Android (Gradle) | modules/federated-android-client |
3 subprojetos (:core, :app, :client-engine-plugin) + includeBuild("../../../hdt-mobile-apps") (br.ufma.lsdi:mdpl) |
| Frontend Web (npm/Vite) | modules/federated-admin-web |
10 arquivos JS/JSX em src/ (SPA desativada no roteamento principal do AdminWebServer desde BL-135) |
| Portal de Documentação | modules/federated-docs |
Repositório independente MkDocs Material + Read the Docs (.readthedocs.yaml, mkdocs.yml, scripts/sync_docs.py, tests/) |
| Scripts Operacionais | modules/scripts (scripts/) |
21 scripts .sh |
| Chaincodes Fabric | deploy/fabric/chaincode/federated-governance-java/ |
19 arquivos Java (fabric-chaincode-shim:2.5.4, Gradle Shadow 9.0.0, Java 25), 3 @Contracts e 9 assets |
| Experimentos de Pesquisa | research/experiments/* |
6 diretórios (exp-ecg5000-anomaly-001, exp-ergonomic-risk-001, exp-har-smartphones-001, exp-mimic-v31-icu-mortality-001, exp-mnist-digits-001, exp-synthetic-smoke-001); exp-dt-federated-001 existe apenas como contrato bootstrap em AdminApplicationBootstrap |
2. Mapa Detalhado de Funcionalidades Implementadas por Subsistema¶
2.1 Núcleo Compartilhado e Segurança (federated-common)¶
- Tratamento de erros (
br.ufma.lsdi.common):ErrorCode(17 códigos padronizados) eFederatedException. - Criptografia, assinatura e integridade (
br.ufma.lsdi.common.crypto): HmacSignatureService(identidades registradas e assinatura/verificação HMAC-SHA256);X509SignatureService("x509:{id}:{base64}", suporte a chaves RSA e EC) eX509SignatureServiceLoader(load,registerOwnIdentity,fromTrustAnchor,fromEnvironmentviaSIGNING_*);CompositeSignatureService(roteamento por identidade entre X.509 e HMAC);Hashing(sha256paraString,Pathvia stream ebyte[]).- Compactação e ZIP seguro (
br.ufma.lsdi.common.io.PackageZipSupport): leitura/escrita determinística comSHA256SUMSe proteção contra Zip Slip e Zip Bomb. - Serialização (
br.ufma.lsdi.common.util):JsonCodec(JacksonObjectMapper+JavaTimeModule) eVectorCodec. - Barramento MQTT (
br.ufma.lsdi.common.mqtt): MqttEnvelope<T>(signed,verify,verifyPayloadIntegrity),MqttPayloadCodec(JacksonObjectMapperserializando os records em camelCase),MqttTopicMatcher,ClientSenderScopeeDockerMqttEnvironment(injeção de env vars MQTT, mTLS eSIGNING_*, além de reescritalocalhost/127.0.0.1→host.docker.internal).MqttTopics(tópicosfl/experiments/{id}/..., constantes wildcard*_WILDCARD/ALL_EXPERIMENT_*, tópicos locais MDPLmdpl/...e canais de artefato do gêmeo digitalclientArtifact/globalModelPayload).IotTopics(entityObservation,entityEvent,cddlService,cddlEventObjectDiscovered/Disconnectede wildcards por cliente).- Modelo de domínio (
br.ufma.lsdi.common.model— 46 tipos): contratos (ExperimentContract,ExperimentSchedule,ParticipationPolicy,AggregationPolicy,PrivacyPolicy,EvaluationDatasetSpec,DataSchemaSpec), vocabulário fechado de tipos (DataTypeCatalogcom 21DataTypeSpec,DataFieldSpec), rodadas e atualizações (RoundConfigcom 13 campos incluindoAlgorithmSelection,RoundFinalizationSignal,ClientUpdateMessage,GlobalModelPublication,RemoteAggregationRequest,TwinValidationDecisionMessage) e 11 implementações deEvidenceProducing.
2.2 SDK de Experimentos e Empacotamento (federated-experiment-sdk, federated-experiment-packager, federated-package-experiment-service)¶
federated-experiment-sdk(12 arquivos):- Contratos de extensão
TrainingLocalModel(algorithmSpec(),execute(TrainingContext) throws TrainingException),TrainingContext(11 campos),TrainingResult(12 campos + construtor legado de 8 args),TrainingStatus(5 constantes:SUCCESS,FAILED,PREFLIGHT_FAILED,COMPLETED_NOT_SUBMITTED,UPDATE_SUBMITTED),ExperimentSessioneExperimentSessionFactory(comforExperiment(String)para clonagem dinâmica). - Catálogo de algoritmos e runtimes:
MlAlgorithmSpec(10 campos),MlRuntimeTarget(7 alvos, incluindoANDROID_ONNX_RUNTIMEeMACOS_APPLE_SILICON_DJL) eMlAlgorithmCatalog(8 especificações prontas). - Resolução portável de diretórios (
ExperimentRuntimePaths) com precedênciaSystem.getProperty>System.getenv> padrão (var/deployed-experiments,var/deployed-datasets,var/deployed-client-packages, etc.), leitura de termos (ConsentTermsMarkdownReader) e diagnóstico de rodada (RoundEvaluationReport). federated-experiment-packager(15 arquivos):- Pacotes de experimento
.hdtpkg.zip(ExperimentPackageDescriptorvia Jackson,ExperimentPackageWritervalidandocodeJarEntryviaJarFile,ExperimentPackageReader,ExperimentPackagerCli). - Pacotes de cliente Android
.hdtclient.zip(ClientPackageDescriptorvia Jackson exigindocode/*.dex, assinatura Ed25519 viaClientPackageSignature,ClientPackageWriter,ClientPackageReaderexigindoSHA256SUMSe cabeçalhodex\n,ClientPackagePackagerCligravandocode/client-engine.dex). - Pacotes de simulação
.hdtsim.zip(CsvTabularDatasetSchema,DatasetPartitionercom estratégiassequential_chunkerandom_shuffle_seed+roundSlice,SimulationDataPackageDescriptor/Writer/Reader/Cli). federated-package-experiment-service(3 arquivos):ArtifactReference(uri, hash, sizeBytes),LocalArtifactExperimentService(store,read(ArtifactReference)com resolução cross-mountresolveAcrossForeignRootdoBL-117,readIfPresent(namespace, filename), sanitização por substituição_em caracteres fora da whitelist eprivate resolveSecure) eArtifactRetentionPolicy(expurgo pós-validTo).
2.3 Dados Locais, Ingestão MQTT e Privacidade (federated-local-cdm — 27 arquivos)¶
DataComponent&SqliteTimeSeriesStore(atualizados noBL-334):DataComponentmantém cache thread-safe dedefaultStorevia double-checked locking; expõesubscribeToMqttSource,awaitIngestion,awaitMqttDataAndMaterialize,materializeDatasetFromStore,loadLocalCdmRepository,authorizedTrainingView(estático), consultas de séries temporais e helpers centralizados de Privacidade Diferencial (differentialPrivacyConfig*,applyDifferentialPrivacyIfConfigured*).SqliteTimeSeriesStoreimplementaTimeSeriesStoreeAutoCloseable, utilizandoWriterResources(conexão JDBC persistente + 3PreparedStatements em cache, transações explícitas comautoCommit=false,SQLiteConfigcomBUSY_TIMEOUT_MS=5000,SynchronousMode.NORMALeTempStore.MEMORY), limpeza viajava.lang.ref.Cleaner, recuperação apósSQLExceptione reabertura transparente em novas escritas.- Persistência de artefatos de modelo local/global em
{dataRoot}/model_artifacts.dbviaModelArtifactStore(SQLite WAL). - Ingestão, Perfilamento e Preflight:
MqttTimeSeriesIngestorassina 4 filtros de tópico (allObservationsForClient,allEventsForClient,cddlServicesForClient,cddlAllEvents) e registraIngestionDiagnostics/IngestionAudit.DataProfileServiceproduzLocalDataProfileeDefaultPreflightValidatoravalia 5 checagens (minimum_examples_per_client,minimum_positive_examples_per_client,minimum_entities_per_client,expected_positive_rate_range,missingness_threshold:{code}), gerandoPreflightResult(eligibleForTraining()).- Privacidade Diferencial (
BL-081):DifferentialPrivacyConfig,DifferentialPrivacyConfigReader(leitura XML segura contra XXE) eDifferentialPrivacyMath(clip L2 + ruído gaussiano + alerta[DP-UTILIDADE]quando ruído domina o sinal).
2.4 Ciclo Federado, Gêmeo Digital Local e Inferência¶
- Cliente Federado (
federated-client— 39 + 5 arquivos): FederatedClientService: valida contrato ativo, consentimento, seleção emselected_clients, compatibilidade deAlgorithmSelectioneClientMlRuntimeSupport, preflight (registrando hash), visão autorizada emauthorized_view.csv, modelo global FedProx, execução doTrainingLocalModel, consistência de métricas/OutputPolicy, verificação de hash pré-DP, aplicação de DP, upload viaClientArtifactChannel(LocalDiskArtifactChannelouTwinArtifactChannel) e registro de hashes de update e métricas no ledger.FederatedDockerClientExecutor: exportatimeseries.dbisolado por cliente/experimento (ClientTimeSeriesExporter), monta/app/lib:roe ambiente MQTT/mTLS, executa container efêmero, lêresult.propertiese cria symlinks emlogs/<containerName>/{data,model}.- Núcleo portável Android (
br.ufma.lsdi.fedandroid.core):ConsentManager,ContractPublishedGate,ObservationStore/TabularAssembler,MultiExperimentRoundCoordinator,RoundLifecycle,LocalTrainer(MlpNetwork),ClientPackageVerifier,MdplTrainingPluginResolvere ponte Androidbr.ufma.lsdi.fedandroid.net(5 classes compiladas pelo:app). - Orquestrador (
federated-orchestrator— 20 arquivos): RoundCoordinator,AllAcceptedClientsStrategy,RandomSampledClientsStrategy,RoundRobinStrategy,FederatedRoundStrategyFactory,SelectionStrategyCatalog,ExternalParticipantRoundTrigger.ClientUpdateRelay(relay obrigatórioclientUpdate→aggregatorClientUpdate),ClientArtifactIngestor,MqttClientUpdateCollector,ClientUpdateResolver,AggregationResultPublisher,RemoteAggregatorClient(HTTPPOST /aggregate),TwinValidationDecisionIngestoreRoundFlowPublisher(atualmente não conectado aos fluxos principais).- Agregador (
federated-aggregator— 12 arquivos): - 6 algoritmos configuráveis via
AggregationStrategyFactory:fedavg,fedmedian,trimmed_mean(poda por norma L2),krum/multikrum,fedadamefedyogi(viaFedAdamAggregationStrategy.fedYogi()). FedAvgAggregationServicerealiza validação de escopo, duplicidade, assinatura, finitude, dimensão, norma, SHA-256 e quórum (AggregationQuorumException). Ainda preserva métodos/campos legados (aggregateFromMessages) e cópia antiga deMqttClientUpdateCollector.- Containers MQTT (
federated-containers— 3 arquivos): MqttBrokerConfig(sufixo UUID obrigatório),MqttTlsConfig(TLSv1.3,PKCS12) ePahoMqttGateway(MQTTv5 QoS 1,automaticReconnect, fallbackhost.docker.internal↔127.0.0.1, re-assinatura emconnectComplete).- Gêmeo Digital Local (
federated-digital-twin-broker— 18 arquivos): EmbeddedRestSseBroker/EmbeddedTwinBroker+RestSseGateway(BL-243: HTTP+SSE interno com backoff500ms → 15s),DigitalTwinBridge(borda externa MQTT 5 comEnvelopeBoundaryGuard↔ barramento interno HTTP+SSE abrindo 7 assinaturas internas totais quandoTwinArtifactChannelé conectado),DigitalTwinClientCommandAdapter,DigitalTwinValidatorAdapter,BaselineComparisonModelValidator,ReferenceMetricHoldoutEvaluatoreLocalDigitalTwinRuntime.- Serviço de Inferência (
federated-model-inference— 14 arquivos): - Empacotamento
.hdtmodel.zip(ModelPackageManifest/Writer/Reader, limite 2 MiB), persistência on-chain (FabricInferencePackageLedgerchamandoFederatedExperimentChaincode),LinearModelInference(linear-regression-v1,logistic-regression-v1) e servidor HTTP:8092(GET /models,GET /models/{id}/package,POST /models,POST /infer,POST /infer/{id},POST /infer/streamNDJSON,POST /infer/{id}/stream).
2.5 Governança Blockchain & Cliente Android¶
- Hyperledger Fabric (
deploy/fabric/chaincode/federated-governance-java/+federated-chaincode): - Chaincode real em Java 25 (
fabric-chaincode-shim:2.5.4, Gradle Shadow9.0.0):ExperimentContractSmartContract(9 transações);ClientConsentSmartContract(6 transações, gravaACCEPTEDe aceita legadoEXPCEPTED);FederatedExperimentSmartContract(18 transações, incluindo pacotes de inferência e assinaturas canônicas de 10 argumentos emregisterLocalUpdateHasheregisterGlobalModelVersion);- 9 tipos de asset (
ExperimentContractAsset,TrainingCodeAsset,ClientConsentAsset,AuditEventAsset,DatasetEvidenceAsset,GlobalModelAsset,ClientUpdateAsset,InferencePackageAsset,InferencePackageMetadataAsset), 9 object types emLedgerConstants/StateKeyse 4 validadores emValidation.
- Simuladores em memória (
modules/federated-chaincode) eFabricGatewayLedgerMirror(SubmitOutcome:SUBMITTED,ALREADY_REGISTERED,FAILED) +FabricCliLedgerMirrorlegado. - Cliente Android (
modules/federated-android-client): - 5 Activities (
MainActivity,ConsentActivity,ExperimentDetailActivity,CollectedDataActivity,ExperimentMonitorActivity), 2 Foreground Services (FederatedMqttService,FederatedMdplInferenceEngineService), coleta CDDL/CDAL (gravada após consentimento ativo),EncryptedSharedPreferences, upload de artefatos por HTTP REST (RestRoundArtifactGateway), sincronização síncrona de consentimento (RestConsentSyncClient), carregamento dinâmico DEX Ed25519 viaMdplClientPackageManagere fallbackLocalTrainer(MlpNetwork).
2.6 Monitor Web, API REST, Simulador e Experimentos¶
- Monitor & API REST (
federated-rest-api— 71 arquivos): AdminWebServer(7.714 linhas, JDKHttpServer/HttpsServerna porta8088),AdminHtmlLayout(abas em PT-BR),AdminMonitoringService(2.389 linhas),AdminExperimentExecutor,IsolatedExperimentRunnerApp(BL-236isolamento em subprocesso),DockerParticipantLaunchService,DockerParticipantDaemonRegistry,ClientDiscoveryService,AnonymousClientInstallationRegistry,CddlStatusRegistry,MqttTrafficMonitorService+MongoMqttMessageStore(BL-306),SimulationSession/SimulationRoundEngine/MqttClientDataFlowInjector(BL-246) e endurecimento de concorrência/SSE/locks (BL-334).- Simulador (
federated-simulator— 8 arquivos):MqttDatasetReplaySimulator,HarMqttReplayAdapter,EcgMqttReplayAdapter,IotDatasetReplayAppe pacotebr.ufma.lsdi.simulator.data(CsvDatasetSimulationSource,DatasetPartitioner,SimulationDataPackagePlayer). - Experimentos (
research/experiments/*): 6 projetos ativos (exp-ecg5000-anomaly-001,exp-har-smartphones-001,exp-mimic-v31-icu-mortality-001,exp-mnist-digits-001,exp-ergonomic-risk-001,exp-synthetic-smoke-001) com sessões, modelos locais e adaptadores de simulação.
3. Achados de Engenharia Identificados (Código × Infraestrutura)¶
Estes achados permanecem no código/infraestrutura atual (não modificados por esta entrega documental) e passam a ser explicitados com transparência na documentação:
FedAdamsilencioso paraHAReECG:HarFederatedSessioneEcgFederatedSessioninvocamaggregator.aggregate(contract, roundConfig, updates)sem passar o vetor global anterior (currentGlobal = null), fazendoFedAdamAggregationStrategy.combinerecair no fallback ponderado (FedAvg).- Clamping ausente em
HarMqttReplayAdaptereEcgMqttReplayAdapter: ApenasCsvDatasetSimulationSourceutilizaDatasetPartitioner.roundSlice; os adaptadores HAR e ECG calculam(roundNumber - 1) * chunkSizesem clamp. RoundFlowPublishernão integrado: Criado emfederated-orchestrator, masRoundCoordinatoreAggregationResultPublisherainda publicam diretamente viaMqttGateway.BaselineComparisonModelValidatoracoplado aoLocalArtifactExperimentService: Lê e grava arquivos de modelo diretamente no serviço de artefatos em vez de operar apenas sobre payloads em memória do broker local.- Divergências entre simuladores in-memory e chaincode Fabric real:
ExperimentContractChaincodepermiteDRAFT -> REVOKEDe rejeitaPUBLISHED -> CLOSED(inverso deExperimentContractSmartContract);FederatedExperimentChaincodeaceita reescritas idênticas e não implementa as 4 transações de pacotes de inferência, enquantoFederatedExperimentSmartContractusarequireMissing(*_ALREADY_EXISTS). - Inconsistências em
AdminWebServere OpenAPI: POST /api/experiments/{id}/simulation-configé interceptado pelo roteamento genérico/{command}antes da rota dedicada e devolveCommandResult;POST /experiments/{id}/clients/{clientId}/registerestá sombreado pela rota genérica de 5 segmentosclients;GET /datasets/deployeGET /datasetsnão estão conectados nodoHandle;POST /api/experiments/{id}/run-with-datasetePOST /experiments/{id}/run-with-datasetexecutam de forma síncrona semrunBoundedRoundAction;GET /api/experiments/{id}/containers/{name}/logsignora?tail=(fixo em 200 linhas);GET /openapi.jsonretorna resumo estático desatualizado (12 rotas);AdminWebServer.stop()não fechaMongoMqttMessageStorenemClientUpdateRelay.- Infraestrutura Docker & Build:
docker/mosquitto/mosquitto.confconfigura apenaslistener 8883(TLS 1.3 + mTLS); portas1883e9001no Compose/VM não possuem listeners ativos no broker;- Serviço
postgresnos arquivos Compose (5432/15432) não possui consumidor Java (Local CDM usa SQLite); docker-compose.ymlraiz não injetaFABRIC_GATEWAY_*, não monta credenciais Fabric nem entra emfabric_test, e referenciaDockerClientSimulationApp/FederatedSimulationAppinexistentes;docker/docker-compose.vm.ymldefineHDT_AF_RESEARCH_ROOT=/app/research, mas não monta./research:/app/research:ro;modules/federated-common/src/main/resources/logback.xmlnão existe no checkout;pom.xmldos consumidoresfederated-rest-apiefederated-system-testsainda lista o diretório inexistenteexp-dt-federated-001/src/main/java, e opom.xmlraiz declara dependências vestigiais de Moquette/Paho v3;FEDERATED_CLIENT_EXECUTION_MODEeMIMIC_V31_DATASETsão variáveis obsoletas não lidas pelo código Java;exp-mimic,exp-mnisteexp-ergonomic-riskpossuemresearch.xmlincompatível comresearch-experiment.xsd, eEcgFederatedSession/MimicV31FederatedSessiondivergem entrePrivacyPolicyJava e<privacy>emresearch.xml.- Testes & Scripts:
ArchitectureComponentTestSuitemantém asserções legadas (2experimentos em vez de3;"OK"em/healthem vez de JSON);HarSessionFactorynão existe (sem suporte a clone dinâmico no HAR);run-coverage.shomitefederated-model-inferenceeexp-synthetic-smoke-001;run-iot-simulator.shomite o mododt;package-experiment.shenvia para/experiments/deployem vez de/api/experiments/deploy.
4. Melhorias Documentais Aplicadas (BL-335)¶
- Novos documentos estruturantes:
docs/ARCHITECTURE.mdedocs/INSTALL.md(alinhados ao padrão canônico do projeto, com diagramas PlantUML inline e guia completo de instalação/execução).- Este relatório técnico de auditoria integral (
docs/analysis/auditoria-funcionalidades-e-documentacao-2026-11-18.md). - Correção de todos os documentos de componente (
docs/components/01a20) eREADME.mddos módulos: alinhamento de assinaturas Java 25, modelos de dados, estratégias, BL-334 (DataComponent,SqliteTimeSeriesStore,AdminWebServer,SseEventBus), BL-244, BL-259, BL-234/235, BL-236, BL-237, BL-243, BL-306, BL-308/309, Android e experimentos reais. - Atualização das especificações OpenAPI (
openapi-admin-monitor.yamleopenapi-hdt-client.yaml) preservando identidade byte a byte entredocs/components/emodules/federated-rest-api/src/main/resources/. - Atualização da camada Blockchain (
docs/blockchain/*e03-hyperledger-fabric.md) para 9 assets, 18 transações deFederatedExperimentSmartContract, Shadow9.0.0,LedgerMode.failOnFabricError(),SubmitOutcomee estado real das sessões. - Atualização da camada MQTT (
docs/mqtt/*e05-mqtt.md) para formatocamelCasedeMqttPayloadCodec, 13 campos deRoundConfig, 11 implementações deEvidenceProducing, X.509/Composite, TLS 8883 e tópicosmhub//fl/. - Atualização dos guias (
execution-guide.md,experiments-guide.md,tutorial-create-experiment.md,simulation-deployment-guide.md,vm-deployment-guide.md,modules.md,docker/README.md,research/README.md), diagramas (docs/diagrams/*), RAG e portal Read the Docs (modules/federated-docs).