项目结构与平台接入

项目边界

前端项目只负责浏览器运行逻辑。业务密钥、数据库访问、第三方系统长期凭据和管理员操作必须放在后端或受控平台能力中。

建议至少区分：

• 页面与路由
• UI 组件
• API client
• 用户会话
• 环境配置
• 错误与日志上报

环境配置

普通网站的公开 API Base URL、站点名称和功能开关可以通过部署配置注入。环境托管平台应用的 API、授权地址和发布目录必须从平台提供的同源配置读取，不能编译为某个环境的固定值。任何会赋予服务访问权的值都不能编译到浏览器产物。

开发、预览和生产环境应使用各自稳定域名。涉及 OAuth 或平台应用 PKCE 时，回跳地址必须与登记入口同源，不能在生产入口上临时使用 localhost。

选择平台应用

只有满足以下任一条件时才创建平台应用：

• 需要显示在工作区应用入口。
• 需要 installId 表示工作区安装态。
• 需要平台用户完成网页授权。
• 需要调用平台应用声明范围内的能力。

满足这些条件时，直接创建类型为 PLATFORM_APPLICATION 的项目，并在同一项目维护 React/Vite 等前端源码和 baijimu.platform-application.json；不要再并行创建一个 React 静态项目作为第二份源码所有者。

这类前端应继续阅读 平台应用开发。 需要调用平台提供的工作区成员能力时，可以直接参考 查询工作区成员完整示例。

需要平台身份和能力的前端使用 ENVIRONMENT_HOSTED_APP，入口为 /index.html 等版本内路径，标准 SDK 从同源配置启动授权。历史 TRUSTED_EXTERNAL_APP 已被启动和授权链路拒绝；普通外链仍可展示，但不取得平台 token，外部系统使用自己的后台授权。