docs: 关键人拓展章鱼图替换设计规格

docs/superpowers/specs/2026-09-10-key-person-expansion-octopus-design.md

@@ -0,0 +1,183 @@
+# 关键人拓展章鱼图 替换设计规格
+
+> 替换现有"帮助记录型章鱼图"（contact_help_logs + OctopusDiagram），上线"关键人拓展型章鱼图"。
+> 面向小程序端用户（家长/孩子），基于会员成交订单挖掘关键人，四步法 + 高频词分析 + ≤8 个拓展方向。
+
+---
+
+## 1. 背景与目标
+
+| 项目 | 说明 |
+|------|------|
+| **替换对象** | 现有 `contact_help_logs` 表、`OctopusController`、`OctopusDiagram.vue`（帮助记录型：谁帮过我） |
+| **新定位** | 关键人拓展图谱：成效对象(会员客户) → 类型(金额大/频次高/新成交) → 关键人(单位/部门/职务/初识场合/如何认识) → 四步法分析 → 高频词提炼 → ≤8 个拓展方向 |
+| **使用端/角色** | 小程序端，面向用户（家长/孩子），非规划师 |
+| **数据隔离** | 以 `user_id` 为唯一租户键，无 child/family 概念 |
+
+---
+
+## 2. 数据模型
+
+### 2.1 三张核心表
+
+#### `octopus_effect_record`（成效记录）
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | BIGINT PK | 自增主键 |
+| `user_id` | BIGINT NOT NULL | 当前用户（租户键） |
+| `member_order_id` | BIGINT | 关联 `MemberSubscriptionOrder.id`（会员订单），可空 |
+| `effect_type` | TINYINT UNSIGNED | 成效类型 bitmask：1=金额大, 2=频次高, 4=新成交（支持多选） |
+| `effect_amount` | DECIMAL(10,2) | 成效金额（元） |
+| `effect_desc` | VARCHAR(500) | 成效描述 |
+| `status` | TINYINT | 1=有效, 0=无效 |
+| `created_at` | DATETIME | 创建时间 |
+| **索引** | `idx_oer_user`(`user_id`), `idx_oer_order`(`member_order_id`) | |
+
+#### `octopus_key_person`（关键人画像）
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | BIGINT PK | 自增主键 |
+| `user_id` | BIGINT NOT NULL | 当前用户（租户键） |
+| `name` | VARCHAR(64) NOT NULL | 关键人姓名 |
+| `organization` | VARCHAR(128) | 单位/公司 |
+| `department` | VARCHAR(64) | 部门 |
+| `title` | VARCHAR(64) | 职务/职位 |
+| `first_meet_scene` | VARCHAR(128) | 初识场合 |
+| `know_way` | VARCHAR(255) | 如何认识（认识路径） |
+| `contact_info` | VARCHAR(255) | 联系方式（可选） |
+| `created_at` | DATETIME | 创建时间 |
+| **索引** | `idx_okp_user`(`user_id`), `idx_okp_org`(`organization`) | |
+
+#### `octopus_effect_key_person`（成效-关键人 多对多）
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `id` | BIGINT PK | 自增主键 |
+| `effect_id` | BIGINT NOT NULL | 关联 `octopus_effect_record.id` |
+| `key_person_id` | BIGINT NOT NULL | 关联 `octopus_key_person.id` |
+| `role` | TINYINT | 1=引荐, 2=决策, 3=其他 |
+| `created_at` | DATETIME | 创建时间 |
+| **索引** | `idx_oekp_effect`(`effect_id`), `idx_oekp_person`(`key_person_id`), `uk_oekp`(`effect_id`,`key_person_id`) UNIQUE | |
+
+---
+
+## 3. API 接口清单（四步法对应）
+
+统一 `POST` + `Result<T>` + `user_id` 从 JWT 解析。
+
+| 步骤 | 接口 | 说明 |
+|------|------|------|
+| **1. 盘点项目** | `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` | 删除成效（级联删除关联关系） |
+| **2. 找关键人** | `POST /api/octopus/key-person/add` | 手工填：name/org/dept/title/first_meet_scene/know_way/contact_info |
+|  | `POST /api/octopus/key-person/update` | 修改关键人画像 |
+|  | `POST /api/octopus/key-person/delete` | 删除关键人（级联关系） |
+|  | `POST /api/octopus/effect/key-persons` | 查看某成效的关键人列表 |
+| **3. 分析关键人** | `POST /api/octopus/analysis/keywords` | 统计用户所有关键人的高频词（org/industry/identity/title/scene/way），返回 Top 词频 |
+|  | `POST /api/octopus/analysis/summary` | 基于高频词提炼 ≤8 个拓展方向（单位/行业/身份/职业维度聚合） |
+| **4. 拓展关键人** | `POST /api/octopus/expansion/suggest` | 根据分析结果推荐新关键人画像模板（预填行业/职位等） |
+
+---
+
+## 4. 前端画图/交互（小程序 Canvas，替换 OctopusDiagram）
+
+### 页面入口
+- `pages/action-detail/index.vue` 内嵌，替换现有 `OctopusDiagram` 区块
+
+### 三态模板
+| 态 | 触发条件 | UI |
+|----|----------|----|
+| 加载中 | 数据请求中 | "加载关键人拓展图..." |
+| 空态 | 无成效记录 | "暂无成效记录" + "➕ 记录成效" 按钮 → 跳转录入页 |
+| 图谱态 | 有数据 | 核心画布 |
+
+### 画布呈现（三层结构）
+```
+中心节点："我"（当前用户）
+  │
+  ├─ 第1层：成效记录节点（卡片/气泡，标签：金额大/频次高/新成交）
+  │    └─ 点击 → 展开该成效的关键人列表
+  │
+  ├─ 第2层：关键人节点（头像+姓名+单位/职务，边标记：引荐/决策）
+  │    └─ 点击 → 弹窗完整画像（单位/部门/职务/初识场合/如何认识/联系方式）
+  │
+  └─ 第3层：拓展方向节点（虚线/浅色，≤8个，来源：analysis/summary）
+       └─ 点击 → 弹出"建议画像模板" → 一键预填 → 跳转"添加关键人"页
+```
+
+### 高频词 → 拓展方向的生成链路
+```
+用户所有关键人
+    │
+    ├─ analysis/keywords：统计 org/industry/identity/title/scene/way 词频
+    │
+    ├─ analysis/summary：聚合维度（单位/行业/身份/职业）提炼 Top 8 方向
+    │
+    └─ expansion/suggest：为每个方向生成"建议画像模板"（预填行业/职位等）
+```
+
+### 交互细节
+- 长按/右上角 "重新分析" → 触发 `analysis/summary` 刷新
+- 空态/加载态复用 `OctopusDiagram` 的三态模板风格
+- Canvas `type="2d"` + `uni.createSelectorQuery().in(this).select('#canvas').fields({node:true,size:true,rect:true})` + dpr 自适应
+- 触摸命中测试 + 弹窗定位（同 `OctopusDiagram`/`PearlDiagram` 复用模式）
+
+---
+
+## 5. 样式规范
+
+| 项目 | 值 |
+|------|----|
+| 主色 | `#F97316`（暖橙） |
+| 次色 | `#F59E0B`(金)、`#10B981`(绿)、`#6366F1`(紫) |
+| 背景 | `#f5f5f5` 页面底，白底卡片圆角 16rpx |
+| 字体 | PingFang SC / 微软雅黑，14px 基准 |
+| 布局 | flexbox only，**禁 CSS Grid** |
+| 日期显示 | `yyyy-MM-dd HH:mm:ss` / `yyyy-MM-dd`（统一前端格式化，禁止 `toLocaleString`） |
+| 可选链 | **禁 `?.`**，用 `&&` 替代 |
+
+---
+
+## 6. 迁移与替换策略
+
+| 步骤 | 动作 |
+|------|------|
+| 1 | 后端新建 3 表迁移（`octopus_effect_record`/`octopus_key_person`/`octopus_effect_key_person`），写入 `DatabaseInitializer` 迁移 304+ |
+| 2 | 后端新建 Entity/Mapper/Service/Controller（`OctopusController` 重写或新建 `KeyPersonController`） |
+| 3 | 前端新建 `OctopusDiagram.vue`（替换旧组件）、成效录入页、关键人录入页 |
+| 4 | `pages/action-detail/index.vue` 替换引用 |
+| 5 | 旧 `contact_help_logs`、`OctopusController`、`OctopusDiagram.vue`、`octopus-add-help.vue`、`octopus-records.vue` 标记废弃（`@Deprecated` + 410），保留 1 版本后清理 |
+| 6 | `API_REFERENCE.md` 同步新接口，旧章鱼图接口标记废弃 |
+| 7 | 灰度验证 → 全量切换 |
+
+---
+
+## 7. 兼容性与约束清单
+
+- [x] 无 `child_id`/`family_id`，纯 `user_id` 隔离
+- [x] 统一 `@PostMapping`，`Result<T>` code=200 成功
+- [x] MyBatis-Plus `@TableName` + `@TableId(type=IdType.AUTO)`
+- [x] `@Resource` 注入，字段名匹配默认 Bean Name
+- [x] 小程序约束：禁 `?.`、禁 CSS Grid、禁 `:key` 表达式、禁 `new Date(string)`、统一日期格式化
+- [x] 现有 `MemberSubscriptionOrder` 只读关联，不修改其结构
+- [x] 迁移幂等：`CREATE TABLE IF NOT EXISTS` + try-catch 忽略已存在
+
+---
+
+## 8. 规格自检（内联已修复）
+
+| 检查项 | 结果 |
+|--------|------|
+| 占位符/待定 | 无 |
+| 内部一致性 | 数据模型/API/前端三节互相对齐 |
+| 范围检查 | 单一规格覆盖完整替换链路，无需拆分子项目 |
+| 模糊性 | 所有枚举值、bitmask 定义、索引策略均已明确 |
+| YAGNI | 移除不必要的字段（如 contact_info 可选、effect_desc 可空） |
+
+---
+
+## 9. 待用户审查
+
+规格已写入 `docs/superpowers/specs/2026-09-10-key-person-expansion-octopus-design.md`。
+
+请审查，如需修改请告诉我；批准后我将调用 `writing-plans` 创建实现计划。