docs(broadcast): plan multi-role file insights

2026-07-25 14:17:04 +08:00
parent aaca11cfab
commit 7c9b837dd3
1 changed files with 522 additions and 0 deletions
@@ -0,0 +1,522 @@
+# 大喇叭公司文件多岗位解读 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 在现有“大喇叭消息 + 单个公司文件”链路中生成有原文依据的多岗位解读，并让员工默认看到自己岗位视角、可切换查看全部相关视角。
+
+**Architecture:** 复用现有附件解析、摘要、鉴权下载和消息追问链路。新增一个职责单一的 `AihrBroadcastInsightService`，使用现有模型调用边界按自然段分块生成结构化岗位解读，服务端只保留引用能在原文块中精确命中的内容；附件文件状态与解读状态分离，解读失败不阻塞文件发布和阅读。
+
+**Tech Stack:** Java 17、Spring Boot、JdbcTemplate、Jackson、MySQL 8、Vue 3、uni-app、TypeScript、Node test、JUnit 5/Mockito。
+
+---
+
+## 文件职责
+
+- Create `backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/broadcast/AihrBroadcastInsightService.java`
+  - 固定岗位目录、岗位映射、自然段分块、模型调用、JSON 清洗、原文引用校验、跨块合并和响应反序列化。
+- Modify `backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/broadcast/AihrBroadcastAttachmentService.java`
+  - 文件提取完成后先保存 `READY`，再独立领取和处理岗位解读任务；恢复卡死任务。
+- Modify `backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/broadcast/AihrBroadcastService.java`
+  - 员工详情查询解读字段，基于认证手机号对应的在职组织岗位计算默认视角，不返回 `extracted_text`。
+- Modify `backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/broadcast/AihrBroadcastDto.java`
+  - 增加岗位解读、来源依据和解读状态字段。
+- Create `backend/script/sql/update/aihr_20260725_broadcast_multi_role_insight_mysql8.sql`
+  - 为附件表增加 `insight_status`、`insights_json`、`insight_version` 及解读队列索引。
+- Create `backend/ruoyi-modules/ruoyi-aihr/src/test/java/org/dromara/aihr/broadcast/AihrBroadcastInsightServiceTest.java`
+  - 覆盖岗位映射、自然段分块、伪造引用剔除、跨块合并和部分成功状态。
+- Modify existing broadcast backend tests
+  - 覆盖文件与解读状态解耦、DTO 不泄漏全文、租户/撤回/在职身份约束不回退。
+- Modify `mobile-uni/src/services/broadcast.ts`
+  - 声明岗位解读响应类型。
+- Modify `mobile-uni/src/pages/user/broadcast/detail.vue`
+  - 在文件摘要之后展示默认岗位、岗位切换、五类要点和折叠的原文依据。
+- Modify `mobile-uni/src/pages/user/broadcast/index.vue`
+  - 将通知命中标签“与我有关”改为“定向提醒”。
+- Create `mobile-uni/tests/broadcast-multi-role-insight.test.mjs`
+  - 覆盖类型契约、默认视角、切换、依据折叠、降级状态及术语改名。
+- Modify `scripts/reset-dev-db.sh`, `scripts/tests/aihr-schema-migrations.test.sh`, `scripts/release-preflight.sh`, `scripts/demo-check.sh`
+  - 纳入正式迁移与远端只读 schema 合同。
+- Modify `docs/API_INTEGRATION.md`, `docs/BRD_IMPLEMENTATION_AUDIT.md`
+  - 记录接口字段、生成状态、失败降级和验收边界。
+
+### Task 1: 数据库合同与 DTO
+
+**Files:**
+- Create: `backend/script/sql/update/aihr_20260725_broadcast_multi_role_insight_mysql8.sql`
+- Modify: `backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/broadcast/AihrBroadcastDto.java`
+- Modify: `scripts/tests/aihr-schema-migrations.test.sh`
+- Test: `backend/ruoyi-modules/ruoyi-aihr/src/test/java/org/dromara/aihr/broadcast/AihrBroadcastAttachmentContractTest.java`
+
+- [ ] **Step 1: 写失败的 schema 与 DTO 合同测试**
+
+在迁移测试中要求以下三列存在：
+
+```bash
+SELECT COUNT(*)
+FROM information_schema.columns
+WHERE table_schema='$DB'
+  AND table_name='aihr_broadcast_attachment'
+  AND column_name IN ('insight_status','insights_json','insight_version');
+```
+
+在 `AihrBroadcastAttachmentContractTest` 中断言响应包含 `insightStatus`、`defaultPerspectiveCode`、`perspectives`，同时不包含 `extractedText` 和 `insightsJson`。
+
+- [ ] **Step 2: 运行测试并确认失败**
+
+Run:
+
+```bash
+bash scripts/tests/aihr-schema-migrations.test.sh
+mvn -f backend/pom.xml -pl ruoyi-modules/ruoyi-aihr -am \
+  -Dtest=AihrBroadcastAttachmentContractTest \
+  -Dsurefire.failIfNoSpecifiedTests=false test
+```
+
+Expected: schema 测试缺少 3 列，Java 测试缺少新的 record component。
+
+- [ ] **Step 3: 写幂等迁移和最小 DTO**
+
+迁移增加：
+
+```sql
+ALTER TABLE aihr_broadcast_attachment
+  ADD COLUMN insight_status varchar(20) NOT NULL DEFAULT 'NOT_PROCESSED' AFTER summary,
+  ADD COLUMN insights_json longtext NULL AFTER insight_status,
+  ADD COLUMN insight_version varchar(30) NULL AFTER insights_json;
+```
+
+迁移必须通过 `information_schema` + prepared statement 分列幂等执行，并增加：
+
+```sql
+KEY idx_aihr_broadcast_attachment_insight_queue
+  (insight_status, status, update_time)
+```
+
+DTO 增加：
+
+```java
+public record BroadcastEvidence(int paragraphIndex, String quote) {}
+
+public record BroadcastPerspective(
+    String code,
+    String label,
+    String summary,
+    List<String> concerns,
+    List<String> impacts,
+    List<String> actions,
+    List<String> risks,
+    List<BroadcastEvidence> evidence
+) {}
+```
+
+附件响应追加：
+
+```java
+String insightStatus,
+String defaultPerspectiveCode,
+List<String> perspectiveLabels,
+List<BroadcastPerspective> perspectives
+```
+
+- [ ] **Step 4: 运行测试并确认通过**
+
+Run the two Task 1 commands.
+
+Expected: PASS，迁移可重复执行，DTO 没有原文和 JSON 存储字段。
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add backend/script/sql/update/aihr_20260725_broadcast_multi_role_insight_mysql8.sql \
+  backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/broadcast/AihrBroadcastDto.java \
+  backend/ruoyi-modules/ruoyi-aihr/src/test/java/org/dromara/aihr/broadcast/AihrBroadcastAttachmentContractTest.java \
+  scripts/tests/aihr-schema-migrations.test.sh
+git commit -m "feat(broadcast): add multi-role insight contract"
+```
+
+### Task 2: 岗位解读生成器
+
+**Files:**
+- Create: `backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/broadcast/AihrBroadcastInsightService.java`
+- Create: `backend/ruoyi-modules/ruoyi-aihr/src/test/java/org/dromara/aihr/broadcast/AihrBroadcastInsightServiceTest.java`
+
+- [ ] **Step 1: 写失败的核心逻辑测试**
+
+使用 Mockito 模拟 `AihrModelSeedService.chat` 返回 OpenAI-compatible JSON，覆盖：
+
+```java
+assertEquals("finance", AihrBroadcastInsightService.defaultPerspectiveCode(List.of("财务经理")));
+assertEquals("living_advisor", AihrBroadcastInsightService.defaultPerspectiveCode(List.of("物业管家")));
+assertNull(AihrBroadcastInsightService.defaultPerspectiveCode(List.of("未知岗位")));
+assertTrue(AihrBroadcastInsightService.chunks(longParagraphText).size() > 1);
+assertTrue(result.perspectives().getFirst().evidence().stream()
+    .allMatch(item -> source.contains(item.quote())));
+assertFalse(resultJson.contains("模型编造但原文不存在"));
+```
+
+另测第二块模型失败时保留第一块结果并返回 `PARTIAL`，所有块失败时返回 `FAILED`。
+
+- [ ] **Step 2: 运行测试并确认失败**
+
+Run:
+
+```bash
+mvn -f backend/pom.xml -pl ruoyi-modules/ruoyi-aihr -am \
+  -Dtest=AihrBroadcastInsightServiceTest \
+  -Dsurefire.failIfNoSpecifiedTests=false test
+```
+
+Expected: FAIL because the service does not exist.
+
+- [ ] **Step 3: 实现最小生成器**
+
+固定九个角色：
+
+```java
+private static final Map<String, String> ROLE_LABELS = Map.ofEntries(
+    entry("living_advisor", "生活顾问/客服"),
+    entry("cleaning", "保洁"),
+    entry("security", "保安"),
+    entry("engineering", "保修/工程"),
+    entry("finance", "财务"),
+    entry("hr", "人力"),
+    entry("operations", "业务运营"),
+    entry("audit_risk", "审计风控"),
+    entry("management", "管理层")
+);
+```
+
+自然段块目标 4,000 字、相邻重叠 300 字，最多 80 块。每块调用：
+
+```java
+modelService.chat(new ChatRequest(
+    prompt(fileName, chunk, paragraphOffset),
+    null,
+    "只根据给定原文返回 JSON；未提及的岗位不要输出；evidence.quote 必须逐字复制原文。"
+));
+```
+
+只接受 `mode == "openai-compatible"` 且 `error` 为空的响应。解析后执行：
+
+```java
+if (!chunk.text().contains(evidence.quote())) {
+    continue;
+}
+```
+
+每岗位最多 5 条 concerns/impacts/actions/risks、3 条 evidence；文本去空白、去重、限制长度；仅保留固定角色代码。成功块少于总块数或正文超过 80 块时为 `PARTIAL`，全部失败为 `FAILED`。
+
+- [ ] **Step 4: 运行测试并确认通过**
+
+Run the Task 2 Maven command.
+
+Expected: PASS.
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/broadcast/AihrBroadcastInsightService.java \
+  backend/ruoyi-modules/ruoyi-aihr/src/test/java/org/dromara/aihr/broadcast/AihrBroadcastInsightServiceTest.java
+git commit -m "feat(broadcast): generate grounded role insights"
+```
+
+### Task 3: 附件异步链路与员工详情
+
+**Files:**
+- Modify: `backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/broadcast/AihrBroadcastAttachmentService.java`
+- Modify: `backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/broadcast/AihrBroadcastService.java`
+- Modify: `backend/ruoyi-modules/ruoyi-aihr/src/test/java/org/dromara/aihr/broadcast/AihrBroadcastServiceTest.java`
+- Modify: `backend/ruoyi-modules/ruoyi-aihr/src/test/java/org/dromara/aihr/broadcast/AihrBroadcastAttachmentContractTest.java`
+
+- [ ] **Step 1: 写失败的链路测试**
+
+测试源代码和 JDBC 参数，要求：
+
+```java
+assertTrue(attachmentSource.contains("set status = 'READY', extracted_text = ?, summary = ?"));
+assertTrue(attachmentSource.contains("insight_status = 'PENDING'"));
+assertTrue(attachmentSource.contains("insight_status = 'FAILED'"));
+assertTrue(detailSql.contains("a.insights_json as attachment_insights_json"));
+assertTrue(detailSql.contains("m.status = 'PUBLISHED'"));
+assertFalse(responseFields.contains("extractedText"));
+```
+
+新增详情测试：岗位 `财务主管` 默认代码为 `finance`；同一响应仍返回其他全部岗位；撤回、跨租户、非在职员工继续在查询前失败关闭。
+
+- [ ] **Step 2: 运行测试并确认失败**
+
+Run:
+
+```bash
+mvn -f backend/pom.xml -pl ruoyi-modules/ruoyi-aihr -am \
+  -Dtest=AihrBroadcastServiceTest,AihrBroadcastAttachmentContractTest \
+  -Dsurefire.failIfNoSpecifiedTests=false test
+```
+
+Expected: FAIL on missing insight queue and response mapping.
+
+- [ ] **Step 3: 分离文件状态和解读状态**
+
+附件解析成功后立即写：
+
+```sql
+status = 'READY',
+extracted_text = ?,
+summary = ?,
+insight_status = 'PENDING',
+insights_json = NULL,
+insight_version = NULL
+```
+
+解读任务领取时把 `PENDING` 原子更新为内部 `PROCESSING`；API 将内部 `PROCESSING` 映射为 `PENDING`。成功保存 `READY/PARTIAL` 与 JSON、版本；异常只写 `insight_status='FAILED'`，不得把附件 `status` 改回 `FAILED`。启动恢复将超过 30 分钟的内部 `PROCESSING` 重置为 `PENDING`。
+
+- [ ] **Step 4: 安全映射员工详情**
+
+详情 SQL 只在既有租户、`PUBLISHED`、在职员工门禁通过后读取存储 JSON。服务端用当前 APP 用户手机号和 `aihr_org_snapshot` 的精确在职匹配读取 `position_name`，再计算 `defaultPerspectiveCode`；客户端不得提交岗位。返回全部已生成岗位，但绝不返回 `extracted_text` 或 `insights_json`。
+
+- [ ] **Step 5: 运行测试并确认通过**
+
+Run the Task 3 Maven command.
+
+Expected: PASS.
+
+- [ ] **Step 6: 提交**
+
+```bash
+git add backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/broadcast/AihrBroadcastAttachmentService.java \
+  backend/ruoyi-modules/ruoyi-aihr/src/main/java/org/dromara/aihr/broadcast/AihrBroadcastService.java \
+  backend/ruoyi-modules/ruoyi-aihr/src/test/java/org/dromara/aihr/broadcast/AihrBroadcastServiceTest.java \
+  backend/ruoyi-modules/ruoyi-aihr/src/test/java/org/dromara/aihr/broadcast/AihrBroadcastAttachmentContractTest.java
+git commit -m "feat(broadcast): expose employee role insights"
+```
+
+### Task 4: 员工端多岗位阅读
+
+**Files:**
+- Modify: `mobile-uni/src/services/broadcast.ts`
+- Modify: `mobile-uni/src/pages/user/broadcast/detail.vue`
+- Modify: `mobile-uni/src/pages/user/broadcast/index.vue`
+- Create: `mobile-uni/tests/broadcast-multi-role-insight.test.mjs`
+- Modify: `mobile-uni/tests/broadcast-attachment.test.mjs`
+
+- [ ] **Step 1: 写失败的移动端合同测试**
+
+断言源码包含：
+
+```js
+assert.match(service, /interface BroadcastPerspective/);
+assert.match(detail, /多岗位解读/);
+assert.match(detail, /defaultPerspectiveCode/);
+assert.match(detail, /原文依据/);
+assert.match(detail, /insightStatus === 'FAILED'/);
+assert.doesNotMatch(detail, /与我有关/);
+assert.match(index, /定向提醒/);
+```
+
+- [ ] **Step 2: 运行测试并确认失败**
+
+Run:
+
+```bash
+npm --prefix mobile-uni run test:unit
+```
+
+Expected: new multi-role test FAIL.
+
+- [ ] **Step 3: 增加类型和默认选择**
+
+类型与后端一致。详情加载后：
+
+```ts
+const perspectives = computed(() => item.value?.attachment?.perspectives || []);
+const selectedCode = ref('');
+
+const selectInitialPerspective = (attachment?: BroadcastAttachment) => {
+  selectedCode.value = attachment?.perspectives.some(
+    perspective => perspective.code === attachment.defaultPerspectiveCode
+  )
+    ? attachment.defaultPerspectiveCode || ''
+    : attachment?.perspectives[0]?.code || '';
+};
+```
+
+显示“我的岗位视角”仅当默认代码实际命中；否则显示“多岗位解读”。
+
+- [ ] **Step 4: 实现移动端布局和降级状态**
+
+摘要保持在前。其后依次展示：
+
+```text
+多岗位解读 / 我的岗位视角
+[生活顾问] [财务] [人力] [业务运营] …
+本岗位摘要
+关注点 / 影响 / 建议行动 / 风险
+原文依据（默认折叠）
+```
+
+`PENDING` 显示“AI 正在从不同岗位解读”；`PARTIAL` 显示“已生成部分岗位解读”；`FAILED` 或 `NOT_PROCESSED` 只显示轻量说明，不隐藏摘要、原文件和“问这条消息”。岗位 chips 允许横向滚动，按钮具备可识别选中态和可读文本。
+
+- [ ] **Step 5: 运行移动端测试、类型检查和构建**
+
+Run:
+
+```bash
+npm --prefix mobile-uni run test:unit
+npm --prefix mobile-uni run typecheck
+npm --prefix mobile-uni run build:h5
+```
+
+Expected: all PASS.
+
+- [ ] **Step 6: 提交**
+
+```bash
+git add mobile-uni/src/services/broadcast.ts \
+  mobile-uni/src/pages/user/broadcast/detail.vue \
+  mobile-uni/src/pages/user/broadcast/index.vue \
+  mobile-uni/tests/broadcast-multi-role-insight.test.mjs \
+  mobile-uni/tests/broadcast-attachment.test.mjs
+git commit -m "feat(mobile): show broadcast role perspectives"
+```
+
+### Task 5: 开发重置、发布预检与文档
+
+**Files:**
+- Modify: `scripts/reset-dev-db.sh`
+- Modify: `scripts/release-preflight.sh`
+- Modify: `scripts/demo-check.sh`
+- Modify: `docs/API_INTEGRATION.md`
+- Modify: `docs/BRD_IMPLEMENTATION_AUDIT.md`
+
+- [ ] **Step 1: 写失败的发布合同**
+
+将远端附件合同从 11 个业务列扩展为 14 个，并明确要求：
+
+```text
+insight_status
+insights_json
+insight_version
+```
+
+`demo-check.sh` 要求新迁移、解读服务、移动端“多岗位解读”和“定向提醒”存在。
+
+- [ ] **Step 2: 运行静态预检并确认失败**
+
+Run:
+
+```bash
+bash scripts/demo-check.sh
+```
+
+Expected: FAIL on missing preflight/docs markers before implementation.
+
+- [ ] **Step 3: 接入迁移与更新文档**
+
+`reset-dev-db.sh` 在附件基础迁移后执行新迁移。API 文档记录：
+
+```text
+insightStatus: NOT_PROCESSED | PENDING | READY | PARTIAL | FAILED
+defaultPerspectiveCode: 服务端按认证手机号对应在职岗位计算
+perspectives[]: code/label/summary/concerns/impacts/actions/risks/evidence
+```
+
+同时记录：所有有原消息阅读权限的员工可切换全部生成岗位；引用必须逐字命中原文；失败不影响摘要、下载和追问；旧“与我有关”改名“定向提醒”且语义仍为通知定向。
+
+- [ ] **Step 4: 运行静态预检**
+
+Run:
+
+```bash
+bash scripts/demo-check.sh
+git diff --check
+```
+
+Expected: PASS.
+
+- [ ] **Step 5: 提交**
+
+```bash
+git add scripts/reset-dev-db.sh scripts/release-preflight.sh scripts/demo-check.sh \
+  docs/API_INTEGRATION.md docs/BRD_IMPLEMENTATION_AUDIT.md
+git commit -m "docs(broadcast): define role insight release contract"
+```
+
+### Task 6: 集成、视觉和真实交互验收
+
+**Files:**
+- Verify all modified files
+- Evidence: local browser screenshots at 390 × 844 and desktop responsive view
+
+- [ ] **Step 1: 运行后端与移动端全量相关检查**
+
+Run:
+
+```bash
+mvn -f backend/pom.xml -pl ruoyi-modules/ruoyi-aihr -am \
+  -DskipITs -Dsurefire.failIfNoSpecifiedTests=false test
+npm --prefix mobile-uni run test:unit
+npm --prefix mobile-uni run typecheck
+npm --prefix mobile-uni run build:h5
+bash scripts/demo-check.sh
+git diff --check
+```
+
+Expected: PASS.
+
+- [ ] **Step 2: 启动本地服务并造两份可识别测试文件**
+
+Run:
+
+```bash
+docker compose -f docker-compose.dev.yml up -d
+portless run --name wygj-api ./scripts/dev-backend.sh
+portless run --name wygj-mobile-uni npm --prefix mobile-uni run dev:h5
+```
+
+通过现有管理端上传并发布：
+
+1. 同时涉及财务、人力、业务运营的短文件；
+2. 超过 4,000 字且关键内容在尾部的长文件。
+
+使用数据库中实际在职手机号和开发固定验证码登录，不在日志、截图或报告中保留手机号。
+
+- [ ] **Step 3: 在 390 × 844 浏览器真实验证**
+
+逐项操作：
+
+1. 打开大喇叭详情，确认摘要位于多岗位解读之前；
+2. 确认默认选中当前员工岗位对应视角；
+3. 横向切换财务、人力、业务运营等全部返回岗位；
+4. 展开原文依据并核对引文存在于文件；
+5. 打开原文件；
+6. 点击“问这条消息”；
+7. 验证 `PENDING/PARTIAL/FAILED` 时主链路仍可用；
+8. 检查文字换行、chip 溢出、底部按钮、滚动与点击区域。
+
+保存并检查截图，不以页面可加载替代视觉验收。
+
+- [ ] **Step 4: 安全回归**
+
+用自动化或直接 HTTP 证据确认：
+
+```text
+撤回消息 -> 404
+跨租户消息 -> 404
+非在职 APP 身份 -> 403
+员工详情 JSON -> 不含 extracted_text / insights_json
+```
+
+- [ ] **Step 5: 代码审查与修复**
+
+分别进行 Java、TypeScript 和整体代码审查；修复所有高/中优先级问题后重跑 Task 6 Step 1。
+
+- [ ] **Step 6: 提交最终修复**
+
+```bash
+git add -u
+git commit -m "fix(broadcast): close multi-role insight review findings"
+```
+
+- [ ] **Step 7: 交付分支**
+
+确认工作区干净，报告 `implemented / locally verified / visually verified`；生产部署与 `production-verified` 只有在执行正式迁移、静态发布、后端发布、完整 `release-preflight` 和线上真实账号验证后才能声明。