# Enagic 本希甄选 - 模块详细设计

> 本文档为 SPEC.md 的补充，详细说明各功能模块的业务逻辑、业务规则和技术实现细节。

---

## 一、AI 数字人模块

### 1.1 功能概述

AI 数字人是基于大语言模型的智能对话系统，为用户提供产品咨询、健康建议、常见问题解答等服务。

### 1.2 业务规则

#### 1.2.1 对话流程规则

| 步骤 | 说明 | 超时/限制 |
|------|------|----------|
| 1. 用户输入 | 用户发送文本消息 | 最大 500 字符 |
| 2. 敏感词过滤 | 检查消息是否包含敏感词 | 敏感词库从 Redis 加载 |
| 3. 知识库检索 | 匹配相关知识条目 | 返回最多 5 条 |
| 4. Context 构建 | 将知识库内容拼接为 prompt | 知识库内容截断至 2000 字符 |
| 5. AI 调用 | 请求大模型生成回答 | 超时 30 秒 |
| 6. 结果过滤 | 检查回答是否包含敏感词 | 过滤后返回 |
| 7. 记录存储 | 存储对话到数据库 | 异步写入 |

#### 1.2.2 敏感词过滤规则

- **数据源**：Redis key `enagic:ai:sensitive`，格式为逗号分隔的词列表
- **匹配规则**：精确匹配，不区分大小写
- **处理结果**：包含敏感词的消息直接返回固定提示，不调用 AI

#### 1.2.3 知识库检索规则

- **检索策略**：基于知识库条目的使用次数（useCount）排序，优先返回热门知识
- **匹配逻辑**：当前采用关键词匹配，可升级为向量检索
- **返回限制**：最多返回 5 条知识条目

#### 1.2.4 对话历史规则

- **存储**：每条对话存储到 `li_enagic_ai_conversation` 表
- **查询**：按 memberId + sessionId 分页查询
- **保留策略**：保留最近 100 条会话，超出自动清理

### 1.3 API 详细设计

#### 1.3.1 AI 对话接口

```
POST /enagic/buyer/ai/chat
```

**请求参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| question | String | 是 | 用户问题，最大 500 字符 |
| sessionId | String | 否 | 会话 ID，用于关联历史 |

**响应参数：**

| 参数名 | 类型 | 说明 |
|--------|------|------|
| answer | String | AI 回答内容 |
| sessionId | String | 会话 ID |

**错误码：**

| 错误码 | 说明 |
|--------|------|
| 1001 | 敏感词过滤拦截 |
| 1002 | AI 服务调用超时 |
| 1003 | AI 服务返回异常 |

#### 1.3.2 对话历史接口

```
GET /enagic/buyer/ai/history
```

**请求参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| sessionId | String | 否 | 会话 ID |
| page | Integer | 否 | 页码，默认 1 |
| pageSize | Integer | 否 | 每页条数，默认 10 |

### 1.4 知识库管理

#### 1.4.1 知识分类

| 分类编码 | 分类名称 | 说明 |
|----------|----------|------|
| PRODUCT | 产品知识 | 产品功效、使用方法、注意事项 |
| HEALTH | 健康知识 | 健康信息、营养建议 |
| FAQ | 常见问题 | 常见问题解答 |

#### 1.4.2 知识库状态

| 状态 | 说明 |
|------|------|
| ACTIVE | 启用，参与知识检索 |
| INACTIVE | 停用，不参与检索 |

---

## 二、健康布施者模块

### 2.1 功能概述

健康布施者是平台的分销/推广角色，负责邀请客户、推广产品、 提供售后服务。区别于普通分销商，健康布施者有永久绑定关系和荣誉体系。

### 2.2 业务规则

#### 2.2.1 邀请关系建立规则

```
用户扫码 → 解析 URL 参数 inviter_id → 写入 li_member.health_advisor_id → 永久绑定
```

**触发条件：**
- 新用户通过带参数的二维码注册
- 新用户通过带邀请链接的分享页面注册

**永久绑定：**
- 关系一旦建立，不可解除
- 即使健康布施者注销账号，客户关系仍然保留
- 通过 `li_member.permanent_bind = true` 标记

#### 2.2.2 勋章体系规则

| 勋章等级 | 勋章类型 | 触发条件 | 积分奖励 | 显示图标 |
|----------|----------|----------|----------|----------|
| 一星 | STAR_1 | 首次成功邀请 1 人 | +10 分 | ⭐ |
| 二星 | STAR_2 | 累计邀请 5 人 | +50 分 | ⭐⭐ |
| 三星 | STAR_3 | 累计邀请 20 人 | +200 分 | ⭐⭐⭐ |
| 宗师 | MASTER | 累计邀请 50 人 | +500 分 | 👑 |

**勋章发放时机：**
- 实时检测：每次邀请成功后立即检查是否满足升级条件
- 自动发放：满足条件后自动创建 `li_enagic_advisor_medal` 记录

#### 2.2.3 顾问积分规则

**积分来源：**

| 来源 | 积分规则 |
|------|----------|
| 邀请客户 | +10 分/次 |
| 勋章升级 | 参见勋章体系表格 |
| 客户消费 | 消费金额 × 1% = 积分 |

**积分用途：**
- 荣誉排名展示
- 平台活动参与资格

#### 2.2.4 客户列表查询规则

- 仅返回该健康布施者邀请的客户
- 支持按注册时间排序
- 分页展示，每页默认 10 条

### 2.3 API 详细设计

#### 2.3.1 获取布施者信息

```
GET /enagic/buyer/advisor/info
```

**响应参数：**

| 参数名 | 类型 | 说明 |
|--------|------|------|
| id | Long | 布施者 ID |
| memberName | String | 会员名称 |
| name | String | 真实姓名 |
| medalLevel | String | 当前勋章等级 |
| totalInvites | Integer | 累计邀请人数 |
| availableCommission | BigDecimal | 可用佣金 |
| advisorCredits | Integer | 顾问积分 |
| status | String | 状态 ACTIVE/INACTIVE |

#### 2.3.2 申请成为布施者

```
POST /enagic/buyer/advisor/apply
```

**请求参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| name | String | 是 | 真实姓名 |
| idNumber | String | 是 | 身份证号（实名认证） |

**业务规则：**
- 同一会员只能申请一次
- 申请后自动审核通过（可根据需要改为人工审核）

#### 2.3.3 邀请二维码

```
GET /enagic/buyer/advisor/invite-qr
```

**返回：** 二维码图片（base64 或 URL）

**参数：** 自动使用当前登录用户的 memberId 作为邀请人

---

## 三、VIP 会员模块

### 3.1 功能概述

VIP 会员是平台的高价值客户群体，享受专属权益。与 Lilishop 原生 VIP 不同，Enagic VIP 无到期时间，采用分享激励模式。

### 3.2 业务规则

#### 3.2.1 VIP 开通规则

- 用户选择 VIP 配置（价格、权益）
- 支付完成后创建 `li_enagic_member_vip` 记录
- 无到期时间限制（validityDays = -1 表示永久）

#### 3.2.2 VIP 配置规则

| 字段 | 类型 | 说明 |
|------|------|------|
| name | String | 配置名称，如"银卡 VIP"、"金卡 VIP" |
| vipLevel | Integer | VIP 等级，1-10 |
| price | BigDecimal | 价格，单位元 |
| upgradeCondition | String | 升级条件描述，如"累计消费满 5000" |
| validityDays | Integer | 有效期天数，-1 表示永久 |
| benefits | String | 权益说明，JSON 数组格式 |
| status | String | OPEN/CLOSE |

#### 3.2.3 感恩提醒规则

**触发条件：**
- VIP 客户连续 30 天无分享行为（无商品分享、无活动分享）
- 定时任务扫描所有 VIP 客户

**提醒内容：**
```
亲爱的 VIP 会员，感谢您一直以来的支持！
您已 X 天没有分享好物了，快去分享心仪的商品吧~
```

**发送方式：**
- 站内消息（利用 Lilishop 消息中心）
- 微信公众号模板消息（需配置）

#### 3.2.4 VIP 权益

| 权益类型 | 说明 |
|----------|------|
| 折扣 | 商品购买享 X 折 |
| 积分 | 消费获得双倍积分 |
| 专属客服 | 专属客服通道 |
| 免费配送 | 订单免配送费 |
| 优先发货 | 订单优先处理 |

### 3.3 API 详细设计

#### 3.3.1 获取 VIP 信息

```
GET /enagic/buyer/vip/info
```

**响应参数：**

| 参数名 | 类型 |说明 |
|--------|------|------|
| vipLevel | Integer | 当前 VIP 等级 |
| vipName | String | VIP 名称 |
| openTime | LocalDateTime | 开通时间 |
| nextGratitudeRemindTime | LocalDateTime | 下次感恩提醒时间 |

#### 3.3.2 开通 VIP

```
POST /enagic/buyer/vip/open
```

**请求参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| configId | Long | 是 | VIP 配置 ID |

**业务规则：**
- 检查配置是否存在且状态为 OPEN
- 检查用户是否已经是 VIP（已开通则提示）
- 支付完成后正式开通

---

## 四、抵扣金模块

### 4.1 功能概述

抵扣金是平台赠送或奖励的虚拟货币，可用于订单支付抵扣。

### 4.2 业务规则

#### 4.2.1 抵扣金获取

| 来源 | 规则 |
|------|------|
| 充值赠送 | 后台配置赠送比例，如充值 100 送 20 |
| 活动奖励 | 平台活动奖励 |
| 退款返还 | 订单退款时优先退还原抵扣金 |

#### 4.2.2 抵扣金使用

- 订单支付时可使用抵扣金抵扣部分金额
- 最低抵扣 1 元（不能全部使用抵扣金）
- 抵扣比例：订单金额的 0-100%（可配置）

#### 4.2.3 冻结机制

**下单时冻结：**
- 用户提交订单时，计算抵扣金可用余额
- 冻结金额 = 订单应付抵扣金
- 冻结后不可用于其他订单

**解冻时机：**
- 订单完成：冻结金额扣除，抵扣金正式消费
- 订单取消：冻结金额解冻，恢复可用余额

#### 4.2.4 流水类型

| 类型 | 说明 | 金额方向 |
|------|------|----------|
| RECHARGE | 充值 | + |
| ORDER_DEDUCT | 订单抵扣 | - |
| REFUND | 退款返还 | + |
| FROZEN | 冻结 | - (冻结) |
| UNFREEZE | 解冻 | + (解冻) |
| ACTIVITY_REWARD | 活动奖励 | + |

### 4.3 API 详细设计

#### 4.3.1 获取抵扣金账户

```
GET /enagic/buyer/deduction/info
```

**响应参数：**

| 参数名 | 类型 | 说明 |
|--------|------|------|
| deductionBalance | BigDecimal | 可用余额 |
| frozenBalance | BigDecimal | 冻结金额 |

#### 4.3.2 获取抵扣金流水

```
GET /enagic/buyer/deduction/log
```

**响应参数：**

| 参数名 | 类型 | 说明 |
|--------|------|------|
| amount | BigDecimal | 变动金额（正数增加，负数减少） |
| type | String | 流水类型 |
| orderSn | String | 关联订单号 |
| remark | String | 备注 |
| createTime | LocalDateTime | 创建时间 |

---

## 五、客户运维模块

### 5.1 功能概述

客户运维是针对购买客户的售后服务系统，通过流程化的节点提醒，提升客户体验。

### 5.2 业务规则

#### 5.2.1 运维流程定义

**数据结构（JSON）：**

```json
{
  "flowName": "标准30天运维流程",
  "description": "适用于常规商品的运维流程",
  "nodes": [
    {
      "name": "发货提醒",
      "day": 1,
      "content": "您的订单已发货，请注意查收",
      "remindType": "WECHAT_MSG"
    },
    {
      "name": "收货确认",
      "day": 3,
      "content": "请确认收货并开始使用产品",
      "remindType": "WECHAT_MSG"
    },
    {
      "name": "使用指导",
      "day": 7,
      "content": "产品使用指导（可调用 AI）",
      "remindType": "AI_REMINDER"
    },
    {
      "name": "使用回访",
      "day": 30,
      "content": "使用体验回访",
      "remindType": "WECHAT_MSG"
    }
  ]
}
```

**节点属性：**

| 属性 | 类型 | 说明 |
|------|------|------|
| name | String | 节点名称 |
| day | Integer | 距离发货的天数 |
| content | String | 提醒内容 |
| remindType | String | 提醒类型：WECHAT_MSG/AI_REMINDER/SMS |

#### 5.2.2 运维计划自动生成

**触发时机：**
- 订单状态变为"已发货"
- RocketMQ 消费 `ORDER_DELIVERED` 事件

**生成逻辑：**
1. 获取订单对应的客户
2. 查找客户所属健康布施者关联的运维流程
3. 如无则使用系统默认运维流程
4. 创建 `li_enagic_operation_plan` 记录
5. 初始化第一个节点

#### 5.2.3 节点执行规则

**执行时机：**
- 定时任务扫描所有 IN_PROGRESS 状态的计划
- 当 `nextNodeTime <= now` 时，触发节点执行

**执行动作：**
- 发送微信通知/AI 提醒/短信
- 记录 `li_enagic_operation_record`
- 更新 `currentNodeIndex` 和 `nextNodeTime`

#### 5.2.4 客户自动转移

**触发条件：**
- 连续 3 次节点被跳过（无人服务）
- 判定方式：skipCount >= 3

**转移流程：**
1. 创建 `li_enagic_member_transfer` 记录
2. 标记原健康布施者与客户的绑定关系终止
3. 客户标记为"待分配"，可分配给其他健康布施者
4. 运维计划状态变更为 TRANSFERRED

### 5.3 API 详细设计

#### 5.3.1 获取我的运维计划

```
GET /enagic/buyer/operation/my-plans
```

**请求参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| memberId | Long | 是 | 会员 ID |
| status | String | 否 | 状态筛选 |
| pageNum | Integer | 否 | 页码 |
| pageSize | Integer | 否 | 每页条数 |

**响应参数：**

| 参数名 | 类型 | 说明 |
|--------|------|------|
| id | Long | 计划 ID |
| flowName | String | 流程名称 |
| currentNodeName | String | 当前节点 |
| status | String | 状态 |
| nextNodeTime | LocalDateTime | 下次节点时间 |

#### 5.3.2 手动触发提醒

```
POST /enagic/manager/operation/plan/remind
```

**请求参数：**

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Long | 是 | 计划 ID |

---

## 六、素材二维码模块

### 6.1 功能概述

素材二维码用于追踪内容的传播效果和用户邀请关系。

### 6.2 业务规则

#### 6.2.1 二维码生成规则

- 用户打开素材详情页时，后台自动生成带参数的二维码
- 二维码内容包含：素材 ID + 分享者 memberId + 有效期
- 二维码存储到 `li_enagic_article_qr` 表

#### 6.2.2 URL 参数格式

```
pages/article/detail?id={articleId}&inviter={memberId}&expire={timestamp}
```

#### 6.2.3 邀请关系绑定

- 用户扫码后跳转小程序
- 小程序读取 URL 参数
- 用户注册/登录后自动绑定关系
- 调用 `/enagic/buyer/advisor/bind-customer` 完成绑定

#### 6.2.4 素材可见性

- 商家上传素材时可设置 `view_role`
- ALL：所有用户可见
- CONSUMER_ONLY：仅消费商可见
- 普通用户只能看到 ALL 的素材

### 6.3 API 详细设计

#### 6.3.1 获取素材二维码

```
GET /enagic/buyer/article/qr/{articleId}
```

**响应：**
- 二维码图片（base64 或 URL）
- 或返回小程序页面路径用于生成小程序码

---

## 七、模块间交互关系

```
┌─────────────────┐
│   用户行为      │
└────────┬────────┘
         │
         ▼
┌─────────────────────────────────────────┐
│           订单模块（复用 Lilishop）      │
│  订单创建 → 订单支付 → 订单发货 → 完成   │
└────────┬────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────┐
│       RocketMQ 事件 (enagic-consumer)  │
├─────────────────────────────────────────┤
│ ORDER_CREATED → 抵扣金冻结               │
│ ORDER_DELIVERED → 创建运维计划          │
│ ORDER_COMPLETED → 抵扣金确认扣款        │
│ ORDER_CANCELLED → 抵扣金解冻            │
└────────┬────────────────────────────────┘
         │
    ┌────┴────┐
    │         │
    ▼         ▼
┌───────┐ ┌───────┐
│运维计划│ │健康布施者│
│提醒   │ │业绩统计│
└───────┘ └───────┘
```

---

## 八、定时任务清单

| 任务名称 | cron 表达式 | 功能 | 处理数据量 |
|----------|-------------|------|------------|
| enagic-operation-remind | 0 0 9 * * ? | 运维计划节点提醒 | 扫描所有 IN_PROGRESS 计划 |
| enagic-gratitude-remind | 0 0 10 * * ? | VIP 感恩提醒 | 扫描所有 VIP 客户 |
| enagic-transfer-check | 0 0 12 * * ? | 客户自动转移检查 | 扫描所有跳过次数 >=3 的计划 |
| enagic-medal-check | 0 0 8 * * ? | 勋章发放检查 | 扫描所有健康布施者 |
| enagic-behavior-clean | 0 0 2 * * ? | 行为日志清理 | 删除 90 天前的日志 |

---

## 九、模块配置清单

### 9.1 AI 配置

```yaml
enagic:
  ai:
    provider: siliconflow  # 或 aliyun
    api-key: ${AI_API_KEY}
    model: Qwen/Qwen2.5-7B-Instruct
    base-url: https://api.siliconflow.cn/v1
    timeout: 30000
    max-context-length: 2000
```

### 9.2 健康布施者配置

```yaml
enagic:
  health-advisor:
    enabled: true
    permanent-bind: true      # 是否永久绑定
    invite-bonus-points: 10   # 邀请奖励积分
```

### 9.3 VIP 配置

```yaml
enagic:
  vip:
    enabled: true
    no-expiry: true           # 无到期时间模式
    gratitude-remind-days: 30 # 感恩提醒周期（天）
```

### 9.4 抵扣金配置

```yaml
enagic:
  deduction:
    enabled: true
    min-deduction: 1           # 最低抵扣金额
    max-deduction-ratio: 100   # 最高抵扣比例（百分比）
```

### 9.5 运维配置

```yaml
enagic:
  operation:
    enabled: true
    default-flow-id: 1         # 默认运维流程 ID
    skip-threshold: 3          # 跳过次数阈值，触发转移
```

---

*文档版本：V1.0*
*创建日期：2026-05-08*