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）：

{
  "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 事件

生成逻辑：

获取订单对应的客户
查找客户所属健康布施者关联的运维流程
如无则使用系统默认运维流程
创建 li_enagic_operation_plan 记录
初始化第一个节点

5.2.3 节点执行规则

执行时机：

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

执行动作：

发送微信通知/AI 提醒/短信
记录 li_enagic_operation_record
更新 currentNodeIndex 和 nextNodeTime

5.2.4 客户自动转移

触发条件：

连续 3 次节点被跳过（无人服务）
判定方式：skipCount >= 3

转移流程：

创建 li_enagic_member_transfer 记录
标记原健康布施者与客户的绑定关系终止
客户标记为"待分配"，可分配给其他健康布施者
运维计划状态变更为 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 配置

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 健康布施者配置

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

9.3 VIP 配置

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

9.4 抵扣金配置

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

9.5 运维配置

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

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

SPEC_DETAIL.md 17 KB Historia Czysty

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

一、AI 数字人模块

1.1 功能概述

1.2 业务规则

1.2.1 对话流程规则

1.2.2 敏感词过滤规则

1.2.3 知识库检索规则

1.2.4 对话历史规则

1.3 API 详细设计

1.3.1 AI 对话接口

1.3.2 对话历史接口

1.4 知识库管理

1.4.1 知识分类

1.4.2 知识库状态

二、健康布施者模块

2.1 功能概述

2.2 业务规则

2.2.1 邀请关系建立规则

2.2.2 勋章体系规则

2.2.3 顾问积分规则

2.2.4 客户列表查询规则

2.3 API 详细设计

2.3.1 获取布施者信息

2.3.2 申请成为布施者

2.3.3 邀请二维码

三、VIP 会员模块

3.1 功能概述

3.2 业务规则

3.2.1 VIP 开通规则

3.2.2 VIP 配置规则

3.2.3 感恩提醒规则

3.2.4 VIP 权益

3.3 API 详细设计

3.3.1 获取 VIP 信息

3.3.2 开通 VIP

四、抵扣金模块

4.1 功能概述

4.2 业务规则

4.2.1 抵扣金获取

4.2.2 抵扣金使用

4.2.3 冻结机制

4.2.4 流水类型

4.3 API 详细设计

4.3.1 获取抵扣金账户

4.3.2 获取抵扣金流水

五、客户运维模块

5.1 功能概述

5.2 业务规则

5.2.1 运维流程定义

5.2.2 运维计划自动生成

5.2.3 节点执行规则

5.2.4 客户自动转移

5.3 API 详细设计

5.3.1 获取我的运维计划

5.3.2 手动触发提醒

六、素材二维码模块

6.1 功能概述

6.2 业务规则

6.2.1 二维码生成规则

6.2.2 URL 参数格式

6.2.3 邀请关系绑定

6.2.4 素材可见性

6.3 API 详细设计

6.3.1 获取素材二维码

七、模块间交互关系

八、定时任务清单

九、模块配置清单

9.1 AI 配置

9.2 健康布施者配置

9.3 VIP 配置

9.4 抵扣金配置

9.5 运维配置

SPEC_DETAIL.md 17 KB

Historia Czysty