feat: prefer supabase jwt in taro api client

docs/refactor/taro-frontend-integration.md

@@ -53,7 +53,23 @@ F:\project\参考\旧题库项目\src
 - 私有 PDF、资料、视频、对象存储签名。
 - 租户后台、平台后台、内容导入、CRM、销售/代理、数据看板。
 
-前端应封装一个统一 API client，所有页面禁止直接散写 `Taro.request`。
+前端应封装一个统一 API client，所有页面禁止直接散写 `Taro.request`。当前统一入口是：
+
+```text
+apps/taro/src/services/api.ts
+apps/taro/src/services/api-auth.ts
+```
+
+`apiRequest` 的默认鉴权模式是 `authMode='auto'`：
+
+| authMode | 行为 | 适用场景 |
+| --- | --- | --- |
+| `auto` | H5 先读取 Supabase Auth access token；没有 Supabase token 时才兜底迁移期 `tk_` session | 绝大多数登录后业务接口 |
+| `supabase` | 只发送 Supabase access token，没有 token 也不回退 `tk_` | 云端 JWT/RLS 回归、需要提前发现迁移 token 依赖的页面 |
+| `legacy` | 只发送迁移期 `tk_` session | 本地迁移、旧数据导入演练、临时内网联调 |
+| `none` | 不发送 Authorization | 租户解析、短信发送/验证、公开目录、公开套餐等接口 |
+
+公共接口必须显式传 `authMode: 'none'`，例如 `tenant/resolve`、`catalog/regions`、`catalog/content-entries`、`catalog/svip-plans`、`auth/sms/send`。平台全局接口或租户解析如不应带租户上下文，必须显式传 `tenantId: null`；不能依赖当前本地缓存的租户。
 
 本地迁移期仍可兼容旧请求头，但新的 Taro 请求封装必须按下面目标实现：
 
@@ -71,20 +87,14 @@ x-tenant-id: <tenantId>   # 作为租户上下文，不能作为身份依据
 
 前端不应再传 `x-user-id`、query/body `userId` 来表示当前用户。后端已经实现 Supabase JWT 和迁移 session 优先解析：如果 Authorization 存在，用户态接口以 token 映射出的业务用户为准；如果请求里伪造了不同的 `userId` 会返回 `AUTH_USER_MISMATCH`，伪造不同租户会返回 `AUTH_TENANT_MISMATCH` 或 `AUTH_SESSION_INVALID`。
 
-H5 使用 Supabase Auth 时，推荐请求流程：
+H5 使用 Supabase Auth 时，不要在页面里手写 `Authorization`，推荐请求流程是由统一 client 完成：
 
 ```ts
-const { data } = await supabase.auth.getSession();
-const accessToken = data.session?.access_token;
-
-await api.request('/api/profile/me', {
-  headers: {
-    Authorization: `Bearer ${accessToken}`,
-    'x-tenant-id': tenantStore.tenantId,
-  },
-});
+await apiRequest('/api/profile/me');
 ```
 
+`apps/taro/src/services/api-auth.ts` 会读取 Supabase session 并生成 `Authorization: Bearer <supabase_access_token>`。页面层禁止通过 `headers.Authorization` 或 `headers['x-tenant-id']` 覆盖身份和租户上下文；如确实要切换租户上下文，必须使用 `tenantId` 显式参数。该规则由 `scripts/taro-api-auth-mode-test.js` 纳入 `npm run test:readiness`。
+
 后端会通过 `auth.users.id -> platform_users.auth_user_id -> tenant_memberships` 映射用户身份。`x-tenant-id` 只能帮助确定当前租户上下文，不能让用户访问自己没有 membership 的租户。
 
 生产或云端测试建议设置：