# 大喇叭公司文件多岗位解读设计

> 状态：产品方向已确认，待设计文档评审
>
> 日期：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. 后续候选项

只有真实使用证明有必要后再考虑：

- 后台维护岗位视角目录和别名；
- 旧文件按需重新拆解；
- 员工对视角结果反馈；
- 多岗位并排比较；
- 独立文件分类和文件管理中心。