@allbluecn/web-app 0.4.22 → 0.5.1

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

@@ -21,36 +21,6 @@ import { z } from "zod";
 import { prisma } from "@allbluecn/database";
 import { requireAuth } from "@/server/auth-helpers";
 
-export const uploadAttachmentFn = createServerFn({ method: "POST" })
-  .handler(async () => {
-    const request = getRequest();
-    const session = await requireAuth(request);
-    const formData = await request.formData();
-
-    const storyId = formData.get("storyId") as string;
-    const file = formData.get("file") as File;
-
-    if (!storyId || !file) {
-      throw new Error("缺少 storyId 或 file");
-    }
-
-    const storageUrl = `/mock-storage/${Date.now()}-${file.name}`;
-    const fileSize = BigInt(file.size);
-    const mimeType = file.type;
-
-    const attachment = await prisma.storyAttachment.create({
-      data: {
-        storyId,
-        fileName: file.name,
-        fileSize,
-        mimeType,
-        storageUrl,
-      },
-    });
-
-    return attachment;
-  });
-
 export const removeAttachmentFn = createServerFn({ method: "POST" })
   .validator(z.object({ attachmentId: z.string() }))
   .handler(async ({ data }) => {
@@ -73,6 +43,14 @@ export const getAttachmentsFn = createServerFn({ method: "GET" })
     const attachments = await prisma.storyAttachment.findMany({
       where: { storyId: data.storyId },
       orderBy: { createdAt: "desc" },
+      select: {
+        id: true,
+        fileName: true,
+        fileSize: true,
+        mimeType: true,
+        description: true,
+        fileHash: true,
+      },
     });
 
     return attachments.map((att) => ({
@@ -80,18 +58,9 @@ export const getAttachmentsFn = createServerFn({ method: "GET" })
       fileName: att.fileName,
       fileSize: Number(att.fileSize),
       mimeType: att.mimeType,
-      storageUrl: att.storageUrl,
+      description: att.description,
+      fileHash: att.fileHash,
+      // 读取入口统一为内容路由（历史 mock 行无文件体，预览会 404）
+      storageUrl: `/api/attachments/${att.id}/content`,
     }));
   });
-
-export const mockCloudStorageFn = createServerFn({ method: "POST" })
-  .validator(z.object({ file: z.any() }))
-  .handler(async ({ data }) => {
-    const { file } = data;
-    const mockUrl = `/mock-storage/${Date.now()}-${file.name}`;
-
-    return {
-      url: mockUrl,
-      provider: "mock",
-    };
-  });

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

@@ -25,7 +25,7 @@ import { isUserInTeam } from "@/server/team-access";
 import { BUILTIN_INDEPENDENT_DISPLAY_ID } from "@/lib/builtin-project";
 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 "./types";
+import { USER_BRIEF_SELECT, STORY_LIST_SELECT, castStoryUsers, castUserBrief, toDateOnly, ACTIVITY_SELECT, toActivityItem } from "./types";
 import { buildListWhere } from "./story-list-query";
 
 async function validateAssignee(projectId: string, assigneeId: string | null | undefined) {
@@ -116,9 +116,10 @@ export const createStoryFn = createServerFn({ method: "POST" })
     for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
       try {
         return await prisma.$transaction(async (tx) => {
+          let parentStory: { id: string; identifier: string; name: string } | null = null;
           if (data.parentId) {
-            const parent = await tx.story.findUnique({ where: { id: data.parentId }, select: { id: true } });
-            if (!parent) throw new Error("父需求不存在");
+            parentStory = await tx.story.findUnique({ where: { id: data.parentId }, select: { id: true, identifier: true, name: true } });
+            if (!parentStory) throw new Error("父需求不存在");
           }
           let sequenceId: number;
           let identifier: string;
@@ -177,7 +178,23 @@ export const createStoryFn = createServerFn({ method: "POST" })
             data: { storyId: story.id, userId, action: "created", isAI: data.isAI },
           });
 
-          return castStoryUsers(story);
+          // 创建时带父需求：父需求侧补「添加子需求」活动
+          let parentActivity: ReturnType<typeof toActivityItem> | null = null;
+          if (parentStory) {
+            const pa = await tx.storyActivity.create({
+              data: {
+                storyId: parentStory.id,
+                userId,
+                action: "child_added",
+                newValue: `${story.identifier} ${story.name}`.trim(),
+                isAI: data.isAI,
+              },
+              select: ACTIVITY_SELECT,
+            });
+            parentActivity = toActivityItem(pa);
+          }
+
+          return { ...castStoryUsers(story), activities: parentActivity ? [parentActivity] : [] };
         });
       } catch (e: unknown) {
         const isUniqueViolation =

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

@@ -20,199 +20,175 @@ import { getRequest } from "@tanstack/react-start/server";
 import { z } from "zod";
 import { prisma } from "@allbluecn/database";
 import { requireAuth } from "@/server/auth-helpers";
-import type { DependencyType } from "@/components/story/types";
+import { STORY_LIST_SELECT, castStoryUsers, ACTIVITY_SELECT, toActivityItem } from "./types";
+import type { DependencyRow } from "@/components/story/types";
 
-async function hasCycle(sourceId: string, targetId: string): Promise<boolean> {
-  const visited = new Set<string>();
+const edgeTypeSchema = z.enum(["BLOCKS", "STARTS_BEFORE", "FINISHES_BEFORE"]);
 
-  async function dfs(currentId: string): Promise<boolean> {
-    if (visited.has(currentId)) return false;
-    visited.add(currentId);
-
-    const outgoing = await prisma.storyDependency.findMany({
-      where: { sourceId: currentId, type: "BLOCKS" },
-      select: { targetId: true },
-    });
-
-    for (const dep of outgoing) {
-      if (dep.targetId === targetId) return true;
-      if (await dfs(dep.targetId)) return true;
-    }
-
-    return false;
-  }
-
-  return dfs(sourceId);
-}
-
-export const addDependencyFn = createServerFn({ method: "POST" })
+export const addDependenciesFn = createServerFn({ method: "POST" })
   .validator(
     z.object({
-      sourceId: z.string(),
-      targetId: z.string(),
-      type: z.enum(["BLOCKS", "BLOCKED_BY", "RELATES_TO"]),
+      items: z
+        .array(
+          z.object({
+            sourceId: z.string(),
+            targetId: z.string(),
+            type: edgeTypeSchema,
+          }),
+        )
+        .min(1),
     }),
   )
   .handler(async ({ data }) => {
     const request = getRequest();
     const session = await requireAuth(request);
+    const userId = session.user!.id!;
 
-    const existing = await prisma.storyDependency.findUnique({
-      where: {
-        sourceId_targetId_type: {
-          sourceId: data.sourceId,
-          targetId: data.targetId,
-          type: data.type,
-        },
-      },
+    // 一次性取全部出边（3 类型合并；不按 projectId 裁剪——跨项目边同样参与环判定），
+    // 构建内存邻接表供本批循环的环检测复用，避免 O(items × 可达节点) 次串行 RTT
+    const allEdges = await prisma.storyDependency.findMany({
+      select: { sourceId: true, targetId: true },
     });
-    if (existing) {
-      throw new Error("依赖关系已存在");
+    const adjacency = new Map<string, string[]>();
+    for (const e of allEdges) {
+      const list = adjacency.get(e.sourceId);
+      if (list) list.push(e.targetId);
+      else adjacency.set(e.sourceId, [e.targetId]);
     }
 
-    const dep = await prisma.storyDependency.create({
-      data: {
-        sourceId: data.sourceId,
-        targetId: data.targetId,
-        type: data.type,
-      },
-    });
+    // 环检测：从 fromId 出发沿 source→target 有向边能否到达 toId（纯内存遍历）
+    // batchEdges：本批已插入边（防批内互指环漏检）
+    function reaches(
+      fromId: string,
+      toId: string,
+      batchEdges: Array<{ sourceId: string; targetId: string }>,
+    ): boolean {
+      const visited = new Set<string>();
+      const stack = [fromId];
+      while (stack.length > 0) {
+        const current = stack.pop()!;
+        if (current === toId) return true;
+        if (visited.has(current)) continue;
+        visited.add(current);
+        for (const next of adjacency.get(current) ?? []) {
+          if (!visited.has(next)) stack.push(next);
+        }
+        for (const e of batchEdges) {
+          if (e.sourceId === current && !visited.has(e.targetId)) stack.push(e.targetId);
+        }
+      }
+      return false;
+    }
+
+    const created: string[] = [];
+    const failed: Array<{ targetId: string; reason: "SELF" | "DUPLICATED" | "CYCLE" }> = [];
+    const batchEdges: Array<{ sourceId: string; targetId: string }> = [];
 
-    return dep;
+    for (const item of data.items) {
+      if (item.sourceId === item.targetId) {
+        failed.push({ targetId: item.targetId, reason: "SELF" });
+        continue;
+      }
+      const existing = await prisma.storyDependency.findFirst({
+        where: {
+          OR: [
+            { sourceId: item.sourceId, targetId: item.targetId },
+            { sourceId: item.targetId, targetId: item.sourceId },
+          ],
+        },
+        select: { id: true },
+      });
+      if (existing) {
+        failed.push({ targetId: item.targetId, reason: "DUPLICATED" });
+        continue;
+      }
+      // 插入 (S,T) 后成环 ⇔ 已存在路径 T →…→ S（含本批边）
+      if (reaches(item.targetId, item.sourceId, batchEdges)) {
+        failed.push({ targetId: item.targetId, reason: "CYCLE" });
+        continue;
+      }
+      const dep = await prisma.storyDependency.create({ data: item });
+      created.push(dep.id);
+      batchEdges.push({ sourceId: item.sourceId, targetId: item.targetId });
+    }
+
+    // 活动记录：依赖两端各记一条「添加依赖关系」（newValue 为对方需求描述），
+    // 返回带 storyId 供 UI 过滤当前需求侧的记录
+    let activities: Array<ReturnType<typeof toActivityItem> & { storyId: string }> = [];
+    if (created.length > 0) {
+      const endpointIds = [...new Set(batchEdges.flatMap((e) => [e.sourceId, e.targetId]))];
+      const endpoints = await prisma.story.findMany({
+        where: { id: { in: endpointIds } },
+        select: { id: true, identifier: true, name: true },
+      });
+      const labelById = new Map(
+        endpoints.map((s) => [s.id, `${s.identifier} ${s.name}`.trim()]),
+      );
+      const createdActivities = await Promise.all(
+        batchEdges.flatMap(({ sourceId, targetId }) => {
+          const sourceLabel = labelById.get(sourceId) ?? "";
+          const targetLabel = labelById.get(targetId) ?? "";
+          return [
+            prisma.storyActivity.create({
+              data: { storyId: sourceId, userId, action: "dependency_added", newValue: targetLabel },
+              select: { ...ACTIVITY_SELECT, storyId: true },
+            }),
+            prisma.storyActivity.create({
+              data: { storyId: targetId, userId, action: "dependency_added", newValue: sourceLabel },
+              select: { ...ACTIVITY_SELECT, storyId: true },
+            }),
+          ];
+        }),
+      );
+      activities = createdActivities.map((a) => ({ ...toActivityItem(a), storyId: a.storyId }));
+    }
+
+    return { created, failed, activities };
   });
 
 export const removeDependencyFn = createServerFn({ method: "POST" })
-  .validator(
-    z.object({
-      sourceId: z.string(),
-      targetId: z.string(),
-      type: z.enum(["BLOCKS", "BLOCKED_BY", "RELATES_TO"]),
-    }),
-  )
+  .validator(z.object({ depId: z.string() }))
   .handler(async ({ data }) => {
     const request = getRequest();
-    const session = await requireAuth(request);
-
-    const dep = await prisma.storyDependency.delete({
-      where: {
-        sourceId_targetId_type: {
-          sourceId: data.sourceId,
-          targetId: data.targetId,
-          type: data.type,
-        },
-      },
-    });
-
-    return dep;
+    await requireAuth(request);
+    return prisma.storyDependency.delete({ where: { id: data.depId } });
   });
 
 export const getDependenciesFn = createServerFn({ method: "GET" })
   .validator(z.object({ storyId: z.string() }))
   .handler(async ({ data }) => {
     const request = getRequest();
-    const session = await requireAuth(request);
+    await requireAuth(request);
 
     const deps = await prisma.storyDependency.findMany({
-      where: {
-        OR: [{ sourceId: data.storyId }, { targetId: data.storyId }],
-      },
-      include: {
-        source: {
-          select: { id: true, name: true, state: true },
-        },
-        target: {
-          select: { id: true, name: true, state: true },
-        },
-      },
+      where: { OR: [{ targetId: data.storyId }, { sourceId: data.storyId }] },
+      select: { id: true, sourceId: true, targetId: true, type: true },
     });
-
-    const grouped = {
-      blocking: deps
-        .filter((d) => d.sourceId === data.storyId && d.type === "BLOCKS")
-        .map((d) => ({
-          id: d.target.id,
-          title: d.target.name,
-          status: d.target.state,
-          type: "blocks" as DependencyType,
-        })),
-      blockedBy: deps
-        .filter((d) => d.targetId === data.storyId && d.type === "BLOCKS")
-        .map((d) => ({
-          id: d.source.id,
-          title: d.source.name,
-          status: d.source.state,
-          type: "blocked_by" as DependencyType,
-        })),
-      relatesTo: deps
-        .filter((d) => d.type === "RELATES_TO")
-        .map((d) => {
-          const isSource = d.sourceId === data.storyId;
-          const other = isSource ? d.target : d.source;
-          return {
-            id: other.id,
-            title: other.name,
-            status: other.state,
-            type: "relates_to" as DependencyType,
-          };
-        }),
-    };
-
-    return grouped;
-  });
-
-export const validateDependencyFn = createServerFn({ method: "POST" })
-  .validator(
-    z.object({
-      sourceId: z.string(),
-      targetId: z.string(),
-      type: z.enum(["BLOCKS", "BLOCKED_BY", "RELATES_TO"]),
-    }),
-  )
-  .handler(async ({ data }) => {
-    const request = getRequest();
-    const session = await requireAuth(request);
-
-    if (data.sourceId === data.targetId) {
-      return { valid: false, reason: "不能创建自我依赖" };
+    if (deps.length === 0) {
+      return { dependsOn: [] as DependencyRow[], dependents: [] as DependencyRow[] };
     }
 
-    if (data.type === "BLOCKS") {
-      const reverse = await prisma.storyDependency.findUnique({
-        where: {
-          sourceId_targetId_type: {
-            sourceId: data.targetId,
-            targetId: data.sourceId,
-            type: "BLOCKS",
-          },
-        },
-      });
-      if (!reverse) {
-        return {
-          valid: false,
-          reason: "blocks 依赖必须成对出现（需要同时创建反向 blocks）",
-        };
-      }
-    }
-
-    const source = await prisma.story.findUnique({
-      where: { id: data.sourceId },
-      select: { parentId: true },
-    });
-    const target = await prisma.story.findUnique({
-      where: { id: data.targetId },
-      select: { parentId: true },
+    const ids = [...new Set(deps.flatMap((d) => [d.sourceId, d.targetId]))];
+    const stories = await prisma.story.findMany({
+      where: { id: { in: ids } },
+      select: STORY_LIST_SELECT,
     });
+    const byId = new Map(stories.map((s) => [s.id, castStoryUsers(s)]));
 
-    if (source?.parentId === data.targetId || target?.parentId === data.sourceId) {
-      return {
-        valid: false,
-        reason: "父子需求之间不能有 blocks/blocked_by 依赖",
-      };
-    }
-
-    if (await hasCycle(data.sourceId, data.targetId)) {
-      return { valid: false, reason: "会形成循环依赖" };
-    }
+    const build = (d: (typeof deps)[number], storyId: string): DependencyRow | null => {
+      const otherId = d.sourceId === storyId ? d.targetId : d.sourceId;
+      const s = byId.get(otherId);
+      return s ? ({ ...s, depId: d.id, depType: d.type } as DependencyRow) : null;
+    };
 
-    return { valid: true };
+    return {
+      dependsOn: deps
+        .filter((d) => d.targetId === data.storyId)
+        .map((d) => build(d, data.storyId))
+        .filter((r): r is DependencyRow => r !== null),
+      dependents: deps
+        .filter((d) => d.sourceId === data.storyId)
+        .map((d) => build(d, data.storyId))
+        .filter((r): r is DependencyRow => r !== null),
+    };
   });

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

@@ -78,9 +78,11 @@ export const listStoriesInGroupFn = createServerFn({ method: "GET" })
 
     const field = ORDER_FIELD[data.orderBy];
     const dir: "asc" | "desc" = data.orderDir === "asc" ? "asc" : "desc";
-    const orderBy: Prisma.StoryOrderByWithRelationInput = field
+    const primary: Prisma.StoryOrderByWithRelationInput = field
       ? { [field]: dir }
       : { createdAt: dir };
+    // id tiebreaker：主排序键相同的行（同批创建等）顺序必须确定，否则重拉时顺序抖动
+    const orderBy: Prisma.StoryOrderByWithRelationInput[] = [primary, { id: "asc" }];
 
     const items = await prisma.story.findMany({
       where,
@@ -132,9 +134,11 @@ export const listAllGroupsItemsFn = createServerFn({ method: "GET" })
     const base = buildListWhere({ ...data, projectId });
     const field = ORDER_FIELD[data.orderBy];
     const dir: "asc" | "desc" = data.orderDir === "asc" ? "asc" : "desc";
-    const orderBy: Prisma.StoryOrderByWithRelationInput = field
+    const primary: Prisma.StoryOrderByWithRelationInput = field
       ? { [field]: dir }
       : { createdAt: dir };
+    // id tiebreaker：与 listStoriesInGroupFn 保持一致，保证分页跨批次全序稳定
+    const orderBy: Prisma.StoryOrderByWithRelationInput[] = [primary, { id: "asc" }];
 
     const batchTake = data.take * data.groupCount;
     const items = await prisma.story.findMany({
@@ -216,6 +220,19 @@ function deriveGroupKey(groupBy: GroupKey, row: Record<string, unknown>): string
   }
 }
 
+/** 组间显示顺序与筛选 pop 的值顺序一致（state/priority 按枚举序，其余维度保持 DB 返回序；未知 key 排最后） */
+const GROUP_DISPLAY_ORDER: Partial<Record<GroupKey, readonly string[]>> = {
+  state: STORY_STATES.map((s) => s.value),
+  priority: STORY_PRIORITIES.map((p) => p.value),
+};
+
+function sortGroupKeys(groupBy: GroupKey, keys: string[]): string[] {
+  const order = GROUP_DISPLAY_ORDER[groupBy];
+  if (!order) return keys;
+  const rank = new Map(order.map((k, i) => [k, i]));
+  return [...keys].sort((a, b) => (rank.get(a) ?? order.length) - (rank.get(b) ?? order.length));
+}
+
 export const listStoryGroupsFn = createServerFn({ method: "GET" })
   .validator(listGroupsSchema)
   .handler(async ({ data }) => {
@@ -293,6 +310,9 @@ export const listStoryGroupsFn = createServerFn({ method: "GET" })
         if (!keys.includes(k)) keys.push(k);
       }
     }
-    const groups: Array<{ key: string; total: number }> = keys.map((k) => ({ key: k, total: totalMap.get(k) ?? 0 }));
+    const groups: Array<{ key: string; total: number }> = sortGroupKeys(data.groupBy, keys).map((k) => ({
+      key: k,
+      total: totalMap.get(k) ?? 0,
+    }));
     return { groups };
   });

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

@@ -20,12 +20,14 @@ import { getRequest } from "@tanstack/react-start/server";
 import { z } from "zod";
 import { prisma } from "@allbluecn/database";
 import { requireAuth } from "@/server/auth-helpers";
+import { ACTIVITY_SELECT, toActivityItem } from "./types";
 
 export const addLinkFn = createServerFn({ method: "POST" })
   .validator(z.object({ storyId: z.string(), url: z.string().url(), title: z.string().optional(), description: z.string().optional() }))
   .handler(async ({ data }) => {
     const request = getRequest();
     const session = await requireAuth(request);
+    const userId = session.user!.id!;
 
     const link = await prisma.storyLink.create({
       data: {
@@ -36,7 +38,17 @@ export const addLinkFn = createServerFn({ method: "POST" })
       },
     });
 
-    return link;
+    const activity = await prisma.storyActivity.create({
+      data: {
+        storyId: data.storyId,
+        userId,
+        action: "link_added",
+        newValue: data.title || data.url,
+      },
+      select: ACTIVITY_SELECT,
+    });
+
+    return { ...link, activity: toActivityItem(activity) };
   });
 
 export const updateLinkFn = createServerFn({ method: "POST" })

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

@@ -349,7 +349,8 @@ const listProjectStoriesSchema = z.object({
   search: z.string().optional(),
   cursor: z.string().optional(),
   excludeStoryId: z.string().optional(),
-  mode: z.enum(["parent", "child"]).default("parent"),
+  excludeIds: z.array(z.string()).optional(),
+  mode: z.enum(["parent", "child", "dependency"]).default("parent"),
   pageSize: z.number().int().min(1).max(50).default(20),
 });
 
@@ -365,16 +366,17 @@ export const listProjectStoriesFn = createServerFn({ method: "GET" })
       if (data.mode === "parent") {
         const descendants = await collectDescendantIds(data.excludeStoryId);
         for (const id of descendants) excludeIds.add(id);
-      } else {
+      } else if (data.mode === "child") {
         const ancestors = await collectAncestorIds(data.excludeStoryId);
         for (const id of ancestors) excludeIds.add(id);
       }
     }
+    for (const id of data.excludeIds ?? []) excludeIds.add(id);
 
     const stories = await prisma.story.findMany({
       where: {
         ...(data.projectId ? { projectId: data.projectId } : {}),
-        parentId: null,
+        ...(data.mode === "dependency" ? {} : { parentId: null }),
         archived: false,
         ...(excludeIds.size > 0
           ? { id: { notIn: Array.from(excludeIds) } }

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

@@ -54,7 +54,8 @@ export const addChildFn = createServerFn({ method: "POST" })
   .validator(z.object({ parentId: z.string(), childId: z.string() }))
   .handler(async ({ data }) => {
     const request = getRequest();
-    await requireAuth(request);
+    const session = await requireAuth(request);
+    const userId = session.user!.id!;
 
     const existingChild = await prisma.story.findUnique({
       where: { id: data.childId },
@@ -68,11 +69,37 @@ export const addChildFn = createServerFn({ method: "POST" })
       throw new Error("不能将子需求设为其父需求的子需求（循环依赖）");
     }
 
+    const parent = await prisma.story.findUnique({
+      where: { id: data.parentId },
+      select: { id: true, identifier: true, name: true },
+    });
+
     const child = await prisma.story.update({
       where: { id: data.childId },
       data: { parentId: data.parentId },
     });
 
+    // 活动记录：父需求记「添加子需求」，子需求记「变更父需求」（与 updateStoryFn 格式一致）
+    if (parent) {
+      const childLabel = `${existingChild?.identifier ?? ""} ${existingChild?.name ?? ""}`.trim();
+      const parentLabel = `${parent.identifier} ${parent.name}`.trim();
+      await prisma.$transaction([
+        prisma.storyActivity.create({
+          data: { storyId: parent.id, userId, action: "child_added", newValue: childLabel },
+        }),
+        prisma.storyActivity.create({
+          data: {
+            storyId: child.id,
+            userId,
+            action: "parent_changed",
+            field: "parentId",
+            oldValue: "",
+            newValue: parentLabel,
+          },
+        }),
+      ]);
+    }
+
     return child;
   });
 

package/src/server/serverFns/story/types.ts

@@ -21,6 +21,7 @@ import type { StoryState, StoryPriority } from "@/components/story/constants";
 import type {
   UserBrief,
   ReactionGroup,
+  ActivityItem,
 } from "@/components/story/types";
 
 export const USER_BRIEF_SELECT = {
@@ -140,6 +141,42 @@ export function castUserBrief(u: {
   };
 }
 
+/** 活动记录 select（含 user brief），供 serverFn 返回新创建的活动给 UI 即时追加 */
+export const ACTIVITY_SELECT = {
+  id: true,
+  action: true,
+  field: true,
+  oldValue: true,
+  newValue: true,
+  isAI: true,
+  createdAt: true,
+  user: { select: USER_BRIEF_SELECT },
+} as const;
+
+export interface ActivityRow {
+  id: string;
+  action: string;
+  field: string | null;
+  oldValue: string | null;
+  newValue: string | null;
+  isAI: boolean;
+  createdAt: Date;
+  user: { id: string; username: string; email: string; avatarConfig: unknown; bgShape: string | null; bgColor: string | null };
+}
+
+export function toActivityItem(a: ActivityRow): ActivityItem {
+  return {
+    id: a.id,
+    action: a.action,
+    field: a.field,
+    oldValue: a.oldValue,
+    newValue: a.newValue,
+    isAI: a.isAI,
+    createdAt: a.createdAt.toISOString(),
+    user: castUserBrief(a.user),
+  };
+}
+
 export function aggregateReactions(
   reactions: { emoji: string; userId: string }[],
   currentUserId: string,