@musnows/scriverse 0.3.7 → 0.3.9

package/dist/app.js

@@ -16,6 +16,7 @@ import { TASK_TYPES } from "./domain.js";
 import { AppError } from "./errors.js";
 import { applyImportFileHints, parseNovelText } from "./parser.js";
 import { Store, versionedEntityTypes } from "./store.js";
+import { parsePagination } from "./pagination.js";
 import { normalizeUploadFileName } from "./utils.js";
 import { assertSafeAiEndpoint, createApiRateLimitMiddleware, createAuthenticationRateLimitMiddleware, createBasicAuthMiddleware, createSameOriginMiddleware, createSecurityHeadersMiddleware } from "./security.js";
 import { ImageCaptchaService } from "./image-captcha.js";
@@ -54,11 +55,12 @@ const loginSchema = z.object({
     ...captchaFields
 }).strict();
 const userUpdateSchema = z.object({ role: z.enum(["admin", "user"]).optional(), status: z.enum(["active", "disabled"]).optional() }).strict();
-const memberSchema = z.object({ userId: identifier, role: z.enum(["editor", "viewer"]) }).strict();
-const memberRoleSchema = z.object({ role: z.enum(["editor", "viewer"]) }).strict();
+const memberSchema = z.object({ userId: identifier, role: z.enum(["editor", "settings-editor", "viewer"]) }).strict();
+const memberRoleSchema = z.object({ role: z.enum(["editor", "settings-editor", "viewer"]) }).strict();
 const profileSchema = z.object({ displayName: z.string().trim().min(1).max(80) }).strict();
 const passwordChangeSchema = z.object({ currentPassword: z.string().max(200), newPassword: passwordSchema }).strict();
 const changeNoteSchema = z.string().trim().max(500).optional();
+const expectedVersionNoSchema = z.coerce.number().int().positive().optional();
 function validateImportedText(text) {
     if (text.length > maximumImportedTextLength)
         throw new AppError(413, "IMPORT_TEXT_TOO_LARGE", "导入文件解压后的文本超过 2000 万字符限制");
@@ -173,7 +175,7 @@ const organizationSchema = z.object({
     description: z.string().max(100_000).optional(),
     settings: z.array(z.string().trim().min(1).max(20_000)).max(200).optional(),
     memberIds: z.array(identifier).max(1000).optional()
-});
+}).strict();
 const raceSchema = z.object({
     name: nonEmpty.max(200),
     parentRaceId: identifier.nullable().optional(),
@@ -474,8 +476,15 @@ export function createRuntime(options) {
         });
         data(response, result);
     });
-    app.get("/api/users", (_request, response) => data(response, auth.listUsers()));
-    app.get("/api/users/directory", (request, response) => data(response, auth.directory(String(request.query.q ?? ""))));
+    app.get("/api/users", (request, response) => {
+        const pagination = parsePagination(request.query);
+        data(response, pagination ? auth.listUsersPage(pagination) : auth.listUsers());
+    });
+    app.get("/api/users/directory", (request, response) => {
+        const pagination = parsePagination(request.query);
+        const query = String(request.query.q ?? "");
+        data(response, pagination ? auth.directoryPage(query, pagination) : auth.directory(query));
+    });
     app.get("/api/user-avatars/:userId", (request, response) => {
         const avatar = auth.getAvatar(request.params.userId);
         response.setHeader("Content-Type", avatar.mimeType);
@@ -491,7 +500,10 @@ export function createRuntime(options) {
         store.audit(null, "user.updated", "user", updated.userId, { role: updated.role, status: updated.status });
         data(response, updated);
     });
-    app.get("/api/works", (_request, response) => data(response, store.listWorks()));
+    app.get("/api/works", (request, response) => {
+        const pagination = parsePagination(request.query);
+        data(response, pagination ? store.listWorksPage(pagination) : store.listWorks());
+    });
     app.post("/api/works", (request, response) => data(response, store.createWork(parse(workSchema, request.body)), 201));
     app.post("/api/works/import", upload.single("file"), async (request, response) => {
         if (!request.file)
@@ -512,8 +524,14 @@ export function createRuntime(options) {
         });
         data(response, store.createImportedWork(input, originalFileName, extension.slice(1), parsedNovel), 201);
     });
-    app.get("/api/works/:workId", (request, response) => data(response, store.getWorkDirectory(request.params.workId)));
-    app.get("/api/works/:workId/members", (request, response) => data(response, auth.listMembers(request.params.workId)));
+    app.get("/api/works/:workId", (request, response) => {
+        const pagination = parsePagination(request.query);
+        data(response, pagination ? store.getWorkDirectoryPage(request.params.workId, pagination) : store.getWorkDirectory(request.params.workId));
+    });
+    app.get("/api/works/:workId/members", (request, response) => {
+        const pagination = parsePagination(request.query);
+        data(response, pagination ? auth.listMembersPage(request.params.workId, pagination) : auth.listMembers(request.params.workId));
+    });
     app.post("/api/works/:workId/members", (request, response) => {
         if (!request.authUser)
             throw new AppError(401, "AUTH_REQUIRED", "请先登录");
@@ -533,9 +551,13 @@ export function createRuntime(options) {
         store.audit(request.params.workId, "work.member-removed", "user", request.params.userId);
         data(response, members);
     });
-    app.patch("/api/works/:workId", (request, response) => data(response, store.updateWork(request.params.workId, parse(workSchema.partial(), request.body))));
+    app.patch("/api/works/:workId", (request, response) => {
+        const { expectedVersionNo, changeNote, ...input } = parse(workSchema.partial().extend({ expectedVersionNo: expectedVersionNoSchema, changeNote: changeNoteSchema }).strict(), request.body);
+        data(response, store.updateWork(request.params.workId, input, expectedVersionNo, "manual", null, changeNote));
+    });
     app.delete("/api/works/:workId", async (request, response) => {
-        const removableStorageKeys = store.deleteWork(request.params.workId);
+        const input = parse(z.object({ expectedVersionNo: expectedVersionNoSchema }).strict(), request.body ?? {});
+        const removableStorageKeys = store.deleteWork(request.params.workId, input.expectedVersionNo);
         await Promise.all(removableStorageKeys.map((storageKey) => attachmentStorage.remove(storageKey)));
         noContent(response);
     });
@@ -557,15 +579,21 @@ export function createRuntime(options) {
         const mimeType = isPng ? "image/png" : isJpeg ? "image/jpeg" : isWebp ? "image/webp" : null;
         if (!mimeType)
             throw new AppError(415, "INVALID_COVER", "封面文件内容不是有效的 PNG、JPEG 或 WebP 图片");
-        data(response, store.setWorkCover(String(request.params.workId), mimeType, bytes));
+        const expectedVersionNo = parse(expectedVersionNoSchema, request.body.expectedVersionNo);
+        data(response, store.setWorkCover(String(request.params.workId), mimeType, bytes, expectedVersionNo));
     });
     app.delete("/api/works/:workId/cover", (request, response) => {
-        store.deleteWorkCover(request.params.workId);
+        const input = parse(z.object({ expectedVersionNo: expectedVersionNoSchema }).strict(), request.body ?? {});
+        store.deleteWorkCover(request.params.workId, input.expectedVersionNo);
         noContent(response);
     });
-    app.get("/api/works/:workId/file-versions", (request, response) => data(response, store.listFileVersions(request.params.workId)));
+    app.get("/api/works/:workId/file-versions", (request, response) => {
+        const pagination = parsePagination(request.query);
+        data(response, pagination ? store.listFileVersionsPage(request.params.workId, pagination) : store.listFileVersions(request.params.workId));
+    });
     app.post("/api/works/:workId/file-versions/:fileVersionId/restore", (request, response) => {
-        data(response, store.restoreFileVersion(request.params.workId, request.params.fileVersionId));
+        const input = parse(z.object({ expectedVersionNo: expectedVersionNoSchema }).strict(), request.body ?? {});
+        data(response, store.restoreFileVersion(request.params.workId, request.params.fileVersionId, input.expectedVersionNo));
     });
     app.post("/api/works/:workId/import", upload.single("file"), async (request, response) => {
         if (!request.file)
@@ -579,19 +607,23 @@ export function createRuntime(options) {
             ? await extractDocxText(request.file.buffer)
             : decodeUtf8ImportedText(request.file.buffer));
         const parsed = applyImportFileHints(parseNovelText(text), originalFileName);
-        data(response, store.importNovel(String(request.params.workId), originalFileName, extension.slice(1), parsed), 201);
+        const mode = parse(z.enum(["append", "overwrite"]), request.body.mode ?? "overwrite");
+        const expectedVersionNo = parse(expectedVersionNoSchema, request.body.expectedVersionNo);
+        data(response, store.importNovel(String(request.params.workId), originalFileName, extension.slice(1), parsed, mode, expectedVersionNo), 201);
     });
     app.post("/api/works/:workId/volumes", (request, response) => {
         const input = parse(z.object({ title: nonEmpty.max(200), kind: z.enum(["main", "prequel", "extra", "epilogue", "appendix"]).optional(), description: z.string().max(5_000).optional(), keywords: z.array(nonEmpty.max(100)).max(100).optional() }), request.body);
         data(response, store.createVolume(request.params.workId, input), 201);
     });
     app.patch("/api/volumes/:volumeId", (request, response) => {
-        const input = parse(z.object({ title: nonEmpty.max(200).optional(), kind: z.enum(["main", "prequel", "extra", "epilogue", "appendix"]).optional(), description: z.string().max(5_000).optional(), keywords: z.array(nonEmpty.max(100)).max(100).optional(), sortOrder: z.number().int().min(0).optional() }), request.body);
-        data(response, store.updateVolume(request.params.volumeId, input));
+        const input = parse(z.object({ title: nonEmpty.max(200).optional(), kind: z.enum(["main", "prequel", "extra", "epilogue", "appendix"]).optional(), description: z.string().max(5_000).optional(), keywords: z.array(nonEmpty.max(100)).max(100).optional(), sortOrder: z.number().int().min(0).optional(), expectedVersionNo: expectedVersionNoSchema, changeNote: changeNoteSchema }).strict(), request.body);
+        const { expectedVersionNo, changeNote, ...volumeInput } = input;
+        data(response, store.updateVolume(request.params.volumeId, volumeInput, expectedVersionNo, "manual", null, changeNote));
     });
     app.get("/api/volumes/:volumeId", (request, response) => data(response, store.getVolume(request.params.volumeId)));
     app.delete("/api/volumes/:volumeId", (request, response) => {
-        store.deleteVolume(request.params.volumeId);
+        const input = parse(z.object({ expectedVersionNo: expectedVersionNoSchema }).strict(), request.body ?? {});
+        store.deleteVolume(request.params.volumeId, input.expectedVersionNo);
         noContent(response);
     });
     app.post("/api/works/:workId/chapters", (request, response) => {
@@ -600,32 +632,44 @@ export function createRuntime(options) {
     });
     app.get("/api/chapters/:chapterId", (request, response) => data(response, store.getChapter(request.params.chapterId)));
     app.patch("/api/chapters/:chapterId", (request, response) => {
-        const input = parse(z.object({ title: nonEmpty.max(300).optional(), content: z.string().max(2_000_000).optional(), excludedFromAnalysis: z.boolean().optional(), chapterType: chapterTypeSchema.optional(), source: z.enum(["manual", "auto"]).optional(), changeNote: changeNoteSchema }).strict(), request.body);
-        const { source, changeNote, ...chapterInput } = input;
-        data(response, store.saveChapter(request.params.chapterId, chapterInput, source ?? "manual", null, changeNote));
+        const input = parse(z.object({ title: nonEmpty.max(300).optional(), content: z.string().max(2_000_000).optional(), excludedFromAnalysis: z.boolean().optional(), chapterType: chapterTypeSchema.optional(), source: z.enum(["manual", "auto"]).optional(), changeNote: changeNoteSchema, expectedVersionNo: expectedVersionNoSchema }).strict(), request.body);
+        const { source, changeNote, expectedVersionNo, ...chapterInput } = input;
+        data(response, store.saveChapter(request.params.chapterId, chapterInput, source ?? "manual", null, changeNote, expectedVersionNo));
     });
     app.delete("/api/chapters/:chapterId", (request, response) => {
-        store.deleteChapter(request.params.chapterId);
+        const input = parse(z.object({ expectedVersionNo: expectedVersionNoSchema }).strict(), request.body ?? {});
+        store.deleteChapter(request.params.chapterId, input.expectedVersionNo);
         noContent(response);
     });
-    app.get("/api/chapters/:chapterId/versions", (request, response) => data(response, store.listChapterVersions(request.params.chapterId)));
-    app.get("/api/chapters/:chapterId/insights", (request, response) => data(response, store.listChapterInsights(request.params.chapterId)));
+    app.get("/api/chapters/:chapterId/versions", (request, response) => {
+        const pagination = parsePagination(request.query);
+        data(response, pagination ? store.listChapterVersionsPage(request.params.chapterId, pagination) : store.listChapterVersions(request.params.chapterId));
+    });
+    app.get("/api/chapters/:chapterId/insights", (request, response) => {
+        const pagination = parsePagination(request.query);
+        data(response, pagination ? store.listChapterInsightsPage(request.params.chapterId, pagination) : store.listChapterInsights(request.params.chapterId));
+    });
     app.post("/api/chapters/:chapterId/restore", (request, response) => {
-        const input = parse(z.object({ versionNo: z.number().int().positive() }), request.body);
-        data(response, store.restoreChapter(request.params.chapterId, input.versionNo));
+        const input = parse(z.object({ versionNo: z.number().int().positive(), expectedVersionNo: expectedVersionNoSchema }).strict(), request.body);
+        data(response, store.restoreChapter(request.params.chapterId, input.versionNo, input.expectedVersionNo));
     });
     app.post("/api/chapters/:chapterId/move", (request, response) => {
-        const input = parse(z.object({ volumeId: identifier, sortOrder: z.number().int().min(0) }), request.body);
-        data(response, store.moveChapter(request.params.chapterId, input));
+        const input = parse(z.object({ volumeId: identifier, sortOrder: z.number().int().min(0), expectedVersionNo: expectedVersionNoSchema }).strict(), request.body);
+        const { expectedVersionNo, ...moveInput } = input;
+        data(response, store.moveChapter(request.params.chapterId, moveInput, expectedVersionNo));
+    });
+    app.get("/api/works/:workId/outlines", (request, response) => {
+        const pagination = parsePagination(request.query);
+        data(response, pagination ? store.listChapterOutlinesPage(request.params.workId, pagination) : store.listChapterOutlines(request.params.workId));
     });
-    app.get("/api/works/:workId/outlines", (request, response) => data(response, store.listChapterOutlines(request.params.workId)));
     app.get("/api/chapters/:chapterId/outline", (request, response) => data(response, store.getChapterOutline(request.params.chapterId)));
     app.put("/api/chapters/:chapterId/outline", (request, response) => {
-        const { changeNote, ...input } = parse(chapterOutlineSchema.extend({ changeNote: changeNoteSchema }), request.body);
-        data(response, store.upsertChapterOutline(request.params.chapterId, input, "manual", null, changeNote));
+        const { changeNote, expectedVersionNo, ...input } = parse(chapterOutlineSchema.extend({ changeNote: changeNoteSchema, expectedVersionNo: expectedVersionNoSchema }).strict(), request.body);
+        data(response, store.upsertChapterOutline(request.params.chapterId, input, "manual", null, changeNote, expectedVersionNo));
     });
     app.delete("/api/chapters/:chapterId/outline", (request, response) => {
-        store.deleteChapterOutline(request.params.chapterId);
+        const input = parse(z.object({ expectedVersionNo: expectedVersionNoSchema }).strict(), request.body ?? {});
+        store.deleteChapterOutline(request.params.chapterId, input.expectedVersionNo);
         noContent(response);
     });
     app.get("/api/works/:workId/foreshadows", (request, response) => {
@@ -633,39 +677,52 @@ export function createRuntime(options) {
             status: z.enum(["all", "unresolved", "resolved"]).default("all"),
             currentChapterId: identifier.optional()
         }), request.query);
-        data(response, store.listForeshadows(request.params.workId, query.status, query.currentChapterId));
+        const pagination = parsePagination(request.query);
+        data(response, pagination
+            ? store.listForeshadowsPage(request.params.workId, pagination, query.status, query.currentChapterId)
+            : store.listForeshadows(request.params.workId, query.status, query.currentChapterId));
     });
     app.post("/api/works/:workId/foreshadows", (request, response) => {
         data(response, store.createForeshadow(request.params.workId, parse(foreshadowSchema, request.body)), 201);
     });
     app.get("/api/foreshadows/:foreshadowId", (request, response) => data(response, store.getForeshadow(request.params.foreshadowId)));
     app.patch("/api/foreshadows/:foreshadowId", (request, response) => {
-        const { changeNote, ...input } = parse(foreshadowSchema.partial().extend({ changeNote: changeNoteSchema }), request.body);
-        data(response, store.updateForeshadow(request.params.foreshadowId, input, "manual", null, changeNote));
+        const { changeNote, expectedVersionNo, ...input } = parse(foreshadowSchema.partial().extend({ changeNote: changeNoteSchema, expectedVersionNo: expectedVersionNoSchema }).strict(), request.body);
+        data(response, store.updateForeshadow(request.params.foreshadowId, input, "manual", null, changeNote, expectedVersionNo));
     });
     app.delete("/api/foreshadows/:foreshadowId", (request, response) => {
-        store.deleteForeshadow(request.params.foreshadowId);
+        const input = parse(z.object({ expectedVersionNo: expectedVersionNoSchema }).strict(), request.body ?? {});
+        store.deleteForeshadow(request.params.foreshadowId, input.expectedVersionNo);
         noContent(response);
     });
     app.post("/api/foreshadows/:foreshadowId/occurrences", (request, response) => {
-        data(response, store.createForeshadowOccurrence(request.params.foreshadowId, parse(foreshadowOccurrenceSchema, request.body)), 201);
+        const input = parse(foreshadowOccurrenceSchema.extend({ expectedVersionNo: expectedVersionNoSchema }).strict(), request.body);
+        const { expectedVersionNo, ...occurrenceInput } = input;
+        data(response, store.createForeshadowOccurrence(request.params.foreshadowId, occurrenceInput, expectedVersionNo), 201);
     });
     app.patch("/api/foreshadow-occurrences/:occurrenceId", (request, response) => {
-        data(response, store.updateForeshadowOccurrence(request.params.occurrenceId, parse(foreshadowOccurrenceSchema.partial(), request.body)));
+        const input = parse(foreshadowOccurrenceSchema.partial().extend({ expectedVersionNo: expectedVersionNoSchema }).strict(), request.body);
+        const { expectedVersionNo, ...occurrenceInput } = input;
+        data(response, store.updateForeshadowOccurrence(request.params.occurrenceId, occurrenceInput, expectedVersionNo));
     });
     app.delete("/api/foreshadow-occurrences/:occurrenceId", (request, response) => {
-        store.deleteForeshadowOccurrence(request.params.occurrenceId);
+        const input = parse(z.object({ expectedVersionNo: expectedVersionNoSchema }).strict(), request.body ?? {});
+        store.deleteForeshadowOccurrence(request.params.occurrenceId, input.expectedVersionNo);
         noContent(response);
     });
-    app.get("/api/works/:workId/settings", (request, response) => data(response, store.listSettings(request.params.workId)));
+    app.get("/api/works/:workId/settings", (request, response) => {
+        const pagination = parsePagination(request.query);
+        data(response, pagination ? store.listSettingsPage(request.params.workId, pagination) : store.listSettings(request.params.workId));
+    });
     app.post("/api/works/:workId/settings", (request, response) => data(response, store.createSetting(request.params.workId, parse(settingSchema, request.body)), 201));
     app.get("/api/settings/:settingId", (request, response) => data(response, store.getSetting(request.params.settingId)));
     app.patch("/api/settings/:settingId", (request, response) => {
-        const { changeNote, ...input } = parse(settingSchema.partial().extend({ changeNote: changeNoteSchema }), request.body);
-        data(response, store.updateSetting(request.params.settingId, input, "manual", null, changeNote));
+        const { changeNote, expectedVersionNo, ...input } = parse(settingSchema.partial().extend({ changeNote: changeNoteSchema, expectedVersionNo: expectedVersionNoSchema }).strict(), request.body);
+        data(response, store.updateSetting(request.params.settingId, input, "manual", null, changeNote, expectedVersionNo));
     });
     app.delete("/api/settings/:settingId", (request, response) => {
-        store.deleteSetting(request.params.settingId);
+        const input = parse(z.object({ expectedVersionNo: expectedVersionNoSchema }).strict(), request.body ?? {});
+        store.deleteSetting(request.params.settingId, input.expectedVersionNo);
         noContent(response);
     });
     app.get("/api/works/:workId/characters", (request, response) => {
@@ -673,25 +730,47 @@ export function createRuntime(options) {
             includeSections: z.enum(["true", "false"]).default("false"),
             includeMerged: z.enum(["0", "1"]).default("0")
         }), request.query);
-        data(response, store.listCharacters(request.params.workId, includeSections === "true", includeMerged === "1"));
+        const pagination = parsePagination(request.query);
+        data(response, pagination
+            ? store.listCharactersPage(request.params.workId, pagination, includeSections === "true", includeMerged === "1")
+            : store.listCharacters(request.params.workId, includeSections === "true", includeMerged === "1"));
     });
     app.post("/api/works/:workId/characters", (request, response) => data(response, store.createCharacter(request.params.workId, parse(characterSchema, request.body)), 201));
     app.get("/api/characters/:characterId", (request, response) => data(response, store.getCharacter(request.params.characterId)));
     app.patch("/api/characters/:characterId", (request, response) => {
-        const { changeNote, ...input } = parse(characterUpdateSchema, request.body);
-        data(response, store.updateCharacter(request.params.characterId, input, "manual", null, changeNote));
+        const { changeNote, expectedVersionNo, ...input } = parse(characterUpdateSchema.extend({ expectedVersionNo: expectedVersionNoSchema }), request.body);
+        data(response, store.updateCharacter(request.params.characterId, input, "manual", null, changeNote, expectedVersionNo));
+    });
+    app.get("/api/characters/:characterId/versions", (request, response) => {
+        const pagination = parsePagination(request.query);
+        data(response, pagination ? store.listCharacterVersionsPage(request.params.characterId, pagination) : store.listCharacterVersions(request.params.characterId));
     });
-    app.get("/api/characters/:characterId/versions", (request, response) => data(response, store.listCharacterVersions(request.params.characterId)));
     app.post("/api/characters/:characterId/restore", (request, response) => {
-        const input = parse(z.object({ versionNo: z.number().int().positive() }), request.body);
-        data(response, store.restoreCharacter(request.params.characterId, input.versionNo));
+        const input = parse(z.object({ versionNo: z.number().int().positive(), expectedVersionNo: expectedVersionNoSchema }).strict(), request.body);
+        data(response, store.restoreCharacter(request.params.characterId, input.versionNo, input.expectedVersionNo));
     });
     app.delete("/api/characters/:characterId", (request, response) => {
-        store.deleteCharacter(request.params.characterId);
+        const input = parse(z.object({ expectedVersionNo: expectedVersionNoSchema }).strict(), request.body ?? {});
+        store.deleteCharacter(request.params.characterId, input.expectedVersionNo);
         noContent(response);
     });
+    app.post("/api/characters/:characterId/merge", (request, response) => {
+        const input = parse(z.object({
+            targetCharacterId: identifier,
+            expectedTargetVersionNo: z.number().int().positive(),
+            expectedSourceVersionNo: z.number().int().positive()
+        }).strict(), request.body);
+        data(response, store.mergeCharacters({
+            reviewId: null,
+            sourceCharacterId: request.params.characterId,
+            ...input
+        }));
+    });
     app.get("/api/characters/:characterId/sections", (request, response) => {
-        data(response, store.listCharacterProfileSections(request.params.characterId));
+        const pagination = parsePagination(request.query);
+        data(response, pagination
+            ? store.listCharacterProfileSectionsPage(request.params.characterId, pagination)
+            : store.listCharacterProfileSections(request.params.characterId));
     });
     app.post("/api/characters/:characterId/sections", (request, response) => {
         data(response, store.createCharacterProfileSection(request.params.characterId, parse(characterProfileSectionSchema, request.body)), 201);
@@ -700,22 +779,27 @@ export function createRuntime(options) {
         data(response, store.getCharacterProfileSection(request.params.sectionId));
     });
     app.patch("/api/character-sections/:sectionId", (request, response) => {
-        const { changeNote, ...input } = parse(characterProfileSectionSchema.partial().extend({ changeNote: changeNoteSchema }).strict(), request.body);
-        data(response, store.updateCharacterProfileSection(request.params.sectionId, input, "manual", null, changeNote));
+        const { changeNote, expectedVersionNo, ...input } = parse(characterProfileSectionSchema.partial().extend({ changeNote: changeNoteSchema, expectedVersionNo: expectedVersionNoSchema }).strict(), request.body);
+        data(response, store.updateCharacterProfileSection(request.params.sectionId, input, "manual", null, changeNote, expectedVersionNo));
     });
     app.delete("/api/character-sections/:sectionId", (request, response) => {
-        store.deleteCharacterProfileSection(request.params.sectionId);
+        const input = parse(z.object({ expectedVersionNo: expectedVersionNoSchema }).strict(), request.body ?? {});
+        store.deleteCharacterProfileSection(request.params.sectionId, input.expectedVersionNo);
         noContent(response);
     });
     app.get("/api/character-sections/:sectionId/versions", (request, response) => {
-        data(response, store.listCharacterProfileSectionVersions(request.params.sectionId));
+        const pagination = parsePagination(request.query);
+        data(response, pagination
+            ? store.listCharacterProfileSectionVersionsPage(request.params.sectionId, pagination)
+            : store.listCharacterProfileSectionVersions(request.params.sectionId));
     });
     app.post("/api/character-sections/:sectionId/restore", (request, response) => {
-        const input = parse(z.object({ versionNo: z.number().int().positive() }).strict(), request.body);
-        data(response, store.restoreCharacterProfileSection(request.params.sectionId, input.versionNo));
+        const input = parse(z.object({ versionNo: z.number().int().positive(), expectedVersionNo: expectedVersionNoSchema }).strict(), request.body);
+        data(response, store.restoreCharacterProfileSection(request.params.sectionId, input.versionNo, input.expectedVersionNo));
     });
     app.get("/api/works/:workId/attachments", (request, response) => {
-        data(response, store.listAttachments(request.params.workId));
+        const pagination = parsePagination(request.query);
+        data(response, pagination ? store.listAttachmentsPage(request.params.workId, pagination) : store.listAttachments(request.params.workId));
     });
     app.post("/api/works/:workId/attachments", attachmentUpload.single("file"), async (request, response) => {
         if (!request.file)
@@ -758,44 +842,67 @@ export function createRuntime(options) {
             await attachmentStorage.remove(deleted.storageKey);
         noContent(response);
     });
-    app.get("/api/works/:workId/races", (request, response) => data(response, store.listRaces(request.params.workId)));
+    app.get("/api/works/:workId/races", (request, response) => {
+        const pagination = parsePagination(request.query);
+        data(response, pagination ? store.listRacesPage(request.params.workId, pagination) : store.listRaces(request.params.workId));
+    });
     app.post("/api/works/:workId/races", (request, response) => {
         data(response, store.createRace(request.params.workId, parse(raceSchema, request.body)), 201);
     });
     app.get("/api/races/:raceId", (request, response) => data(response, store.getRace(request.params.raceId)));
     app.patch("/api/races/:raceId", (request, response) => {
-        const { changeNote, ...input } = parse(raceSchema.partial().extend({ changeNote: changeNoteSchema }), request.body);
-        data(response, store.updateRace(request.params.raceId, input, "manual", null, changeNote));
+        const { changeNote, expectedVersionNo, ...input } = parse(raceSchema.partial().extend({ changeNote: changeNoteSchema, expectedVersionNo: expectedVersionNoSchema }).strict(), request.body);
+        data(response, store.updateRace(request.params.raceId, input, "manual", null, changeNote, expectedVersionNo));
     });
     app.delete("/api/races/:raceId", (request, response) => {
-        store.deleteRace(request.params.raceId);
+        const input = parse(z.object({ expectedVersionNo: expectedVersionNoSchema }).strict(), request.body ?? {});
+        store.deleteRace(request.params.raceId, input.expectedVersionNo);
         noContent(response);
     });
-    app.get("/api/works/:workId/organizations", (request, response) => data(response, store.listOrganizations(request.params.workId)));
+    app.post("/api/races/:raceId/merge", (request, response) => {
+        const input = parse(z.object({ targetRaceId: identifier }).strict(), request.body);
+        data(response, store.mergeRaces(request.params.raceId, input.targetRaceId));
+    });
+    app.get("/api/works/:workId/organizations", (request, response) => {
+        const pagination = parsePagination(request.query);
+        data(response, pagination ? store.listOrganizationsPage(request.params.workId, pagination) : store.listOrganizations(request.params.workId));
+    });
     app.post("/api/works/:workId/organizations", (request, response) => {
         data(response, store.createOrganization(request.params.workId, parse(organizationSchema, request.body)), 201);
     });
     app.get("/api/organizations/:organizationId", (request, response) => data(response, store.getOrganization(request.params.organizationId)));
     app.patch("/api/organizations/:organizationId", (request, response) => {
-        const { changeNote, ...input } = parse(organizationSchema.partial().extend({ changeNote: changeNoteSchema }), request.body);
-        data(response, store.updateOrganization(request.params.organizationId, input, "manual", null, changeNote));
+        const { changeNote, expectedVersionNo, ...input } = parse(organizationSchema.partial().extend({ changeNote: changeNoteSchema, expectedVersionNo: expectedVersionNoSchema }).strict(), request.body);
+        data(response, store.updateOrganization(request.params.organizationId, input, "manual", null, changeNote, expectedVersionNo));
     });
     app.delete("/api/organizations/:organizationId", (request, response) => {
-        store.deleteOrganization(request.params.organizationId);
+        const input = parse(z.object({ expectedVersionNo: expectedVersionNoSchema }).strict(), request.body ?? {});
+        store.deleteOrganization(request.params.organizationId, input.expectedVersionNo);
         noContent(response);
     });
-    app.get("/api/works/:workId/timeline-tracks", (request, response) => data(response, store.listTimelineTracks(request.params.workId)));
+    app.post("/api/organizations/:organizationId/merge", (request, response) => {
+        const input = parse(z.object({ targetOrganizationId: identifier }).strict(), request.body);
+        data(response, store.mergeOrganizations(request.params.organizationId, input.targetOrganizationId));
+    });
+    app.get("/api/works/:workId/timeline-tracks", (request, response) => {
+        const pagination = parsePagination(request.query);
+        data(response, pagination ? store.listTimelineTracksPage(request.params.workId, pagination) : store.listTimelineTracks(request.params.workId));
+    });
     app.post("/api/works/:workId/timeline-tracks", (request, response) => data(response, store.createTimelineTrack(request.params.workId, parse(timelineTrackSchema, request.body)), 201));
     app.get("/api/timeline-tracks/:trackId", (request, response) => data(response, store.getTimelineTrack(request.params.trackId)));
     app.patch("/api/timeline-tracks/:trackId", (request, response) => {
-        const { changeNote, ...input } = parse(timelineTrackSchema.partial().extend({ changeNote: changeNoteSchema }), request.body);
-        data(response, store.updateTimelineTrack(request.params.trackId, input, "manual", null, changeNote));
+        const { changeNote, expectedVersionNo, ...input } = parse(timelineTrackSchema.partial().extend({ changeNote: changeNoteSchema, expectedVersionNo: expectedVersionNoSchema }).strict(), request.body);
+        data(response, store.updateTimelineTrack(request.params.trackId, input, "manual", null, changeNote, expectedVersionNo));
     });
     app.delete("/api/timeline-tracks/:trackId", (request, response) => {
-        store.deleteTimelineTrack(request.params.trackId);
+        const input = parse(z.object({ expectedVersionNo: expectedVersionNoSchema }).strict(), request.body ?? {});
+        store.deleteTimelineTrack(request.params.trackId, input.expectedVersionNo);
         noContent(response);
     });
-    app.get("/api/works/:workId/timeline", (request, response) => data(response, store.listTimelineEvents(request.params.workId)));
+    app.get("/api/works/:workId/timeline", (request, response) => {
+        const pagination = parsePagination(request.query);
+        data(response, pagination ? store.listTimelineEventsPage(request.params.workId, pagination) : store.listTimelineEvents(request.params.workId));
+    });
     app.post("/api/works/:workId/timeline", (request, response) => data(response, store.createTimelineEvent(request.params.workId, parse(timelineSchema, request.body)), 201));
     app.post("/api/works/:workId/timeline/merge", (request, response) => {
         const input = parse(z.object({
@@ -803,14 +910,16 @@ export function createRuntime(options) {
             name: nonEmpty.max(300),
             description: z.string().max(100_000).optional(),
             timeLabel: z.string().max(300).optional(),
-            timeSort: z.number().finite().nullable().optional()
-        }), request.body);
-        data(response, store.mergeTimelineEvents(request.params.workId, input.eventIds, input), 201);
+            timeSort: z.number().finite().nullable().optional(),
+            expectedVersionNos: z.record(identifier, z.number().int().positive()).optional()
+        }).strict(), request.body);
+        const { expectedVersionNos, ...mergeInput } = input;
+        data(response, store.mergeTimelineEvents(request.params.workId, input.eventIds, mergeInput, expectedVersionNos), 201);
     });
     app.get("/api/timeline/:eventId", (request, response) => data(response, store.getTimelineEvent(request.params.eventId)));
     app.patch("/api/timeline/:eventId", (request, response) => {
-        const { changeNote, ...input } = parse(timelineSchema.partial().extend({ changeNote: changeNoteSchema }), request.body);
-        data(response, store.updateTimelineEvent(request.params.eventId, input, "manual", null, changeNote));
+        const { changeNote, expectedVersionNo, ...input } = parse(timelineSchema.partial().extend({ changeNote: changeNoteSchema, expectedVersionNo: expectedVersionNoSchema }).strict(), request.body);
+        data(response, store.updateTimelineEvent(request.params.eventId, input, "manual", null, changeNote, expectedVersionNo));
     });
     app.post("/api/timeline/:eventId/split", (request, response) => {
         const input = parse(z.object({
@@ -819,42 +928,52 @@ export function createRuntime(options) {
                 description: z.string().max(100_000).optional(),
                 timeLabel: z.string().max(300).optional(),
                 timeSort: z.number().finite().nullable().optional()
-            })).min(2)
-        }), request.body);
-        data(response, store.splitTimelineEvent(request.params.eventId, input.parts), 201);
+            })).min(2),
+            expectedVersionNo: expectedVersionNoSchema
+        }).strict(), request.body);
+        data(response, store.splitTimelineEvent(request.params.eventId, input.parts, input.expectedVersionNo), 201);
     });
     app.delete("/api/timeline/:eventId", (request, response) => {
-        store.deleteTimelineEvent(request.params.eventId);
+        const input = parse(z.object({ expectedVersionNo: expectedVersionNoSchema }).strict(), request.body ?? {});
+        store.deleteTimelineEvent(request.params.eventId, input.expectedVersionNo);
         noContent(response);
     });
     app.get("/api/works/:workId/relationships", (request, response) => {
         const confidence = request.query.minimumConfidence ? Number(request.query.minimumConfidence) : 0;
         if (!Number.isFinite(confidence) || confidence < 0 || confidence > 1)
             throw new AppError(400, "INVALID_CONFIDENCE", "置信度必须在 0 到 1 之间");
-        data(response, store.listRelationships(request.params.workId, confidence));
+        const pagination = parsePagination(request.query);
+        data(response, pagination
+            ? store.listRelationshipsPage(request.params.workId, pagination, confidence)
+            : store.listRelationships(request.params.workId, confidence));
     });
     app.post("/api/works/:workId/relationships", (request, response) => data(response, store.createRelationship(request.params.workId, parse(relationshipSchema, request.body)), 201));
     app.get("/api/relationships/:relationshipId", (request, response) => data(response, store.getRelationship(request.params.relationshipId)));
     app.patch("/api/relationships/:relationshipId", (request, response) => {
-        const { changeNote, ...input } = parse(relationshipSchema.partial().extend({ changeNote: changeNoteSchema }), request.body);
-        data(response, store.updateRelationship(request.params.relationshipId, input, "manual", null, changeNote));
+        const { changeNote, expectedVersionNo, ...input } = parse(relationshipSchema.partial().extend({ changeNote: changeNoteSchema, expectedVersionNo: expectedVersionNoSchema }).strict(), request.body);
+        data(response, store.updateRelationship(request.params.relationshipId, input, "manual", null, changeNote, expectedVersionNo));
     });
     app.delete("/api/relationships/:relationshipId", (request, response) => {
-        store.deleteRelationship(request.params.relationshipId);
+        const input = parse(z.object({ expectedVersionNo: expectedVersionNoSchema }).strict(), request.body ?? {});
+        store.deleteRelationship(request.params.relationshipId, input.expectedVersionNo);
         noContent(response);
     });
     app.get("/api/entity-versions/:entityType/:entityId", (request, response) => {
         const input = parse(z.object({ entityType: versionedEntityTypeSchema, entityId: identifier }), request.params);
-        data(response, store.listEntityVersions(input.entityType, input.entityId));
+        const pagination = parsePagination(request.query);
+        data(response, pagination
+            ? store.listEntityVersionsPage(input.entityType, input.entityId, pagination)
+            : store.listEntityVersions(input.entityType, input.entityId));
     });
     app.post("/api/entity-versions/:entityType/:entityId/restore", (request, response) => {
         const params = parse(z.object({ entityType: versionedEntityTypeSchema, entityId: identifier }), request.params);
-        const input = parse(z.object({ versionNo: z.number().int().positive() }), request.body);
-        data(response, store.restoreEntityVersion(params.entityType, params.entityId, input.versionNo));
+        const input = parse(z.object({ versionNo: z.number().int().positive(), expectedVersionNo: expectedVersionNoSchema }).strict(), request.body);
+        data(response, store.restoreEntityVersion(params.entityType, params.entityId, input.versionNo, input.expectedVersionNo));
     });
     app.get("/api/works/:workId/reviews", (request, response) => {
         const status = typeof request.query.status === "string" ? request.query.status : undefined;
-        data(response, store.listReviewItems(request.params.workId, status));
+        const pagination = parsePagination(request.query);
+        data(response, pagination ? store.listReviewItemsPage(request.params.workId, pagination, status) : store.listReviewItems(request.params.workId, status));
     });
     app.post("/api/works/:workId/reviews", (request, response) => data(response, store.createReviewItem(request.params.workId, parse(reviewSchema, request.body)), 201));
     app.patch("/api/reviews/:reviewId", (request, response) => data(response, store.updateReviewItem(request.params.reviewId, parse(reviewSchema.partial(), request.body))));
@@ -875,7 +994,10 @@ export function createRuntime(options) {
         }
         data(response, store.mergeCharacters({ reviewId: request.params.reviewId, ...input }));
     });
-    app.get("/api/works/:workId/tasks", (request, response) => data(response, store.listTasks(request.params.workId)));
+    app.get("/api/works/:workId/tasks", (request, response) => {
+        const pagination = parsePagination(request.query);
+        data(response, pagination ? store.listTasksPage(request.params.workId, pagination) : store.listTasks(request.params.workId));
+    });
     app.post("/api/works/:workId/tasks", (request, response) => {
         const input = parse(z.object({ taskType: z.enum(["structure", "chapter-analysis", "character-extraction", "character-summary", "character-identity-audit", "timeline-analysis", "relationship-analysis", "worldview-analysis", "setting-extraction", "consistency-check", "report-update", "book-analysis"]), scope: jsonObject.optional() }), request.body);
         data(response, store.createTask(request.params.workId, input), 201);
@@ -889,9 +1011,15 @@ export function createRuntime(options) {
         data(response, await ai.runTask(request.params.taskId, input.modelId));
     });
     app.post("/api/tasks/:taskId/cancel", (request, response) => data(response, ai.cancelTask(request.params.taskId)));
-    app.get("/api/platform/ai/providers", (_request, response) => data(response, ai.listProviders()));
+    app.get("/api/platform/ai/providers", (request, response) => {
+        const pagination = parsePagination(request.query);
+        data(response, pagination ? ai.listProvidersPage(pagination) : ai.listProviders());
+    });
     app.post("/api/platform/ai/providers", (request, response) => data(response, ai.createProvider(parse(providerSchema, request.body)), 201));
-    app.get("/api/platform/ai/models", (_request, response) => data(response, ai.listPlatformModels()));
+    app.get("/api/platform/ai/models", (request, response) => {
+        const pagination = parsePagination(request.query);
+        data(response, pagination ? ai.listPlatformModelsPage(pagination) : ai.listPlatformModels());
+    });
     app.get("/api/platform/ai/settings", (_request, response) => data(response, store.getPlatformAiSettings()));
     app.patch("/api/platform/ai/settings", (request, response) => data(response, store.updatePlatformAiSettings(parse(aiPromptSchema, request.body))));
     app.get("/api/ui-settings", (_request, response) => data(response, store.getPlatformUiSettings()));
@@ -911,12 +1039,18 @@ export function createRuntime(options) {
         }
         data(response, updated);
     });
-    app.get("/api/works/:workId/ai-conversations", (request, response) => data(response, store.listAiConversations(request.params.workId)));
+    app.get("/api/works/:workId/ai-conversations", (request, response) => {
+        const pagination = parsePagination(request.query);
+        data(response, pagination ? store.listAiConversationsPage(request.params.workId, pagination) : store.listAiConversations(request.params.workId));
+    });
     app.post("/api/works/:workId/ai-conversations", (request, response) => {
         const input = parse(z.object({ title: z.string().max(200).optional() }), request.body ?? {});
         data(response, store.createAiConversation(request.params.workId, input.title), 201);
     });
-    app.get("/api/ai-conversations/:conversationId", (request, response) => data(response, store.getAiConversation(request.params.conversationId)));
+    app.get("/api/ai-conversations/:conversationId", (request, response) => {
+        const pagination = parsePagination(request.query);
+        data(response, pagination ? store.getAiConversationPage(request.params.conversationId, pagination) : store.getAiConversation(request.params.conversationId));
+    });
     app.post("/api/ai-conversations/:conversationId/fork", (request, response) => {
         const input = parse(z.object({ messageId: identifier, title: z.string().max(200).optional() }), request.body);
         data(response, store.forkAiConversation(request.params.conversationId, input.messageId, input.title), 201);
@@ -997,7 +1131,10 @@ export function createRuntime(options) {
         noContent(response);
     });
     app.post("/api/providers/:providerId/test", async (request, response) => data(response, await ai.testProvider(request.params.providerId)));
-    app.get("/api/providers/:providerId/models", (request, response) => data(response, ai.listModels(request.params.providerId)));
+    app.get("/api/providers/:providerId/models", (request, response) => {
+        const pagination = parsePagination(request.query);
+        data(response, pagination ? ai.listModelsPage(request.params.providerId, pagination) : ai.listModels(request.params.providerId));
+    });
     app.post("/api/providers/:providerId/models", (request, response) => data(response, ai.createModel(request.params.providerId, parse(modelSchema, request.body)), 201));
     app.get("/api/models/:modelId", (request, response) => data(response, ai.getModel(request.params.modelId)));
     app.patch("/api/models/:modelId", (request, response) => data(response, ai.updateModel(request.params.modelId, parse(modelSchema.partial(), request.body))));
@@ -1005,8 +1142,14 @@ export function createRuntime(options) {
         ai.deleteModel(request.params.modelId);
         noContent(response);
     });
-    app.get("/api/works/:workId/models", (request, response) => data(response, ai.listWorkModels(request.params.workId)));
-    app.get("/api/works/:workId/task-defaults", (request, response) => data(response, ai.listTaskDefaults(request.params.workId)));
+    app.get("/api/works/:workId/models", (request, response) => {
+        const pagination = parsePagination(request.query);
+        data(response, pagination ? ai.listWorkModelsPage(request.params.workId, pagination) : ai.listWorkModels(request.params.workId));
+    });
+    app.get("/api/works/:workId/task-defaults", (request, response) => {
+        const pagination = parsePagination(request.query);
+        data(response, pagination ? ai.listTaskDefaultsPage(request.params.workId, pagination) : ai.listTaskDefaults(request.params.workId));
+    });
     app.put("/api/works/:workId/task-defaults/:taskType", (request, response) => {
         const taskType = parse(z.enum(TASK_TYPES), request.params.taskType);
         const input = parse(z.object({ modelId: identifier }), request.body);
@@ -1014,7 +1157,8 @@ export function createRuntime(options) {
     });
     app.get("/api/works/:workId/suggestions", (request, response) => {
         const status = typeof request.query.status === "string" ? request.query.status : undefined;
-        data(response, ai.listSuggestions(request.params.workId, status));
+        const pagination = parsePagination(request.query);
+        data(response, pagination ? ai.listSuggestionsPage(request.params.workId, pagination, status) : ai.listSuggestions(request.params.workId, status));
     });
     app.post("/api/works/:workId/suggestions", async (request, response) => {
         const input = parse(z.object({
@@ -1109,7 +1253,10 @@ export function createRuntime(options) {
     });
     app.get("/api/suggestions/:suggestionId", (request, response) => data(response, ai.getSuggestion(request.params.suggestionId)));
     app.get("/api/suggestions/:suggestionId/guards", (request, response) => {
-        data(response, store.listContinuationGuards(request.params.suggestionId));
+        const pagination = parsePagination(request.query);
+        data(response, pagination
+            ? store.listContinuationGuardsPage(request.params.suggestionId, pagination)
+            : store.listContinuationGuards(request.params.suggestionId));
     });
     app.post("/api/suggestions/:suggestionId/guard", async (request, response) => {
         const input = parse(z.object({ content: z.string().max(2_000_000).optional() }), request.body ?? {});
@@ -1120,7 +1267,10 @@ export function createRuntime(options) {
         data(response, ai.acceptSuggestion(request.params.suggestionId, input.content));
     });
     app.post("/api/suggestions/:suggestionId/reject", (request, response) => data(response, ai.rejectSuggestion(request.params.suggestionId)));
-    app.get("/api/works/:workId/ai-calls", (request, response) => data(response, ai.listCalls(request.params.workId)));
+    app.get("/api/works/:workId/ai-calls", (request, response) => {
+        const pagination = parsePagination(request.query);
+        data(response, pagination ? ai.listCallsPage(request.params.workId, pagination) : ai.listCalls(request.params.workId));
+    });
     app.get("/api/works/:workId/search", (request, response) => {
         const query = parse(z.string().trim().min(1).max(500), request.query.q);
         data(response, store.search(request.params.workId, query));
@@ -1136,7 +1286,10 @@ export function createRuntime(options) {
         response.setHeader("Content-Disposition", `attachment; filename=novel-${request.params.workId}.${format === "markdown" ? "md" : "txt"}`);
         response.send(store.exportText(request.params.workId, format));
     });
-    app.get("/api/works/:workId/audit-logs", (request, response) => data(response, store.listAuditLogs(request.params.workId)));
+    app.get("/api/works/:workId/audit-logs", (request, response) => {
+        const pagination = parsePagination(request.query);
+        data(response, pagination ? store.listAuditLogsPage(request.params.workId, pagination) : store.listAuditLogs(request.params.workId));
+    });
     if (options.serveUi ?? true) {
         const publicPath = options.publicPath ?? join(process.cwd(), "src", "public");
         // index.html 按登录态动态下发：未登录时注入 login-route 类，首帧直接渲染登录页；