feat(frontend): add shared API client infrastructure

[huyanxius]

功能说明

• 增加不含业务语义的共享 HTTP 客户端，为后续各 XxxApis 实现提供统一请求入口。
• 对齐后端公共响应、分页、业务码与 Bearer Token 契约。
• 提供惰性的 Token Provider 注册边界，供后续登录模块注入读取函数。
• 保持 Projects、entities、pages、Mock 和 UI 不变。

实现方式

• 从 VITE_API_BASE_URL 读取服务地址，并在请求发出时读取当前 Token。
• 统一处理 JSON、查询参数、Response<T>、ListResponse<T> 与四类 API 错误。
• 通过 registerApiAccessTokenProvider 注册读取函数，公共层不保存、刷新或解析 Token。
• 将 HTTP 列表结果留在 shared/api 自身边界内，避免违反主线同层模块不互相依赖的规则。

测试

• npm run format:check：通过，46 个文件。
• npm run lint：通过。
• npm run typecheck：通过。
• npm run test：通过，4 个测试文件、17 项测试。
• npm run build：通过，89 个模块完成构建。
• git diff --check：通过。

范围边界

• 不包含 Project 或 Character 接口接入。
• 不修改页面、路由、UI、Mock 或 livedemo。
• 不负责登录、Token 保存、自动刷新或业务 DTO 映射。
• 不增加运行时依赖。

关联

• Closes feat: 增加前端通用 API 客户端基础设施 #116
• 后端契约：feat:backend dev #75

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
windup	Ready	Preview	Aug 5, 2026 3:48am

[fennoai]

The new client looks sound overall, but I found one concrete transport-classification bug.

[johnnyzhang-eng]

集成验证反馈：信封形状这条踩对了，另附一个争用点

把 main + 本 PR + #119 + #111 + #110 合成一个本地集成分支做了端到端验证（构建通过、单测 63/63、连真实后端跑通只读链路）。两条反馈：

1. requestList 对信封形状的假设是对的，建议写进注释钉住

后端把 total / page / page_size 放在信封顶层、与 data 同级，data 直接就是数组：

{ "code": 0, "message": "...", "data": [ ... ], "total": 5, "page": 1, "page_size": 12 }

本 PR 的三个 Number.isInteger 断言正好按这个形状写，实测全过。

之所以专门提一句：这里有个很容易写反的坑。在另一处代码里按 raw.data.map(...) 解析过（即假设 data 里还嵌一层分页对象），表现是页面报「角色列表读取失败」，看起来像后端挂了，实际是解析层的问题，排查方向会被带偏。修法就是按数组解析。

建议：把这个形状以注释形式钉在 requestList 上，并让 entities 层统一走它，不要各自 raw.data 解析——否则同一个坑会在每个 entity 里各踩一次。

2. frontend/src/entities/index.ts 是当前前端 PR 群唯一的争用点

试合验证时发现：#95 / #86 / #107 相互之间的冲突全部只冲这一个 barrel 文件，其余文件零冲突。也就是说合并成本几乎完全集中在这里。

建议在本 PR（基础设施层）里就把这个 barrel 的归并规则定下来（例如按 entity 分文件导出、index 只做再导出且按字母序），后续几个 PR 的合并成本会明显下降。

[huyanxius]

感谢集成验证，这两点都确认了。

1. requestList 当前按后端真实契约处理：data 是数组，total / page / page_size 位于响应信封顶层。已在 d888e9a 中补充注释，明确这一固定形状，避免后续实体层重复按 raw.data 解析。

2. frontend/src/entities/index.ts 确实是多个实体 PR 的共同冲突点。但它属于实体导出归并问题，不属于本 PR 的共享 API 传输层范围。当前 PR 不修改该文件，以避免与 feat(quick-start): add guided creation and animation review #95、feat(workflow-run): implement resumable generation orchestration #86、feat(workflow-controller): add resumable workflow coordination #107 产生额外冲突；后续按统一的 barrel 导出规则集中处理。