@allbluecn/web-app 0.18.2 → 0.19.0

package/src/server/serverFns/story/story-crud.ts

@@ -19,14 +19,19 @@ import { getPrisma } from "@allbluecn/database/get-prisma"
 import { createServerFn } from "@tanstack/react-start";
 import { getRequest } from "@tanstack/react-start/server";
 import { z } from "zod";
+import { buildRoomName } from "@allbluecn/collab-core/rooms";
 import { requireAuth } from "@/server/auth-helpers";
-import { ensureBuiltinIndependentProject, resolveStoryScopeProjectId } from "@/server/builtin-project";
+import { ensureBuiltinIndependentProject, resolveStoryScopeProjectIds } from "@/server/builtin-project";
 import { isUserInTeam } from "@/server/team-access";
+import { withCollabGuard } from "@/server/collab/write-guard";
+import { touchCollabSnapshot } from "@/server/collab/touch-snapshot";
 import type { ActivityItem } from "@/components/story/types";
 import { diffDescriptionBlocks } from "@/lib/story/description-diff";
-import { USER_BRIEF_SELECT, STORY_LIST_SELECT, castStoryUsers, castUserBrief, toDateOnly } from "@/server/story/types";
+import { USER_BRIEF_SELECT, STORY_LIST_SELECT, castStoryUsers, castUserBrief } from "@/server/story/types";
+import { toDateKeyUtc } from "@/server/story/date-key";
 import { buildListWhere } from "./story-list-query";
 import { createStoryInternal } from "./story-crud/create-story-internal";
+import { withSequenceNumberRetry } from "@/server/lib/sequence-number-retry";
 import type { Prisma } from "@allbluecn/database";
 
 /** 项目有效成员校验（口径同 testcase-crud / deleteBugFn：suspended 视同无权限） */
@@ -74,9 +79,9 @@ export const listStoriesFn = createServerFn({ method: "GET" })
     const session = await requireAuth(request);
     const userId = session.user!.id!;
 
-    const projectId = await resolveStoryScopeProjectId(data.projectId, userId);
+    const projectIds = await resolveStoryScopeProjectIds(data.projectId, userId);
 
-    const where = buildListWhere({ ...data, projectId });
+    const where = buildListWhere({ ...data, projectId: undefined, projectIds });
 
     const [items, total] = await Promise.all([
       prisma.story.findMany({
@@ -129,25 +134,17 @@ export const createStoryFn = createServerFn({ method: "POST" })
     await assertProjectMembership(resolvedProjectId, userId);
     await validateAssignee(resolvedProjectId, data.assigneeId);
 
-    const MAX_RETRIES = 5;
-    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
-      try {
-        // 发号 + 建单事务段已提取为共享导出（convertBugToStoryFn 复用，任务 6 DRY）
-        return await prisma.$transaction((tx) =>
+    // 计数器回滚使重试对「落后存量」类冲突无效（增量随事务一并回滚，每轮重发同一个号）——
+    // 该类冲突由 create-story-internal 发号时以存量 max 为下界自愈；此重试仅兜真实并发
+    // 竞态（identifier 撞唯一键 / 新项目首创并发撞 sequence_counters.scope 唯一键）。
+    // 发号 + 建单事务段已提取为共享导出（convertBugToStoryFn 复用，任务 6 DRY）
+    return withSequenceNumberRetry(
+      () =>
+        prisma.$transaction((tx) =>
           createStoryInternal(tx, { ...data, projectId: resolvedProjectId }, userId),
-        );
-      } catch (e: unknown) {
-        const isUniqueViolation =
-          e instanceof Error &&
-          "code" in e &&
-          (e as { code: string }).code === "P2002" &&
-          "meta" in e &&
-          Array.isArray((e as { meta?: { target?: string[] } }).meta?.target) &&
-          (e as { meta: { target: string[] } }).meta.target.includes("identifier");
-        if (!isUniqueViolation || attempt === MAX_RETRIES - 1) throw e;
-      }
-    }
-    throw new Error("创建需求失败：编号冲突，请重试");
+        ),
+      { exhaustedMessage: "创建需求失败：编号冲突，请重试" },
+    );
   });
 
 const updateSchema = z.object({
@@ -166,6 +163,59 @@ const updateSchema = z.object({
   isAI: z.boolean().default(false),
 });
 
+/**
+ * entity room 的 Y 属主字段清单（Yjs 多人协作 §7.1，任务 21）——与客户端写端
+ * components/story/detail/story-detail-body.tsx 的 STORY_COLLAB_FIELDS 镜像，
+ * 两侧必须同步维护（漏字段 = 旁路写互吞/协同态丢写）。iteration/projectId
+ * 不入 Y（iteration 本组件无协同绑定；projectId 是归属非字段）。
+ */
+const STORY_Y_OWNED_FIELDS = [
+  "name",
+  "state",
+  "priority",
+  "assigneeId",
+  "startDate",
+  "targetDate",
+  "labelIds",
+  "parentId",
+] as const;
+
+/**
+ * Prisma.StoryUpdateInput 键视角的 Y 属主面（R11 touch 判定用）——请求字段
+ * 名与 update input 键的差异面：assigneeId→assignee、labelIds→labels、
+ * parentId→parent；description 虽不在 STORY_Y_OWNED_FIELDS（content 面非
+ * fields 面）但同属 Y 直写面。
+ */
+const STORY_Y_UPDATE_KEYS = new Set([
+  "name",
+  "state",
+  "priority",
+  "assignee",
+  "startDate",
+  "targetDate",
+  "description",
+  "labels",
+  "parent",
+]);
+
+/**
+ * Story.description（Text 列 JSON 串）→ {html, markdown} 门卫 content。
+ * 与 components/story/types.ts parseStoryDescription 读取口径同构的镜像
+ * （服务端不 import 组件模块）；历史裸串兜底为双轨原串。
+ */
+function storyDescriptionToContent(description: string): { html: string; markdown: string } {
+  try {
+    const parsed = JSON.parse(description) as { html?: unknown; markdown?: unknown };
+    if (typeof parsed.html === "string") {
+      const markdown = typeof parsed.markdown === "string" ? parsed.markdown : parsed.html;
+      return { html: parsed.html, markdown };
+    }
+  } catch {
+    // 历史裸串兜底
+  }
+  return { html: description, markdown: description };
+}
+
 export const updateStoryFn = createServerFn({ method: "POST" })
   .validator(updateSchema)
   .handler(async ({ data }) => {
@@ -174,6 +224,49 @@ export const updateStoryFn = createServerFn({ method: "POST" })
     const session = await requireAuth(request);
     const userId = session.user!.id!;
 
+    // ── Yjs 多人协作 §5.3 写入门卫（任务 21；审查修正：提至 $transaction
+    // 之前——门卫转发含网络 I/O（TTL 内重试最坏 ≈4s），事务内等待会击穿
+    // Prisma 默认 5s 事务超时（P2028）让 degraded 兜底失效，且全程占用连
+    // 接池连接；T17 knowledge.ts 先例同此序）。patch 的 Y 属主面 =
+    // description + 8 字段；快照存在 → 一律转发 collab 内部通道（在线应用
+    // Y 并广播 / 离线 collab 直落业务列）；无快照 pass-through、不可达 TTL
+    // 降级 → 照旧直写（非协同态零行为变化）。Y 属主面的成员/团队政策校验
+    // 在 assertWriteAllowed 内前置（转发发生前）——防「collab 已应用、web
+    // 侧才报无权限/政策违规」的部分应用窗口；回调用非 tx prisma（门卫在
+    // 事务外，属主预检与事务内直写各带校验，TOCTOU 由直写路径复查兜底）。
+    const yFields: Record<string, unknown> = {};
+    for (const key of STORY_Y_OWNED_FIELDS) {
+      const value = (data as Record<string, unknown>)[key];
+      if (value !== undefined) yFields[key] = value;
+    }
+    const guard = await withCollabGuard({
+      roomName: buildRoomName({ kind: "entity-story", storyId: data.storyId }),
+      docId: data.storyId,
+      actor: userId,
+      patch: {
+        ...(data.description !== undefined && {
+          content: storyDescriptionToContent(data.description),
+        }),
+        ...(Object.keys(yFields).length > 0 && { fields: yFields }),
+      },
+      assertWriteAllowed: async () => {
+        const row = await prisma.story.findUnique({
+          where: { id: data.storyId },
+          select: { projectId: true },
+        });
+        if (!row) throw new Error("需求不存在");
+        await assertProjectMembership(row.projectId, userId);
+        // null projectId 与主流程语义一致（?? existing → 视为不变更）
+        if (data.projectId != null && data.projectId !== row.projectId) {
+          await assertProjectMembership(data.projectId, userId);
+        }
+        if (data.assigneeId !== undefined) {
+          await validateAssignee(row.projectId, data.assigneeId);
+        }
+      },
+    });
+    const forwarded = guard.kind === "forwarded";
+
     return prisma.$transaction(async (tx) => {
       const existing = await tx.story.findUnique({
         where: { id: data.storyId },
@@ -195,111 +288,136 @@ export const updateStoryFn = createServerFn({ method: "POST" })
       const updates: Prisma.StoryUpdateInput = {};
       const activities: Array<{ action: string; field: string; oldValue: string; newValue: string }> = [];
 
-      if (data.name !== undefined && data.name !== existing.name) {
-        activities.push({ action: "name_changed", field: "name", oldValue: existing.name, newValue: data.name });
-        updates.name = data.name;
-      }
-      if (data.state !== undefined && data.state !== existing.state) {
-        activities.push({ action: "state_changed", field: "state", oldValue: existing.state, newValue: data.state });
-        updates.state = data.state;
-      }
-      if (data.priority !== undefined && data.priority !== existing.priority) {
-        activities.push({ action: "priority_changed", field: "priority", oldValue: existing.priority, newValue: data.priority });
-        updates.priority = data.priority;
-      }
-      const newAssigneeId = data.assigneeId === null ? null : (data.assigneeId ?? existing.assignee?.id ?? null);
-      if (data.assigneeId !== undefined && newAssigneeId !== (existing.assignee?.id ?? null)) {
-        if (newAssigneeId) updates.assignee = { connect: { id: newAssigneeId } };
-        else updates.assignee = { disconnect: true };
-        let newAssigneeName = "";
-        if (newAssigneeId) {
-          const newAssignee = await tx.user.findUnique({
-            where: { id: newAssigneeId },
-            select: { username: true },
+      // Y 属主字段（name/state/priority/assignee/startDate/targetDate/
+      // description/labels/parent）：forwarded 时从直写数据与活动流剥离——
+      // 写入由 collab 接管（web 侧再写即双写互吞；活动由 collab 落库侧
+      // writeStoryColumns 产出，web 再写即重复流水）。
+      if (!forwarded) {
+        if (data.name !== undefined && data.name !== existing.name) {
+          activities.push({ action: "name_changed", field: "name", oldValue: existing.name, newValue: data.name });
+          activities.push({
+            action: "content_edited",
+            field: "name",
+            oldValue: "",
+            newValue: "",
           });
-          newAssigneeName = newAssignee?.username ?? newAssigneeId;
+          updates.name = data.name;
         }
-        activities.push({
-          action: "assignee_changed",
-          field: "assigneeId",
-          oldValue: existing.assignee?.username ?? "",
-          newValue: newAssigneeName,
-        });
-      }
-      if (data.projectId !== undefined && newProjectId !== existing.projectId) {
-        updates.project = { connect: { id: newProjectId } };
-      }
-      if (data.startDate !== undefined) {
-        const newDate = data.startDate ? new Date(data.startDate) : null;
-        const newStart = newDate ? toDateOnly(newDate) : "";
-        const oldStart = existing.startDate ? toDateOnly(existing.startDate) : "";
-        if (newStart !== oldStart) {
-          activities.push({ action: "startDate_changed", field: "startDate", oldValue: oldStart, newValue: newStart });
-          updates.startDate = newDate;
+        if (data.state !== undefined && data.state !== existing.state) {
+          activities.push({ action: "state_changed", field: "state", oldValue: existing.state, newValue: data.state });
+          updates.state = data.state;
         }
-      }
-      if (data.targetDate !== undefined) {
-        const newDate = data.targetDate ? new Date(data.targetDate) : null;
-        const newTarget = newDate ? toDateOnly(newDate) : "";
-        const oldTarget = existing.targetDate ? toDateOnly(existing.targetDate) : "";
-        if (newTarget !== oldTarget) {
-          activities.push({ action: "targetDate_changed", field: "targetDate", oldValue: oldTarget, newValue: newTarget });
-          updates.targetDate = newDate;
+        if (data.priority !== undefined && data.priority !== existing.priority) {
+          activities.push({ action: "priority_changed", field: "priority", oldValue: existing.priority, newValue: data.priority });
+          updates.priority = data.priority;
         }
-      }
-      if (data.description !== undefined && data.description !== existing.description) {
-        const diffs = diffDescriptionBlocks(existing.description, data.description);
-        for (const d of diffs) {
+        const newAssigneeId = data.assigneeId === null ? null : (data.assigneeId ?? existing.assignee?.id ?? null);
+        if (data.assigneeId !== undefined && newAssigneeId !== (existing.assignee?.id ?? null)) {
+          if (newAssigneeId) updates.assignee = { connect: { id: newAssigneeId } };
+          else updates.assignee = { disconnect: true };
+          let newAssigneeName = "";
+          if (newAssigneeId) {
+            const newAssignee = await tx.user.findUnique({
+              where: { id: newAssigneeId },
+              select: { username: true },
+            });
+            newAssigneeName = newAssignee?.username ?? newAssigneeId;
+          }
           activities.push({
-            action: "description_changed",
+            action: "assignee_changed",
+            field: "assigneeId",
+            oldValue: existing.assignee?.username ?? "",
+            newValue: newAssigneeName,
+          });
+        }
+        if (data.startDate !== undefined) {
+          const newDate = data.startDate ? new Date(data.startDate) : null;
+          // 日键同域（task-8 根因 B）：旧值键用 UTC 日切片（与客户端
+          // parseDate/payload 同源），本地日键对带时刻的历史数据会 +1 天，
+          // 把 +1 天改期误判为「无变化」静默丢写
+          const newStart = data.startDate ? data.startDate.slice(0, 10) : "";
+          const oldStart = existing.startDate ? toDateKeyUtc(existing.startDate) : "";
+          if (newStart !== oldStart) {
+            activities.push({ action: "startDate_changed", field: "startDate", oldValue: oldStart, newValue: newStart });
+            updates.startDate = newDate;
+          }
+        }
+        if (data.targetDate !== undefined) {
+          const newDate = data.targetDate ? new Date(data.targetDate) : null;
+          // 同上：旧值键用 UTC 日切片，与客户端键同域
+          const newTarget = data.targetDate ? data.targetDate.slice(0, 10) : "";
+          const oldTarget = existing.targetDate ? toDateKeyUtc(existing.targetDate) : "";
+          if (newTarget !== oldTarget) {
+            activities.push({ action: "targetDate_changed", field: "targetDate", oldValue: oldTarget, newValue: newTarget });
+            updates.targetDate = newDate;
+          }
+        }
+        if (data.description !== undefined && data.description !== existing.description) {
+          const diffs = diffDescriptionBlocks(existing.description, data.description);
+          for (const d of diffs) {
+            activities.push({
+              action: "description_changed",
+              field: "description",
+              oldValue: d.oldValue,
+              newValue: d.newValue,
+            });
+          }
+          updates.description = data.description;
+          // 内容编辑时间锚（测试用例 stale 判定专用，窄口径=描述/标题）
+          activities.push({
+            action: "content_edited",
             field: "description",
-            oldValue: d.oldValue,
-            newValue: d.newValue,
+            oldValue: "",
+            newValue: "",
           });
         }
-        updates.description = data.description;
-      }
 
-      if (data.labelIds !== undefined) {
-        updates.labels = {
-          deleteMany: {},
-          create: data.labelIds.map((labelId) => ({ labelId })),
-        };
-      }
+        if (data.labelIds !== undefined) {
+          updates.labels = {
+            deleteMany: {},
+            create: data.labelIds.map((labelId) => ({ labelId })),
+          };
+        }
 
-      if (data.parentId !== undefined) {
-        const newParentId = data.parentId;
-        const oldParentId = existing.parentId;
-        if (newParentId !== oldParentId) {
-          if (newParentId) {
-            const parentStory = await tx.story.findUnique({
-              where: { id: newParentId },
-              select: { id: true, name: true, identifier: true },
-            });
-            if (!parentStory) throw new Error("父需求不存在");
-            updates.parent = { connect: { id: newParentId } };
-            activities.push({
-              action: "parent_changed",
-              field: "parentId",
-              oldValue: existing.parent
-                ? `${existing.parent.identifier ?? ""} ${existing.parent.name}`.trim()
-                : "",
-              newValue: `${parentStory.identifier} ${parentStory.name}`,
-            });
-          } else {
-            updates.parent = { disconnect: true };
-            activities.push({
-              action: "parent_changed",
-              field: "parentId",
-              oldValue: existing.parent
-                ? `${existing.parent.identifier ?? ""} ${existing.parent.name}`.trim()
-                : "",
-              newValue: "",
-            });
+        if (data.parentId !== undefined) {
+          const newParentId = data.parentId;
+          const oldParentId = existing.parentId;
+          if (newParentId !== oldParentId) {
+            if (newParentId) {
+              const parentStory = await tx.story.findUnique({
+                where: { id: newParentId },
+                select: { id: true, name: true, identifier: true },
+              });
+              if (!parentStory) throw new Error("父需求不存在");
+              updates.parent = { connect: { id: newParentId } };
+              activities.push({
+                action: "parent_changed",
+                field: "parentId",
+                oldValue: existing.parent
+                  ? `${existing.parent.identifier ?? ""} ${existing.parent.name}`.trim()
+                  : "",
+                newValue: `${parentStory.identifier} ${parentStory.name}`,
+              });
+            } else {
+              updates.parent = { disconnect: true };
+              activities.push({
+                action: "parent_changed",
+                field: "parentId",
+                oldValue: existing.parent
+                  ? `${existing.parent.identifier ?? ""} ${existing.parent.name}`.trim()
+                  : "",
+                newValue: "",
+              });
+            }
           }
         }
       }
 
+      // 非 Y 字段照旧直写（无论门卫裁决——Y 从不拥有它们，无互吞面）
+      if (data.projectId !== undefined && newProjectId !== existing.projectId) {
+        updates.project = { connect: { id: newProjectId } };
+      }
+
       if (data.iterationId !== undefined) {
         const newIterationId = data.iterationId;
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -329,6 +447,28 @@ export const updateStoryFn = createServerFn({ method: "POST" })
         }
       }
 
+      // forwarded 且剥离后无非 Y 写入 → web 侧零 mutation：不 update（不 bump
+      // updatedAt——防「web 无谓 bump → 误判旁路写 → 下次打开重种子化炸协同
+      // 历史」）、不写活动。响应回读 existing + description 回显请求值
+      // （content 回显口径同任务 17 updateDocumentFn）。
+      const hasDirectUpdates = Object.keys(updates).some((key) => key !== "updatedBy");
+      if (forwarded && !hasDirectUpdates) {
+        const echo = castStoryUsers(existing);
+        return {
+          story:
+            data.description !== undefined
+              ? { ...echo, description: data.description }
+              : echo,
+          activities: [] as ActivityItem[],
+        };
+      }
+
+      // R11 touch 不变式判定：生效直写是否含 Y 属主面。forwarded 时 Y 字段
+      // 已剥离（updates 只剩 project/iteration 等非 Y 面）；pass-through/
+      // degraded 直写 Y 字段（含 description）→ 旁路语义，业务列必须反超
+      // 快照让重种子化兜底，刻意不 touch。
+      const writesYFace = Object.keys(updates).some((key) => STORY_Y_UPDATE_KEYS.has(key));
+
       updates.updatedBy = { connect: { id: userId } };
 
       const updated = await tx.story.update({
@@ -337,6 +477,16 @@ export const updateStoryFn = createServerFn({ method: "POST" })
         select: STORY_LIST_SELECT,
       });
 
+      // R11 touch：生效直写为纯非 Y patch（如 iterationId/projectId）时
+      // 同步快照 updatedAt = 回读行 updatedAt（无快照计 0 天然跳过）
+      if (!writesYFace) {
+        await touchCollabSnapshot(
+          tx,
+          buildRoomName({ kind: "entity-story", storyId: data.storyId }),
+          updated.updatedAt,
+        );
+      }
+
       if (activities.length > 0) {
         const created = await Promise.all(
           activities.map((a) =>
@@ -363,10 +513,18 @@ export const updateStoryFn = createServerFn({ method: "POST" })
             })
           )
         );
-        return { story: castStoryUsers(updated), activities: created.map((a) => ({ ...a, isAI: a.isAI, createdAt: a.createdAt.toISOString(), user: castUserBrief(a.user) } satisfies ActivityItem)) };
+        const echo =
+          forwarded && data.description !== undefined
+            ? { ...castStoryUsers(updated), description: data.description }
+            : castStoryUsers(updated);
+        return { story: echo, activities: created.map((a) => ({ ...a, isAI: a.isAI, createdAt: a.createdAt.toISOString(), user: castUserBrief(a.user) } satisfies ActivityItem)) };
       }
 
-      return { story: castStoryUsers(updated), activities: [] as ActivityItem[] };
+      const echo =
+        forwarded && data.description !== undefined
+          ? { ...castStoryUsers(updated), description: data.description }
+          : castStoryUsers(updated);
+      return { story: echo, activities: [] as ActivityItem[] };
     });
   });
 
@@ -388,6 +546,15 @@ export const deleteStoryFn = createServerFn({ method: "POST" })
     if (!existing) throw new Error("需求不存在");
     await assertProjectMembership(existing.projectId, userId);
 
-    await prisma.story.delete({ where: { id: data.storyId } });
+    // 删除实体 + 协同快照同事务清理（Yjs 多人协作 §5.2 删除路径，任务 21 与
+    // 任务 16 知识库删除同构）：实体删后快照行必删，防 collab 服务后续装载
+    // 幽灵 room；用 deleteMany 而非 delete——room 未协同打开过时无行，delete
+    // 会 P2025 竞态炸。room 命名与 collab-core 注册表一致（entity:story:<id>）。
+    await prisma.$transaction([
+      prisma.story.delete({ where: { id: data.storyId } }),
+      prisma.collabDocument.deleteMany({
+        where: { roomName: buildRoomName({ kind: "entity-story", storyId: data.storyId }) },
+      }),
+    ]);
     return { success: true };
   });

package/src/server/serverFns/story/story-dependencies.ts

@@ -20,6 +20,7 @@ import { createServerFn } from "@tanstack/react-start";
 import { getRequest } from "@tanstack/react-start/server";
 import { z } from "zod";
 import { requireAuth } from "@/server/auth-helpers";
+import { resolveStoryScopeProjectIds } from "@/server/builtin-project";
 import { STORY_LIST_SELECT, castStoryUsers, ACTIVITY_SELECT, toActivityItem } from "@/server/story/types";
 import type { DependencyRow } from "@/components/story/types";
 
@@ -376,3 +377,33 @@ export const getDependenciesFn = createServerFn({ method: "GET" })
         .filter((r): r is DependencyRow => r !== null),
     };
   });
+
+// 甘特图依赖箭头数据源（列表/分组场景）：按项目范围聚合批量取依赖边
+export const listStoryDependenciesFn = createServerFn({ method: "GET" })
+  .validator(z.object({ projectId: z.string().optional() }))
+  .handler(async ({ data }) => {
+    const prisma = await getPrisma();
+    const request = getRequest();
+    const session = await requireAuth(request);
+    const userId = session.user!.id!;
+
+    // 「全部项目」聚合语义：缺省 → 成员关系内全部 projectId；显式 → 单元素数组（含鉴权）
+    const projectIds = await resolveStoryScopeProjectIds(data.projectId, userId);
+
+    // scope 口径（R-5 裁决）：依赖边双向圈范围——source 或 target 任一端落在
+    // scope 项目即命中。原单边口径会让「本组需求被范围外项目需求依赖」的边
+    // 整条丢失（箭头端点不全）；archived:false 双侧同步保留（端点已归档的边
+    // 不画，与甘特可见行集一致，reui 对隐藏行端点本就自动跳过）。
+    // 甘特画布只需端点 id 与类型；type 为 DependencyType 枚举（仅三种合法值），序列化后即字符串
+    const edges = await prisma.storyDependency.findMany({
+      where: {
+        OR: [
+          { source: { projectId: { in: projectIds }, archived: false } },
+          { target: { projectId: { in: projectIds }, archived: false } },
+        ],
+      },
+      select: { sourceId: true, targetId: true, type: true },
+    });
+
+    return { edges };
+  });

package/src/server/serverFns/story/story-groups.ts

@@ -20,8 +20,9 @@ import { createServerFn } from "@tanstack/react-start";
 import { getRequest } from "@tanstack/react-start/server";
 import { z } from "zod";
 import { requireAuth } from "@/server/auth-helpers";
-import { resolveStoryScopeProjectId } from "@/server/builtin-project";
-import { GROUP_KEYS, ORDER_KEYS, ORDER_DIRECTIONS, type GroupKey, type OrderKey } from "@/components/story/display/types";
+import { resolveStoryScopeProjectIds } from "@/server/builtin-project";
+import { GROUP_KEYS, ORDER_KEYS, ORDER_DIRECTIONS, resolveOrderDir } from "@/components/shared-kit/list-kit/display/values";
+import type { GroupKey, OrderKey } from "@/components/shared-kit/list-kit/display/types";
 import { STORY_STATES, STORY_PRIORITIES, type StoryState, type StoryPriority } from "@/components/story/constants";
 import { STORY_LIST_SELECT_LIGHT, castStoryUsersLight, type StoryListRowLight } from "@/server/story/types";
 import { buildListWhere, buildGroupFilter } from "./story-list-query";
@@ -63,9 +64,9 @@ export const listStoriesInGroupFn = createServerFn({ method: "GET" })
     const session = await requireAuth(request);
     const userId = session.user!.id!;
 
-    const projectId = await resolveStoryScopeProjectId(data.projectId, userId);
+    const projectIds = await resolveStoryScopeProjectIds(data.projectId, userId);
 
-    const base = buildListWhere({ ...data, projectId });
+    const base = buildListWhere({ ...data, projectId: undefined, projectIds });
     const baseAnd = Array.isArray(base.AND) ? base.AND : base.AND ? [base.AND] : [];
     const extras: Prisma.StoryWhereInput[] = [];
     const groupWhere = buildGroupFilter(data.groupBy, data.groupKey);
@@ -76,7 +77,7 @@ export const listStoriesInGroupFn = createServerFn({ method: "GET" })
     const where = extras.length ? { ...base, AND: [...baseAnd, ...extras] } : base;
 
     const field = ORDER_FIELD[data.orderBy];
-    const dir: "asc" | "desc" = data.orderDir === "asc" ? "asc" : "desc";
+    const dir: "asc" | "desc" = resolveOrderDir(data.orderBy, data.orderDir);
     const primary: Prisma.StoryOrderByWithRelationInput = field
       ? { [field]: dir }
       : { createdAt: dir };
@@ -126,11 +127,11 @@ export const listAllGroupsItemsFn = createServerFn({ method: "GET" })
     const session = await requireAuth(request);
     const userId = session.user!.id!;
 
-    const projectId = await resolveStoryScopeProjectId(data.projectId, userId);
+    const projectIds = await resolveStoryScopeProjectIds(data.projectId, userId);
 
-    const base = buildListWhere({ ...data, projectId });
+    const base = buildListWhere({ ...data, projectId: undefined, projectIds });
     const field = ORDER_FIELD[data.orderBy];
-    const dir: "asc" | "desc" = data.orderDir === "asc" ? "asc" : "desc";
+    const dir: "asc" | "desc" = resolveOrderDir(data.orderBy, data.orderDir);
     const primary: Prisma.StoryOrderByWithRelationInput = field
       ? { [field]: dir }
       : { createdAt: dir };
@@ -198,7 +199,10 @@ const GROUP_BY_FIELD = {
   assignee: "assigneeId",
   createdBy: "createdById",
   project: "projectId",
-} as const satisfies Record<Exclude<GroupKey, "none" | "labels">, Prisma.StoryScalarFieldEnum>;
+} as const satisfies Record<
+  Exclude<GroupKey, "none" | "labels" | "iteration">,
+  Prisma.StoryScalarFieldEnum
+>;
 
 function deriveGroupKey(groupBy: GroupKey, row: Record<string, unknown>): string | null {
   switch (groupBy) {
@@ -238,9 +242,9 @@ export const listStoryGroupsFn = createServerFn({ method: "GET" })
     const session = await requireAuth(request);
     const userId = session.user!.id!;
 
-    const projectId = await resolveStoryScopeProjectId(data.projectId, userId);
+    const projectIds = await resolveStoryScopeProjectIds(data.projectId, userId);
 
-    const where = buildListWhere({ ...data, projectId });
+    const where = buildListWhere({ ...data, projectId: undefined, projectIds });
     if (data.groupBy === "none") return { groups: [] };
     if (data.parentGroupBy !== "none" && data.parentGroupKey) {
       const parentWhere = buildGroupFilter(data.parentGroupBy, data.parentGroupKey);