[jacksonsr451]

Summary

Implements the complete consultation intake domain for EventFlow's Work Management bounded context, including multi-source intake, consultation lifecycle management, persistent drafts, evidence, secure attachments, and auditable history.

This PR builds upon the existing authentication, workspace authorization, persistence, and API contracts delivered by Issues #9, #10, #11, and #12.

The implementation enables consultations to originate from manual input, web applications, VS Code, and desktop clients while preserving tenant isolation, action-level RBAC, transactional consistency, and the established Work Management workflow.

Changes

• Implement consultation intake, retrieval, listing, and authorized triage operations.
• Support consultation origins: manual, VS Code, web, and desktop.
• Support optional initial consultation classification.
• Associate consultations with workspaces, projects, authors, and repository context.
• Introduce persistent consultation drafts.
• Implement draft creation, updates, and explicit submission.
• Preserve direct consultation submission.
• Add evidence persistence and validation.
• Implement secure attachment handling.
• Introduce fail-closed attachment quarantine behavior.
• Add authenticated attachment upload, download, and deletion operations.
• Implement consultation history retrieval and pagination.
• Integrate with existing append-only audit infrastructure.
• Enforce workspace/project authorization and tenant isolation.
• Extend OpenAPI and JSON Schema contracts.
• Introduce incremental Alembic migrations.
• Add PostgreSQL integration, security, authorization, and regression tests.
• Update architecture and security documentation.

Motivation

Consultations are the entry point for EventFlow's Work Management workflow.

Before this implementation, the platform had foundational persistence, authentication, authorization, and API contracts but lacked the complete executable intake lifecycle required to receive, manage, and track consultation requests from multiple sources.

This PR provides that foundation while preserving the separation between raw intake, triage, proposals, approvals, and executable work.

A consultation does not automatically create a Proposal, WorkItem, or BoardCard.

Type of Change

• Bug fix
• New feature
• Refactoring
• Performance improvement
• Security improvement
• Documentation
• CI/CD or infrastructure
• Dependency update
• Breaking change

Related Issues

Closes #4

Depends on:

• [FEAT] Implementar workspaces, projetos, membros e permissões #9 — Workspace administration, membership, and RBAC.
• [FEAT] Implementar autenticação e gestão segura de sessão dos três clientes #10 — OAuth/OIDC authentication and secure sessions.
• [FEAT] Criar API pública versionada e contratos de workflow #11 — Versioned Work Management API contracts.
• [FEAT] Criar backend persistente e migrations para gestão de trabalho #12 — Work Management persistence.
• [SECURITY] Definir threat model, segregação e política de dados do produto #35 — Security and data governance specifications.

Implementation Details

Architecture

The implementation extends the existing Work Management bounded context without introducing a parallel consultation domain.

It reuses:

• FastAPI application infrastructure.
• AuthenticatedPrincipal.
• Workspace authorization and action-level RBAC.
• SQLAlchemy 2 persistence.
• PostgreSQL transactions.
• Existing consultation models and repositories.
• Idempotency infrastructure.
• Append-only audit infrastructure.
• OpenAPI 3.1 contracts.
• RFC 9457 error handling.

The established workflow remains:

Consultation → Triage → Proposal → Review → Approval → WorkItem → BoardCard

Consultation creation and submission do not bypass triage or approval.

Multi-Source Intake

Consultations support the following origins:

Origin	Description
Manual	Direct user-created consultation
Web	Consultation submitted through the web application
VS Code	Consultation originating from editor workflows
Desktop	Consultation originating from desktop applications

All origins use the same consultation domain and persistence infrastructure.

The intake model supports workspace/project association, author identity, descriptions, optional initial classification, repository context, and timestamps.

Consultation Lifecycle

Introduces persistent draft support while preserving direct consultation submission.

The lifecycle includes:

• Draft creation.
• Draft modification.
• Draft retrieval.
• Explicit draft submission.
• Direct consultation submission.
• Consultation retrieval and listing.
• Authorized triage operations.
• Consultation history.

The draft extension preserves the established consultation workflow after submission.

Invalid lifecycle transitions are rejected rather than silently changing downstream workflow state.

Evidence Management

Adds consultation evidence support with validation and persistence.

Evidence is associated with the corresponding consultation and remains subject to workspace/project authorization.

The implementation supports evidence references and attachment associations without bypassing the consultation domain boundary.

Secure Attachments

Implements consultation-scoped attachment handling with security controls.

The implementation includes:

• Attachment validation.
• File-type and allowlist enforcement.
• Filename and path traversal protection.
• Upload size limits.
• Quota enforcement.
• Secure attachment references.
• Authenticated access.
• Workspace isolation.
• Attachment deletion.
• Fail-closed quarantine behavior.
• Rejection of infected content.
• Protection against unauthorized attachment association.

Attachments that have not satisfied the required security checks remain quarantined.

Quarantined attachments cannot be treated as approved consultation evidence.

The implementation does not assume that unverified content is safe.

Consultation History

Implements consultation history using the existing audit infrastructure.

History retrieval provides an auditable view of consultation activity while preserving authorization and tenant isolation.

History pagination is covered by integration tests.

Authorization and Tenant Isolation

Consultation operations integrate with the workspace authorization infrastructure delivered by Issue #9.

Authorization uses the trusted internal user identity established by Issue #10.

Security boundaries include:

• Active workspace membership.
• Action-level RBAC.
• Project ownership validation.
• Consultation ownership and lifecycle restrictions.
• Attachment authorization.
• Evidence association validation.
• Cross-workspace access prevention.

Client-provided identifiers do not establish authorization.

Persistence and Migrations

Extends the existing PostgreSQL persistence model through incremental Alembic migrations.

The implementation preserves previously merged migration history.

During final validation, the attachment/evidence migration revision identifier exceeded the 32-character limit of alembic_version.version_num.

The revision was corrected from:

0006_consultation_attachments_evidence

to:

0006_attachments_evidence

This resolved the migration failure affecting 68 database-backed tests.

API Contracts

Updates:

• contracts/openapi/work-management.yaml
• contracts/schemas/work_management.yaml

The implementation preserves:

• OpenAPI 3.1.
• /v1/ API conventions.
• RFC 9457 Problem Details.
• Existing authentication schemes.
• Workspace-scoped authorization.
• Consultation lifecycle contracts.
• Established compatibility requirements.

Security Considerations

Authentication

Consultation operations reuse the existing OAuth/OIDC authentication infrastructure.

No alternative authentication mechanism is introduced.

Authorization

Workspace and project permissions are enforced through the existing RBAC architecture.

Unauthorized operations are rejected without granting access to unrelated workspace resources.

Attachment Security

Attachment handling follows a fail-closed policy.

The implementation validates content, type, size, and authorization before permitting access.

Quarantined or rejected content cannot be used as approved evidence.

Tenant Isolation

Consultations, evidence, attachments, and history remain scoped to their authorized workspace and project.

Cross-workspace references cannot establish access rights.

Auditability

Consultation activity integrates with existing audit and security observability mechanisms.

Security-sensitive operations are documented in the updated security specifications.

Testing

The implementation was validated locally using the existing jsr-testrunner infrastructure.

Results

Test suite	Passed	Failed	Skipped
Work Management	118	0	1
Repository regression suite	110	0	0
Total	228	0	1

The single skipped test requires a live Keycloak environment and belongs to the authentication integration suite.

Verified Scenarios

• Consultation intake and retrieval.
• Consultation lifecycle and triage.
• Draft creation and submission.
• PostgreSQL persistence.
• Attachment upload and download.
• Attachment deletion.
• Fail-closed quarantine.
• Infected attachment rejection.
• Base64 validation.
• Attachment type validation.
• File allowlist enforcement.
• Path traversal protection.
• Upload size limits.
• Attachment quotas.
• Evidence type validation.
• Evidence attachment references.
• Quarantined attachment citation rejection.
• Idempotency.
• RBAC and tenant isolation.
• Consultation history pagination.
• OpenAPI and schema validation.
• Repository regression tests.
• Pre-commit validation.

The attachment integration suite adds 11 tests covering successful operations, invalid inputs, security restrictions, and persistence behavior.

Validation Commands

testrunner services/work-management/tests --disable-plugin-autoload
testrunner tests --disable-plugin-autoload
python scripts/validate_contracts.py
git diff --check

Pre-commit hooks passed, including:

• Trailing whitespace.
• End-of-file formatting.
• YAML validation.
• Merge conflict detection.
• Large file detection.
• Case conflict detection.
• Private key detection.
• Contract and repository reference validation.

Documentation

Updated the following documentation:

• docs/architecture/work-management-api.md
• docs/architecture/work-management-workflow.md
• docs/security/untrusted-content.md
• docs/security/security-observability.md
• docs/security/open-decisions.md
• docs/security/traceability.md
• docs/security/risk-register.md

The documentation covers consultation lifecycle changes, evidence and attachment handling, security requirements, observability, and traceability.

Security decisions OD-04 and OD-05 were updated as part of the attachment implementation.

Backward Compatibility

• Existing direct consultation submission is preserved.
• Draft support extends the consultation lifecycle.
• Existing authentication and workspace RBAC are reused.
• Previously merged migrations remain unchanged.
• Existing Work Management API conventions are maintained.
• The downstream Proposal, Approval, WorkItem, and BoardCard workflow remains protected.
• Order Processing remains outside the scope of this PR.

Known Limitations and Reservations

Live Keycloak Integration

One authentication integration test was skipped locally because the live Keycloak stack was unavailable.

This is an existing Issue #10 integration requirement and does not represent a reported failure in the consultation implementation.

Remote CI

Remote CI has not yet been executed for this branch.

The local validation results must be confirmed by GitHub Actions before merging.

External Attachment Security Services

Attachment handling implements fail-closed quarantine behavior.

Any external malware-scanning provider or operational security integration must follow the approved deployment configuration and documented security decisions.

Unverified attachments must not bypass quarantine.

Review Checklist

• Multi-source consultation intake implemented.
• Optional initial consultation classification supported.
• Draft lifecycle implemented.
• Direct submission preserved.
• Consultation persistence implemented.
• Evidence handling implemented.
• Secure attachment handling implemented.
• Quarantine behavior enforced.
• Consultation history implemented.
• Workspace/project authorization integrated.
• RBAC and tenant isolation tested.
• Attachment security tests passed.
• Migration revision issue corrected.
• PostgreSQL integration tests passed.
• OpenAPI and schema contracts updated.
• Architecture and security documentation updated.
• Repository regression suite passed.
• Pre-commit checks passed.
• Local working tree clean.
• Remote CI verification.
• Final maintainer review.

Commits

• 27a587c — feat(work-management): implement consultation intake, reads, and triage ([FEAT] Implementar domínio de consultas e intake multiorigem #4)
• bc788d4 — feat(work-management): add draft consultation lifecycle ([FEAT] Implementar domínio de consultas e intake multiorigem #4)
• a4c8724 — feat(work-management): add consultation attachments, evidence, and history ([FEAT] Implementar domínio de consultas e intake multiorigem #4)

Outcome

Issue #4 delivers the consultation intake foundation required by EventFlow's Work Management domain.

The implementation supports multi-source intake, persistent drafts, consultation submission, evidence, secure attachments, and auditable history while preserving the existing authentication, authorization, and workflow boundaries.

Local validation completed with 228 passing tests, no reported failures, and one unrelated Keycloak-live test skipped.

Status: Ready for Pull Request review, pending remote CI verification.