Add order parameter to addDocumentToStructure function (#9342)

* Add order parameter to addDocumentToStructure function

- Add 'order' parameter with 'prepend' | 'append' options to Collection.addDocumentToStructure
- Update import logic to use 'append' order to preserve document sorting during import
- Fixes issue where exported documents lose their sorting when re-imported
- Maintains backward compatibility by defaulting to append behavior

Fixes #7532

* Fix TypeScript error: rename order parameter to insertOrder

The 'order' parameter in addDocumentToStructure was conflicting with
Sequelize's FindOptions.order property, causing a type intersection
error. Renamed it to 'insertOrder' to avoid the conflict.

Fixes TypeScript compilation errors in:
- server/queues/processors/ImportsProcessor.ts
- server/queues/tasks/ImportTask.ts

---------

Co-authored-by: codegen-sh[bot] <131295404+codegen-sh[bot]@users.noreply.github.com>

server/models/Collection.ts

@@ -840,6 +840,7 @@ class Collection extends ParanoidModel<
       silent?: boolean;
       documentJson?: NavigationNode;
       includeArchived?: boolean;
+      insertOrder?: "prepend" | "append";
     } = {}
   ) {
     if (!this.documentStructure) {
@@ -856,24 +857,36 @@ class Collection extends ParanoidModel<
       ...options.documentJson,
     };
 
+    // Determine the insertion index based on order parameter or explicit index
+    let insertionIndex: number;
+
+    if (index !== undefined) {
+      // Explicit index takes precedence
+      insertionIndex = index;
+    } else if (options.insertOrder === "prepend") {
+      // Prepend to the beginning
+      insertionIndex = 0;
+    } else {
+      // Default behavior: append to the end (maintains backward compatibility)
+      insertionIndex = this.documentStructure.length;
+    }
+
     if (!document.parentDocumentId) {
       // Note: Index is supported on DB level but it's being ignored
       // by the API presentation until we build product support for it.
-      this.documentStructure.splice(
-        index !== undefined ? index : this.documentStructure.length,
-        0,
-        documentJson
-      );
+      this.documentStructure.splice(insertionIndex, 0, documentJson);
     } else {
       // Recursively place document
       const placeDocument = (documentList: NavigationNode[]) =>
         documentList.map((childDocument) => {
           if (document.parentDocumentId === childDocument.id) {
-            childDocument.children.splice(
-              index !== undefined ? index : childDocument.children.length,
-              0,
-              documentJson
-            );
+            const childInsertionIndex =
+              index !== undefined
+                ? index
+                : options.insertOrder === "prepend"
+                ? 0
+                : childDocument.children.length;
+            childDocument.children.splice(childInsertionIndex, 0, documentJson);
           } else {
             childDocument.children = placeDocument(childDocument.children);
           }

server/queues/processors/ImportsProcessor.ts

@@ -181,10 +181,11 @@ export default abstract class ImportsProcessor<
           },
           async (documents) => {
             for (const document of documents) {
-              await collection.addDocumentToStructure(document, 0, {
+              await collection.addDocumentToStructure(document, undefined, {
                 save: false,
                 silent: true,
                 transaction,
+                insertOrder: "append",
               });
             }
           }

server/queues/tasks/ImportTask.ts

@@ -473,9 +473,10 @@ export default abstract class ImportTask extends BaseTask<Props> {
             });
             documents.set(item.id, document);
 
-            await collection.addDocumentToStructure(document, 0, {
+            await collection.addDocumentToStructure(document, undefined, {
               transaction,
               save: false,
+              insertOrder: "append",
             });
           }