# 项目结构与平台接入

设计前端环境配置、API 边界，并选择普通网站或平台应用入口。

## 项目边界

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

建议至少区分：

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

## 环境配置

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

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

## 选择平台应用

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

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

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

这类前端应继续阅读 [平台应用开发](/development/bundle-development/platform-application-development/)。
需要调用平台提供的工作区成员能力时，可以直接参考
[查询工作区成员完整示例](/development/bundle-development/platform-application-development/workspace-member-list-example/)。

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

> **环境托管应用无需单独发布静态站点**
>
> 提交项目主线、发布平台应用版本并安装或升级 Bundle 后，平台自动完成托管部署、生成入口和提供同源配置。
> 开发者不需要创建另一份静态站点、手工上传产物或配置网关与授权地址。完整步骤见
> [发布并纳入 Bundle](/development/bundle-development/platform-application-development/create-and-install/)。