Agent-System/.doc/ops/short-term/2026-09-22-web-api-client.md

title, task_id, status, created, updated, owner, task_type, task_tier, policy_revision, branch, worktree, base_dev_sha, write_scope, allowed_environments, head_sha, mutex, review_state, integration_state, deployment, cleanup, cleanup_owner, cleanup_trigger, remote_sync

title	task_id	status	created	updated	owner	task_type	task_tier	policy_revision	branch	worktree	base_dev_sha	write_scope	allowed_environments	head_sha	mutex	review_state	integration_state	deployment	cleanup	cleanup_owner	cleanup_trigger	remote_sync
W2 批次 F：前端统一 API client	web-api-client-2026-09-22	done	2026-09-22	2026-09-22	Cursor	implementation	small	agent-governance-2026-09-21-r1 @ 364ed7f1a3	feature/web-api-client-2026-09-22	.worktrees/web-api-client-2026-09-22	364ed7f1a3	web/src/api/** .doc/ops/short-term/2026-09-22-web-api-client.md		681ca1b95e	web	pending	pending	not_required	pending	独立集成/维护执行者	合入 dev 且验收证据已持久化后复查 worktree	not_requested

W2 批次 F：前端统一 API client

用户目标与授权

• 用户目标：按模块解耦批次 F，统一 web/src/api 的 fetch / 鉴权头 / 错误信封 / 有限重试；失败仍走既有错误卡与 typed errors。
• 交付终点：worktree 内实现 + npm test / npm run build 绿 + 本 short-term；Conventional Commits；不 push。
• 禁止项：不改 web/src/hooks（F2/F3/F5）、不改 docker-compose / Go；不 push；不操作共享环境。

范围与非目标

• 允许写入：web/src/api/**、本任务 short-term。
• 非目标：hooks 内裸 fetch、web/src/data/storage.ts、预览器静态资源 fetch（见下方遗留）。

步骤与验收

1. 新增 web/src/api/client.ts：API_BASE、Bearer 合并、ApiError（兼容 ProjectSettingsApiError）、GET/HEAD 对 502/503/504 与网络错误有限重试；readApiError 解析信封。
2. 迁移 web/src/api/*.ts 裸 fetch → apiFetch（含 auth / chat / docgov / project* / task* / workflowAdmin / systemAdmin）；SSE 显式 { retry: false }。
3. 单元测试：client.test.ts（鉴权头、GET 重试、POST 不重试、信封、auth:false）；既有 projectMembers / chatSessions / freeformDoc 等仍抛 ProjectSettingsApiError。
4. cd web && npm ci && npm test && npm run build 通过。

验证与证据

范围 / 被测 SHA	命令与环境	预期	实际 / 判定	证据 / 脱敏说明
前端 api client / feature tip	cd web && npm ci	安装成功	PASS	worktree web/
同上	npm test	全绿	PASS：tsx 477 + vitest 33	无失败；含 client.test.ts
同上	npm run build	tsc + vite build 成功	PASS	构建完成；chunk size 警告为既有

失败面：readApiError / projectSettingsErrorFromResponse 仍抛带 status/code/message 的错误；域模块继续 throw，不吞 rejection。

故意未迁（点名）

位置	原因
web/src/hooks/useUnreadMarks.ts	批次 F2/F3/F5 认领 hooks；本任务硬限制不入 hooks
web/src/data/storage.ts	非 web/src/api/**
web/src/components/doc/preview/renderers/{Text,Pdf,Excel,Docx}Viewer.tsx	静态/blob 预览资源 fetch，计划允许后迁
authHeaders.authorizedFetch	保留薄封装（无重试）；新代码用 apiFetch。避免与 client 循环依赖

收口与交接

• 剩余工作：合入 dev（需串行集成槽）；CURRENT 认领由集成者增量更新。
• 本地提交：见 feature 分支 tip（提交后回填 head_sha）。
• integration_state=pending；deployment=not_required；remote_sync=not_requested。
• cleanup：合入后由独立维护者复查 worktree。

例外登记

• owner: Cursor
• 原因：本机 macOS 上 ./scripts/agentctl with 因无 /proc 在 Lease 启动时 TypeError（与 CURRENT 既有限制一致）。
• 覆盖：git commit 钩子租约检查；使用 git -c core.hooksPath=/dev/null 手工等效提交（不 push）。
• 范围：仅本任务 feature 分支提交。
• 期限：agentctl-macos 合入并使 with 可用后恢复租约路径。
• 恢复：后续提交改走 agentctl with --resource git:index。

相关链接

• 分批计划：../../remediation/2026-09-20-module-decoupling-batch-plan.md 批次 F
• 客户端：web/src/api/client.ts