# 项目方案入口技术对接说明

版本：v0.1  
日期：2026-09-15  
状态：研发实现建议；业务边界以A端07为准，尚未真实接入验证

## 修订记录

| 日期 | 版本 | 类型 | 摘要 |
| --- | --- | --- | --- |
| 2026-09-15 | v0.1 | 初始创建 | 建议以入口身份解析目标页面及交互模式，统一初次进入和快速切换，列出权限与状态对接约束。 |

## 1. 实现结论

复用页面内容读取能力，入口身份和页面编号分开处理。演示入口与自由入口可以引用同一页面，但不能仅用页面编号判断交互模式；不能使用一个“自由/演示”开关保留当前目标页面。

## 2. 建议保存的数据

项目配置保存自由页引用、有序演示页引用和最近修改标识；名称、目录、语言内容继续从页面读取。

建议入口身份为二选一：

- `free`：指当前项目配置的自由入口；目标页面由服务端解析。
- `presentation + pageId`：指当前项目演示列表中的页面；必须确认该页仍在列表，不能把任意页面编号作为有效方案。

修改标识只用于检测多人覆盖，不是内容历史版本或可回滚快照。保存配置前后作为一个完整结果变化。

## 3. 建议入口与刷新策略

例如 `/projects/:projectId/present?entry=free` 与 `/projects/:projectId/present?entry=presentation&page=:pageId`。这是待研发选择的路由示例，不是已上线地址。

初次从P02进入、内容内快速切换、浏览器刷新和直接地址均调用同一套入口解析。服务端完成员工、项目权限及有效期、配置关联和页面状态校验后，返回完整目标上下文。

不以URL的`mode`参数直接授予能力，不复用顾客链接启停作为员工权限。顾客分享页继续沿用原访问链路，不能因为统一内容渲染而拿到员工方案列表。

## 4. 目标上下文与切换顺序

建议统一处理函数 `selectProjectEntry(entry)`：

1. 记录本次明确选择的入口，读取其获准配置。
2. 解析目标页面、当前语言的名称、Widget实例目录及入口对应交互方式。
3. 校验结果完整后，同步更新页面上下文、标题、导航/演示控制，不分批替换出错配画面。
4. 清理旧目标尚未完成的请求或忽略其晚到结果，避免旧内容覆盖新选择。
5. 当前页面内Widget功能继续使用已有内容及交互定义，不因外层模式而丢失内部能力。

自由访问显示对应页面的导航；演示项显示对应方案场景列表和演示控制。快速方案选择是独立的员工入口，两种交互下都能使用，不能跟随演示前后按钮一起隐藏。

## 5. 异常与必须验证的接口边界

- 保存前：新添加目标失效时拒绝新增；已有停用演示引用可保留位置；自由目标必须有效。
- 内容入口：配置已移除、页面停用/删除或员工无权时拒绝进入，不能只依赖旧列表缓存。
- 快速选择：区分“尚未完成的目标”和“已成功展示的目标”，不要先改标题再加载另一页面。
- 失败提示遵守现有C端Toast规则；保留旧画面还是显示目标失败占位、如何重试由P02/C04剩余状态决策落实，不在本技术建议中暗自决定。
- 浏览进度按方案入口分开识别，是否恢复尚待产品决定；不要因两个入口引用同页而默认共享播放进度。
- 自动刷新、推送失效及已加载内容如何中断由技术接入和C端状态专项确定，不能宣称配置保存会远程清空所有浏览器。

## 6. 本轮实现与未实现

A端原型已用独立入口身份（自由入口与演示页身份）实现联动预览，选择时共同更新目标、目录及交互说明；用浏览器存储模拟保存和冲突检查。

没有接入上面的生产路由、服务端权限或真实Widget加载器。后续研发应先完成入口解析契约，再连接P02及C端快速切换控件；不能以原型通过宣布生产权限或完整播放器已完成。