API

从 TanStack 路由、Worker 入口到鉴权、校验与错误处理，扩展自己的业务 API。

请求经过哪些文件

Flare 使用 TanStack Start 和原生 Worker binding，不使用 Next.js App Router 或 OpenNext。

apps/web/src/server.ts 接收请求，并处理 Paraglide、公开 robots/sitemap、队列和定时入口。
apps/web/src/server/api.ts 分发 /api/* 请求，执行输入校验、会话检查与业务调用。
apps/web/src/routes/$.tsx 负责公开页、认证页、工作台及后台的页面路径，受保护页面先执行加载前鉴权。
packages/* 提供认证、数据库、支付、存储、AI 和任务实现。

界面隐藏按钮只能改善体验。每个 API 仍必须检查自己的权限，不能依赖页面已经鉴权。

常用 API 合约

路径	方法与输入	权限 / 返回
`/api/health`	GET	健康和环境信息，不返回密钥
`/api/public/auth`	GET	可公开的 provider 与 Turnstile site key
`/api/auth/*`	Better Auth 自有接口	登录、会话、两步验证与 API Keys
`/api/files`	GET / POST multipart `file`	用户文件列表或上传；支持受限文件 API Key
`/api/chat`	POST `{prompt, requestId?}`	会话、积分；返回事件流
`/api/summary`	POST `{fileId}`	用户所有的文本文件；返回后台任务
`/api/checkout`	POST `{planId,gateway,requestId}`	会话、启用的支付方案；requestId 为 UUID
`/api/billing/manage`	POST `{orderId,action}`	自己的订单；action 为 portal 或 cancel
`/api/admin/*`	GET / POST	逐接口验证管理员权限

/api/summary 的输入只有 fileId，不要照搬聊天或支付的 requestId 字段。具体响应类型及错误处理以当前 api.ts 为准；扩展时同步调用方与契约检查。

发起同源 JSON 请求

const response = await fetch('/api/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    prompt: 'Summarize the release notes',
    requestId: crypto.randomUUID(),
  }),
});
if (!response.ok) {
  // Read the server error and show an actionable message.
  throw new Error('Chat request failed');
}
// Consume the text/event-stream progressively; do not parse it as JSON.

浏览器同源调用携带自己的会话。应用变更请求校验 Origin 与 APP_URL 相同；跨域代理、测试脚本或错误的生产 APP_URL 会被拒绝。API Keys 只开放当前文件接口，不能替代后台、聊天或结账的会话。

添加一个业务模块

先在 packages 中定义服务，再在 api.ts 添加方法与 schema 校验，最后连接组件。列表查询必须按当前 userId 过滤；按 ID 读写也必须验证归属。涉及积分或支付时复用账本、outbox 和现有幂等实现，不在页面上自行扣减。

对生产认证与修改操作保留持久化限流：认证默认每分钟 30 次，修改默认每分钟 120 次，主体在 D1 中以哈希保存。新增敏感接口应沿用相同控制点，而不是只加一个客户端防抖。

页面与语言路径

/app、/app/files、/app/ai、/app/billing、/app/usage、/app/settings、/app/onboarding 和 /app/admin 保持现有 URL。中文页面使用 /zh 前缀，API 始终使用 /api，不要添加 /zh/api。

验证与排障

未登录访问工作台应跳转登录；直接调用其 API 仍应拒绝。
使用用户 A 的会话请求用户 B 的文件或订单，不能返回其数据。
空 prompt、非法 UUID 和未知 planId 应产生明确失败，不创建任务或订单。
事件流验证逐段到达、取消与失败反馈，不能只测试最终字符串。
403：检查角色、资源归属及 Origin；不要删除校验来绕过配置错误。

修改后执行 pnpm check:contracts、pnpm type-check，再按测试指南运行相关 API 测试。