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

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

替换现有"帮助记录型章鱼图"（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	根据分析结果推荐新关键人画像模板（预填行业/职位等）

API 响应约定

所有列表接口：统一 Result<{list, total, page, pageSize}>。

effect/list 每条记录：

{
  "id": 1,
  "memberOrderId": 100,
  "effectType": 7,
  "effectTypeList": ["金额大","频次高","新成交"],
  "effectAmount": 2500.00,
  "effectDesc": "...",
  "status": 1,
  "createdAt": "2026-09-01 10:00:00"
}

effectType 为 bitmask（1=金额大 2=频次高 4=新成交），同时返回解析后的 effectTypeList 供前端展示标签。

effect/key-persons 每条记录：

{
  "id": 200,
  "name": "张三",
  "organization": "XX公司",
  "department": "市场部",
  "title": "总监",
  "firstMeetScene": "家长会",
  "knowWay": "孩子班主任介绍认识",
  "contactInfo": "138xxxx",
  "role": 1,
  "roleName": "引荐",
  "createdAt": "..."
}

role 1=引荐 2=决策 3=其他，同时返回 roleName。

analysis/summary 返回：

{
  "directions": [
    { "dimension": "organization", "keyword": "重点小学家委会", "count": 12, "reason": "家长社群聚集地" },
    { "dimension": "title", "keyword": "教育从业者", "count": 8, "reason": "行业垂直人脉" }
  ]
}

directions 数组长度 ≤8，按 count 降序。

expansion/suggest 返回： 每个方向提供可直接用于 key-person/add 的请求体模板（organization/department/title/firstMeetScene/knowWay 均预填），前端一键点击后跳转到录入页并预填。

---

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+（先 grep 确认最新编号再递增）
2	后端新建 Entity/Mapper/Service/Controller（新建 KeyPersonController，不在 OctopusController 上改，保持职责清晰）
3	前端新建 OctopusDiagram.vue（全新实现，替换旧组件）、成效录入页、关键人录入页
4	pages/action-detail/index.vue 替换 <OctopusDiagram> 引用为新组件
5	旧文件处理：OctopusDiagram.vue / octopus-add-help.vue / octopus-records.vue 直接删除（不保留废弃版本）；OctopusController.java 标记 @Deprecated，所有接口返回 410 Gone + 新接口路径；contact_help_logs 表保留归档不删，DatabaseInitializer 中该迁移块注释掉（保持幂等）
6	API_REFERENCE.md 同步新接口；OctopusController 接口标记废弃，指向新 /api/octopus/effect/* 等路径
7	灰度验证（先测试库运行）→ 全量切换

---

7. 兼容性、权限与错误处理

权限

• 所有登录用户（家长/孩子端）均可使用，无需额外角色校验（JWT 拦截器已保证登录态）
• 数据严格按 user_id 隔离，不可跨用户访问

错误处理约定

场景	前端行为
接口返回 code ≠ 200	uni.showToast({ title: res.message, icon: 'none' })
网络异常	uni.showToast({ title: '网络错误', icon: 'none' })
删除成功	uni.showToast({ title: '已删除', icon: 'success' }) 后重载列表
保存成功	uni.showToast({ title: '保存成功', icon: 'success' }) 后 navigateBack

约束清单

• 无 child_id/family_id，纯 user_id 隔离
• 统一 @PostMapping，Result<T> code=200 成功
• MyBatis-Plus @TableName + @TableId(type=IdType.AUTO)
• @Resource 注入，字段名匹配默认 Bean Name
• 小程序约束：禁 ?.、禁 CSS Grid、禁 :key 表达式、禁 new Date(string)、统一日期格式化
• 现有 MemberSubscriptionOrder 只读关联，不修改其结构
• 迁移幂等：CREATE TABLE IF NOT EXISTS + try-catch 忽略已存在
• 接口文档与代码同步：API_REFERENCE.md 必须随接口上线更新

---

8. 规格自检（第2轮内联修复）

检查项	结果
占位符/待定	无，所有枚举/bitmask/响应结构均已明确
内部一致性	数据模型/API/前端三节互相对齐，API 响应结构与前端三态模板一一对应
范围检查	单一规格覆盖完整替换链路，无需拆分子项目
模糊性	bitmask 语义、role 枚举、≤8 方向、预填字段均明确定义
YAGNI	移除不必要字段（contact_info 可选、effect_desc 可空）；analysis/keywords 仅 summary 驱动，不额外暴露
错误处理	统一 Toast 三态（成功/失败/网络），已写入第7节
权限	所有登录用户可用，无额外角色检查，已写入第7节
旧文件清理	删除旧组件 + 标记 Controller 410 + 保留 contact_help_logs 归档，已写入第6节

---

9. 待用户审查

规格已写入 docs/superpowers/specs/2026-09-10-key-person-expansion-octopus-design.md。

请审查，如需修改请告诉我；批准后我将调用 writing-plans 创建实现计划。