changes

Implementation fix.md

@@ -0,0 +1,273 @@
+Implementation Goal
+Deliver a single, continuous evidence flow so users do not re-upload PDFs across M4->M5->M8->M9->M10, and always see the right document lineage.
+
+Target User Flow (after changes)
+
+User analyzes source docs in M4 from M3 or M5 context.
+User opens M5 and gets only relevant extracted requirements.
+User creates M8 contract from M5 and contract gets proposal PDF continuity automatically.
+User opens M9 from M8 with contractId preserved through diagnosis and case creation.
+User opens M10 and sees live dossier with file-level links, freshness state, and clear traceability.
+Phase Plan
+
+Phase 1: Fix Critical Continuity Breaks
+Stop unrelated M4 history fallback in M5 extraction when proposal has no linked source.
+Persist and use contractId in legal diagnosis finalization.
+Replace M9 contract selector from “IDs from existing cases” to “actual contracts list”.
+Files: workflow extract API, M5 detail page, legal diagnosis start, legal diagnosis answer, M9 view, M9 page.
+Phase 2: M5->M8 Document Reuse (No Reupload)
+On M8 autocreate, auto-copy latest proposal PDF into ContractDocument.
+Extend M8 extraction endpoint to accept sourceProposalId without mandatory new file upload.
+Add “Use proposal PDF from M5” action in M8 upload tab.
+Files: M8 page, contract extract API, contracts view, contract storage, proposal storage.
+Phase 3: Complete Contract Document UX
+Wire existing /api/contracts/upload into M8 UI.
+Show contract documents list in M8 cards.
+Add delete endpoint for contract documents and surface actions in UI.
+Files: contracts upload API, contracts view, contracts API folder.
+Phase 4: M10 Live Dossier + File-Level Traceability
+Make dossier load strategy explicit (live default, snapshot optional).
+Add freshness metadata (generatedAt, isStale, source indicator).
+Extend dossier payload from counts to include document-level entries and link targets.
+Render proposals/contracts/legal sections with drill-down and links in M10.
+Files: audits server, audits types, expediente API, M10 view.
+Phase 5: Secure Download Endpoints
+Add proposal document download endpoint.
+Add contract document download endpoint.
+Enforce ownership checks and safe storage path resolution.
+Files: proposals API folder, contracts API folder, proposal delete route pattern.
+Phase 6: Continuity Safeguards and Observability
+Add structured logs for handoffs (sourceProposalId, contractId, history source used).
+Add continuity warnings in UI when source context is missing.
+Add “why this file” trace badges where extraction picks source docs.
+Files: M4 view, M5 workflow view, M8 view, M10 view.
+Phase 7: Tests and Release Gates
+Add integration tests for full continuity path M4->M5->M8->M9->M10.
+Add regression tests for “wrong history picked” and “diagnosis loses contractId”.
+Add API tests for download ownership and safe path rules.
+Keep existing npm test, npm run lint, npm run build as mandatory gate.
+Files: lib tests root, component tests root.
+Acceptance Criteria
+
+No forced reupload from M5 to M8 when proposal PDF exists.
+Legal cases created via diagnosis stay linked to selected contract.
+M5 never uses unrelated M4 history for extraction.
+M10 shows live, fresh dossier state and file-level evidence traceability.
+Users can securely download proposal/contract evidence from module context.
+End-to-end continuity test passes for M4->M10.
+Execution Order (Critical Path)
+
+Phase 1
+Phase 2
+Phase 4
+Phase 5
+Phase 3
+Phase 6
+Phase 7
+Estimated Delivery
+
+Phase 1-2: 2-3 days
+Phase 3-5: 2-3 days
+Phase 6-7: 1-2 days
+Total: ~1 week of focused implementation
+If you want, I can start immediately with Phase 1 and push the exact code changes in that order.
+
+Progress Update
+
+Date: 2026-04-09
+Phase 1 Status: Completed
+
+Completed in Phase 1
+
+- M5 extraction continuity guard: removed unrelated M4 history fallback when proposal has no linked `sourceLicitationId`.
+- M5 detail continuity guard: history context now loads only when tied to the same linked `sourceLicitationId`.
+- M9 diagnosis continuity: diagnosis start now validates and persists `contractId` in diagnosis context.
+- M9 diagnosis finalization continuity: legal case auto-created from diagnosis now reuses persisted `contractId` (with ownership validation).
+- M9 contract selector source: selector options now come from actual M8 contracts instead of contract IDs inferred from existing legal cases.
+
+Validation Run
+
+- `npm test`: passed (22 files, 61 tests).
+- `npm run lint`: passed with existing warnings in `pdfExtractor.js` (no errors).
+- `npm run build`: passed (Next.js production build succeeded).
+
+Next Planned Step
+
+- Phase 2: M5 -> M8 document reuse (no reupload).
+
+Progress Update
+
+Date: 2026-04-09
+Phase 2 Status: Completed
+
+Completed in Phase 2
+
+- M8 autocreate continuity: when opening M8 from M5 (`autocreate=1`), the flow now auto-links the latest proposal PDF into `ContractDocument` (deduplicated).
+- M8 extraction endpoint continuity: `/api/contracts/extract` now accepts `sourceProposalId` without mandatory file upload.
+- M8 extraction source handling: route can analyze either uploaded PDF or proposal PDF; it preserves `sourceProposalId` on contract create/update.
+- M8 proposal PDF reuse UI: added explicit action in upload tab to "Usar PDF de propuesta de M5" with proposal selector and timestamped file labels.
+- Shared continuity utilities:
+  - Safe proposal document read helper in proposal storage.
+  - Proposal->contract continuity helper for latest PDF lookup and deduplicated linking.
+
+Validation Run (Phase 2)
+
+- `npm test`: passed (22 files, 61 tests).
+- `npm run build`: passed (Next.js production build succeeded).
+- `npm run lint`: passed with existing warnings in `pdfExtractor.js` (no errors).
+
+Next Planned Step
+
+- Phase 4: M10 live dossier + file-level traceability (per critical path order).
+
+Progress Update
+
+Date: 2026-04-14
+Phase 4 Status: Completed
+
+Completed in Phase 4
+
+- Dossier load strategy is now explicit in M10:
+  - API and UI support `live` (default) and `snapshot` (optional) loading.
+  - M10 now shows requested strategy vs actual source used.
+- Freshness metadata added and surfaced:
+  - `generatedAt`, `isStale`, `source`, `snapshotId`, `staleAfterMinutes`.
+  - Snapshot generation returns synchronized freshness metadata.
+- Dossier payload upgraded from aggregate-only counts to file-level traceability:
+  - M5 proposals now include `documentEntries` with links and trace labels.
+  - M8 contracts now include `documentEntries` with links, kind, and lineage to source proposal when available.
+  - M9 legal cases now include `documentEntries` with links and trace labels to legal context/contract continuity.
+- M10 UI drill-down completed:
+  - Separate sections for proposals/contracts/legal with per-record links.
+  - Per-file expandable trace blocks showing mime, size/date, trace reason, and actionable links.
+
+Validation Run (Phase 4)
+
+- `npm test`: passed (23 files, 67 tests).
+- `npm run lint`: passed with existing warnings in `pdfExtractor.js` (no errors).
+- `npm run build`: passed (Next.js production build succeeded).
+
+Next Planned Step
+
+- Phase 5: secure download endpoints for proposal and contract evidence.
+
+Progress Update
+
+Date: 2026-04-14
+Phase 5 Status: Completed
+
+Completed in Phase 5
+
+- Added secure proposal evidence download endpoint:
+  - `GET /api/proposals/[id]/documents/[documentId]`.
+  - Enforces ownership (`proposalId` + `documentId` + `userId`) before file access.
+  - Uses safe storage path guard and bounded file read helper.
+  - Returns attachment headers with safe filename handling.
+- Added secure contract evidence download endpoint:
+  - `GET /api/contracts/[id]/documents/[documentId]`.
+  - Enforces ownership via contract relation (`contract.userId`).
+  - Uses new safe contract document read helper with path traversal protection.
+  - Returns attachment headers with safe filename handling.
+- Added safe contract storage read helper:
+  - `readStoredContractDocumentFile(...)` with canonical path validation and size guard.
+- M10 file-level traceability now exposes direct secure download links for proposal and contract evidence from dossier context.
+
+Validation Run (Phase 5)
+
+- `npm test`: passed (23 files, 67 tests).
+- `npm run lint`: passed with existing warnings in `pdfExtractor.js` (no errors).
+- `npm run build`: passed (Next.js production build succeeded).
+
+Next Planned Step
+
+- Phase 3: complete contract document UX (wire upload UI, show docs in M8 cards, add delete endpoint/actions).
+
+Progress Update
+
+Date: 2026-04-14
+Phase 3 Status: Completed
+
+Completed in Phase 3
+
+- M8 upload UX now wires existing `/api/contracts/upload`:
+  - Added explicit "Adjuntar documento al contrato (sin IA)" flow in M8 upload tab.
+  - Supports selecting contract target, document kind, and PDF file.
+- Contract document cards in M8 now include document list and actions:
+  - File name, kind, size, and timestamp shown per document.
+  - Direct download action per file.
+  - Delete action per file.
+- Added contract document delete endpoint:
+  - `DELETE /api/contracts/[id]/documents/[documentId]`.
+  - Enforces ownership via `contract.userId`.
+  - Removes both storage file and DB row with safe path handling.
+
+Validation Run (Phase 3)
+
+- `npm test`: passed (23 files, 67 tests).
+- `npm run lint`: passed with existing warnings in `pdfExtractor.js` (no errors).
+- `npm run build`: passed (Next.js production build succeeded).
+
+Next Planned Step
+
+- Phase 6: continuity safeguards and observability.
+
+Progress Update
+
+Date: 2026-04-15
+Phase 6 Status: Completed
+
+Completed in Phase 6
+
+- Added structured continuity handoff logs across critical APIs:
+  - `m4_to_m5_*` events in `/api/proposals/[id]/workflow/extract`.
+  - `m5_to_m8_*` events in `/api/contracts/extract`.
+  - `m8_to_m9_*` events in `/api/legal/diagnosis/start`.
+  - `m9_*` continuity events in `/api/legal/diagnosis/answer`.
+- Added page-level observability for M5->M8 autocreate in `/gestion-contratos`:
+  - Logs for autocreate request, proposal resolution, contract target resolution, proposal PDF lookup, and link outcomes.
+- Added continuity safeguards and operator-facing warnings in UI:
+  - M4 (`normative-analysis-view`): warning when no linked source context.
+  - M5 (`proposal-workflow-view`): warning when no M4 context for extraction.
+  - M8 (`contracts-management-view`): warnings for missing proposal PDFs and contracts without `sourceProposalId`.
+  - M10 (`preventive-dossier-view`): warnings derived from incomplete dossier component evidence.
+- Added explicit traceability badges (`Por que este archivo`) where file/source selection affects continuity in M4, M5, M8, and M10.
+
+Validation Note (Phase 6)
+
+- Continuity observability changes were carried into Phase 7 release-gate validation and passed together with final gates.
+
+Next Planned Step
+
+- Phase 7: tests and release gates.
+
+Progress Update
+
+Date: 2026-04-15
+Phase 7 Status: Completed
+
+Completed in Phase 7
+
+- Added integration continuity test for M4->M5->M8->M9->M10 dossier lineage:
+  - `src/lib/audits/__tests__/dossier-continuity.integration.test.ts`.
+  - Verifies proposal->contract->legal continuity links and evidence trace payload in M10.
+- Added regression test for "wrong history picked" continuity break:
+  - `src/app/api/proposals/[id]/workflow/extract/route.test.ts`.
+  - Verifies extraction is blocked when no linked M4 source and no uploaded PDF.
+- Added regression test for "diagnosis loses contractId":
+  - `src/app/api/legal/diagnosis/answer/route.test.ts`.
+  - Verifies finalization preserves persisted `contractId` and links the auto-created legal case to that contract.
+- Added API security tests for download ownership/path safety:
+  - `src/app/api/proposals/[id]/documents/[documentId]/route.test.ts`.
+  - `src/app/api/contracts/[id]/documents/[documentId]/route.test.ts`.
+  - Verifies 404 on non-owned/missing document and 400 on invalid storage path.
+- Fixed JSX parsing safety in M8 continuity messaging (`M5->M8`) to keep lint/build green.
+
+Validation Run (Phase 7)
+
+- `npm test`: passed (28 files, 74 tests).
+- `npm run lint`: passed with existing warnings in `pdfExtractor.js` (no errors).
+- `npm run build`: passed (Next.js production build succeeded).
+
+Next Planned Step
+
+- Planned implementation phases (1-7) are complete. Ready for QA/UAT and deployment checklist.