feat(api): expose CSE files URLs in declarations export (#2905) (#3200)

Viczei · web-flow · commit ac5b06c22b78 · 2026-04-13T15:33:44.000+02:00
diff --git a/packages/app/src/app/api/v1/export/declarations/route.ts b/packages/app/src/app/api/v1/export/declarations/route.ts
@@ -1,6 +1,7 @@
 import { AUDIT_ACTIONS } from "~/modules/audit";
 import {
 	assembleDeclaration,
+	fetchCseFilesByDeclaration,
 	fetchCseOpinionsByDeclaration,
 	fetchIndicatorGByDeclaration,
 	fetchSubmittedDeclarations,
@@ -68,9 +69,10 @@ async function apiExportDeclarationsHandler(
 		const sirenYearKeys = rows.map((r) => ({ siren: r.siren, year: r.year }));
 		const declarationIds = rows.map((r) => r.declarationId);
 
-		const [indicatorGMap, cseMap] = await Promise.all([
+		const [indicatorGMap, cseMap, cseFilesMap] = await Promise.all([
 			fetchIndicatorGByDeclaration(declarationIds),
 			fetchCseOpinionsByDeclaration(declarationIds),
+			fetchCseFilesByDeclaration(sirenYearKeys),
 		]);
 
 		const data = rows.map((row) => {
@@ -79,6 +81,7 @@ async function apiExportDeclarationsHandler(
 				row,
 				indicatorGMap.get(row.declarationId) ?? [],
 				cseMap.get(row.declarationId) ?? [],
+				cseFilesMap.get(key) ?? [],
 			);
 		});
 
diff --git a/packages/app/src/modules/export/__tests__/exportApi.test.ts b/packages/app/src/modules/export/__tests__/exportApi.test.ts
@@ -3,14 +3,16 @@ import { describe, expect, it, vi } from "vitest";
 const mockFetchSubmitted = vi.fn().mockResolvedValue([]);
 const mockFetchIndicatorG = vi.fn().mockResolvedValue(new Map());
 const mockFetchCse = vi.fn().mockResolvedValue(new Map());
+const mockFetchCseFiles = vi.fn().mockResolvedValue(new Map());
 
 vi.mock("~/modules/export/queries", () => ({
 	fetchSubmittedDeclarations: (...args: unknown[]) =>
 		mockFetchSubmitted(...args),
 	fetchIndicatorGByDeclaration: (...args: unknown[]) =>
 		mockFetchIndicatorG(...args),
 	fetchCseOpinionsByDeclaration: (...args: unknown[]) => mockFetchCse(...args),
-	fetchCseFilesByDeclaration: vi.fn().mockResolvedValue(new Map()),
+	fetchCseFilesByDeclaration: (...args: unknown[]) =>
+		mockFetchCseFiles(...args),
 	fetchJointEvaluationFilesByDeclaration: vi.fn().mockResolvedValue(new Map()),
 }));
 
@@ -74,6 +76,7 @@ describe("GET /api/v1/export/declarations", () => {
 		mockFetchSubmitted.mockResolvedValue([]);
 		mockFetchIndicatorG.mockResolvedValue(new Map());
 		mockFetchCse.mockResolvedValue(new Map());
+		mockFetchCseFiles.mockResolvedValue(new Map());
 	});
 
 	it("should return 401 when Authorization header is missing", async () => {
@@ -294,5 +297,145 @@ describe("GET /api/v1/export/declarations", () => {
 		expect(decl.indicators.F.annual).toHaveLength(4);
 		expect(decl.secondDeclaration.correction).toBeNull();
 		expect(decl.cseOpinions).toEqual([]);
+		expect(decl.cseFiles).toEqual([]);
+	});
+
+	it("should expose CSE opinion declarationNumber alongside type", async () => {
+		mockFetchSubmitted.mockResolvedValue([
+			{
+				declarationId: "decl-1",
+				siren: "123456789",
+				year: 2027,
+				status: "submitted",
+				compliancePath: null,
+				totalWomen: 100,
+				totalMen: 150,
+				secondDeclarationStatus: null,
+				secondDeclReferencePeriodStart: null,
+				secondDeclReferencePeriodEnd: null,
+				createdAt: new Date("2027-03-15T10:00:00Z"),
+				updatedAt: new Date("2027-03-15T12:00:00Z"),
+				companyName: "ACME Corp",
+				workforce: 250,
+				nafCode: "62.02",
+				address: "1 rue test",
+				hasCse: true,
+				declarantFirstName: "Jean",
+				declarantLastName: "Dupont",
+				declarantEmail: "jean@acme.fr",
+				declarantPhone: "0612345678",
+				...nullIndicators,
+			},
+		]);
+		mockFetchCse.mockResolvedValue(
+			new Map([
+				[
+					"decl-1",
+					[
+						{
+							declarationNumber: 1,
+							type: "accuracy",
+							opinion: "favorable",
+							opinionDate: "2027-03-01",
+						},
+						{
+							declarationNumber: 2,
+							type: "gap",
+							opinion: "unfavorable",
+							opinionDate: "2027-06-01",
+						},
+					],
+				],
+			]),
+		);
+
+		const { GET } = await import("~/app/api/v1/export/declarations/route");
+		const request = authedRequest(
+			"http://localhost/api/v1/export/declarations?date_begin=2027-03-15",
+		);
+		const response = await GET(request);
+
+		expect(response.status).toBe(200);
+		const body = await response.json();
+		expect(body.declarations[0].cseOpinions).toEqual([
+			{
+				declarationNumber: 1,
+				type: "accuracy",
+				opinion: "favorable",
+				date: "2027-03-01",
+			},
+			{
+				declarationNumber: 2,
+				type: "gap",
+				opinion: "unfavorable",
+				date: "2027-06-01",
+			},
+		]);
+	});
+
+	it("should include CSE file URLs in the declaration response", async () => {
+		mockFetchSubmitted.mockResolvedValue([
+			{
+				declarationId: "decl-1",
+				siren: "123456789",
+				year: 2027,
+				status: "submitted",
+				compliancePath: null,
+				totalWomen: 100,
+				totalMen: 150,
+				secondDeclarationStatus: null,
+				secondDeclReferencePeriodStart: null,
+				secondDeclReferencePeriodEnd: null,
+				createdAt: new Date("2027-03-15T10:00:00Z"),
+				updatedAt: new Date("2027-03-15T12:00:00Z"),
+				companyName: "ACME Corp",
+				workforce: 250,
+				nafCode: "62.02",
+				address: "1 rue test",
+				hasCse: true,
+				declarantFirstName: "Jean",
+				declarantLastName: "Dupont",
+				declarantEmail: "jean@acme.fr",
+				declarantPhone: "0612345678",
+				...nullIndicators,
+			},
+		]);
+		mockFetchCseFiles.mockResolvedValue(
+			new Map([
+				[
+					"123456789-2027",
+					[
+						{
+							id: "file-abc",
+							siren: "123456789",
+							year: 2027,
+							fileName: "avis-cse-2027.pdf",
+							filePath: "/s3/path",
+							uploadedAt: new Date("2027-03-10T08:30:00Z"),
+						},
+					],
+				],
+			]),
+		);
+
+		const { GET } = await import("~/app/api/v1/export/declarations/route");
+		const request = authedRequest(
+			"http://localhost/api/v1/export/declarations?date_begin=2027-03-15",
+		);
+		const response = await GET(request);
+
+		expect(response.status).toBe(200);
+		expect(mockFetchCseFiles).toHaveBeenCalledWith([
+			{ siren: "123456789", year: 2027 },
+		]);
+		const body = await response.json();
+		expect(body.declarations[0].cseFiles).toEqual([
+			{
+				id: "file-abc",
+				fileName: "avis-cse-2027.pdf",
+				uploadedAt: "2027-03-10T08:30:00.000Z",
+				downloadUrl: "/api/v1/files/file-abc",
+			},
+		]);
 	});
 });
diff --git a/packages/app/src/modules/export/__tests__/fetchDeclarations.test.ts b/packages/app/src/modules/export/__tests__/fetchDeclarations.test.ts
@@ -282,19 +282,54 @@ describe("assembleDeclaration", () => {
 
 	it("should map CSE opinions", () => {
 		const opinions: CseRow[] = [
-			{ type: "initial", opinion: "favorable", opinionDate: "2027-01-15" },
+			{
+				declarationNumber: 1,
+				type: "accuracy",
+				opinion: "favorable",
+				opinionDate: "2027-01-15",
+			},
 		];
 
 		const result = assembleDeclaration(baseRow, [], opinions);
 
 		expect(result.cseOpinions).toHaveLength(1);
 		expect(result.cseOpinions[0]).toEqual({
-			type: "initial",
+			declarationNumber: 1,
+			type: "accuracy",
 			opinion: "favorable",
 			date: "2027-01-15",
 		});
 	});
 
+	it("should map CSE files with download URLs", () => {
+		const files = [
+			{
+				id: "file-xyz",
+				siren: "123456789",
+				year: 2027,
+				fileName: "avis-cse.pdf",
+				filePath: "/s3/path",
+				uploadedAt: new Date("2027-02-10T08:30:00Z"),
+			},
+		];
+
+		const result = assembleDeclaration(baseRow, [], [], files);
+
+		expect(result.cseFiles).toEqual([
+			{
+				id: "file-xyz",
+				fileName: "avis-cse.pdf",
+				uploadedAt: "2027-02-10T08:30:00.000Z",
+				downloadUrl: "/api/v1/files/file-xyz",
+			},
+		]);
+	});
+
+	it("should default cseFiles to empty array when not provided", () => {
+		const result = assembleDeclaration(baseRow, [], []);
+		expect(result.cseFiles).toEqual([]);
+	});
+
 	it("should handle null dates", () => {
 		const rowWithNullDates = { ...baseRow, createdAt: null, updatedAt: null };
 		const result = assembleDeclaration(rowWithNullDates, [], []);
diff --git a/packages/app/src/modules/export/__tests__/openapi.test.ts b/packages/app/src/modules/export/__tests__/openapi.test.ts
@@ -6,7 +6,7 @@ describe("openApiSpec", () => {
 	it("should be a valid OpenAPI 3.1 structure", () => {
 		expect(openApiSpec.openapi).toBe("3.1.0");
 		expect(openApiSpec.info.title).toBeDefined();
-		expect(openApiSpec.info.version).toBe("1.2.0");
+		expect(openApiSpec.info.version).toBe("1.3.0");
 		expect(openApiSpec.paths).toBeDefined();
 	});
 
diff --git a/packages/app/src/modules/export/fetchDeclarations.ts b/packages/app/src/modules/export/fetchDeclarations.ts
@@ -34,6 +34,7 @@ export type IndicatorGEntry = {
 };
 
 export type CseRow = {
+	declarationNumber: number;
 	type: string;
 	opinion: string | null;
 	opinionDate: string | null;
@@ -153,6 +154,7 @@ export function assembleDeclaration(
 	row: DeclarationRow,
 	indicatorGEntries: IndicatorGEntry[],
 	opinions: CseRow[],
+	cseFiles: FileRow[] = [],
 ) {
 	const { initial, correction } = buildIndicatorG(indicatorGEntries);
 
@@ -187,9 +189,16 @@ export function assembleDeclaration(
 			phone: row.declarantPhone,
 		},
 		cseOpinions: opinions.map((o) => ({
+			declarationNumber: o.declarationNumber,
 			type: o.type,
 			opinion: o.opinion,
 			date: o.opinionDate,
 		})),
+		cseFiles: cseFiles.map((f) => ({
+			id: f.id,
+			fileName: f.fileName,
+			uploadedAt: f.uploadedAt.toISOString(),
+			downloadUrl: `/api/v1/files/${f.id}`,
+		})),
 	};
 }
diff --git a/packages/app/src/modules/export/openapi.ts b/packages/app/src/modules/export/openapi.ts
@@ -34,7 +34,18 @@ const indicatorGCategorySchema = {
 const cseOpinionSchema = {
 	type: "object",
 	properties: {
-		type: { type: "string" },
+		declarationNumber: {
+			type: "integer",
+			enum: [1, 2],
+			description:
+				"Declaration number the CSE opinion refers to: 1 = initial declaration, 2 = second declaration (required when pay gap >= 5%)",
+		},
+		type: {
+			type: "string",
+			enum: ["accuracy", "gap"],
+			description:
+				"CSE opinion type: 'accuracy' = opinion on data accuracy, 'gap' = opinion on pay gap correction measures",
+		},
 		opinion: { type: ["string", "null"] },
 		date: { type: ["string", "null"], format: "date" },
 	},
@@ -213,6 +224,25 @@ const declarationSchema = {
 			description:
 				"CSE opinions (PDF uploads, up to 4/year, companies >= 100 employees)",
 		},
+		cseFiles: {
+			type: "array",
+			items: {
+				type: "object",
+				properties: {
+					id: { type: "string", description: "File unique identifier" },
+					fileName: { type: "string", example: "avis-cse-2026.pdf" },
+					uploadedAt: { type: "string", format: "date-time" },
+					downloadUrl: {
+						type: "string",
+						description:
+							"Relative URL to download the file via GET /api/v1/files/{fileId}",
+						example: "/api/v1/files/abc-123",
+					},
+				},
+			},
+			description:
+				"CSE opinion files (PDF) attached to the declaration, with a download URL pointing to /api/v1/files/{fileId}",
+		},
 	},
 } as const;
 
@@ -227,6 +257,12 @@ const fileMetadataSchema = {
 		},
 		fileName: { type: "string", example: "avis-cse-2026.pdf" },
 		uploadedAt: { type: "string", format: "date-time" },
+		downloadUrl: {
+			type: "string",
+			description:
+				"Relative URL to download the file via GET /api/v1/files/{fileId}",
+			example: "/api/v1/files/abc-123",
+		},
 	},
 } as const;
 
@@ -253,7 +289,7 @@ export const openApiSpec = {
 		title: "EGAPRO — API d'export",
 		description:
 			"API REST sécurisée permettant de consulter les déclarations d'égalité professionnelle et les fichiers associés (avis CSE, évaluations conjointes). L'accès nécessite une signature de requête (RSA-SHA256) et une clé API (Bearer token).",
-		version: "1.2.0",
+		version: "1.3.0",
 		contact: {
 			name: "Équipe EGAPRO — DNUM",
 		},
diff --git a/packages/app/src/modules/export/queries.ts b/packages/app/src/modules/export/queries.ts
@@ -174,6 +174,7 @@ export async function fetchCseOpinionsByDeclaration(
 	const rows = await database
 		.select({
 			declarationId: cseOpinions.declarationId,
+			declarationNumber: cseOpinions.declarationNumber,
 			type: cseOpinions.type,
 			opinion: cseOpinions.opinion,
 			opinionDate: cseOpinions.opinionDate,
