# 飞书后台实际配置包 v1

## 1. 文档目的
本文件用于把“飞书前门已具备 go-live readiness”进一步转化为飞书管理员可执行的后台配置包。
目标不是继续停留在系统侧 ready，而是明确：
- 飞书后台要配什么
- 哪些字段必须填写
- 哪些 URL 必须替换
- 哪些检查项必须通过
- 哪些白名单用户应先放行

一句话判断：
这份文档的意义，是把“产品 ready”翻译成“管理员可执行”。

## 2. 当前阶段判断
当前系统已经具备：
- Runtime Portal
- Feishu Frontdoor Homepage
- current_release
- release_history
- latest_release_bundle
- feishu_frontdoor_runtime_v1.yaml
- feishu_frontdoor_app_template_v1.yaml
- feishu_frontdoor_readiness.json 且 go_live_ready = true

因此，现在距离“真正能在飞书里打开页面”只差最后一层：
- 真实地址替换
- 飞书后台应用配置
- 信任域名配置
- 白名单放行
- 小范围验证

## 3. 配置目标
第一阶段飞书后台配置的目标不是做深度集成，而是做到：

1. 在飞书工作台能看到应用
2. 点开后能进入首页
3. 桌面端首页能正常访问
4. 移动端首页能正常访问
5. 首页能展示当前正式版本与推荐下载
6. 白名单用户能完成小范围试点验证

## 4. 推荐配置形态
建议采用：
- 企业自建应用
- H5 / Web 页
- Runtime Portal 或 Feishu Frontdoor Homepage 作为首页

更推荐的第一阶段方案是：
- 飞书前门默认首页：`feishu_frontdoor_homepage.html`
- 轻首页内再点击进入完整 `Runtime Portal`

原因：
- 更轻
- 更适合飞书 H5 首屏
- 更适合移动端
- 更适合试点

## 5. 飞书后台需要实际配置的内容

### 5.1 应用基础信息
需要配置：
- 应用名称
- 应用描述
- 应用图标
- 应用分类
- 负责人
- 可见范围

建议值：
- 应用名称：Talent Review OS
- 应用描述：人才盘点与组织决策平台飞书前门

### 5.2 首页配置
需要配置：
- 桌面端首页
- 移动端首页
- 默认首页 URL
- 是否使用统一首页

建议：
- 桌面端首页：Feishu Frontdoor Homepage
- 移动端首页：Feishu Frontdoor Homepage
- 第一阶段 desktop / mobile 可先使用同一 URL

### 5.3 菜单与入口
建议配置以下入口：
1. 首页：Feishu Frontdoor Homepage
2. Runtime Portal
3. 最新交付包
4. 历史发布版本
5. 趋势分析（后续可选）

### 5.4 trusted domain
需要配置：
- trusted domain
- 文件下载域名
- 前端资源域名

当前建议最少包含：
- 主产品域名
- 下载域名

### 5.5 redirect URL
当前阶段即使暂不启用 SSO，也建议提前预留：
- feishu callback redirect URL
- sso callback redirect URL

原因：
避免后续再反复改应用配置。

## 6. 替换项
当前配置文件中的若干 URL 仍是占位地址，正式 go-live 前必须替换。

### 6.1 当前占位地址示例
- https://talent-review.example.com/runtime-portal
- https://downloads.talent-review.example.com
- https://talent-review.example.com/feishu/callback
- https://talent-review.example.com/feishu/sso/callback

### 6.2 正式替换时必须明确
- 最终产品访问域名
- 是否使用同一域名承载 Portal 与前门首页
- 下载资源是否使用独立域名
- callback 是否挂在主域名下

一句话判断：
不替换真实地址，飞书后台就算配完也无法真正进入试点。

## 7. 推荐首页选择
### 7.1 Feishu Frontdoor Homepage
建议作为飞书首页，原因：
- 首屏轻量
- 信息密度更适合飞书入口
- 能直达当前正式版本与推荐下载
- 适合试点验证

### 7.2 Runtime Portal
建议作为二级入口，原因：
- 更完整
- 更适合深入使用
- 更适合治理和版本回看

## 8. 白名单建议
第一阶段建议：
- 先按白名单放行
- 只开放给核心试点用户

建议白名单角色：
- system_admin
- hrbp
- business_manager
- reviewer

建议白名单用户：
- 产品负责人
- 系统维护人
- HRBP 试点用户
- 一到两位核心管理者
- 一到两位真实使用者

## 9. 飞书后台配置步骤建议
建议按以下顺序操作：

1. 创建企业自建应用
2. 填写应用名称 / 图标 / 描述
3. 配置桌面端首页
4. 配置移动端首页
5. 配置 trusted domain
6. 配置 redirect URL
7. 配置可见范围 / 白名单
8. 发布到小范围试点用户
9. 用桌面端验证
10. 用移动端验证

## 10. go-live 前检查项
### 10.1 应用配置检查
- 自建应用创建完成
- 桌面端首页配置完成
- 移动端首页配置完成
- trusted domain 配置完成
- redirect URL 配置完成

### 10.2 页面检查
- Feishu Frontdoor Homepage 可打开
- Runtime Portal 可打开
- 首页无明显白屏 / 崩溃
- current_release 展示正确
- 推荐下载可点击
- latest_release_bundle 可点击

### 10.3 白名单检查
- 白名单用户可见应用
- 白名单用户能打开首页
- 非白名单用户不应默认可见（若策略如此）

### 10.4 产品检查
- go_live_ready = true
- failed_check_count = 0
- release_history 已同步
- 当前版本与历史版本展示一致

## 11. 建议的试点验证方式
建议至少验证以下四条路径：

### 路径 A：从飞书进入首页
- 打开应用
- 进入 Feishu Frontdoor Homepage
- 首页加载正常

### 路径 B：进入完整 Portal
- 从轻首页进入 Runtime Portal
- 查看当前正式版本
- 查看历史版本

### 路径 C：下载正式交付物
- 下载最新交付包
- 下载 PPT v2
- 下载团队汇总 PDF
- 下载多期对比 PDF

### 路径 D：理解版本信息
- 查看 current_release
- 查看 release_note
- 查看 release_history

## 12. 成功标准
第一阶段飞书后台配置成功，不等于“页面能打开”这么简单。
建议成功标准定义为：

1. 飞书工作台中能稳定看到应用
2. 首页能稳定打开
3. 推荐下载和 latest_release_bundle 有使用价值
4. 白名单用户愿意继续通过飞书进入
5. 至少形成一轮真实试点反馈

## 13. 建议的后台配置模板字段
建议管理员最终至少确认以下字段：

- app_name
- app_description
- owner
- desktop_homepage_url
- mobile_homepage_url
- trusted_domains
- redirect_urls
- visibility_scope
- whitelist_users
- whitelist_roles
- go_live_date
- rollback_entry_url

## 14. 风险与注意事项
### 14.1 主要风险
- URL 未替换为真实地址
- trusted domain 漏配
- 首页信息密度过高
- 移动端展示不佳
- 白名单放错或范围过大

### 14.2 注意事项
- 先小范围 go-live，再扩范围
- 先入口与下载通，再考虑深集成
- 不要一开始就追求复杂审批或消息中心
- 先把首页体验和版本体验跑顺

## 15. 一句话总结
飞书后台实际配置包的意义，不是为了多一份清单，而是让 Talent Review OS 真正从“系统侧已 ready”推进到“飞书管理员可以直接落地配置和试点上线”的阶段。
