bounded-frontend

Bounded 前端

Bounded 应用的客户端部分：Web 或移动应用调用的 SDK、终端用户的身份验证方式，以及托管前端的提供方式。客户端的每次写入仍受策略约束，因此，当客户端操作需要规则或不变量时，请配合使用 bounded-backend 技能；关于托管和域名，请使用 bounded-deploy。如需在整个技能系列中进行路由，请参阅根目录下的 bounded 技能。

参考路由器

只阅读与当前任务或术语对应的行。

任务或术语	阅读
SDK 读取、写入、订阅、分页、queryAggregate、count、筛选、排序、游标、setMany、set(path, null)	SDK 参考
构建 Web 前端	Web 应用指南
本地开发服务器（npm run dev、Vite、localhost）、登录弹窗失败、redirect_uri origin is not a registered origin、本地开发期间的 CORS	在 localhost 上开发
刷新计时器、setInterval、轮询、“保持最新”、倒计时、过时的 UI	SDK 参考
构建 React Native / 移动应用	React Native 指南
应用用户的电子邮件 OTP、OAuth、openBoundedWidget、统一登录组件、默认 Turnkey 身份验证	应用身份验证
使用自有钱包登录；walletLogin、authMethod:'phantom'、supportsWalletSignIn、不支持的钱包 / Wallet Standard	钱包登录
钱包登录状态在刷新后丢失、重新加载后 getCurrentUser() 为 null、bounded_last_auth_method、会话恢复方式	钱包登录 -“钱包会话在重新加载后仍会保留”
访客、匿名用户、邀请链接、账户升级	匿名账户
关联用户的 X 账户、connect('x')、completeConnection、getConnections、已验证的 X 账号名、__connections__	关联账户
托管前端和应用 URL	前端托管
隐藏或限制托管组件、/__bounded/widget.js、openApps.widget.visibility	隐藏组件
运行自身服务器的 Next.js 应用（vinext）、其密钥和限制	服务器应用
CLI 开发者登录或 bounded login	开发者账户
嵌入式钱包、auth.wallets、通过电子邮件 / 社交登录后使用 @user.address	嵌入式钱包
onramp()、用银行卡购买 SOL/USDC、Coinbase Onramp、钱包充值	入金服务

经验法则

• 每次客户端写入都受策略管控；写入时出现 403 表示规则拒绝，而不是客户端错误。规则请参阅 bounded-backend 技能。
• 被拒绝的读取会返回空的 200 响应，绝不会返回 403。
• 默认实时；绝不轮询。 所有集合都基于推送，因此使用 setInterval 重新读取路径是错误做法，不是调优选择——请使用 useQuery（React）或 subscribe。倒计时根据本地时钟状态更新，而不是重新读取。少数非实时的界面（runQuery、functions.invoke、第三方服务）需要轮询时，请有意为之：标签页隐藏时暂停，将计时器限定在需要它的状态范围内，逐步延长间隔，并设置上限。请参阅 sdk-reference.md。
• 对计算值列表进行批量读取时，请使用 runQueryMany；绝不要对列表映射调用 runQuery。请参阅 sdk-reference.md。
• 将提供商 API 密钥放入 Bounded secrets（后端），绝不要放在前端代码中。
• 如果 npm audit 报告 uuid 存在 GHSA-w5hq-g745-h8pq 安全公告，且依赖路径为 @solana/web3.js -> jayson，请使用限定范围的覆盖方案。 该方案可解决此安全公告；请对已安装的 lockfile 运行 npm audit --omit=dev，并单独调查其他剩余问题。
• 大多数应用请保留默认身份验证设置。 不要添加 authMode 或 auth.wallets 来“启用钱包”：默认的 Turnkey 电子邮件／社交登录已包含 @user.address。仅在使用 EXTERNAL 密钥对会话时部署 "auth": { "wallets": true }（自带钱包登录、server-SDK 密钥对客户端、CLI 密钥对数据通道）。完整规则和退出选项请参阅：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。