docs(pearl): API_REFERENCE 同步珍珠图 25 类与新增接口

docs/superpowers/api/API_REFERENCE.md

@@ -75,7 +75,7 @@ find cfc-backend/src/main/java -name "*XxxService.java" -o -name "*XxxController
 | `ContactController` | `/api/contact` | 联系人 CRUD/互动/邀请入家庭 | — |
 | `ContactMatchController` | `/api/contact/match` | 联系人对接（send/accept/reject/列表） | — |
 | `OctopusController` | `/api/octopus` | 章鱼图（帮助记录/触手聚合） | — |
-| `PearlController` | `/api/pearl` | 珍珠图（四类资源聚合 + 登记 CRUD） | — |
+| `PearlController` | `/api/pearl` | 珍珠图（25 类社会连接聚合 + 互动/提醒/优先级） | — |
 | `AbilityController` | `/api/ability` | 能力图（SKILL 帮助记录聚合为能力节点） | — |
 
 ---
@@ -1092,17 +1092,18 @@ score 范围：0-100（整数）
 
 ### 4.39 珍珠图/能力图（`/api/pearl/*`, `/api/ability/*`）
 
-关系三图体系：章鱼图（谁帮过我）→ 珍珠图（我有什么）→ 能力图（谁会什么）。珍珠图聚合四类资源，能力图聚合 SKILL 类帮助记录。
+关系三图体系：章鱼图（谁帮过我）→ 珍珠图（我有什么）→ 能力图（谁会什么）。珍珠图聚合 25 类社会连接（12 必备内圈 + 13 理想外圈），附带互动日志、价值分级、定期提醒。
 
 | 路径 | 说明 |
 |------|------|
-| `POST /api/octopus/tentacles` | 章鱼图：帮助次数榜+金额榜前 8 触手（已存在，见章鱼图功能） |
-| `POST /api/octopus/add` | 新增帮助记录 |
-| `POST /api/octopus/delete` | 删除帮助记录 |
-| `POST /api/octopus/records` | 按联系人查询帮助记录明细 |
-| `POST /api/pearl/resources` | 珍珠图聚合：人脉(contacts) + 技能(help_logs SKILL) + 信息/场所(resource_items) |
-| `POST /api/pearl/item/add` | 登记珍珠图资源（type=INFO/PLACE/SKILL，name 必填，contactId 可选） |
+| `POST /api/pearl/resources` | 珍珠图聚合：25 组（ESSENTIAL 内圈 + IDEAL 外圈）+ legacyGroups（历史资源） |
+| `POST /api/pearl/connection-types` | 获取 25 类连接类型列表（code/label/category/suggestIntervalMonth） |
+| `POST /api/pearl/item/add` | 登记珍珠图资源（connectionType 必填，type 可选，name 必填，contactId 可选） |
 | `POST /api/pearl/item/delete` | 删除登记的珍珠图资源（itemId） |
+| `POST /api/pearl/item/update-priority` | 手动覆盖优先级（itemId/priority 1-3），同步 valueScore |
+| `POST /api/pearl/interaction/add` | 记录互动（itemId/interactionType/content），更新价值分并关闭 PENDING 提醒 |
+| `POST /api/pearl/interaction/list` | 互动历史分页（itemId/page/size） |
+| `POST /api/pearl/reminder/list` | 待办提醒列表（PENDING） |
 | `POST /api/ability/map` | 能力图：SKILL 帮助记录按联系人聚合为能力节点 |
 
 **`/api/pearl/resources` 响应结构：**
@@ -1111,18 +1112,88 @@ score 范围：0-100（整数）
   "code": 200,
   "data": {
     "groups": [
-      { "type": "PERSON", "typeName": "人脉", "items": [{ "id": 1, "name": "张三", "avatar": "", "relationshipType": "好友" }] },
-      { "type": "SKILL", "typeName": "技能", "items": [{ "contactId": 2, "name": "李四", "skillCount": 3, "skills": ["画画", "辅导"], "lastHelpedAt": "2026-08-01 10:00:00" }] },
-      { "type": "INFO", "typeName": "信息", "items": [{ "id": 3, "name": "升学政策", "description": "..." }] },
-      { "type": "PLACE", "typeName": "场所", "items": [{ "id": 4, "name": "社区图书馆", "description": "..." }] }
+      {
+        "type": "MEDICAL", "typeName": "医疗", "category": "ESSENTIAL", "ring": "inner",
+        "items": [
+          {
+            "id": 1, "name": "社区王医生", "description": "儿科主治", "avatar": null,
+            "valueScore": 72, "priority": 1, "contactId": 5,
+            "lastInteractionAt": "2026-08-15T10:30:00",
+            "interactionCount": 8, "daysSinceLast": 26
+          }
+        ]
+      }
+      // ... 共 25 组，为空时 items=[]
+    ],
+    "legacyGroups": [
+      { "type": "PERSON", "typeName": "人脉", "items": [...] },
+      { "type": "SKILL", "typeName": "技能", "items": [...] },
+      { "type": "INFO", "typeName": "信息", "items": [...] },
+      { "type": "PLACE", "typeName": "场所", "items": [...] }
     ]
   }
 }
 ```
 
+**价值分算法**（`/api/pearl/interaction/add` 后自动重算）：
+- 类型基础权重：ESSENTIAL=30，IDEAL=20
+- 近 90 天互动次数 × 5，上限 30
+- 最近互动时效性：≤30天=+20，≤90天=+10，≤180天=+5
+- 互动总量 × 2，上限 20
+- 总分 0-100，`priority=1`（高/大珍珠）→ valueScore≥70，`priority=2`（中）→ 40-69，`priority=3`（低/小珍珠）→ <40
+
 **`/api/ability/map` 响应结构：** `data` 为数组，元素结构同 SKILL 组 items（contactId/name/avatar/relationshipType/skillCount/skills/lastHelpedAt）。
 
-**「已记录关系三图 API 端点 — 禁止重复注册。」**
+**珍珠图前端组件：** `PearlDiagram.vue`（Canvas 2D，两层同心圆，内圈 radiusPct=0.28 / 外圈 0.55，珍珠半径按 priority/valueScore 映射 8-26px）。
+
+**珍珠图定时提醒：** `PearlReminderScheduledTask` 每日 08:00 执行，遍历 connection_type 非空资源，daysSinceLast ≥ suggestIntervalMonth×30 时生成 PENDING 提醒。
+
+**珍珠图交互流程：** 打开页 → 加载 resources → 渲染两层同心圆 → 点击珍珠弹窗（联系/优先级/删除）→ 记录互动 → 重算价值分 → 逾期角标红点。
+
+**`/api/pearl/interaction/add` 请求体：** `{ "itemId": 1, "interactionType": "WECHAT", "content": "咨询过敏问题" }`
+interactionType 取值：`PHONE` / `WECHAT` / `MEETING` / `OTHER`。
+
+**`/api/pearl/item/update-priority` 请求体：** `{ "itemId": 1, "priority": 1 }`（1=高/大珍珠，2=中，3=低/小珍珠）。
+
+**珍珠图前端页面：**
+- 珍珠图：`pages/action-detail/index.vue`（内嵌 `PearlDiagram.vue` 组件）
+- 登记资源：`pages/action-detail/pearl-add-resource.vue`（25 类类型分组选择器）
+- 互动提醒：`pages/pearl-reminders/index.vue`（PENDING 提醒列表）
+
+**前端 API（`utils/api.js`）：**
+- `getPearlResources()`
+- `getConnectionTypes()`
+- `addPearlResource(data)` （data.connectionType 必填）
+- `deletePearlResource(data)`
+- `addPearlInteraction(data)`
+- `getPearlInteractionList(data)`
+- `getPearlReminders()`
+- `updatePearlPriority(data)`
+
+**已记录珍珠图/能力图 API 端点 — 禁止重复注册。**
+
+### 4.40 关键人拓展章鱼图（`/api/octopus/*`）
+
+**替代旧章鱼图（help_logs）**。核心：成效记录 → 关键人画像 → 高频词分析 → 拓展方向。
+
+| 路径 | 说明 |
+|------|------|
+| `POST /api/octopus/tentacles` | ⚠️ **已废弃（410）** 旧章鱼图：触手榜 |
+| `POST /api/octopus/add` | ⚠️ **已废弃（410）** 旧章鱼图：新增帮助记录 |
+| `POST /api/octopus/delete` | ⚠️ **已废弃（410）** 旧章鱼图：删除帮助记录 |
+| `POST /api/octopus/records` | ⚠️ **已废弃（410）** 旧章鱼图：帮助记录明细 |
+| `POST /api/octopus/effect/list` | 成效记录分页列表（支持 effect_type 筛选） |
+| `POST /api/octopus/effect/add` | 新增成效（member_order_id + effect_type bitmask + amount + desc） |
+| `POST /api/octopus/effect/delete` | 删除成效（级联关系） |
+| `POST /api/octopus/key-person/add` | 新增关键人（姓名/单位/部门/职务/初识场合/如何认识） |
+| `POST /api/octopus/key-person/update` | 修改关键人画像 |
+| `POST /api/octopus/key-person/delete` | 删除关键人（级联关系） |
+| `POST /api/octopus/effect/key-persons` | 某成效的关键人列表 |
+| `POST /api/octopus/analysis/keywords` | 高频词统计（单位/部门/职务/场合/路径） |
+| `POST /api/octopus/analysis/summary` | 高频词提炼 ≤8 个拓展方向 |
+| `POST /api/octopus/expansion/suggest` | 基于分析推荐关键人画像模板（预填） |
+
+> **已记录关键人拓展 API 端点 — 禁止重复注册。**
 
 ## 六、待清理的废弃接口
 
@@ -1136,6 +1207,7 @@ score 范围：0-100（整数）
 | `TeacherController` | 全部 `/api/teacher/*` 方法 | `/api/guide/families/*` | @Deprecated + UnsupportedOperationException | 确认规划师端无调用 |
 | `DanAssessmentController` | `/current` | — | 需验证 | 无前端调用方 |
 | `NoticeController` | `GET /list`（违反 POST 规范） | `/api/admin/notices/list` | 已修复：@Deprecated + 410 | 可删除 |
+| `OctopusController` | `/tentacles`, `/add`, `/delete`, `/records` | `/api/octopus/effect/*`, `/api/octopus/key-person/*` | @Deprecated + 410 ✓（2026-09-10 替换为关键人拓展） | 确认前端无调用（旧页面已删除） |
 
 ---