fec-api-integration · diff
git:20260529.c76cc44 to git:20260611.9d7f5e4
55 added, 55 removed. Audit A to A.
---
name: fec-api-integration
- description: Use when designing, implementing, or reviewing frontend-to-backend API integration, typed API clients, REST/tRPC/OpenAPI client choices, auth refresh, API error mapping, upload flows, SSE/WebSocket/polling choices, CORS-facing frontend behavior, or cross-boundary loading/error states. Do not use for backend-only service architecture or TanStack Query cache policy alone; Chinese triggers include API 集成, 前后端联调, typed API client, 接口错误处理, SSE, WebSocket.
+ description: Use when designing, implementing, or reviewing frontend-to-backend API integration, typed API clients, REST/tRPC/OpenAPI client choices, auth refresh, API error mapping, upload flows, SSE/WebSocket/polling choices, CORS-facing frontend behavior, or cross-boundary loading/error states. Do not use for backend-only service architecture or TanStack Query cache policy alone; Chinese triggers include API integration, front-end and back-end joint debugging, typed API client, Interface error handling, SSE, WebSocket.
---
- # API 集成
+ # API integration
- 适用于前端与后端边界的类型、错误、鉴权、上传、实时通信和用户状态设计。需要具体代码模式时加载 [integration-patterns.md](references/integration-patterns.md)。
+ Suitable for front-end and back-end boundary types, errors, authentication, uploads, real-time communication and user status design. Load [integration-patterns.md](references/integration-patterns.md) when specific code patterns are required.
## Purpose
- 规范前端 API 集成边界，让请求、错误、鉴权和实时数据可维护。
+ Standardize front-end API integration boundaries to make requests, errors, authentication, and real-time data maintainable.
## Procedure
- 1. 明确接口所有权
- - 同团队 TypeScript 全栈可考虑 tRPC 或共享 schema。
- - 多语言或多消费者 API 优先 OpenAPI/GraphQL codegen。
- - 小型内部应用可用 typed fetch wrapper，但类型必须集中维护。
- - 不在组件里散落 `fetch`、URL、header、错误解析和 token 逻辑。
- - 公共接口需要明确版本、兼容窗口、废弃字段策略和调用方范围。
+ 1. Clarify interface ownership
+ - For TypeScript full stack in the same team, tRPC or shared schema can be considered.
+ - Multi-language or multi-consumer API preferred OpenAPI/GraphQL codegen.
+ - Typed fetch wrapper can be used for small internal applications, but types must be maintained centrally.
+ - Do not scatter `fetch`, URL, header, error parsing and token logic in components.
+ - Public interfaces need to specify versions, compatibility windows, obsolete field policies, and caller scope.
- 2. 建立客户端边界
- - 用一个 API client 处理 base URL、credentials、JSON 解析、超时、取消和统一错误。
- - 环境变量只读取公开前缀，私密 token 不进入客户端 bundle。
- - 组件只消费 domain 函数或 query/mutation hook，不直接拼接接口路径。
- - 204、空响应、非 JSON 错误和网络断开要有明确行为。
- - TypeScript contract 必须覆盖请求、响应、错误形状和分页/游标元数据。
+ 2. Establish client boundaries
+ - Handle base URL, credentials, JSON parsing, timeouts, cancellation and unified errors with an API client.
+ - The environment variable only reads the public prefix, and the private token does not enter the client bundle.
+ - The component only consumes domain functions or query/mutation hooks, and does not directly splice interface paths.
+ - 204, empty response, non-JSON error and network disconnection must have clear behavior.
+ - TypeScript contracts must cover request, response, error shapes, and pagination/cursor metadata.
- 3. 映射用户可理解的错误
- - 401：刷新失败后引导登录。
- - 403：说明权限不足，不重复重试。
- - 404：展示缺失状态或返回上级入口。
- - 409：提示冲突和下一步操作。
- - 422：映射字段级错误。
- - 429/5xx/网络错误：允许退避重试或展示稍后再试。
- - 未识别错误要落到统一 fallback，不把原始后端异常暴露给用户。
- - 所有错误都应归一到用户可恢复动作：重试、重新登录、修改输入、返回上级、联系支持或稍后再试。
- - 错误对象要保留面向日志的 trace id / request id，但 UI 不暴露内部堆栈、SQL、服务名或敏感字段。
+ 3. Map user-understandable errors
+ - 401: Boot login after failed refresh.
+ - 403: Indicates insufficient permissions, do not retry.
+ - 404: Display missing status or return to the upper level entrance.
+ - 409: Prompt for conflict and next step.
+ - 422: Mapping field level error.
+ - 429/5xx/Network Error: Allow backoff to retry or show try again later.
+ - Unrecognized errors should fall into a unified fallback, and the original backend exception should not be exposed to the user.
+ - All errors should be attributed to user-recoverable actions: retry, log in again, modify input, return to the previous level, contact support, or try again later.
+ - The error object should retain the log-oriented trace id / request id, but the UI should not expose the internal stack, SQL, service name or sensitive fields.
- 4. 管理接口演进
- - 兼容新增字段；删除或改名字段必须走迁移期、适配层或双写/双读策略。
- - 用 schema、类型生成物或 contract test 捕捉破坏性变更。
- - 对前后端协作项记录状态码、错误码、幂等性、重试语义和时区/金额/枚举规则。
+ 4. Management interface evolution
+ - Compatible with new fields; deleting or renaming fields must go through the migration period, adaptation layer or double-write/double-read strategy.
+ - Capture breaking changes using schema, type generators or contract tests.
+ - Record status codes, error codes, idempotence, retry semantics and time zone/amount/enumeration rules for front-end and back-end collaboration items.
- 5. 处理鉴权刷新
- - Access token 生命周期短，refresh 优先放在 httpOnly cookie 或服务端会话。
- - 401 后只允许单次刷新队列，避免多个请求同时刷新。
- - 刷新失败要清理本地身份状态并跳转登录。
- - 不把 bearer token 放在 URL、localStorage 或日志里。
+ 5. Handle authentication refresh
+ - Access token has a short life cycle, and refresh is prioritized in httpOnly cookies or server sessions.
+ - Only a single refresh of the queue is allowed after 401 to avoid multiple requests being refreshed at the same time.
+ - If the refresh fails, you need to clear the local identity status and jump to login.
+ - Do not put bearer token in URL, localStorage or logs.
- 6. 选择上传与实时方案
- - 小文件可用 multipart；大文件优先预签名直传或分片上传。
- - 只需要服务端推送时用 SSE；双向协作、聊天或多人状态用 WebSocket。
- - 简单状态刷新、低频任务进度可用 polling，并设置停止条件。
- - 上传和实时连接都需要取消、重连、超时和错误 UI。
+ 6. Select the upload and real-time plan
+ - Multipart is available for small files; large files are given priority for pre-signed direct upload or multipart upload.
+ - Only use SSE for server push; use WebSocket for two-way collaboration, chat or multi-person status.
+ - Simple status refresh, low-frequency task progress can be polled, and stop conditions can be set.
+ - Both uploads and live connections require cancellation, reconnection, timeout and error UI.
- 7. 验证集成质量
- - 检查 loading、empty、error、unauthorized、offline、retrying 状态。
- - 用浏览器网络面板确认 base URL、credentials、CORS 和状态码行为。
- - 用 mock 或测试服务覆盖 401、403、422、500、断网和取消请求。
- - 确认客户端 bundle 不包含私密环境变量、服务端密钥或内部地址。
- - 对关键 API client 行为补最小测试，证明超时、取消、错误映射和刷新队列可预期。
- - 验证错误边界与请求层协作：渲染异常进 Error Boundary，请求失败进可恢复 UI，不互相吞掉。
+ 7. Verify integration quality
+ - Check loading, empty, error, unauthorized, offline, retrying status.
+ - Confirm base URL, credentials, CORS, and status code behavior using the browser network panel.
+ - Use mock or test services to cover 401, 403, 422, 500, disconnection and cancellation requests.
+ - Verify that the client bundle does not contain private environment variables, server keys, or internal addresses.
+ - Add minimal testing for key API client behaviors to demonstrate that timeouts, cancellations, error mappings, and flush queues are expected.
+ - Verification error boundary cooperates with the request layer: rendering exceptions go to the Error Boundary, and request failures go to the recoverable UI, without swallowing each other.
## Constraints
- - 不在页面组件中直接管理 token refresh、错误格式解析或重试策略。
- - 不对 4xx 业务错误做盲目自动重试。
- - 不把后端异常栈、内部错误码或原始 SQL/服务名暴露给用户。
- - 不用 localStorage 存储高价值 token；若遗留系统无法避免，必须联动安全审查。
- - 不用 WebSocket 替代简单轮询，也不用轮询实现高频双向协作。
- - 不让上传经过 API 服务器转发大文件，除非有明确合规或扫描需求。
- - 不在公共接口里直接暴露临时字段、数据库字段名或后端内部错误结构。
+ - Do not manage token refresh, error format parsing, or retry strategies directly in page components.
+ - No blind automatic retries for 4xx business errors.
+ - Do not expose backend exception stacks, internal error codes or raw SQL/service names to users.
+ - Do not use localStorage to store high-value tokens; if legacy systems cannot be avoided, security review must be linked.
+ - No need to use WebSocket to replace simple polling, and no need to use polling to achieve high-frequency two-way collaboration.
+ - Do not allow uploads to be forwarded through the API server for large files unless there is an explicit compliance or scanning need.
+ - Do not directly expose temporary fields, database field names or backend internal error structures in the public interface.
## Expected Output
- 输出应包含 API client 边界、接口类型来源、错误映射、鉴权刷新策略、上传/实时方案和验证结果。完成后组件不散落请求细节，用户状态完整，失败场景可恢复，客户端不会泄露服务端密钥。
+ The output should include API client boundaries, interface type sources, error mappings, authentication refresh policies, upload/real-time schemes, and validation results. After completion, the component will not scatter request details, the user status will be intact, failure scenarios can be recovered, and the client will not leak the server key.