chore: add code documentation

Author: justandras

meteor/server/api/rest/v1/ingest.ts

@@ -439,6 +439,19 @@ class IngestServerAPI implements IngestRestAPI {
 		return ClientAPI.responseSuccess(rundown)
 	}
 
+	/**
+	 * Create a rundown through the REST ingest API.
+	 *
+	 * Note about playlist handling:
+	 *
+	 * Rundowns in Sofie are not owned by playlists. A playlist is merely a container
+	 * that may group multiple rundowns, and a rundown may move between playlists or
+	 * exist without an explicitly defined playlist.
+	 *
+	 * For this reason we intentionally do NOT include the playlistId when checking
+	 * if a rundown already exists. The `externalId` of a rundown is expected to be
+	 * unique within a studio, regardless of which playlist it belongs to.
+	 */
 	async postRundown(
 		_connection: Meteor.Connection,
 		_event: string,
@@ -455,6 +468,8 @@ class IngestServerAPI implements IngestRestAPI {
 		this.validateRundown(ingestRundown)
 		await this.validateAPIPayloadsForRundown(studio.blueprintId, ingestRundown)
 
+		// IMPORTANT: Do not scope rundown existence checks by playlistId.
+		// Rundowns are unique per studio, not per playlist.
 		const existingRundown = await Rundowns.findOneAsync({
 			$or: [
 				{