@sleep2agi/commhub-server 0.9.0-preview.73 → 0.9.0-preview.75

package/src/requirements.ts

@@ -2,11 +2,17 @@
 // 不是 tasks：tasks 是正在派给节点的活，状态由节点收尾。
 import { createHash } from "node:crypto";
 import { encodeCursor, matchesTaskId, matchesTerms, parseListQuery, type ListQuery, type NameMaps } from "./requirements-search.js";
-import { db } from "./db.js";
-import { normalizeTags, storedTags } from "./requirement-tags.js";
+import { db, logAudit } from "./db.js";
+import { markGzipReusable } from "./http-gzip.js";
+import { applyTagOp, normalizeTags, parseTagOp, storedTags, type TagOp } from "./requirement-tags.js";
+import { aggregateStats, parseStatsQuery, type StatsRow } from "./requirements-stats.js";
 import { addHumanNetworkScope, canRestWriteNetwork, canRestWriteNetworkAsHuman, resolveRestWriteNetworkId, type RestNetworkScope } from "./network-scope.js";
-import { isAgentRestricted, visibleAgents } from "./agent-access.js";
-import { ensureRequirementIndexes, ensureRequirementProjects, ensureRequirementSeq, migrateRequirementAgentOwners, migrateRequirementPriorityCheck, nextRequirementSeq } from "./requirements-migrate.js";
+import { isAgentRestricted, restrictedNetworkIds, visibleAgents } from "./agent-access.js";
+import {
+  addProjectVisibilityScope, addTaskVisibilityScope, canDeleteTask, canEditTask, canSeeTask, canUseProject, deleteTaskGrantsForProject,
+  isTaskScoped, shouldAuditDenied, taskPermissionsResolver, type TaskCaller,
+} from "./task-access.js";
+import { ensureNetworkTags, ensureRequirementCompletedAt, ensureRequirementIndexes, ensureRequirementProjects, ensureRequirementSeq, ensureRequirementTombstones, migrateRequirementAgentOwners, migrateRequirementPriorityCheck, nextRequirementSeq } from "./requirements-migrate.js";
 
 // 启动迁移:旧库里节点当负责人的卡,节点挪到 agent_owner(列由 db.ts 的加列循环加上)。
 // 放在这里而不是 db.ts:db.ts 每多一行,文档里钉着的行号就漂一次。
@@ -15,6 +21,9 @@ migrateRequirementAgentOwners(db);
 ensureRequirementProjects(db);
 ensureRequirementIndexes(db);
 ensureRequirementSeq(db);
+ensureRequirementCompletedAt(db);
+ensureNetworkTags(db);
+ensureRequirementTombstones(db);
 
 type RequestAuth = { userId: string; networkId: string | null; username: string; tokenId?: string | null; tokenName?: string | null } | null;
 
@@ -61,12 +70,36 @@ type Row = {
   tags_json: string | null;
   created_at: string;
   seq: number | null;
+  completed_at: string | null;
+  completed_by_json: string | null;
+  completed_at_approx: number | null;
 };
 
 function jsonError(error: string, status: number): Response {
   return Response.json({ ok: false, error }, { status });
 }
 
+// ── 任务的人员权限(RFC-038 §9,判定在 task-access.ts) ──
+// 节点令牌(Agent)、Hub 管理员、没有身份的旧全局令牌:不受任务权限约束(null)。
+function taskCaller(ctx: RequirementsRequestContext): TaskCaller {
+  if (!ctx.auth || ctx.isNodeToken || ctx.isAdmin) return null;
+  return { userId: ctx.auth.userId };
+}
+/** 看得见但没权限写:403,并按 (用户, 卡) 每小时最多记一条审计。 */
+function taskDenied(ctx: RequirementsRequestContext, row: Row, error: "task_read_only" | "task_delete_denied"): Response {
+  if (ctx.auth && shouldAuditDenied(ctx.auth.userId, row.requirement_id)) {
+    logAudit(ctx.auth.userId, ctx.auth.username || null, "task_access_denied", "requirement", row.requirement_id, JSON.stringify({ error }), undefined, row.network_id);
+  }
+  return jsonError(error, 403);
+}
+/** 父卡对调用者不可见 = 与不存在同一个错误(不给 scoped 成员留卡片存在性探测)。 */
+function parentHidden(ctx: RequirementsRequestContext, parentId: string): boolean {
+  const caller = taskCaller(ctx);
+  if (!caller) return false;
+  const parent = db.get<Row>(`SELECT ${SELECT} FROM requirements WHERE requirement_id = ?1`, parentId);
+  return !!parent && !canSeeTask(caller, parent);
+}
+
 function dueOk(due: string): boolean {
   if (!DUE.test(due)) return false;
   const [y, m, d] = due.split("-").map(Number);
@@ -219,10 +252,15 @@ async function handleProjects(ctx: RequirementsRequestContext): Promise<Response
   if (!networkId) return jsonError("network_id_required", 400);
   const one = url.pathname.match(/^\/api\/requirements\/projects\/([^/]+)$/);
   if (url.pathname === "/api/requirements/projects" && req.method === "GET") {
-    const rows = db.all<ProjectRow>(`SELECT ${PROJECT_SELECT} FROM requirement_projects WHERE network_id = ?1 ORDER BY sort, created_at`, networkId);
+    // scoped 成员只列授权给自己的项目(RFC-038 §9.3)。
+    const projectParams: unknown[] = [networkId];
+    const projectSql = addProjectVisibilityScope(`SELECT ${PROJECT_SELECT} FROM requirement_projects WHERE network_id = ?1`, projectParams, taskCaller(ctx), networkId);
+    const rows = db.all<ProjectRow>(`${projectSql} ORDER BY sort, created_at`, ...projectParams);
     return Response.json({ ok: true, projects: rows.map(projectPublic) });
   }
   if (!canWrite(ctx, networkId)) return jsonError("permission_denied", 403);
+  // 项目管理(建 / 改名 / 归档 / 删)只给不受任务范围限制的人。
+  if (taskCaller(ctx) && isTaskScoped(ctx.auth!.userId, networkId)) return jsonError("permission_denied", 403);
   let body: Record<string, unknown> = {};
   if (req.method === "POST" || req.method === "PATCH") {
     try { body = await bodyObject(req); } catch { return jsonError("invalid_json", 400); }
@@ -246,8 +284,10 @@ async function handleProjects(ctx: RequirementsRequestContext): Promise<Response
   if (!current || current.network_id !== networkId) return jsonError("project_not_found", 404);
   if (req.method === "DELETE") {
     // 先把卡片上的引用置空,再删项目:卡片一张不少。
-    db.run("UPDATE requirements SET project_id = NULL WHERE project_id = ?1", [current.project_id]);
+    // updated_at 跟着动:按 updated_since 增量同步的客户端要看得见「项目被清空」这一改动。
+    db.run("UPDATE requirements SET project_id = NULL, updated_at = ?2 WHERE project_id = ?1", [current.project_id, new Date().toISOString()]);
     db.run("DELETE FROM requirement_projects WHERE project_id = ?1", [current.project_id]);
+    deleteTaskGrantsForProject(current.project_id);
     return Response.json({ ok: true });
   }
   if (req.method !== "PATCH") return jsonError("not_found", 404);
@@ -274,6 +314,65 @@ async function handleProjects(ctx: RequirementsRequestContext): Promise<Response
   return Response.json({ ok: true, project: projectPublic(db.get<ProjectRow>(`SELECT ${PROJECT_SELECT} FROM requirement_projects WHERE project_id = ?1`, current.project_id)!) });
 }
 
+// ── 标签管理(RFC-038 §9 的取舍:同项目管理) ──
+// 改名 / 合并 / 删除要改写网络里**每一张**带这个标签的卡,包括调用者看不见的;所以只给不受任务范围限制的人
+// (网络 owner / 管理员 / task_access='all' 的成员),scoped 成员一律 403 —— 不做「只改我看得见的那几张」:
+// 那样同一个标签会被拆成两半,而且改动条数会泄露看不见的卡有几张。节点令牌在入口已被拒(tags_write)。
+function canManageTags(ctx: RequirementsRequestContext, networkId: string): boolean {
+  if (ctx.isNodeToken || !canWrite(ctx, networkId)) return false;
+  return !(taskCaller(ctx) && isTaskScoped(ctx.auth!.userId, networkId));
+}
+
+async function handleTagOp(ctx: RequirementsRequestContext): Promise<Response> {
+  const networkId = resolveRestWriteNetworkId(ctx.scope, ctx.auth, ctx.isAdmin);
+  if (!networkId) return jsonError("network_id_required", 400);
+  if (!canManageTags(ctx, networkId)) return jsonError("permission_denied", 403);
+  let body: Record<string, unknown>;
+  try { body = await bodyObject(ctx.req); } catch { return jsonError("invalid_json", 400); }
+  const op = parseTagOp(body);
+  if ("error" in op) return jsonError(op.error, 400);
+  const now = new Date().toISOString();
+  const actor = JSON.stringify(actorOf(ctx));
+  // 读-改-写整个网络的标签在一个事务里:中途失败一张都不改;颜色表跟着一起挪。
+  const result = db.transaction(() => {
+    const cards = db.all<{ requirement_id: string; tags_json: string | null }>(
+      "SELECT requirement_id, tags_json FROM requirements WHERE network_id = ?1 AND tags_json IS NOT NULL AND tags_json <> '[]'", networkId,
+    );
+    const colorOf = (name: string) => db.get<{ color: string }>("SELECT color FROM network_tags WHERE network_id = ?1 AND name = ?2", networkId, name)?.color ?? null;
+    const sources = op.op === "rename" ? [op.from] : op.op === "merge" ? op.from : [op.tag];
+    const known = cards.some(card => storedTags(card.tags_json).some(tag => sources.includes(tag))) || sources.some(tag => colorOf(tag) !== null);
+    if (!known) return null;
+    if (op.op === "color") {
+      if (op.color === null) db.run("DELETE FROM network_tags WHERE network_id = ?1 AND name = ?2", [networkId, op.tag]);
+      else db.run("INSERT INTO network_tags (network_id, name, color, updated_at) VALUES (?1, ?2, ?3, ?4) ON CONFLICT (network_id, name) DO UPDATE SET color = excluded.color, updated_at = excluded.updated_at", [networkId, op.tag, op.color, now]);
+      return { affected: 0 };
+    }
+    let affected = 0;
+    for (const card of cards) {
+      const next = applyTagOp(storedTags(card.tags_json), op);
+      if (!next) continue;
+      db.run("UPDATE requirements SET tags_json = ?1, updated_at = ?2, updated_by_json = ?3 WHERE requirement_id = ?4", [JSON.stringify(next), now, actor, card.requirement_id]);
+      affected++;
+    }
+    moveTagColors(networkId, op, colorOf, now);
+    return { affected };
+  });
+  if (!result) return jsonError("tag_not_found", 404);
+  if (ctx.auth) logAudit(ctx.auth.userId, ctx.auth.username || null, `requirement_tag_${op.op}`, "requirement_tag", op.op === "rename" || op.op === "merge" ? op.to : op.tag, JSON.stringify({ ...op, affected: result.affected }).slice(0, 1000), undefined, networkId);
+  return Response.json({ ok: true, op: op.op, affected: result.affected });
+}
+
+/** 改名 / 合并:目标没有颜色就继承第一个有颜色的来源;来源的颜色行删掉。删除:删颜色行。 */
+function moveTagColors(networkId: string, op: TagOp, colorOf: (name: string) => string | null, now: string): void {
+  if (op.op === "color") return;
+  const sources = op.op === "rename" ? [op.from] : op.op === "merge" ? op.from : [op.tag];
+  if (op.op !== "delete" && colorOf(op.to) === null) {
+    const inherited = sources.map(colorOf).find(color => color !== null);
+    if (inherited) db.run("INSERT INTO network_tags (network_id, name, color, updated_at) VALUES (?1, ?2, ?3, ?4)", [networkId, op.to, inherited, now]);
+  }
+  for (const tag of sources) db.run("DELETE FROM network_tags WHERE network_id = ?1 AND name = ?2", [networkId, tag]);
+}
+
 function toPublic(row: Row) {
   return {
     owner: row.owner_json ? JSON.parse(row.owner_json) : null,
@@ -309,6 +408,11 @@ function toPublic(row: Row) {
     // 子需求:parent_id(可空)和父卡上的子需求进度(未归档的子需求数 / 其中完成的)。
     parent_id: row.parent_id || null,
     children: { total: Number(row.children_total ?? 0), done: Number(row.children_done ?? 0) },
+    // 完成时间:进「完成」列的时刻,移出清空(不在「完成」列 = null)。completedAtApprox = 升级前就完成的卡,
+    // 时刻是按 updated_at 补的近似值。completedBy = 谁移进「完成」的(近似值的卡为 null)。旧 App 忽略这三个字段。
+    completedAt: row.completed_at || null,
+    completedAtApprox: !!row.completed_at_approx,
+    completedBy: row.completed_by_json ? JSON.parse(row.completed_by_json) : null,
   };
 }
 
@@ -348,8 +452,14 @@ function isHiddenRef(ref: unknown, hidden: HiddenNode): boolean {
   const r = ref as { kind?: unknown; id?: unknown };
   return r.kind === "node" && typeof r.id === "string" && hidden(r.id);
 }
+// 每个请求一个权限解析器(按网络缓存成员行与项目授权)。
+const permsByCtx = new WeakMap<RequirementsRequestContext, ReturnType<typeof taskPermissionsResolver>>();
 function toPublicFor(ctx: RequirementsRequestContext, row: Row) {
-  const pub = toPublic(row);
+  let perms = permsByCtx.get(ctx);
+  if (!perms) permsByCtx.set(ctx, perms = taskPermissionsResolver(taskCaller(ctx)));
+  // viewer_can:只对「只看相关任务」的调用者出现,客户端据此画只读锁、藏删除;不出现 = 与今天一样全能(旧 Hub 也不出现)。
+  const can = perms(row);
+  const pub = can ? { ...toPublic(row), viewer_can: can } : toPublic(row);
   const hidden = hiddenNodeFilter(ctx, row.network_id);
   if (!hidden) return pub;
   return {
@@ -359,10 +469,11 @@ function toPublicFor(ctx: RequirementsRequestContext, row: Row) {
     participants: Array.isArray(pub.participants) ? pub.participants.filter((ref: unknown) => !isHiddenRef(ref, hidden)) : pub.participants,
     created_by: isHiddenRef(pub.created_by, hidden) ? null : pub.created_by,
     updated_by: isHiddenRef(pub.updated_by, hidden) ? null : pub.updated_by,
+    completedBy: isHiddenRef(pub.completedBy, hidden) ? null : pub.completedBy,
   };
 }
 
-const SELECT = "requirement_id, network_id, title, column_name, priority, due_on, assignee, issues_json, tags_json, created_at, owner_json, participants_json, agent_owner_json, description, checklist_json, project_id, external_ref, external_url, archived, created_by, created_by_json, updated_by_json, updated_at, parent_id, start_on, seq, " +
+const SELECT = "requirement_id, network_id, title, column_name, priority, due_on, assignee, issues_json, tags_json, created_at, owner_json, participants_json, agent_owner_json, description, checklist_json, project_id, external_ref, external_url, archived, created_by, created_by_json, updated_by_json, updated_at, parent_id, start_on, seq, completed_at, completed_by_json, completed_at_approx, " +
   "(SELECT COUNT(*) FROM requirements c WHERE c.parent_id = requirements.requirement_id AND COALESCE(c.archived, 0) = 0) AS children_total, " +
   "(SELECT COUNT(*) FROM requirements c WHERE c.parent_id = requirements.requirement_id AND COALESCE(c.archived, 0) = 0 AND c.column_name = 'done') AS children_done";
 
@@ -428,6 +539,7 @@ function assignments(body: Record<string, unknown>, networkId: string, current?:
 const NODE_TOKEN_OPERATIONS: ReadonlySet<string> = new Set<string>(["read", "create", "patch", "checklist_item", "upsert", "projects_read"]);
 function operationOf(req: Request, url: URL): string {
   if (/^\/api\/requirements\/projects(\/|$)/.test(url.pathname)) return req.method === "GET" ? "projects_read" : "projects_write";
+  if (url.pathname === "/api/requirements/tags/ops") return "tags_write";
   if (req.method === "GET") return "read";
   if (/^\/api\/requirements\/[^/]+\/checklist\/[^/]+$/.test(url.pathname)) return "checklist_item";
   if (url.pathname === "/api/requirements/upsert") return "upsert";
@@ -444,11 +556,19 @@ function operationOf(req: Request, url: URL): string {
  */
 export function conditionalJson(req: Request, payload: unknown): Response {
   const body = JSON.stringify(payload);
-  const etag = `W/"${createHash("sha256").update(body).digest("base64url").slice(0, 27)}"`;
+  return conditionalBody(req, body, bodyEtag(body));
+}
+
+function bodyEtag(body: string): string {
+  return `W/"${createHash("sha256").update(body).digest("base64url").slice(0, 27)}"`;
+}
+
+function conditionalBody(req: Request, body: string, etag: string): Response {
   // private:按用户可见范围生成,不能被共享缓存复用;no-cache:每次都要回来验证,不会拿旧表当新的。
   const headers = { ETag: etag, "Cache-Control": "private, no-cache" };
   if (ifNoneMatchHits(req.headers.get("if-none-match"), etag)) return new Response(null, { status: 304, headers });
-  return new Response(body, { headers: { ...headers, "Content-Type": "application/json;charset=utf-8" } });
+  // ETag 就是正文的哈希:同一份正文的 gzip 结果可以复用(http-gzip.ts)。
+  return markGzipReusable(new Response(body, { headers: { ...headers, "Content-Type": "application/json;charset=utf-8" } }), etag);
 }
 
 function ifNoneMatchHits(header: string | null, etag: string): boolean {
@@ -457,8 +577,11 @@ function ifNoneMatchHits(header: string | null, etag: string): boolean {
   return header.split(",").some(tag => tag.trim() === "*" || bare(tag) === bare(etag));
 }
 
+// tag_ops:有 POST /api/requirements/tags/ops(标签改名 / 合并 / 删除 / 颜色),GET /api/requirements/tags 带 counts / colors / can_manage。
 // search:GET 认 q=(服务端搜索,语义同 App 的任务搜索);paging:认 limit / cursor,响应带 has_more / next_cursor。
-export const REQUIREMENT_CAPABILITIES = ["agent_owner", "description", "checklist", "projects", "due_datetime", "external_ref", "archived", "agent_api", "sub_requirements", "tags", "priority_lowest", "start_date", "requirement_seq", "search", "paging"] as const;
+// list_summary:GET 认 view=summary(不带描述正文与子任务条目,见 toSummary);changes:GET 认 changes=1 + updated_since
+// (改过的卡含归档的,加上 deleted 墓碑与 server_time,见 listChanges)。
+export const REQUIREMENT_CAPABILITIES = ["agent_owner", "description", "checklist", "projects", "due_datetime", "external_ref", "archived", "agent_api", "sub_requirements", "tags", "priority_lowest", "start_date", "requirement_seq", "search", "paging", "completed_at", "stats", "tag_ops", "list_summary", "changes"] as const;
 
 // ── 子需求 ──
 // parent_id:同一网络里的另一张卡;不能成环;最多 5 层(顶层是第 1 层)。删父卡 = 子卡保留、parent_id 置空。
@@ -579,18 +702,24 @@ async function createRequirement(ctx: RequirementsRequestContext, body: Record<s
   if (description === null) return jsonError("invalid_description", 400);
   const checklist = body.checklist === undefined ? [] : normalizeChecklist(body.checklist);
   if (checklist === null) return jsonError("invalid_checklist", 400);
+  const caller = taskCaller(ctx);
+  const scoped = !!caller && isTaskScoped(caller.userId, networkId);
   let projectId: string | null = null;
   if (body.project_id !== undefined) {
     try { projectId = projectRef(body.project_id, networkId); } catch (e) { return jsonError((e as Error).message, 400); }
+    // scoped 成员只能建进自己 can_edit 的项目;没授权的项目与不存在的项目同一个错误。
+    if (!canUseProject(caller, networkId, projectId)) return jsonError("project_not_in_network", 400);
   }
   const ref = body.external_ref === undefined ? null : externalRef(body.external_ref);
   if (ref === undefined) return jsonError("invalid_external_ref", 400);
+  // scoped 成员不能带 external_ref:「external_ref_exists」会把别人的卡号回给他。
+  if (ref && scoped) return jsonError("external_ref_not_allowed", 403);
   const extUrl = body.external_url === undefined ? null : externalUrl(body.external_url);
   if (extUrl === undefined) return jsonError("invalid_external_url", 400);
   const parentId = body.parent_id === undefined ? null : parentIdOf(body.parent_id);
   if (parentId === undefined) return jsonError("invalid_parent_id", 400);
   if (parentId) {
-    const err = parentError(networkId, parentId, null);
+    const err = parentHidden(ctx, parentId) ? "parent_not_found" : parentError(networkId, parentId, null);
     if (err) return jsonError(err, 400);
   }
   if (ref) {
@@ -600,7 +729,8 @@ async function createRequirement(ctx: RequirementsRequestContext, body: Record<s
   }
   if (clientId) {
     const existing = db.get<Row>(`SELECT ${SELECT} FROM requirements WHERE network_id = ?1 AND client_id = ?2`, networkId, clientId);
-    if (existing) return Response.json({ ok: true, requirement: toPublicFor(ctx, existing) });
+    // 重放只回调用者看得见的卡;撞上别人的卡(scoped 看不见)= 固定的 409,不把那张卡回给他。
+    if (existing) return canSeeTask(caller, existing) ? Response.json({ ok: true, requirement: toPublicFor(ctx, existing) }) : jsonError("client_id_taken", 409);
   }
   const id = `req_${crypto.randomUUID()}`;
   const createdAt = new Date().toISOString();
@@ -611,9 +741,11 @@ async function createRequirement(ctx: RequirementsRequestContext, body: Record<s
     // 领号和插入在同一个事务里:插入被唯一索引挡下时,号一起回滚,不留空洞。
     db.transaction(() => db.run(
       `INSERT INTO requirements
-       (requirement_id, network_id, title, column_name, priority, due_on, assignee, client_id, issues_json, created_by, created_at, updated_at, owner_json, participants_json, agent_owner_json, description, checklist_json, project_id, external_ref, external_url, created_by_json, updated_by_json, archived, parent_id, tags_json, start_on, seq)
-       VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?11, ?12, ?13, ?14, ?15, ?16, ?17, ?18, ?19, ?20, ?20, 0, ?21, ?22, ?23, ?24)`,
-      [id, networkId, name, column, priority, due || null, assignee, clientId || null, JSON.stringify(issues), ctx.auth?.userId ?? null, createdAt, people.ownerJson, people.participantsJson, people.agentOwnerJson, description || null, JSON.stringify(checklist), projectId, ref, extUrl, actor, parentId, JSON.stringify(tags), start || null, nextRequirementSeq(db, networkId)],
+       (requirement_id, network_id, title, column_name, priority, due_on, assignee, client_id, issues_json, created_by, created_at, updated_at, owner_json, participants_json, agent_owner_json, description, checklist_json, project_id, external_ref, external_url, created_by_json, updated_by_json, archived, parent_id, tags_json, start_on, seq, completed_at, completed_by_json, completed_at_approx)
+       VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?11, ?12, ?13, ?14, ?15, ?16, ?17, ?18, ?19, ?20, ?20, 0, ?21, ?22, ?23, ?24, ?25, ?26, 0)`,
+      [id, networkId, name, column, priority, due || null, assignee, clientId || null, JSON.stringify(issues), ctx.auth?.userId ?? null, createdAt, people.ownerJson, people.participantsJson, people.agentOwnerJson, description || null, JSON.stringify(checklist), projectId, ref, extUrl, actor, parentId, JSON.stringify(tags), start || null, nextRequirementSeq(db, networkId),
+        // 直接建在「完成」列 = 此刻完成、由建卡的人完成。
+        column === "done" ? createdAt : null, column === "done" ? actor : null],
     ));
   } catch {
     // 并发的同一个 external_ref / client_id:唯一索引挡住了第二个,回已有的那条。
@@ -624,6 +756,7 @@ async function createRequirement(ctx: RequirementsRequestContext, body: Record<s
     if (!clientId) return jsonError("insert_failed", 500);
     const existing = db.get<Row>(`SELECT ${SELECT} FROM requirements WHERE network_id = ?1 AND client_id = ?2`, networkId, clientId);
     if (!existing) return jsonError("insert_failed", 500);
+    if (!canSeeTask(caller, existing)) return jsonError("client_id_taken", 409);
     return Response.json({ ok: true, requirement: toPublicFor(ctx, existing) });
   }
   const created = db.get<Row>(`SELECT ${SELECT} FROM requirements WHERE requirement_id = ?1`, id)!;
@@ -636,6 +769,10 @@ function patchRequirement(ctx: RequirementsRequestContext, row: Row, body: Recor
   if (!PATCH_FIELDS.some(k => Object.prototype.hasOwnProperty.call(body, k))) return jsonError("empty_patch", 400);
   const has = (k: string) => Object.prototype.hasOwnProperty.call(body, k);
   if (!canWrite(ctx, row.network_id)) return jsonError("permission_denied", 403);
+  const caller = taskCaller(ctx);
+  if (!canEditTask(caller, row)) return taskDenied(ctx, row, "task_read_only");
+  // scoped 成员不能写 external_ref:唯一索引冲突会泄露别的卡用了这个 ref。
+  if (has("external_ref") && caller && isTaskScoped(caller.userId, row.network_id)) return jsonError("external_ref_not_allowed", 403);
   if (has("column") && !COLUMNS.has(String(body.column))) return jsonError("invalid_column", 400);
   const issues = has("issues") ? normalizeIssues(body.issues) : null;
   if (has("issues") && issues === null) return jsonError("invalid_issues", 400);
@@ -679,6 +816,8 @@ function patchRequirement(ctx: RequirementsRequestContext, row: Row, body: Recor
   let projectId = row.project_id;
   if (has("project_id")) {
     try { projectId = projectRef(body.project_id, row.network_id); } catch (e) { return jsonError((e as Error).message, 400); }
+    // scoped 成员只能挪进自己 can_edit 的项目;没授权的项目与不存在的项目同一个错误。
+    if (projectId !== row.project_id && !canUseProject(caller, row.network_id, projectId)) return jsonError("project_not_in_network", 400);
   }
   let ref = row.external_ref;
   if (has("external_ref")) {
@@ -701,7 +840,7 @@ function patchRequirement(ctx: RequirementsRequestContext, row: Row, body: Recor
     const next = parentIdOf(body.parent_id);
     if (next === undefined) return jsonError("invalid_parent_id", 400);
     if (next) {
-      const err = parentError(row.network_id, next, row.requirement_id);
+      const err = parentHidden(ctx, next) ? "parent_not_found" : parentError(row.network_id, next, row.requirement_id);
       if (err) return jsonError(err, 400);
     }
     parentId = next;
@@ -712,12 +851,20 @@ function patchRequirement(ctx: RequirementsRequestContext, row: Row, body: Recor
     archived = body.archived ? 1 : 0;
   }
   const updatedAt = new Date().toISOString();
+  const column = has("column") ? String(body.column) : row.column_name;
+  const actor = JSON.stringify(actorOf(ctx));
+  // 完成时间:移进「完成」= 此刻 + 这次的操作者;移出 = 清空;留在「完成」(done → done、改别的字段)= 原样不动。
+  const completed = column !== "done" ? { at: null, by: null, approx: 0 }
+    : row.column_name !== "done" ? { at: updatedAt, by: actor, approx: 0 }
+    : { at: row.completed_at, by: row.completed_by_json, approx: row.completed_at_approx ? 1 : 0 };
   db.run(
     `UPDATE requirements SET column_name = ?1, updated_at = ?2, title = ?7, priority = ?8, due_on = ?9, assignee = ?10, owner_json = ?4, participants_json = ?5, issues_json = ?6,
-       agent_owner_json = ?11, description = ?12, checklist_json = ?13, project_id = ?14, external_ref = ?15, external_url = ?16, archived = ?17, updated_by_json = ?18, parent_id = ?19, tags_json = ?20, start_on = ?21
+       agent_owner_json = ?11, description = ?12, checklist_json = ?13, project_id = ?14, external_ref = ?15, external_url = ?16, archived = ?17, updated_by_json = ?18, parent_id = ?19, tags_json = ?20, start_on = ?21,
+       completed_at = ?22, completed_by_json = ?23, completed_at_approx = ?24
      WHERE requirement_id = ?3`,
-    [has("column") ? body.column : row.column_name, updatedAt, row.requirement_id, people.ownerJson, people.participantsJson, has("issues") ? JSON.stringify(issues) : row.issues_json, name, priority, due || null, assignee, people.agentOwnerJson,
-      has("description") ? (description || null) : row.description, has("checklist") ? JSON.stringify(checklist) : row.checklist_json, projectId, ref, extUrl, archived, JSON.stringify(actorOf(ctx)), parentId, has("tags") ? JSON.stringify(tags) : row.tags_json, start || null],
+    [column, updatedAt, row.requirement_id, people.ownerJson, people.participantsJson, has("issues") ? JSON.stringify(issues) : row.issues_json, name, priority, due || null, assignee, people.agentOwnerJson,
+      has("description") ? (description || null) : row.description, has("checklist") ? JSON.stringify(checklist) : row.checklist_json, projectId, ref, extUrl, archived, actor, parentId, has("tags") ? JSON.stringify(tags) : row.tags_json, start || null,
+      completed.at, completed.by, completed.approx],
   );
   const updated = db.get<Row>(`SELECT ${SELECT} FROM requirements WHERE requirement_id = ?1`, row.requirement_id)!;
   return Response.json(withLegacyOwner(toPublicFor(ctx, updated), people.coerced));
@@ -748,6 +895,8 @@ function scopedRow(ctx: RequirementsRequestContext, id: string): Row | Response
   const params: unknown[] = [seq ?? id];
   let sql = `SELECT ${SELECT} FROM requirements WHERE ${seq === null ? "requirement_id" : "seq"} = ?1`;
   sql = addHumanNetworkScope(sql, params, ctx.scope);
+  // 看不见的卡与不存在的卡同一个 404(逐字节相同);#N 的 ambiguous_seq 也只在看得见的行里判定。
+  sql = addTaskVisibilityScope(sql, params, taskCaller(ctx));
   const rows = db.all<Row>(`${sql} LIMIT 2`, ...params);
   if (rows.length > 1) {
     const networks = rows.map(r => r.network_id);
@@ -793,8 +942,9 @@ function listFilters(url: URL, sql: string, params: unknown[], ctx?: Requirement
   if (parent !== null) sql += parent === "none" ? " AND parent_id IS NULL" : ` AND parent_id = ?${params.push(parent)}`;
   if (q.get("top_level") === "1") sql += " AND parent_id IS NULL";
   // Explicit archived-only wins over the legacy include-all switch.
+  // changes=1 看得见「被归档」这一改动:默认连归档的一起回(行上 archived: true),客户端据此把它移出看板。
   if (q.get("archived") === "true") sql += " AND COALESCE(archived, 0) = 1";
-  else if (q.get("include_archived") !== "1") sql += " AND COALESCE(archived, 0) = 0";
+  else if (q.get("include_archived") !== "1" && q.get("changes") !== "1") sql += " AND COALESCE(archived, 0) = 0";
   return sql;
 }
 
@@ -857,9 +1007,106 @@ function hiddenFilterForScope(ctx: RequirementsRequestContext, nodeId: string):
   return false;
 }
 
+// ── 列表省流(2026-09-30,App「连接较慢 · 数据可能稍有延迟」)──
+// 生产:425 张卡、1447 条子任务,整张表 1 MB(gzip 240 KB),任务页每 15 s 读一次;中国经 RELAY 的链路上
+// 一次要好几秒。三件事,都是加法,旧 App 不带新参数就与原来逐字相同:
+//   1. view=summary:不带描述正文和子任务条目(打开一张卡再 GET /api/requirements/:id 读全文);
+//   2. changes=1 + updated_since:只回这之后改过的卡(含归档的),加上删掉的卡的 id 和下次用的 server_time;
+//   3. 表没变时不重算:按「调用者 + 查询」缓存上一次的正文和 ETag,需求表一有写入就作废(见 requirementsGeneration)。
+
+/** view=summary 的一行:去掉 description / checklist,换成 has_description 和 checklist_count。 */
+function toSummary<T extends { description: string; checklist: ChecklistItem[] }>(pub: T): Omit<T, "description" | "checklist"> & { has_description: boolean; checklist_count: { total: number; done: number } } {
+  const { description, checklist, ...rest } = pub;
+  return { ...rest, has_description: !!description, checklist_count: { total: checklist.length, done: checklist.filter(item => item.done).length } };
+}
+
+/** 墓碑保留多久。changes 的 updated_since 早于这之前,删除就可能漏报 —— 响应里的 tombstones_since 告诉客户端这个下限。 */
+export const TOMBSTONE_RETENTION_MS = 30 * 86_400_000;
+
+/** 删卡时留一条墓碑(连同判断「谁看得见」要用的列,受限成员只收到他本来看得见的卡的删除)。 */
+function recordTombstone(row: Row, deletedAt: string): void {
+  db.run(
+    `INSERT INTO requirement_tombstones (requirement_id, network_id, deleted_at, project_id, owner_json, participants_json, created_by, created_by_json)
+     VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)
+     ON CONFLICT(requirement_id) DO UPDATE SET deleted_at = excluded.deleted_at`,
+    [row.requirement_id, row.network_id, deletedAt, row.project_id || null, row.owner_json || null, row.participants_json || null, row.created_by || null, row.created_by_json || null],
+  );
+  db.run("DELETE FROM requirement_tombstones WHERE deleted_at < ?1", [new Date(Date.parse(deletedAt) - TOMBSTONE_RETENTION_MS).toISOString()]);
+}
+
+type TombstoneRow = { requirement_id: string; network_id: string; deleted_at: string; project_id: string | null; owner_json: string | null; participants_json: string | null; created_by: string | null; created_by_json: string | null };
+
+/** updated_since 之后删掉的、调用者看得见的卡。同 id 又出现在表里的(不该有)不算删除。 */
+function deletedSince(ctx: RequirementsRequestContext, sinceIso: string): string[] {
+  const params: unknown[] = [sinceIso];
+  let sql = "SELECT requirement_id, network_id, deleted_at, project_id, owner_json, participants_json, created_by, created_by_json FROM requirement_tombstones WHERE deleted_at >= ?1";
+  sql = addHumanNetworkScope(sql, params, ctx.scope);
+  sql += " AND requirement_id NOT IN (SELECT requirement_id FROM requirements) ORDER BY deleted_at, requirement_id";
+  const caller = taskCaller(ctx);
+  return db.all<TombstoneRow>(sql, ...params).filter(row => canSeeTask(caller, row)).map(row => row.requirement_id);
+}
+
+/**
+ * 需求表的写入代数:每个经过 handleRequirementsRequest 的非 GET 请求处理完就 +1(REST 和 MCP 的写入都走它,
+ * tools.ts 调的是同一个处理函数)。列表缓存只在代数没变时复用。进程重启 = 缓存清空。
+ */
+let requirementsGeneration = 0;
+/** 缓存条目最长信任这么久:兜住不经过处理函数的改动(启动迁移、运维脚本直接改库)。 */
+export const LIST_CACHE_MAX_AGE_MS = 60_000;
+/** 只缓存不带搜索词的列表(搜索每打一个字就是一个新键),总共最多这么多字符(条目按最近使用淘汰)。 */
+const LIST_CACHE_MAX_CHARS = 16 * 1024 * 1024;
+type ListCacheEntry = { generation: number; acl: string; at: number; body: string; etag: string };
+const listCache = new Map<string, ListCacheEntry>();
+let listCacheChars = 0;
+function rememberList(key: string, entry: ListCacheEntry): void {
+  const old = listCache.get(key);
+  if (old) { listCache.delete(key); listCacheChars -= old.body.length; }
+  if (entry.body.length > LIST_CACHE_MAX_CHARS / 4) return;
+  listCache.set(key, entry);
+  listCacheChars += entry.body.length;
+  for (const [k, v] of listCache) {
+    if (listCacheChars <= LIST_CACHE_MAX_CHARS) break;
+    listCache.delete(k);
+    listCacheChars -= v.body.length;
+  }
+}
+
+/**
+ * 缓存能不能用、以及调用者权限的指纹。null = 这个调用者不缓存:受限成员(看得见哪些 Agent 取决于节点表)
+ * 和「只看相关任务」的成员(看得见哪些卡取决于项目授权)每次照旧现算。
+ * 其余调用者的输出只取决于需求表本身 + 他的角色 / 成员行:这些都放进指纹,变了就不命中。
+ */
+function listCacheAcl(ctx: RequirementsRequestContext): string | null {
+  const caller = taskCaller(ctx);
+  if (!caller) return `open:${ctx.isAdmin ? 1 : 0}:${ctx.isNodeToken ? 1 : 0}`;
+  if (restrictedNetworkIds(caller.userId).length > 0) return null;
+  const members = db.all<Record<string, unknown>>("SELECT * FROM network_members WHERE user_id = ?1 ORDER BY network_id", caller.userId);
+  const networks = members.map(m => String(m.network_id));
+  if (networks.some(networkId => isTaskScoped(caller.userId, networkId))) return null;
+  const role = db.get<{ role: string | null }>("SELECT role FROM users WHERE user_id = ?1", caller.userId)?.role ?? null;
+  return JSON.stringify({ role, members });
+}
+
+function listCacheKey(ctx: RequirementsRequestContext): string {
+  const sorted = [...ctx.url.searchParams.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return JSON.stringify({ u: ctx.auth?.userId ?? null, n: ctx.auth?.networkId ?? null, a: ctx.isAdmin, t: ctx.isNodeToken, s: ctx.scope, q: sorted });
+}
+
+/** Test-only. */
+export function __requirementsListCacheForTest() {
+  return { size: () => listCache.size, clear: () => { listCache.clear(); listCacheChars = 0; }, generation: () => requirementsGeneration };
+}
+
 export async function handleRequirementsRequest(ctx: RequirementsRequestContext): Promise<Response | null> {
-  const { req, url } = ctx;
+  const { url } = ctx;
   if (url.pathname !== "/api/requirements" && !url.pathname.startsWith("/api/requirements/")) return null;
+  if (ctx.req.method === "GET") return handleRequirementsRequestInner(ctx);
+  // 写完(成功与否)才 +1:之后的 GET 一定看得见这次写入。
+  try { return await handleRequirementsRequestInner(ctx); } finally { requirementsGeneration++; }
+}
+
+async function handleRequirementsRequestInner(ctx: RequirementsRequestContext): Promise<Response | null> {
+  const { req, url } = ctx;
   // 节点令牌只能做 NODE_TOKEN_OPERATIONS 里的事(读 / 建 / 改 / 勾子任务 / upsert / 读项目),
   // 而且只在它绑定的网络里 —— 范围由 scope 强制,写入再由 canWrite 核一次。
   if (ctx.isNodeToken && !NODE_TOKEN_OPERATIONS.has(operationOf(req, url))) return jsonError("user_token_required", 403);
@@ -869,9 +1116,40 @@ export async function handleRequirementsRequest(ctx: RequirementsRequestContext)
   if (url.pathname === "/api/requirements/tags" && req.method === "GET") {
     const networkId = resolveRestWriteNetworkId(ctx.scope, ctx.auth, ctx.isAdmin);
     if (!networkId) return jsonError("network_id_required", 400);
-    const rows = db.all<{ tags_json: string | null }>("SELECT tags_json FROM requirements WHERE network_id=?1", networkId);
-    const tags = [...new Set(rows.flatMap(row => storedTags(row.tags_json)))].sort();
-    return Response.json({ ok: true, networkId, tags });
+    const tagParams: unknown[] = [networkId];
+    const tagSql = addTaskVisibilityScope("SELECT tags_json FROM requirements WHERE network_id=?1", tagParams, taskCaller(ctx));
+    const rows = db.all<{ tags_json: string | null }>(tagSql, ...tagParams);
+    // counts:调用者看得见的卡里(含归档)每个标签用了几张;colors:只回这些标签的颜色(看不见的卡上的标签不外泄)。
+    // can_manage:这个调用者能不能用 /tags/ops。旧 App 只读 tags,多出的字段忽略。
+    const counts: Record<string, number> = {};
+    for (const row of rows) for (const tag of storedTags(row.tags_json)) counts[tag] = (counts[tag] ?? 0) + 1;
+    const tags = Object.keys(counts).sort();
+    const colors: Record<string, string> = {};
+    for (const row of db.all<{ name: string; color: string }>("SELECT name, color FROM network_tags WHERE network_id = ?1", networkId)) {
+      if (counts[row.name]) colors[row.name] = row.color;
+    }
+    return Response.json({ ok: true, networkId, tags, counts, colors, can_manage: canManageTags(ctx, networkId) });
+  }
+
+  if (url.pathname === "/api/requirements/tags/ops") {
+    if (req.method !== "POST") return jsonError("not_found", 404);
+    return handleTagOp(ctx);
+  }
+
+  // 仪表盘聚合(requirements-stats.ts):一个网络、调用者看得见的卡(与列表同一个可见范围),含归档的卡 ——
+  // 完成的卡常被归档,不算它们「今天完成了多少」就会偏少。
+  if (url.pathname === "/api/requirements/stats" && req.method === "GET") {
+    const networkId = resolveRestWriteNetworkId(ctx.scope, ctx.auth, ctx.isAdmin);
+    if (!networkId) return jsonError("network_id_required", 400);
+    const sq = parseStatsQuery(url.searchParams, Date.now());
+    if ("error" in sq) return jsonError(sq.error, 400);
+    const statsParams: unknown[] = [networkId];
+    const statsSql = addTaskVisibilityScope(
+      "SELECT requirement_id, seq, title, project_id, column_name, archived, created_at, completed_at, completed_at_approx, completed_by_json FROM requirements WHERE network_id = ?1",
+      statsParams, taskCaller(ctx),
+    );
+    const rows = db.all<StatsRow>(statsSql, ...statsParams);
+    return conditionalJson(ctx.req, { ok: true, networkId, ...aggregateStats(rows, sq, hiddenNodeFilter(ctx, networkId)) });
   }
 
   if (url.pathname === '/api/requirements/people' && req.method === 'GET') {
@@ -892,15 +1170,43 @@ export async function handleRequirementsRequest(ctx: RequirementsRequestContext)
     // 只拼 FROM … WHERE:同一组条件既用来读整行,也用来(搜索时)先读轻量列。
     let sql = "FROM requirements WHERE 1=1";
     sql = addHumanNetworkScope(sql, params, ctx.scope);
+    sql = addTaskVisibilityScope(sql, params, taskCaller(ctx));
     const filtered = listFilters(url, sql, params, ctx);
     if (typeof filtered !== "string") return filtered;
     // q= / limit / cursor(requirements-search.ts)。都不带 = 旧行为:最新 500 张、同样的顺序。
     const lq = parseListQuery(url.searchParams);
     if ("error" in lq) return jsonError(lq.error, 400);
+    const view = url.searchParams.get("view");
+    if (view !== null && view !== "full" && view !== "summary") return jsonError("invalid_view", 400);
+    const changes = url.searchParams.get("changes") === "1";
+    if (changes && url.searchParams.get("updated_since") === null) return jsonError("updated_since_required", 400);
+    // changes 模式:server_time 取在读表之前,下次拿它当 updated_since,读表期间的写入不会漏(>= 会重复回一次,客户端按 id 覆盖)。
+    const serverTime = new Date().toISOString();
+    const cacheKey = changes || url.searchParams.get("q") ? null : listCacheKey(ctx);
+    const acl = cacheKey ? listCacheAcl(ctx) : null;
+    const generation = requirementsGeneration;
+    const cached = cacheKey && acl !== null ? listCache.get(cacheKey) : undefined;
+    if (cached && cached.generation === generation && cached.acl === acl && Date.now() - cached.at < LIST_CACHE_MAX_AGE_MS) {
+      listCache.delete(cacheKey!);
+      listCache.set(cacheKey!, cached);
+      return conditionalBody(ctx.req, cached.body, cached.etag);
+    }
     const page = listPage(ctx, filtered, params, lq);
+    const rows = page.rows.map(row => toPublicFor(ctx, row));
     // capabilities:客户端按这个决定显示哪些功能(预计完成能不能带时刻、有没有项目…),不用靠猜字段。
     // has_more / next_cursor:后面还有没有(带 cursor=next_cursor 再读一页)。旧客户端不认识,忽略即可。
-    return conditionalJson(ctx.req, { ok: true, requirements: page.rows.map(row => toPublicFor(ctx, row)), capabilities: REQUIREMENT_CAPABILITIES, has_more: page.hasMore, next_cursor: page.nextCursor });
+    const payload: Record<string, unknown> = { ok: true, requirements: view === "summary" ? rows.map(toSummary) : rows, capabilities: REQUIREMENT_CAPABILITIES, has_more: page.hasMore, next_cursor: page.nextCursor };
+    if (view === "summary") payload.view = "summary";
+    if (changes) {
+      const since = new Date(Date.parse(url.searchParams.get("updated_since")!)).toISOString();
+      payload.deleted = deletedSince(ctx, since);
+      payload.server_time = serverTime;
+      payload.tombstones_since = new Date(Date.parse(serverTime) - TOMBSTONE_RETENTION_MS).toISOString();
+    }
+    const body = JSON.stringify(payload);
+    const etag = bodyEtag(body);
+    if (cacheKey && acl !== null) rememberList(cacheKey, { generation, acl, at: Date.now(), body, etag });
+    return conditionalBody(ctx.req, body, etag);
   }
 
   if (url.pathname === "/api/requirements" && req.method === "POST") {
@@ -919,6 +1225,8 @@ export async function handleRequirementsRequest(ctx: RequirementsRequestContext)
     const networkId = writeNetwork(body, ctx);
     if (!networkId) return jsonError("network_id_required", 400);
     if (!canWrite(ctx, networkId)) return jsonError("permission_denied", 403);
+    // scoped 成员不能用同步接口:external_ref 的唯一索引会把「这个 ref 已经有卡」泄露出去。固定错误,不看 ref。
+    if (taskCaller(ctx) && isTaskScoped(ctx.auth!.userId, networkId)) return jsonError("upsert_not_allowed", 403);
     const existing = rowByExternalRef(networkId, ref);
     if (!existing) {
       const res = await createRequirement(ctx, body);
@@ -943,6 +1251,7 @@ export async function handleRequirementsRequest(ctx: RequirementsRequestContext)
     const row = scopedRow(ctx, decodeURIComponent(itemMatch[1]));
     if (row instanceof Response) return row;
     if (!canWrite(ctx, row.network_id)) return jsonError("permission_denied", 403);
+    if (!canEditTask(taskCaller(ctx), row)) return taskDenied(ctx, row, "task_read_only");
     // 读-改-写在同一个同步段里完成(中间没有 await),同一进程里的两次勾选不会交错。
     const items = storedChecklist(row.checklist_json);
     const itemId = decodeURIComponent(itemMatch[2]);
@@ -966,9 +1275,14 @@ export async function handleRequirementsRequest(ctx: RequirementsRequestContext)
     const row = scopedRow(ctx, id);
     if (row instanceof Response) return row;
     if (!canWrite(ctx, row.network_id)) return jsonError("permission_denied", 403);
+    if (!canDeleteTask(taskCaller(ctx), row)) return taskDenied(ctx, row, "task_delete_denied");
     // 子需求不跟着删:先解挂(变成顶层),再删父卡。
-    db.run("UPDATE requirements SET parent_id = NULL WHERE parent_id = ?1", [row.requirement_id]);
+    const deletedAt = new Date().toISOString();
+    db.run("UPDATE requirements SET parent_id = NULL, updated_at = ?2 WHERE parent_id = ?1", [row.requirement_id, deletedAt]);
     db.run("DELETE FROM requirements WHERE requirement_id = ?1", [row.requirement_id]);
+    recordTombstone(row, deletedAt);
+    // 硬删除以前不留痕(RFC-038 §9.1):记下是谁删了哪张(标题 + 短号),卡本身已经没了。
+    if (ctx.auth) logAudit(ctx.auth.userId, ctx.auth.username || null, "requirement_deleted", "requirement", row.requirement_id, JSON.stringify({ title: row.title, seq: row.seq ?? null }).slice(0, 1000), undefined, row.network_id);
     return Response.json({ ok: true, deleted: row.requirement_id });
   }
   if (req.method !== "PATCH") return jsonError("not_found", 404);

package/src/rest-explicit-columns-http.test.ts

@@ -31,7 +31,7 @@ const GOLDEN_RESPONSE_KEYS = {
   //    —— 理由见本文件顶部：从投影推导会让被删掉的列同时从响应和期望里消失，产生假绿。
   authMeNetwork: [
     "network_id", "network_name", "owner_id", "description", "settings",
-    "created_at", "updated_at", "visibility", "max_members", "member_role", "agent_access",
+    "created_at", "updated_at", "visibility", "max_members", "member_role", "agent_access", "task_access",
   ],
   networkDetail: [
     "network_id", "network_name", "owner_id", "description", "settings",