openapps-frontend

OpenApps 前端

OpenApps 应用的客户端部分：您的 Web 或移动应用调用的 SDK、终端用户如何认证，以及托管前端如何被服务。策略（Policy）仍然控制来自客户端的每一次写入，因此当客户端操作需要规则或不变量时，请将此技能与 openapps-backend 技能配对；托管和域名配置请使用 openapps-deploy。如需在系列技能中路由，请参阅根 openapps 技能。

参考路由器

仅读取与当前任务或术语匹配的行。

任务或术语	阅读文档
SDK 读取、写入、订阅、分页、queryAggregate、count、过滤器、排序、游标、setMany、set(path, null)	SDK 参考
构建 Web 前端	Web 应用指南
本地开发服务器（npm run dev、Vite、localhost）、登录弹窗失败、redirect_uri origin is not a registered origin、本地开发期间的 CORS	本地主机开发
刷新定时器、setInterval、轮询、“保持最新”、倒计时、过时 UI	SDK 参考
为 React Native / 移动端构建	React Native 指南
应用用户邮箱 OTP、OAuth、openBoundedWidget、统一登录小部件、默认 Turnkey 认证	应用认证
自带钱包登录；walletLogin、authMethod:'phantom'、supportsWalletSignIn、不支持的 wallet / Wallet Standard	钱包登录
刷新后钱包登录丢失、重载后 getCurrentUser() 返回 null、bounded_last_auth_method、会话恢复方法	钱包登录 - “钱包会话在重载后仍然存在”
访客、匿名用户、邀请链接、账户升级	匿名账户
关联用户的 X 账户、connect('x')、completeConnection、getConnections、已验证的 X 句柄、__connections__	关联账户
托管前端和应用程序 URL	前端托管
CLI 开发者登录或 openapps login	开发者账户
嵌入式钱包、auth.wallets、邮箱/社交登录后的 @user.address	嵌入式钱包
onramp()、通过信用卡购买 SOL/USDC、Coinbase Onramp、钱包充值	Onramp

经验法则

• 每次客户端写入都受策略控制；写入时收到 403 是规则拒绝，而非客户端错误。请参阅 openapps-backend 技能以了解规则。
• 拒绝的读取操作返回空的 200 响应，绝不会返回 403。
• 默认实时，永远不要轮询。 每个集合都是基于推送的，因此使用 setInterval 重新读取路径是一个 bug，而不是调整选择——请使用 useQuery（React）或 subscribe。倒计时基于本地时钟状态，而非重新读取。对于少数非实时的表面（runQuery、functions.invoke、第三方），请有意识地轮询：在隐藏标签页时暂停，将定时器范围限定在需要它的状态，进行退避，并设置上限。请参阅 sdk-reference.md。
• 使用 runQueryMany 批量读取计算值列表；切勿在列表上映射 runQuery。请参阅 sdk-reference.md。
• 将提供商 API 密钥放在 OpenApps 的秘密（后端）中，切勿放在前端代码中。
• 如果 npm audit 报告通过 @solana/web3.js -> jayson 引入 uuid 安全公告 GHSA-w5hq-g745-h8pq，请使用作用域化的 覆盖方案。该方案专门处理该公告；在已安装的 lockfile 上运行 npm audit --omit=dev，并单独调查发现的任何其他问题。
• 对于大多数应用，请保留认证默认设置。 不要添加 authMode 或 auth.wallets 来“启用钱包”：默认的 Turnkey 邮箱/社交登录已经带有 @user.address。仅当需要 EXTERNAL 密钥对会话（自带钱包登录、服务器 SDK 密钥对客户端、CLI 密钥对数据通道）时才部署 "auth": { "wallets": true }。完整规则及选择退出方式：embedded-wallets.md。
• @user.id（账户 ID）是身份/所有权；@user.address 是钱包。 在 @user.id（始终存在）上进行密钥所有权、成员身份和认证守护。仅为了钱包/链上语义才使用 @user.address——切勿将其作为身份密钥。
• 在手机上钱包登录需要 Solana Mobile 适配器。 手机浏览器永远不会注入钱包应用；保持安装 @solana-mobile/wallet-standard-mobile（在 .npmrc 中设置 legacy-peer-deps=true），并且切勿在打开小部件之前预检查 window.solana。请参阅 Solana Mobile。