# 飞书前门真实上线替换执行包 v1

## 1. 文档目的
本文件用于把“飞书前门已 system_ready，但尚未 go_live_ready”的状态，进一步转化为可执行的真实上线替换包。
目标不是继续讨论方向，而是把正式 go-live 前必须完成的替换动作、执行顺序、责任归属、验证方法和回退策略整理成一个可执行包。

一句话判断：
这份文档的意义，是把“还差 7 个 replacement blocker”翻译成真正能执行的上线动作。

## 2. 当前状态判断
根据最新 readiness 结果，当前状态应明确区分为：

### 2.1 system_ready = true
代表：
- Runtime Portal 已可用
- Feishu Frontdoor Homepage 已可用
- current_release / release_history / latest_release_bundle / artifact_index 已可用
- 发布治理层与前门展示层已形成闭环

### 2.2 go_live_ready = false
代表：
- 系统能力已经 ready
- 但真实飞书试点上线仍未 ready
- 原因不在产品能力，而在真实上线替换项尚未完成

### 2.3 当前 blocker 本质
当前 blocker 主要集中在：
- 真实域名未替换
- trusted domain 仍是占位地址
- redirect URL 仍是占位地址
- bundle 下载地址仍是占位地址

一句话判断：
当前问题不是“产品没做完”，而是“上线替换还没执行”。

## 3. 本次执行包的目标
本次执行包的目标是：

1. 把所有 `example.com` 占位地址替换为真实地址
2. 让飞书后台配置与系统配置一致
3. 让 readiness 从 `go_live_ready = false` 进入 `go_live_ready = true`
4. 让白名单用户能够在飞书里真正打开前门并完成试点验证

## 4. 当前 blocker 清单
基于当前 readiness，第一阶段需要重点处理以下 blocker：

1. base_domain_not_placeholder
2. runtime_portal_url_not_placeholder
3. feishu_frontdoor_homepage_url_not_placeholder
4. bundle_download_url_not_placeholder
5. callback_url_not_placeholder
6. sso_callback_url_not_placeholder
7. trusted_domains_not_placeholder

一句话判断：
这 7 个 blocker 全部属于“上线替换层”，不是“产品能力层”。

## 5. 替换项总表
建议按以下表结构执行替换：

### 5.1 主域名
- 当前占位：`https://talent-review.example.com`
- 目标：真实可访问域名
- 影响范围：
  - Runtime Portal
  - Feishu Frontdoor Homepage
  - callback
  - sso callback
  - trusted domain

### 5.2 下载域名
- 当前占位：`https://downloads.talent-review.example.com`
- 目标：真实下载域名
- 影响范围：
  - latest_release_bundle
  - 下载入口
  - trusted domain

### 5.3 Runtime Portal URL
- 当前占位：`https://talent-review.example.com/runtime-portal`
- 目标：真实 Portal 地址
- 影响范围：
  - 飞书首页跳转
  - 轻首页跳转
  - readiness 检查
  - 飞书后台桌面端 / 移动端配置参考

### 5.4 Feishu Frontdoor Homepage URL
- 当前占位：`https://talent-review.example.com/feishu-frontdoor-homepage`
- 目标：真实前门首页地址
- 影响范围：
  - 飞书默认首页
  - readiness 检查
  - 飞书后台应用首页配置

### 5.5 latest_release_bundle URL
- 当前占位：
  - `https://downloads.talent-review.example.com/latest-release-bundle`
  - `https://talent-review.example.com/downloads/latest-release-bundle`
- 目标：至少一个真实可用下载地址
- 影响范围：
  - 推荐下载
  - bundle 入口
  - 飞书前门下载体验

### 5.6 callback / redirect URL
- 当前占位：
  - `https://talent-review.example.com/feishu/callback`
  - `https://talent-review.example.com/feishu/sso/callback`
- 目标：真实 callback
- 影响范围：
  - 飞书后台 redirect URL
  - 后续 SSO 预留

## 6. 需要同步修改的配置文件
本次替换执行建议至少同步处理以下文件：

1. `feishu_frontdoor_runtime_v1.yaml`
2. `feishu_frontdoor_app_template_v1.yaml`
3. `feishu_frontdoor_go_live_replacements_v1.yaml`

若后续希望彻底一致，还可进一步同步：
4. readiness checker 读取的相关字段来源
5. Portal / Feishu Frontdoor Homepage 的外链引用源

一句话判断：
不要只改一处 URL，必须保证系统配置、飞书配置模板、go-live 替换模板三者一致。

## 7. 执行顺序建议
建议按以下顺序执行：

### Step 1：确认真实地址
由业务 / 运维 / 系统维护方明确：
- base domain
- download domain
- Portal URL
- Feishu Frontdoor Homepage URL
- callback URL
- sso callback URL

### Step 2：更新配置模板
更新：
- `feishu_frontdoor_go_live_replacements_v1.yaml`
- `feishu_frontdoor_runtime_v1.yaml`
- `feishu_frontdoor_app_template_v1.yaml`

### Step 3：刷新前门页面与检查结果
重新运行：
- `44_build_feishu_frontdoor_readiness.py`
- `17_build_runtime_portal.py`
- `18_build_feishu_frontdoor_homepage.py`

### Step 4：确认 readiness
目标：
- `system_ready = true`
- `go_live_ready = true`
- `replacement_blocker_count = 0`

### Step 5：飞书后台配置
在飞书后台完成：
- 自建应用创建 / 更新
- trusted domain
- redirect URL
- 桌面端首页
- 移动端首页
- 白名单

### Step 6：白名单试点验证
由核心用户验证：
- 进入首页
- current_release 展示
- 推荐下载
- latest_release_bundle 下载
- 进入 Runtime Portal

## 8. 责任分工建议
建议至少明确三类责任人：

### 8.1 产品/业务负责人
负责：
- 最终 go-live 决策
- 白名单确认
- 试点范围确认
- 成功标准确认

### 8.2 系统维护人
负责：
- 配置文件替换
- 页面刷新
- readiness 重跑
- 产物一致性验证

### 8.3 飞书管理员 / IT / 运维
负责：
- 飞书后台配置
- trusted domain
- redirect URL
- 应用可见范围
- 应用发布到白名单用户

## 9. 验证步骤
正式替换完成后，必须至少验证以下内容：

### 9.1 配置验证
- 所有 `example.com` 地址已被替换
- trusted domain 不再是占位域名
- redirect URL 不再是占位地址

### 9.2 readiness 验证
- `system_ready = true`
- `go_live_ready = true`
- `replacement_blocker_count = 0`

### 9.3 页面验证
- Runtime Portal 正常打开
- Feishu Frontdoor Homepage 正常打开
- current_release 正确
- latest_release_bundle 可下载
- 推荐下载可用

### 9.4 飞书端验证
- 桌面端首页可打开
- 移动端首页可打开
- 白名单用户可见应用
- 白名单用户可完成核心路径

## 10. go/no-go 判断
建议明确以下 go/no-go 规则：

### go 条件
必须同时满足：
1. `go_live_ready = true`
2. `replacement_blocker_count = 0`
3. 飞书后台配置完成
4. 白名单验证通过
5. current_release / bundle / Portal 均正常

### no-go 条件
任一项成立则不应上线：
1. 仍存在 `example.com`
2. trusted domain 未配置完成
3. redirect URL 未配置完成
4. 首页或下载链路异常
5. 白名单用户无法打开或使用

一句话判断：
go-live 不应凭感觉判断，必须有明确 go/no-go 条件。

## 11. 回退策略
若试点中出现问题，建议按以下方式回退：

1. 保留当前 Web 直链作为备用入口
2. 缩小或关闭白名单范围
3. 飞书首页先只保留 Feishu Frontdoor Homepage，不开放更多入口
4. 回退到上一个稳定版本的 URL 配置
5. 重新运行 readiness 检查，确认问题来源

## 12. 当前阶段不建议做的事
当前阶段仍不建议在真实 go-live 前重投入以下能力：
- 深度 JSAPI 集成
- 复杂审批流
- 全量通讯录同步
- 全员开放
- 复杂消息中心
- 复杂移动端单独适配

原因：
现在最重要的是先把“真实飞书试点入口”跑通。

## 13. 一句话总结
真实上线替换执行包的意义，不是为了多一个 checklist，而是让 Talent Review OS 从“系统侧 ready，但仍用占位地址”真正推进到“真实飞书试点可上线”的状态。
