|
|
@@ -77,6 +77,57 @@
|
|
|
| | `POST /api/octopus/analysis/summary` | 基于高频词提炼 ≤8 个拓展方向（单位/行业/身份/职业维度聚合） |
|
|
|
| **4. 拓展关键人** | `POST /api/octopus/expansion/suggest` | 根据分析结果推荐新关键人画像模板（预填行业/职位等） |
|
|
|
|
|
|
+### API 响应约定
|
|
|
+
|
|
|
+**所有列表接口**：统一 `Result<{list, total, page, pageSize}>`。
|
|
|
+
|
|
|
+**`effect/list` 每条记录**：
|
|
|
+```json
|
|
|
+{
|
|
|
+ "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` 每条记录**：
|
|
|
+```json
|
|
|
+{
|
|
|
+ "id": 200,
|
|
|
+ "name": "张三",
|
|
|
+ "organization": "XX公司",
|
|
|
+ "department": "市场部",
|
|
|
+ "title": "总监",
|
|
|
+ "firstMeetScene": "家长会",
|
|
|
+ "knowWay": "孩子班主任介绍认识",
|
|
|
+ "contactInfo": "138xxxx",
|
|
|
+ "role": 1,
|
|
|
+ "roleName": "引荐",
|
|
|
+ "createdAt": "..."
|
|
|
+}
|
|
|
+```
|
|
|
+> role 1=引荐 2=决策 3=其他，同时返回 roleName。
|
|
|
+
|
|
|
+**`analysis/summary` 返回**：
|
|
|
+```json
|
|
|
+{
|
|
|
+ "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）
|
|
|
@@ -142,18 +193,31 @@
|
|
|
|
|
|
| 步骤 | 动作 |
|
|
|
|------|------|
|
|
|
-| 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 | 灰度验证 → 全量切换 |
|
|
|
+| 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. 兼容性与约束清单
|
|
|
+## 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` |
|
|
|
|
|
|
+### 约束清单
|
|
|
- [x] 无 `child_id`/`family_id`，纯 `user_id` 隔离
|
|
|
- [x] 统一 `@PostMapping`，`Result<T>` code=200 成功
|
|
|
- [x] MyBatis-Plus `@TableName` + `@TableId(type=IdType.AUTO)`
|
|
|
@@ -161,18 +225,22 @@
|
|
|
- [x] 小程序约束：禁 `?.`、禁 CSS Grid、禁 `:key` 表达式、禁 `new Date(string)`、统一日期格式化
|
|
|
- [x] 现有 `MemberSubscriptionOrder` 只读关联，不修改其结构
|
|
|
- [x] 迁移幂等：`CREATE TABLE IF NOT EXISTS` + try-catch 忽略已存在
|
|
|
+- [x] 接口文档与代码同步：`API_REFERENCE.md` 必须随接口上线更新
|
|
|
|
|
|
---
|
|
|
|
|
|
-## 8. 规格自检（内联已修复）
|
|
|
+## 8. 规格自检（第2轮内联修复）
|
|
|
|
|
|
| 检查项 | 结果 |
|
|
|
|--------|------|
|
|
|
-| 占位符/待定 | 无 |
|
|
|
-| 内部一致性 | 数据模型/API/前端三节互相对齐 |
|
|
|
+| 占位符/待定 | 无，所有枚举/bitmask/响应结构均已明确 |
|
|
|
+| 内部一致性 | 数据模型/API/前端三节互相对齐，API 响应结构与前端三态模板一一对应 |
|
|
|
| 范围检查 | 单一规格覆盖完整替换链路，无需拆分子项目 |
|
|
|
-| 模糊性 | 所有枚举值、bitmask 定义、索引策略均已明确 |
|
|
|
-| YAGNI | 移除不必要的字段（如 contact_info 可选、effect_desc 可空） |
|
|
|
+| 模糊性 | bitmask 语义、role 枚举、≤8 方向、预填字段均明确定义 |
|
|
|
+| YAGNI | 移除不必要字段（contact_info 可选、effect_desc 可空）；analysis/keywords 仅 summary 驱动，不额外暴露 |
|
|
|
+| 错误处理 | 统一 Toast 三态（成功/失败/网络），已写入第7节 |
|
|
|
+| 权限 | 所有登录用户可用，无额外角色检查，已写入第7节 |
|
|
|
+| 旧文件清理 | 删除旧组件 + 标记 Controller 410 + 保留 contact_help_logs 归档，已写入第6节 |
|
|
|
|
|
|
---
|
|
|
|
Sisyphus Agent