docs(broadcast): design multi-role file insights
This commit is contained in:
@@ -0,0 +1,285 @@
|
||||
# 大喇叭公司文件多岗位解读设计
|
||||
|
||||
> 状态：产品方向已确认，待设计文档评审
|
||||
>
|
||||
> 日期：2026-07-25
|
||||
>
|
||||
> 范围：帮道大喇叭单文件附件，不建设独立文件管理系统
|
||||
|
||||
## 1. 目标
|
||||
|
||||
员工打开一份公司文件时，除查看通用摘要、消息正文和原文件外，还可以：
|
||||
|
||||
1. 默认查看“我的岗位如何理解这份文件”；
|
||||
2. 主动切换财务、人力、业务运营等其他关键岗位视角；
|
||||
3. 看清不同岗位分别关注什么、受到什么影响、需要做什么；
|
||||
4. 查看每条 AI 判断对应的原文依据；
|
||||
5. 继续使用现有“问这条消息”追问完整文件。
|
||||
|
||||
该能力的产品名称统一为“多岗位解读”。它是同一份文件的多视角阅读，不是文件分类、权限过滤或目录管理。
|
||||
|
||||
## 2. 当前基线
|
||||
|
||||
当前生产链路已经具备：
|
||||
|
||||
- 管理端上传一份公司文件并异步解析；
|
||||
- 生成一份通用摘要；
|
||||
- 发布时按项目、岗位、层级做定向提醒；
|
||||
- 员工查看消息正文、通用摘要和受控原文件；
|
||||
- 员工以 `broadcastMessageId` 进入“问”，由服务端加载完整提取文本；
|
||||
- 消息撤回后，同时拒绝详情、文件下载和消息上下文追问。
|
||||
|
||||
当前不具备：
|
||||
|
||||
- 从全文识别多个岗位视角；
|
||||
- 提取与当前员工岗位直接相关的原文片段；
|
||||
- 在文件详情内切换其他岗位视角；
|
||||
- 为岗位判断提供可核验的原文依据。
|
||||
|
||||
现有“与我有关”只表示该消息命中了发布时冻结的定向提醒，不表示附件内容已按本人岗位拆解。
|
||||
|
||||
## 3. 产品口径
|
||||
|
||||
### 3.1 两种“相关”必须分开
|
||||
|
||||
| 概念 | 含义 | 员工端文案 |
|
||||
|---|---|---|
|
||||
| 消息定向 | 发布人选择的项目、岗位或层级命中了当前员工 | 定向提醒 |
|
||||
| 内容相关 | AI 在文件原文中找到与当前岗位有关的内容 | 与我相关 |
|
||||
|
||||
内部 API 字段 `targeted` 和列表筛选值 `RELATED` 本轮保持兼容；只调整员工端展示文案，避免两个概念混淆。
|
||||
|
||||
### 3.2 多岗位解读结构
|
||||
|
||||
每个岗位视角固定返回：
|
||||
|
||||
1. `summary`：该岗位如何理解这份文件；
|
||||
2. `concerns`：最需要关注的事项；
|
||||
3. `impacts`：对该岗位职责、流程或指标的影响；
|
||||
4. `actions`：文件原文明确要求的行动；
|
||||
5. `risks`：原文明确存在的风险、限制或待确认事项；
|
||||
6. `evidence`：支持上述判断的原文短片段和段落序号。
|
||||
|
||||
文件未提及某岗位时，不生成补充常识，明确返回“原文未发现与该岗位直接相关的内容”。
|
||||
|
||||
### 3.3 V1 岗位视角目录
|
||||
|
||||
V1 使用版本化的服务端岗位视角目录，不建设配置后台：
|
||||
|
||||
- 生活顾问/客服；
|
||||
- 保洁；
|
||||
- 保安；
|
||||
- 保修/工程；
|
||||
- 财务；
|
||||
- 人力；
|
||||
- 业务运营；
|
||||
- 审计/风控；
|
||||
- 管理层。
|
||||
|
||||
AI 只返回文件实际涉及的视角。员工仍可查看全部已生成视角；服务端根据当前 APP 登录身份的组织岗位，为其中一个视角标记 `default=true`。
|
||||
|
||||
如果当前岗位无法可靠映射到目录，默认展示“文件概览”，并提示暂未识别专属岗位视角；不得猜测身份或拿客户端字段兜底。
|
||||
|
||||
## 4. 非目标
|
||||
|
||||
本轮不做：
|
||||
|
||||
- 行政、财务、业务等文件目录；
|
||||
- 文件库、文件归档、目录树和主动文件检索；
|
||||
- 多文件版本管理；
|
||||
- 文件修订、补推或外部强触达；
|
||||
- 员工自定义岗位身份；
|
||||
- AI 根据外部常识补充文件中不存在的要求；
|
||||
- 以岗位解读替代原文件或改变文件可见权限；
|
||||
- 后台岗位视角配置器。
|
||||
|
||||
## 5. 员工端交互
|
||||
|
||||
大喇叭文件详情保持一个主阅读流：
|
||||
|
||||
1. 消息标题、必读和“定向提醒”标签；
|
||||
2. 消息正文；
|
||||
3. 公司文件名称和通用摘要；
|
||||
4. “多岗位解读”区域；
|
||||
5. “查看原文件”和“问这份文件”两个动作。
|
||||
|
||||
“多岗位解读”区域：
|
||||
|
||||
- 默认选中“与我相关”；无法映射时选中“文件概览”；
|
||||
- 其余岗位使用横向可滚动的文本标签切换；
|
||||
- 只展示 AI 实际识别到内容的岗位；
|
||||
- 当前视角按“关注重点、岗位影响、需要行动、风险提醒、原文依据”顺序展示；
|
||||
- 原文依据默认折叠，员工主动展开后查看；
|
||||
- 不把所有岗位内容同时铺满页面。
|
||||
|
||||
状态处理：
|
||||
|
||||
| 状态 | 员工端表现 |
|
||||
|---|---|
|
||||
| `PENDING` | 显示“AI多岗位解读生成中”，其他功能照常使用 |
|
||||
| `READY` | 展示多岗位解读 |
|
||||
| `PARTIAL` | 展示已生成视角，并明确提示“文件较长，部分内容未完成解读” |
|
||||
| `FAILED` | 显示“多岗位解读暂不可用”，保留通用摘要、原文件和追问 |
|
||||
| 旧文件无状态 | 按 `NOT_PROCESSED` 兼容，不显示错误 |
|
||||
|
||||
## 6. 后端设计
|
||||
|
||||
### 6.1 数据结构
|
||||
|
||||
在 `aihr_broadcast_attachment` 增加：
|
||||
|
||||
- `insight_status varchar(20)`：`NOT_PROCESSED/PENDING/READY/PARTIAL/FAILED`；
|
||||
- `insights_json longtext`：结构化多岗位解读；
|
||||
- `insight_version varchar(30)`：例如 `role-perspective-v1`。
|
||||
|
||||
不新增文件主表，不把公司文件导入知识空间，不改变一条消息最多绑定一个附件的约束。
|
||||
|
||||
`insights_json` 逻辑结构：
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "role-perspective-v1",
|
||||
"perspectives": [
|
||||
{
|
||||
"code": "FINANCE",
|
||||
"label": "财务视角",
|
||||
"summary": "……",
|
||||
"concerns": ["……"],
|
||||
"impacts": ["……"],
|
||||
"actions": ["……"],
|
||||
"risks": ["……"],
|
||||
"evidence": [
|
||||
{
|
||||
"paragraphIndex": 12,
|
||||
"quote": "……"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
公开 DTO 不返回完整 `extracted_text`、模型提示词、模型原始响应或内部岗位匹配信息。
|
||||
|
||||
### 6.2 加工流程
|
||||
|
||||
复用现有附件上传、OSS、文档解析、异步 worker 和已启用的 chat 模型：
|
||||
|
||||
1. 解析原文件，得到完整 `extracted_text`；
|
||||
2. 生成并保存现有通用摘要；
|
||||
3. 将全文按自然段和字符上限切片；
|
||||
4. 每个切片提取岗位候选、关注点、影响、行动、风险和原文短证据；
|
||||
5. 合并同岗位结果，去重并限制数量；
|
||||
6. 校验每条证据确实出现在对应原文切片中；
|
||||
7. 保存结构化结果和版本；
|
||||
8. 将文件状态保持为 `READY`，多岗位解读独立记录成功或失败。
|
||||
|
||||
现有通用摘要方法只分析正文摘录，不能直接承担长文件多岗位解读。新增逻辑放在独立、单一职责的 `AihrBroadcastInsightService`，避免继续扩大通用 SOP 服务。
|
||||
|
||||
V1 使用以下边界：
|
||||
|
||||
- 每个切片最多 4000 个字符，相邻切片保留 300 个字符重叠；
|
||||
- 单文件最多处理 80 个切片，超过时按正文顺序处理前 80 个并标记 `PARTIAL`；
|
||||
- 最多返回 9 个岗位视角；
|
||||
- 每个视角的关注、影响、行动和风险各最多 5 条；
|
||||
- 每个视角最多返回 3 条原文依据，每条 20–200 字；
|
||||
- 原文依据必须是对应切片的连续子串，否则丢弃。
|
||||
|
||||
### 6.3 失败策略
|
||||
|
||||
- 未配置模型、超时、非法 JSON 或证据校验失败时，`insight_status=FAILED`；
|
||||
- 多岗位解读失败不回滚文件解析、通用摘要或原文件；
|
||||
- 不返回无依据的规则式伪岗位结论；
|
||||
- 单个切片失败可忽略，但最终结果必须至少有一个通过证据校验的岗位视角，否则整体失败；
|
||||
- 超过 80 个切片或部分切片失败但仍有有效结果时标记 `PARTIAL`，不得伪装成完整解读；
|
||||
- 模型响应、原始文件和提取全文不得写入普通错误日志。
|
||||
|
||||
### 6.4 身份与默认视角
|
||||
|
||||
员工详情继续只接受当前 APP 登录态：
|
||||
|
||||
1. 服务端按认证手机号精确解析唯一在职组织主体；
|
||||
2. 读取该主体的岗位、层级和项目范围；
|
||||
3. 使用服务端岗位别名规则映射默认视角；
|
||||
4. 只返回 `defaultPerspectiveCode`，不接受客户端提交岗位覆盖；
|
||||
5. 身份歧义或无法映射时返回空默认视角，不猜测。
|
||||
|
||||
其他岗位视角来自同一份已授权文件，员工可以主动切换查看；该能力不扩大原文件权限。
|
||||
|
||||
## 7. API 变化
|
||||
|
||||
继续复用：
|
||||
|
||||
- `GET /api/aihr/broadcast/messages/{id}`；
|
||||
- `GET /api/aihr/broadcast/attachments/{id}/content`；
|
||||
- `POST /api/knowledge/query` 的 `broadcastMessageId`。
|
||||
|
||||
扩展 `BroadcastAttachmentResponse`：
|
||||
|
||||
```json
|
||||
{
|
||||
"insightStatus": "READY",
|
||||
"defaultPerspectiveCode": "CLEANING",
|
||||
"perspectives": []
|
||||
}
|
||||
```
|
||||
|
||||
管理端附件状态响应只增加：
|
||||
|
||||
- `insightStatus`；
|
||||
- `perspectiveLabels`。
|
||||
|
||||
管理端不读取员工默认视角，不返回提取全文。
|
||||
|
||||
## 8. 管理端
|
||||
|
||||
现有大喇叭发布页仅增加：
|
||||
|
||||
- “AI多岗位解读生成中/已完成/暂不可用”状态；
|
||||
- 已识别岗位视角名称；
|
||||
- 解读失败不阻止发布。
|
||||
|
||||
不增加目录选择、文件中心、视角内容编辑器或批量文件管理。
|
||||
|
||||
## 9. 安全与审计
|
||||
|
||||
- 每次详情读取仍校验租户、当前在职 APP 身份和消息 `PUBLISHED` 状态；
|
||||
- 撤回消息后，多岗位解读与原文件、追问同时不可访问；
|
||||
- 所有证据只来自当前附件的 `extracted_text`；
|
||||
- 模型不得调用全网，也不得读取其他文件；
|
||||
- 员工反馈、查看岗位视角等行为本轮不新增审计表；
|
||||
- 原有发布、阅读、下载和撤回审计保持不变。
|
||||
|
||||
## 10. 验收标准
|
||||
|
||||
使用两份真实企业文件进行生产验收：
|
||||
|
||||
1. 管理端上传后可看到通用摘要和多岗位解读状态；
|
||||
2. 文件涉及财务、人力、业务等多个岗位时，员工端显示对应视角；
|
||||
3. 不同组织岗位登录后默认视角不同，但都能主动查看其他岗位视角；
|
||||
4. 每条结论都能展开看到确实存在于文件中的原文短片段；
|
||||
5. 长文件后半部分的相关内容能够进入解读结果；
|
||||
6. 文件未涉及某岗位时，不生成该岗位的虚构行动；
|
||||
7. AI失败时，通用摘要、原文件下载和“问这份文件”继续可用；
|
||||
8. API 不返回完整提取全文或原始 OSS 地址；
|
||||
9. 跨租户、非在职账号和撤回消息均无法获取解读；
|
||||
10. 390×844 下完成默认视角、视角切换、依据展开、原文件和追问的视觉与交互检查。
|
||||
|
||||
## 11. 兼容与发布
|
||||
|
||||
- 旧附件迁移后为 `NOT_PROCESSED`，不自动批量调用模型；
|
||||
- 本轮验收文件在新版本发布后重新上传，直接走新链路；
|
||||
- 现有 `summary`、`downloadUrl` 和消息追问契约保持兼容；
|
||||
- 正式 SQL migration 更新远端 schema 预检；
|
||||
- 发布后同时核对静态资源、后端包和生产 schema；
|
||||
- 不将两份演示文件的成功等同于公司全量文件内容验收。
|
||||
|
||||
## 12. 后续候选项
|
||||
|
||||
只有真实使用证明有必要后再考虑：
|
||||
|
||||
- 后台维护岗位视角目录和别名；
|
||||
- 旧文件按需重新拆解；
|
||||
- 员工对视角结果反馈；
|
||||
- 多岗位并排比较；
|
||||
- 独立文件分类和文件管理中心。
|
||||
Reference in New Issue
Block a user