开发指南
办公场景接口与后续待办
办公首页当前接口边界、配置方式和后续推荐与统计待办。
本文记录办公场景首页已接入的数据边界，以及尚未实现的个性化推荐和深度效果统计。
已复用现有能力
以下功能已经沿用现有请求、状态和路由，不需要新增接口：
- 账号级场景读取、切换与持久化。
- 最近会话、会话状态和会话跳转。
- 任务输入、附件、能力选择、任务创建和执行页跳转。
- 定时任务、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分类；分类管理维护中英文名称，首页按当前语言读取。 - 前端只识别约定的图标与语义色，不接收组件名或固定色值。
最小数据契约：
| 字段 | 说明 |
|---|---|
id | 数据主键 |
item_key | 稳定业务标识 |
item_type | quick_action 或 best_practice |
title | 当前语言下的标题 |
description | 当前语言下的简介 |
category_id | 分类管理中的办公首页分类 ID |
category | 当前语言下的分类名称 |
icon | 前端可识别的图标语义，不传任意组件名 |
tone | primary/info/success/warning 等语义色调 |
prompt | 点击使用时填入任务输入器的内容 |
sort_order | 排序 |
is_enabled | 是否可见 |
usage_count | 真实累计使用次数 |
公开接口按语言和启用状态返回数据。首页通过独立 Hook 调用服务层，卡片 View 只消费稳定的 ViewModel。
待办 2：最佳实践推荐
设计稿中的“换一换”目前轮换公开接口返回的数组。后续需要明确产品策略：
- 若只要求随机展示，最佳实践目录接口返回完整列表即可，由前端轮换。
- 若要求按账号、部门或历史行为个性化，新增服务端推荐能力，返回已排序的实践 ID。
在个性化规则明确前，不提前约定接口路径或推荐算法。
待办 3：实践效果统计
当前点击快捷按钮或实践卡片会把 Prompt 填入现有任务输入器，并记录去重后的真实点击次数；任务仍通过原有创建链路提交。若后续需要统计更深层的实践效果，服务端应继续记录：
- 提交、执行成功等事件类型。
- 由实践创建的 Session/Run ID。
- 事件时间。
如果实践未来包含结构化参数或工作流模板，创建任务接口需要接收稳定的实践 ID 或模板版本，不能只依赖前端展开后的 Prompt 文本。
后续完成标准
- “换一换”的行为与最终个性化推荐策略一致。
- 卡片发起任务仍复用统一任务链路，不复制任务创建逻辑。