业务与办公场景 UI 架构

Poco 双场景布局的路由策略、代码边界、渐进迁移方式和验收要求。

Poco 支持两套用途不同的界面：

业务场景：保留现有功能密度较高的 UI 和布局。
办公场景：面向日常办公人员，强调任务发起、最近会话、常用能力和最佳实践。

场景不是主题。场景决定信息架构和页面布局，主题预设与 Light/Dark 继续独立决定颜色、字体、圆角和阴影。

默认场景与切换权限

Backend 返回的账号级 ui_scene 始终决定用户登录后的界面场景，同一账号跨浏览器、跨设备保持一致。未知或缺失值统一回退为业务场景。

管理员可在用户管理中设置每个用户的默认进入场景；新建用户默认使用业务场景。
“新用户配置”中的默认场景仅用于后续通过 SSO 自动注册的用户，不覆盖已有用户。
权限菜单 feature.settings.sceneSwitch 只控制用户是否可见切换入口以及是否可写入自己的场景偏好，不改变其已配置的默认场景。
场景页面按 ui_scene 渲染，具体业务操作继续使用各自的功能权限判断。例如缺少“新任务”权限时仍显示办公场景，但任务发起入口不可用。

场景切换不再依赖 Frontend 环境变量。部署时需先执行 Backend Alembic 迁移；迁移会创建权限菜单并向现有功能角色授予该权限，避免正在使用场景切换的用户升级后失去入口。如需全局关闭，可在权限菜单中禁用“场景切换”资源。部署步骤参考部署指南。

核心决策

保留一套 URL 路由

同一个业务页面只保留一个稳定地址，例如：

/{lng}/home
/{lng}/agents/free
/{lng}/chat/{session_id}

不创建 /business/home 或 /office/home。账号字段 ui_scene 决定当前地址渲染哪个场景视图。

这样可以避免：

重复维护权限、导航、深链和页面参数。
场景切换时发生额外重定向。
新设备登录后先显示业务页面，再跳转到办公页面。
两套路由逐渐产生不同的请求和行为逻辑。

只有业务语义、权限或数据契约本身不同的新功能，才应新增独立 URL。

共享行为，隔离视图

请求、状态、权限、计算和跳转属于行为层；布局、文案组织和组件组合属于视图层。

代码边界：

app 路由文件保持轻量，只挂载场景分发组件。
容器组件读取场景、调用 hooks，并把 ViewModel 与事件回调交给视图。
hooks、actions、services 和 model 不感知场景。
场景 View 不直接调用接口，不复制会话创建、权限和统计逻辑。
components/ui 保持 shadcn/ui 的项目级默认实现，不为办公场景修改基础圆角或全局样式。

目录约定

页面级代码按业务功能归档，再按场景拆分视图：

frontend/features/home/
├── components/
│   ├── home-scene-page-client.tsx
│   ├── home-overview-page-client.tsx
│   └── home-page-client.tsx
├── hooks/
│   └── use-office-home-content.ts
├── model/
│   ├── office-home-content.ts
│   └── office-home-icons.ts
├── services/
│   └── office-home-content-service.ts
└── views/
    └── office/
        └── office-home-view.tsx

首页侧栏也在现有共享侧栏入口按场景分发：

frontend/components/shared/sidebar/
├── app-sidebar.tsx
├── global-navigation-sidebar.tsx
└── office-navigation-sidebar.tsx

home-overview-page-client.tsx 继续承载业务场景首页，home-page-client.tsx 复用现有任务发起行为，办公 View 只负责布局和展示。办公首页与定时任务共用 office-navigation-sidebar.tsx，页面内容仍按各自功能目录隔离。

定时任务的办公场景视图统一放在功能目录内：

frontend/features/scheduled-tasks/components/
├── scheduled-tasks-scene-page-client.tsx
├── scheduled-task-detail-scene-page-client.tsx
└── office/
    ├── office-scheduled-tasks-page.tsx
    ├── office-scheduled-task-form-page.tsx
    └── office-scheduled-task-detail-page.tsx

不要建立一份包含所有办公功能的巨型 office-ui 页面目录。页面视图与其所属功能放在一起，未来的场景外壳只处理全局导航和内容区域。