用途
auth-setup 用于在 Convex 项目中搭建身份认证体系，覆盖用户管理、身份映射与访问控制模式。当需要首次配置认证、实现用户管理（users 表、身份映射）、创建认证辅助函数，或接入 OAuth 提供方（如 WorkOS、Auth0 等）时，可使用该技能。
架构概览
Convex 认证分为两部分：
- 客户端认证：使用某个提供方（WorkOS、Auth0、自定义 JWT）。
- 后端身份：将认证提供方的身份映射到自己的 users 表。
Schema 设置
在 convex/schema.ts 中定义 users 表，字段包括 tokenIdentifier（每个认证提供方唯一）、name、email、pictureUrl（可选）、role（user 或 admin）、createdAt、updatedAt（可选），并建立 by_token 与 by_email 索引。
核心辅助函数
在 convex/lib/auth.ts 中提供：
- getCurrentUser：读取当前身份，未认证时抛出 "Not authenticated"，查不到用户时抛出 "User not found"。
- getCurrentUserOrNull：未认证时返回 null。
- requireAdmin：在 getCurrentUser 基础上校验 role 是否为 admin，否则抛出 "Admin access required"。
用户创建与更新
在 convex/users.ts 中提供 storeUser mutation：读取身份，若用户已存在则更新 updatedAt 并返回其 _id；否则插入新用户，tokenIdentifier 取自身份，name 缺省为 "Anonymous"，email 缺省为空字符串，role 为 "user"，并记录 createdAt。
访问控制模式
- 所有者访问：如 updateProfile，先取当前用户再更新其自身记录。
- 资源归属：如 deleteTask，读取资源后校验 task.userId 是否等于当前用户 _id，否则抛出 "You can only delete your own tasks"。
- 团队访问：schema 中增加 teams 与 teamMembers 表（含 by_team、by_user、by_team_and_user 索引），通过 requireTeamAccess 校验成员关系，无权限时抛出 "You don't have access to this team"。
- 公开/私有/混合查询：公开查询不做认证检查；私有查询要求认证；混合查询用 getCurrentUserOrNull 区分登录与匿名用户返回不同数据。
客户端设置（以 WorkOS 为例）
WorkOS AuthKit 提供完整认证方案，配置较少。
React/Vite：安装 @workos-inc/authkit-react，创建 ConvexReactClient，调用 convex.setAuth(useAuth)，并用 AuthKitProvider 与 ConvexProvider 包裹应用。
Next.js：安装 @workos-inc/authkit-nextjs，在 app/layout.tsx 中使用 AuthKitProvider 与 ConvexClientProvider；在 ConvexClientProvider 中通过 useAuth 的 getToken 调用 convex.setAuth。
环境变量：React/Vite 使用 VITE_CONVEX_URL、VITE_WORKOS_CLIENT_ID；Next.js 使用 NEXT_PUBLIC_CONVEX_URL、NEXT_PUBLIC_WORKOS_CLIENT_ID、WORKOS_API_KEY、WORKOS_COOKIE_PASSWORD（随机 32 位字符串）。
登录后调用 storeUser：在应用中通过 useMutation(api.users.storeUser)，在 user 存在时于 useEffect 中调用。
其他认证提供方
如需使用其他提供方，可参考 Convex 认证文档中的自定义 JWT、Auth0 及其他 OAuth 提供方。
检查清单
- users 表含 tokenIdentifier 索引
- 提供 getCurrentUser 辅助函数
- 提供首次登录用的 storeUser mutation
- 所有受保护函数中做认证检查
- 资源访问做授权检查
- 错误信息清晰（"Not authenticated"、"Unauthorized"）
- 配置客户端认证提供方（WorkOS、Auth0 等）
限制
资料未提供该技能的收费、价格、平台支持范围或效果数据，暂未提供。