@sleep2agi/commhub-server 0.9.0-preview.72 → 0.9.0-preview.74

package/src/requirements.ts

@@ -2,11 +2,16 @@
 // 不是 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 { 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 {
+  addProjectVisibilityScope, addTaskVisibilityScope, canDeleteTask, canEditTask, canSeeTask, canUseProject, deleteTaskGrantsForProject,
+  isTaskScoped, shouldAuditDenied, taskPermissionsResolver, type TaskCaller,
+} from "./task-access.js";
+import { ensureNetworkTags, ensureRequirementCompletedAt, ensureRequirementIndexes, ensureRequirementProjects, ensureRequirementSeq, migrateRequirementAgentOwners, migrateRequirementPriorityCheck, nextRequirementSeq } from "./requirements-migrate.js";
 
 // 启动迁移:旧库里节点当负责人的卡,节点挪到 agent_owner(列由 db.ts 的加列循环加上)。
 // 放在这里而不是 db.ts:db.ts 每多一行,文档里钉着的行号就漂一次。
@@ -15,6 +20,8 @@ migrateRequirementAgentOwners(db);
 ensureRequirementProjects(db);
 ensureRequirementIndexes(db);
 ensureRequirementSeq(db);
+ensureRequirementCompletedAt(db);
+ensureNetworkTags(db);
 
 type RequestAuth = { userId: string; networkId: string | null; username: string; tokenId?: string | null; tokenName?: string | null } | null;
 
@@ -61,12 +68,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 +250,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); }
@@ -248,6 +284,7 @@ async function handleProjects(ctx: RequirementsRequestContext): Promise<Response
     // 先把卡片上的引用置空,再删项目:卡片一张不少。
     db.run("UPDATE requirements SET project_id = NULL WHERE project_id = ?1", [current.project_id]);
     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 +311,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 +405,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 +449,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 +466,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 +536,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";
@@ -457,8 +566,9 @@ 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;
+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"] as const;
 
 // ── 子需求 ──
 // parent_id:同一网络里的另一张卡;不能成环;最多 5 层(顶层是第 1 层)。删父卡 = 子卡保留、parent_id 置空。
@@ -579,18 +689,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 +716,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 +728,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 +743,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 +756,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 +803,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 +827,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 +838,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 +882,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);
@@ -869,9 +1005,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,6 +1059,7 @@ 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 张、同样的顺序。
@@ -919,6 +1087,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 +1113,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 +1137,12 @@ 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]);
     db.run("DELETE FROM requirements WHERE requirement_id = ?1", [row.requirement_id]);
+    // 硬删除以前不留痕(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",

package/src/scheduled-reply-unread-http.test.ts

@@ -0,0 +1,212 @@
+// 定时任务的回复要进建排程那个人的未读(Vincent 2026-09-30「定时任务触发的…那个红点它是不显示的」)。
+//
+// scheduler 派的任务 from_name='scheduler',回复以前按 from_name 落进 inbox(session_name='scheduler'):
+// app 会话里看得到(会话取自 tasks 表),但 unread_by_agent 只数 session_name=用户名 的行 ⇒ 永远没红点。
+// 这里走真 Hub(bootServer)+ 真节点令牌回复路径(send_reply,callerTokenIsNetwork=true)。
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { addNetworkMember, createNetworkTokenForNode, register } from "./auth.js";
+import { db } from "./db.js";
+import { runDueScheduledTasks } from "./scheduled-tasks.js";
+import { registerTools } from "./tools.js";
+
+const activeDbPath = process.env.COMMHUB_DB ?? (process.env.COMMHUB_TEST_PG_URL ? "postgres" : undefined);
+if (!activeDbPath) throw new Error("scheduled-reply-unread requires COMMHUB_DB (or COMMHUB_TEST_PG_URL) before module import");
+
+let server: any;
+let base = "";
+let ownerToken = "";
+let ownerName = "";
+let memberToken = "";
+let memberName = "";
+let networkId = "";
+let ownerId = "";
+const stamp = Date.now();
+const ALIAS = `sched-reply-node-${stamp}`;
+const nodeId = `n_sched_reply_${stamp}`;
+
+async function api(token: string, path: string, init?: RequestInit) {
+  const res = await fetch(`${base}${path}`, {
+    ...init,
+    headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json", ...(init?.headers || {}) },
+  });
+  return { status: res.status, body: await res.json() as any };
+}
+
+/** 节点令牌身份调 send_reply(与真节点的 commhub_reply 同一个 handler、同一组归属校验)。 */
+async function nodeReply(args: Record<string, unknown>): Promise<any> {
+  const mcp = new McpServer({ name: "sched-reply", version: "0" }) as any;
+  const handlers: Record<string, (a: any) => Promise<any>> = {};
+  const original = mcp.tool.bind(mcp);
+  mcp.tool = (name: string, ...rest: any[]) => {
+    const handler = rest.at(-1);
+    if (typeof handler === "function") handlers[name] = handler;
+    return original(name, ...rest);
+  };
+  registerTools(mcp, undefined, networkId, ownerId, ALIAS, true, null);
+  const out = await handlers.send_reply(args);
+  return JSON.parse(out.content[0].text);
+}
+
+async function unreadFor(token: string): Promise<Record<string, number>> {
+  const res = await api(token, "/api/messages?scope=user&limit=50");
+  expect(res.status).toBe(200);
+  return res.body.unread_by_agent ?? {};
+}
+
+async function ackAgent(token: string) {
+  const res = await api(token, "/api/messages/ack", { method: "POST", body: JSON.stringify({ agent: ALIAS }) });
+  expect(res.status).toBe(200);
+  return res.body;
+}
+
+/** 建一个排程、让它立刻到期、跑一次,返回它派出的 task_id。 */
+async function fireSchedule(token: string, name: string): Promise<{ scheduleId: string; taskId: string }> {
+  const created = await api(token, "/api/scheduled-tasks", {
+    method: "POST",
+    body: JSON.stringify({
+      network_id: networkId, name, target_node_id: nodeId, task: `${name} tick`,
+      timezone: "UTC", schedule: { type: "interval", every_seconds: 120 },
+    }),
+  });
+  expect(created.status).toBe(201);
+  const scheduleId = created.body.schedule.schedule_id as string;
+  // 别的排程不许在这次 sweep 里一起跑
+  db.run("UPDATE scheduled_tasks SET next_run_at = ?1 WHERE schedule_id != ?2", [new Date(Date.now() + 24 * 3600_000).toISOString(), scheduleId]);
+  db.run("UPDATE scheduled_tasks SET next_run_at = ?1 WHERE schedule_id = ?2", [new Date(Date.now() - 60_000).toISOString(), scheduleId]);
+  await runDueScheduledTasks();
+  const run = db.get<{ task_id: string | null }>(
+    "SELECT task_id FROM scheduled_task_runs WHERE schedule_id = ?1 ORDER BY scheduled_for DESC LIMIT 1", scheduleId,
+  );
+  expect(run?.task_id).toBeTruthy();
+  const task = db.get<{ from_name: string }>("SELECT from_name FROM tasks WHERE task_id = ?1", run!.task_id!);
+  expect(task?.from_name).toBe("scheduler");
+  return { scheduleId, taskId: run!.task_id! };
+}
+
+function replyRow(taskId: string) {
+  return db.get<{ session_name: string; from_session: string; acked: number }>(
+    "SELECT session_name, from_session, acked FROM inbox WHERE type = 'reply' AND in_reply_to = ?1", taskId,
+  );
+}
+
+beforeAll(async () => {
+  ownerName = `sched_reply_owner_${stamp}`;
+  const owner = register(ownerName, "SchedReplyOwner123!", undefined, "seed");
+  expect(owner.ok).toBe(true);
+  ownerToken = owner.token!;
+  networkId = owner.network_id!;
+  ownerId = db.get<{ owner_id: string }>("SELECT owner_id FROM networks WHERE network_id = ?1", networkId)!.owner_id;
+
+  memberName = `sched_reply_member_${stamp}`;
+  const member = register(memberName, "SchedReplyMember123!", undefined, "seed");
+  expect(member.ok).toBe(true);
+  memberToken = member.token!;
+  const memberId = db.get<{ user_id: string }>("SELECT user_id FROM users WHERE username = ?1", memberName)!.user_id;
+  expect(addNetworkMember(networkId, memberId, "member", ownerId, { agentAccess: "all" }).ok).toBe(true);
+
+  expect(createNetworkTokenForNode(ownerId, networkId, ALIAS).ok).toBe(true);
+  db.run(
+    "INSERT INTO nodes (node_id, node_name, alias, runtime, network_id) VALUES (?1, ?2, ?2, 'claude-code', ?3)",
+    [nodeId, ALIAS, networkId],
+  );
+  db.run(
+    "INSERT INTO sessions (resume_id, alias, status, node_id, network_id) VALUES (?1, ?2, 'idle', ?3, ?4)",
+    [`r_sched_reply_${stamp}`, ALIAS, nodeId, networkId],
+  );
+  const mod: any = await import("./server.js");
+  server = mod.bootServer({ port: 0, hostname: "127.0.0.1" });
+  base = `http://127.0.0.1:${server.port}`;
+}, 30_000);
+
+afterAll(() => {
+  try { server?.stop?.(true); } catch {}
+});
+
+describe("scheduled-task replies reach the schedule creator's unread", () => {
+  test("a direct reply still lands on the sender and counts once", async () => {
+    await ackAgent(ownerToken);
+    const sent = await api(ownerToken, "/api/task", { method: "POST", body: JSON.stringify({ network_id: networkId, alias: ALIAS, task: "direct hello" }) });
+    expect(sent.status).toBe(200);
+    const taskId = sent.body.task_id as string;
+    const reply = await nodeReply({ in_reply_to: taskId, text: "direct answer", status: "replied" });
+    expect(reply.ok).toBe(true);
+    expect(replyRow(taskId)?.session_name).toBe(ownerName);
+    expect((await unreadFor(ownerToken))[ALIAS]).toBe(1);
+    await ackAgent(ownerToken);
+    expect((await unreadFor(ownerToken))[ALIAS]).toBeUndefined();
+  });
+
+  test("a scheduled-task reply counts for the creator, and ack-by-agent clears it", async () => {
+    await ackAgent(ownerToken);
+    const { taskId } = await fireSchedule(ownerToken, "owner-every-2m");
+    // 节点不带 alias(SDK 运行时)——收件人由 in_reply_to 推出
+    const reply = await nodeReply({ in_reply_to: taskId, text: "tick answer", status: "replied" });
+    expect(reply.ok).toBe(true);
+    expect(replyRow(taskId)).toEqual({ session_name: ownerName, from_session: ALIAS, acked: 0 });
+    expect(db.get<{ status: string; result: string }>("SELECT status, result FROM tasks WHERE task_id = ?1", taskId))
+      .toEqual({ status: "replied", result: "tick answer" });
+    expect((await unreadFor(ownerToken))[ALIAS]).toBe(1);
+
+    const acked = await ackAgent(ownerToken);
+    expect(acked.acked_inbox).toBe(1);
+    expect((await unreadFor(ownerToken))[ALIAS]).toBeUndefined();
+    expect(replyRow(taskId)?.acked).toBe(1);
+  });
+
+  test("a node that names alias='scheduler' explicitly is routed the same way", async () => {
+    await ackAgent(ownerToken);
+    const { taskId } = await fireSchedule(ownerToken, "owner-explicit-alias");
+    const reply = await nodeReply({ alias: "scheduler", in_reply_to: taskId, text: "explicit answer", status: "replied" });
+    expect(reply.ok).toBe(true);
+    expect(replyRow(taskId)?.session_name).toBe(ownerName);
+    expect((await unreadFor(ownerToken))[ALIAS]).toBe(1);
+    await ackAgent(ownerToken);
+  });
+
+  test("another member of the network does not get the owner's scheduled reply, and gets their own", async () => {
+    await ackAgent(ownerToken);
+    await ackAgent(memberToken);
+    const ownerRun = await fireSchedule(ownerToken, "owner-only");
+    expect((await nodeReply({ in_reply_to: ownerRun.taskId, text: "for owner", status: "replied" })).ok).toBe(true);
+    expect((await unreadFor(memberToken))[ALIAS]).toBeUndefined();
+    expect((await unreadFor(ownerToken))[ALIAS]).toBe(1);
+
+    const memberRun = await fireSchedule(memberToken, "member-only");
+    expect((await nodeReply({ in_reply_to: memberRun.taskId, text: "for member", status: "replied" })).ok).toBe(true);
+    expect(replyRow(memberRun.taskId)?.session_name).toBe(memberName);
+    expect((await unreadFor(memberToken))[ALIAS]).toBe(1);
+    expect((await unreadFor(ownerToken))[ALIAS]).toBe(1);
+    await ackAgent(ownerToken);
+    await ackAgent(memberToken);
+  });
+
+  test("a schedule with no creator falls back to 'scheduler'", async () => {
+    await ackAgent(ownerToken);
+    const { scheduleId, taskId } = await fireSchedule(ownerToken, "creatorless");
+    db.run("UPDATE scheduled_tasks SET created_by = NULL WHERE schedule_id = ?1", [scheduleId]);
+    expect((await nodeReply({ in_reply_to: taskId, text: "nobody's", status: "replied" })).ok).toBe(true);
+    expect(replyRow(taskId)?.session_name).toBe("scheduler");
+    expect((await unreadFor(ownerToken))[ALIAS]).toBeUndefined();
+  });
+
+  test("a creator whose username is also a node alias falls back to 'scheduler' (the collision guard)", async () => {
+    await ackAgent(ownerToken);
+    const { taskId } = await fireSchedule(ownerToken, "colliding-creator");
+    const clashNodeId = `n_clash_${stamp}`;
+    db.run(
+      "INSERT INTO nodes (node_id, node_name, alias, runtime, network_id) VALUES (?1, ?2, ?2, 'claude-code', ?3)",
+      [clashNodeId, ownerName, networkId],
+    );
+    try {
+      expect((await nodeReply({ in_reply_to: taskId, text: "not a todo", status: "replied" })).ok).toBe(true);
+      // 那个同名节点收不到这条(它不是节点的待办),用户名也拿不到(inbox 半边整体跳过)
+      expect(replyRow(taskId)?.session_name).toBe("scheduler");
+      expect(db.get<{ n: number }>(
+        "SELECT COUNT(*) AS n FROM inbox WHERE session_name = ?1 AND in_reply_to = ?2", ownerName, taskId,
+      )?.n).toBe(0);
+    } finally {
+      db.run("DELETE FROM nodes WHERE node_id = ?1", [clashNodeId]);
+    }
+  });
+});