办公场景接口与后续待办

本文记录办公场景首页已接入的数据边界，以及尚未实现的个性化推荐和深度效果统计。

已复用现有能力

以下功能已经沿用现有请求、状态和路由，不需要新增接口：

账号级场景读取、切换与持久化。
最近会话、会话状态和会话跳转。
任务输入、附件、能力选择、任务创建和执行页跳转。
定时任务、AI 员工 Skills、AI 听记等现有功能入口。
当前账号权限和公开品牌配置。

已接入：首页内容目录

快捷按钮和最佳实践均由 office_home_content_items 表管理。数据库迁移写入首批 6 个快捷按钮和 8 个最佳实践，后续由后台“首页内容”页面维护。

用户端通过 GET /api/v1/office-home-content?lng=zh 获取已启用内容。
用户点击快捷按钮或最佳实践时通过 POST /api/v1/office-home-content/{item_id}/usage 累加使用次数；同一用户对同一内容在滚动 5 分钟内只计一次，重复点击正常返回且不影响使用。
管理端通过 /api/v1/admin/office-home-content 完成查询、新增、编辑和软删除。
最佳实践通过 category_id 关联分类管理中的 office_home 分类；分类管理维护中英文名称，首页按当前语言读取。
前端只识别约定的图标与语义色，不接收组件名或固定色值。

用户与管理数据契约

用户端 GET 返回 data.quick_actions 与 data.practices 两个数组。快捷入口包含 id、item_key、title、prompt、icon、tone、sort_order；实践还包含 description、category、usage_count。用户响应不返回 item_type、category_id、is_enabled 等后台维护字段。

后台接口返回中英文标题、简介与 prompt、category_id、排序和启用状态等编辑字段。usage_count 可由管理员设置，也会按用户点击去重累加，因此不是不可修改的纯行为计数，不能直接当作任务成功量。

首页内容 Hook 调用服务，office-home-view 使用该 Hook 及个性化 Hook 展示数据。个性化已实现人物选择、主题联动、图片与成组文案；用户设置保存到 Backend，前端维护对应缓存。按固定步长轮换目录数组是前端展示行为，不代表已有服务端个性化推荐。

个性化接口为 GET /api/v1/office-home-personalization?lng=zh，返回 data.themePreset、data.selectedCharacterId 和 data.characters。人物选择通过 GET/PUT /api/v1/user-customer-settings 读取或保存 office_home_hero_character，沿用登录账号的用户设置。

待办 2：最佳实践推荐

设计稿中的“换一换”目前轮换公开接口返回的数组。后续需要明确产品策略：

若只要求随机展示，最佳实践目录接口返回完整列表即可，由前端轮换。
若要求按账号、部门或历史行为个性化，新增服务端推荐能力，返回已排序的实践 ID。

在个性化规则明确前，不提前约定接口路径或推荐算法。

待办 3：实践效果统计

当前点击快捷按钮或实践卡片会把 Prompt 填入现有任务输入器，并累加去重点击到可由管理员维护的 usage_count；任务仍通过原有创建链路提交。若后续需要统计更深层的实践效果，服务端应继续记录：

提交、执行成功等事件类型。
由实践创建的 Session/Run ID。
事件时间。

如果实践未来包含结构化参数或工作流模板，创建任务接口需要接收稳定的实践 ID 或模板版本，不能只依赖前端展开后的 Prompt 文本。

后续完成标准

“换一换”的行为与最终个性化推荐策略一致。
卡片发起任务仍复用统一任务链路，不复制任务创建逻辑。