Merge pull request #63 from NYCU-SDC/refactor/refactor-answer-request-model

Refactor answer request models and update response structures

Author: YukinaMochizuki

src/form/answer/models.tsp

@@ -1,36 +1,55 @@
 using Http;
 
 namespace CoreSystem.Responses {
-	@example(#{ questionId: "ee894524-4bd8-4a64-8fd2-a53b39ca94cd", questionType: CoreSystem.Forms.QuestionTypes.shortText, value: #["John Doe"] })
+	@example(#{ questionId: "ee894524-4bd8-4a64-8fd2-a53b39ca94cd", questionType: CoreSystem.Forms.QuestionTypes.shortText, value: "John Doe" })
+	model StringAnswer {
+		@doc("The question being answered.")
+		questionId: uuid;
+
+		@doc("The type of the question being answered.")
+		questionType: CoreSystem.Forms.QuestionTypes.shortText | CoreSystem.Forms.QuestionTypes.longText | CoreSystem.Forms.QuestionTypes.hyperlink;
+
+		@doc("The answer value (format depends on questionType from questionId).")
+		value: string;
+	}
+
 	@example(#{
 		questionId: "2b2bc4f4-71c1-478b-9e36-516eac6b36c3",
 		questionType: CoreSystem.Forms.QuestionTypes.multipleChoice,
 		value: #["f421cfc2-2b84-4da9-9629-011af609935a", "2ca86a6d-7735-4f17-8676-29b4724b524f"],
 	})
 	@doc("Request model for submitting an individual answer")
-	model AnswerJSON {
+	model StringArrayAnswer {
 		@doc("The question being answered.")
 		questionId: uuid;
 
 		@doc("The type of the question being answered.")
 		questionType:
-			| CoreSystem.Forms.QuestionTypes.shortText
-			| CoreSystem.Forms.QuestionTypes.longText
 			| CoreSystem.Forms.QuestionTypes.singleChoice
 			| CoreSystem.Forms.QuestionTypes.multipleChoice
 			| CoreSystem.Forms.QuestionTypes.dropdown
 			| CoreSystem.Forms.QuestionTypes.detailedMultipleChoice
-			| CoreSystem.Forms.QuestionTypes.date
-			| CoreSystem.Forms.QuestionTypes.ranking
-			| CoreSystem.Forms.QuestionTypes.hyperlink;
+			| CoreSystem.Forms.QuestionTypes.ranking;
 
 		@doc("The answer value (format depends on questionType from questionId).")
 		value: string[];
 	}
 
+	@example(#{ questionId: "2b2bc4f4-71c1-478b-9e36-516eac6b36c3", questionType: CoreSystem.Forms.QuestionTypes.date, value: utcDateTime.fromISO("2024-05-06T12:20-12Z") })
+	model DateAnswer {
+		@doc("The question being answered.")
+		questionId: uuid;
+
+		@doc("The type of the question being answered.")
+		questionType: CoreSystem.Forms.QuestionTypes.date;
+
+		@doc("The answer value for date question in ISO format (e.g., '2024-12-31').")
+		value: utcDateTime;
+	}
+
 	@example(#{ questionId: "2b2bc4f4-71c1-478b-9e36-516eac6b36c3", questionType: CoreSystem.Forms.QuestionTypes.linearScale, value: 4 })
 	@doc("Request model for submitting an individual scale answer")
-	model ScaleAnswerJSON {
+	model ScaleAnswer {
 		@doc("The question being answered.")
 		questionId: uuid;
 
@@ -41,32 +60,38 @@ namespace CoreSystem.Responses {
 		value: int32;
 	}
 
-	@example(#{ questionId: "2b2bc4f4-71c1-478b-9e36-516eac6b36c3", questionType: CoreSystem.Forms.QuestionTypes.oauthConnect, avatarUrl: "https://example.com/avatar.jpg", username: "JohnDoe" })
+	@example(#{
+		questionId: "2b2bc4f4-71c1-478b-9e36-516eac6b36c3",
+		questionType: CoreSystem.Forms.QuestionTypes.oauthConnect,
+		value: #{ username: "johndoe", avatarUrl: "https://example.com/avatar.jpg" },
+	})
 	@doc("Response model for an OAuth answer")
-	model OauthAnswerJSON {
+	model OauthAnswer {
 		@doc("The question being answered.")
 		questionId: uuid;
 
 		@doc("The type of the question being answered.")
 		questionType: CoreSystem.Forms.QuestionTypes.oauthConnect;
 
-		@doc("The avatar URL from the OAuth provider.")
-		avatarUrl: string;
+		value: {
+			@doc("The avatar URL from the OAuth provider.")
+			avatarUrl: string;
 
-		@doc("The username from the OAuth provider.")
-		username: string;
+			@doc("The username from the OAuth provider.")
+			username: string;
+		};
 	}
 
 	@doc("Request model for update or submit the form response.")
 	@example(#{
 		answers: #[
-			#{ questionId: "ee894524-4bd8-4a64-8fd2-a53b39ca94cd", questionType: CoreSystem.Forms.QuestionTypes.shortText, value: #["John Doe"] },
+			#{ questionId: "ee894524-4bd8-4a64-8fd2-a53b39ca94cd", questionType: CoreSystem.Forms.QuestionTypes.shortText, value: "John Doe" },
 			#{ questionId: "2b2bc4f4-71c1-478b-9e36-516eac6b36c3", questionType: CoreSystem.Forms.QuestionTypes.linearScale, value: 4 }
 		],
 	})
 	model AnswersRequest {
 		@doc("The answers to be saved. Can contain a partial subset for drafts or the full set for submission.")
-		answers: (AnswerJSON | ScaleAnswerJSON)[];
+		answers: (StringAnswer | StringArrayAnswer | ScaleAnswer | DateAnswer)[];
 	}
 
 	@doc("Request model for uploading files as answers to a specific question in a response.")
@@ -81,7 +106,7 @@ namespace CoreSystem.Responses {
 		id: uuid;
 
 		@doc("The auto-created/updated answer with file URLs.")
-		questionAnswerPair: AnswerJSON;
+		questionAnswerPair: StringArrayAnswer;
 	}
 
 	@doc("Model for a question with its answer in preview view")
@@ -93,7 +118,7 @@ namespace CoreSystem.Responses {
 		displayValue: string;
 
 		@doc("The structured answer data for submission. Null if not answered yet.")
-		answerData?: AnswerJSON | ScaleAnswerJSON | OauthAnswerJSON;
+		answerData?: StringAnswer | StringArrayAnswer | ScaleAnswer | DateAnswer | OauthAnswer;
 	}
 
 	@example(#{
@@ -106,11 +131,11 @@ namespace CoreSystem.Responses {
 	})
 	@doc("Response model for getting an answer of a specific question.")
 	model GetQuestionResponse {
-		@doc("The response's unique identifier.")
+		@doc("Response ID that this question answer belongs to.")
 		id: uuid;
 
 		@doc("A question with its answer for this response..")
-		questionAnswerPair: AnswerJSON;
+		questionAnswerPair: StringAnswer | StringArrayAnswer | ScaleAnswer | DateAnswer | OauthAnswer;
 	}
 
 	@doc("Response model for a single answer in question answers view")
@@ -125,7 +150,7 @@ namespace CoreSystem.Responses {
 		submittedBy: uuid;
 
 		@doc("The answer data. Type depends on the question type.")
-		answer: AnswerJSON | ScaleAnswerJSON | OauthAnswerJSON;
+		answer: StringAnswer | StringArrayAnswer | ScaleAnswer | DateAnswer | OauthAnswer;
 
 		@doc("The creation timestamp of the answer.")
 		createdAt: utcDateTime;

src/form/answer/operations.tsp

@@ -32,12 +32,7 @@ namespace CoreSystem.Responses {
 	@doc("Upload files as answers for a specific question in the response. This operation automatically creates or updates the answer for this question with the uploaded file URLs.")
 	@route("/responses/{responseId}/questions/{questionId}/files")
 	@post
-	op uploadQuestionFiles(
-		@path responseId: uuid,
-		@path questionId: uuid,
-		@header("content-type") contentType: "multipart/form-data",
-		@multipartBody body: QuestionFilesUploadRequest,
-	): {
+	op uploadQuestionFiles(@path responseId: uuid, @path questionId: uuid, @header("content-type") contentType: "multipart/form-data", @multipartBody body: QuestionFilesUploadRequest): {
 		@statusCode statusCode: 200;
 		@body response: QuestionFilesUploadResponse;
 	} | {

src/form/question/models.tsp

@@ -162,6 +162,24 @@ namespace CoreSystem.Forms {
 		description?: string;
 	}
 
+	@doc("Options for date questions.")
+	model DateOption {
+		@doc("Whether the year component is required for the date.")
+		hasYear: boolean;
+
+		@doc("Whether the month component is required for the date.")
+		hasMonth: boolean;
+
+		@doc("Whether the day component is required for the date.")
+		hasDay: boolean;
+
+		@doc("Minimum date range in utcDateTime (e.g., 2025-01-01T00:00:00Z for 2025/1/1 00:00:00 UTC). If specified, use the first day of the month/year for the minimum value.")
+		minDate?: utcDateTime;
+
+		@doc("Maximum date range in utcDateTime (e.g., 2025-05-31T23:59:59Z for 2025/5/31 23:59:59 UTC). If specified, use the last day of the month/year for the maximum value.")
+		maxDate?: utcDateTime;
+	}
+
 	@doc("Response model for the detailed structure of a question.")
 	model QuestionResponse {
 		@doc("The question's unique identifier.")
@@ -191,6 +209,9 @@ namespace CoreSystem.Forms {
 		@doc("Available options for file upload questions.")
 		uploadFile?: UploadFileOption;
 
+		@doc("Available options for date questions.")
+		date?: DateOption;
+
 		@doc("Available options for OAuth connect questions.")
 		oauthConnect?: CoreSystem.Auth.OAuthProviders;
 
@@ -273,6 +294,22 @@ namespace CoreSystem.Forms {
 		order: 12,
 		oauthConnect: CoreSystem.Auth.OAuthProviders.github,
 	})
+	@example(#{
+		required: true,
+		type: QuestionTypes.date,
+		title: "When will you graduate?",
+		description: "Please select your graduation date",
+		order: 13,
+		date: #{ hasYear: true, hasMonth: true, hasDay: true },
+	})
+	@example(#{
+		required: true,
+		type: QuestionTypes.date,
+		title: "Which year did you join?",
+		description: "Select year and month only",
+		order: 14,
+		date: #{ hasYear: true, hasMonth: true, hasDay: false },
+	})
 	model QuestionRequest {
 		@doc("Whether the question is required to answer or not.")
 		required: boolean;
@@ -298,6 +335,9 @@ namespace CoreSystem.Forms {
 		@doc("Available options for file upload questions.")
 		uploadFile?: UploadFileOption;
 
+		@doc("Available options for date questions.")
+		date?: DateOption;
+
 		@doc("Available options for OAuth connect questions.")
 		oauthConnect?: CoreSystem.Auth.OAuthProviders;
 

src/form/response/models.tsp

@@ -16,11 +16,11 @@ namespace CoreSystem.Responses {
 		updatedAt: utcDateTime;
 
 		@doc("The updated answer data.")
-		answers: (AnswerJSON | ScaleAnswerJSON | OauthAnswerJSON)[];
+		answers: (StringAnswer | StringArrayAnswer | ScaleAnswer | DateAnswer)[];
 	}
 
 	@doc("Response model for a single response in list view")
-	model ResponseJSON {
+	model Response {
 		@doc("The response's unique identifier.")
 		id: uuid;
 
@@ -40,7 +40,7 @@ namespace CoreSystem.Responses {
 		formId: uuid;
 
 		@doc("All responses for this form.")
-		responses: ResponseJSON[];
+		responses: Response[];
 	}
 
 	@doc("Model for a single section in preview view")