# Enagic 本希甄选小程序 - 技术方案文档

> **项目版本：** V1.0
>
> **编制日期：** 2025-05-07
>
> **基于：** Lilishop B2B2C 商城系统 V4.3
>
> **方案：** B（核心用 Lilishop，差异化自研）

---

## 一、项目概述

### 1.1 项目背景

本希甄选小程序是一个集商品销售、素材共享、健康顾问服务于一体的高端消费者服务平台。系统基于 Lilishop B2B2C 开源商城进行扩展开发，保留 Lilishop成熟的电商核心能力，叠加差异化业务功能（AI 数字人、健康布施者体系、客户运维流程等）。

### 1.2 技术选型

| 层级 | 技术选型 | 说明 |
|------|---------|------|
| 后端框架 | Spring Boot 2.4 + MyBatis-Plus | 复用 Lilishop |
| 数据库 | MySQL + Redis + MongoDB | 复用 Lilishop |
| 搜索引擎 | Elasticsearch | 复用 Lilishop |
| 消息队列 | RocketMQ | 复用 Lilishop |
| 认证 | JWT | 复用 Lilishop |
| PC 管理前端 | Vue 2 + ViewUI (iView) | 扩展 |
| 移动端小程序 | UniApp + uView UI | 扩展 |
| AI 大模型 | 硅基流动 / 阿里云百炼 | 新增 |

---

## 二、项目结构

```
代码/
├── enagic-lilishop/                 # 基于 Lilishop 的后台项目
│   ├── lilishop/                    # Lilishop 源码（forked）
│   │   ├── framework/               # 框架层（实体、工具类、插件接口）
│   │   ├── buyer-api/               # 买家端 API
│   │   ├── seller-api/              # 商家端 API
│   │   ├── manager-api/             # 平台管理端 API
│   │   ├── admin/                    # PC 管理端页面（Vue）
│   │   ├── common-api/              # 公共 API
│   │   ├── consumer/                 # 消息消费者
│   │   ├── im-api/                  # IM 即时通讯 API
│   │   └── pom.xml
│   │
│   └── enagic-plugin/                # Enagic 插件模块（新增）
│       ├── enagic-admin/             # 后台管理插件
│       │   ├── src/main/java/        # Java 源码
│       │   ├── src/main/resources/   # 配置文件
│       │   ├── src/main/vue/         # Vue 管理页面
│       │   └── pom.xml
│       │
│       ├── enagic-api/               # 业务 API 插件
│       │   ├── src/main/java/        # Java 源码
│       │   ├── src/main/resources/   # 配置文件
│       │   └── pom.xml
│       │
│       ├── enagic-entity/            # 实体和 DTO
│       │   ├── src/main/java/
│       │   └── pom.xml
│       │
│       ├── enagic-consumer/          # 消息消费者（事件驱动）
│       │   ├── src/main/java/
│       │   └── pom.xml
│       │
│       └── pom.xml                   # 聚合 POM
│
└── enagic-uniapp/                    # 小程序项目（forked from lilishop-uniapp）
    ├── api/                          # API 调用层（新增 enagic 相关）
    ├── pages/                        # 页面
    ├── store/                        # Vuex 状态管理
    ├── config/                       # 配置文件
    └── uview-ui/                     # UI 框架
```

---

## 三、插件架构设计

### 3.1 为什么用插件架构

Lilishop 没有 OSGi 或 Spring Boot auto-configuration 那种热插拔插件系统，但它的 **Factory + Plugin 模式**和 **Spring 组件扫描**机制足够实现模块扩展：

- **现有插件示例**：短信插件（`SmsPlugin`）、物流插件（`LogisticsPlugin`）、支付插件（`PaymentPlugin`）
- **扩展方式**：新增 Maven 模块，通过 Spring `@Component` + `@Configuration` 自动注册到 Lilishop 应用上下文
- **API 隔离**：新增 API 使用独立命名空间（`/enagic/**`），不影响 Lilishop 原有 API
- **事件驱动**：利用 RocketMQ 消费者监听 Lilishop 事件（订单创建、支付完成等），触发自定义业务逻辑

### 3.2 插件模块职责划分

| 模块 | 职责 | 部署方式 |
|------|------|---------|
| `enagic-entity` | 实体类、DTO、枚举、常量 | 打成 JAR，被其他模块依赖 |
| `enagic-api` | 业务 API（健康布施者、VIP、抵扣金、AI数字人、客户运维） | 与 `buyer-api`/`manager-api` 合并部署 |
| `enagic-admin` | PC 后台管理 Vue 页面 + 管理 API | 与 `admin` 合并部署 |
| `enagic-consumer` | 事件监听（RocketMQ）、定时任务 | 与 `consumer` 合并部署 |

### 3.3 与 Lilishop 的集成方式

#### API 扩展（enagic-api）

新增 Controller 使用与 Lilishop 相同的包命名规则：

```
com.dan.modules.enagic.*    # 复用 dan 包名，自动被 Spring 扫描
```

API 路径前缀：`/enagic/buyer/`、`/enagic/manager/`

**无需修改 Lilishop 源码**，只需在 `enagic-api` 模块的 `spring.factories` 或自动配置类中注册新的 Controller。

#### 事件监听（enagic-consumer）

```java
// 监听 Lilishop 的订单创建事件
@RocketMQMessageListener(
    topic = "order_topic",
    consumerGroup = "enagic-consumer-group"
)
public class EnagicOrderListener implements RocketMQListener<Order> {
    // 触发：客户运维流程生成、健康布施者业绩统计
}
```

#### 后台管理（enagic-admin）

Vue 页面通过 **路由配置** 和 **菜单 API** 动态注册到 Lilishop 管理后台：
- 新增 `/enagic/**` 路由
- 菜单数据通过 `manager-api` 动态返回

---

## 四、数据库设计

### 4.1 新增表清单

| 序号 | 表名 | 说明 | 主要字段 |
|------|------|------|---------|
| 1 | `li_enagic_health_advisor` | 健康布施者表 | member_id, name, id_number, medal_level, total_invites, status |
| 2 | `li_enagic_advisor_medal` | 荣誉勋章表 | id, advisor_id, medal_type, medal_level, grant_time, grant_reason |
| 3 | `li_enagic_vip_config` | VIP 配置表 | id, vip_name, price, upgrade_conditions(JSON), benefits(JSON), no_expiry |
| 4 | `li_enagic_member_vip` | 会员 VIP 表 | id, member_id, vip_config_id, open_time, gratitude_remind_time |
| 5 | `li_enagic_deduction` | 抵扣金账户表 | id, member_id, deduction_balance, frozen_balance |
| 6 | `li_enagic_deduction_log` | 抵扣金流水表 | id, deduction_id, amount, type, order_sn, create_time |
| 7 | `li_enagic_operation_flow` | 运维流程模板表 | id, product_id, flow_name, nodes(JSON) |
| 8 | `li_enagic_operation_plan` | 运维计划表 | id, flow_id, member_id, product_id, order_sn, status, next_remind_time |
| 9 | `li_enagic_operation_record` | 运维记录表 | id, plan_id, operator_id, content, result, operate_time |
| 10 | `li_enagic_member_transfer` | 客户移交记录表 | id, original_advisor_id, new_advisor_id, member_id, transfer_reason, transfer_time, status |
| 11 | `li_enagic_behavior_log` | 行为日志表 | id, member_id, event_type, event_data(JSON), create_time |
| 12 | `li_enagic_article_qr` | 素材二维码表 | id, article_id, qr_url, bind_member_id, create_time |
| 13 | `li_enagic_ai_conversation` | AI 对话记录表 | id, member_id, question, answer, model, create_time |
| 14 | `li_enagic_ai_knowledge` | AI 知识库表 | id, category, question, answer, status, create_time |

### 4.2 扩展的 Lilishop 原有表

| 表名 | 新增字段 | 说明 |
|------|---------|------|
| `li_member` | `health_advisor_id`, `advisor_credits` | 关联健康布施者、顾问积分 |
| `li_member_grade` | `upgrade_conditions` (JSON) | 升级条件（金额/积分/人数组合） |
| `li_article` | `view_role` (VARCHAR) | 可见角色：ALL/CONSUMER_ONLY |
| `li_distribution` | `medal_level`, `permanent_bind` | 勋章等级、永久绑定标志 |
| `li_goods` | `operation_flow_id` | 关联运维流程模板 |

### 4.3 ER 关系简图

```
li_member
├── health_advisor_id → li_enagic_health_advisor.id
└── advisor_credits → 顾问积分

li_enagic_health_advisor
├── medal_level → li_enagic_advisor_medal.medal_type
└── member_id → li_member.id (一对一)

li_enagic_vip_config ←→ li_enagic_member_vip (一对多)
                         └── member_id → li_member.id

li_enagic_operation_flow ←→ li_enagic_operation_plan (一对多)
                              └── order_sn → li_order.sn

li_goods.operation_flow_id → li_enagic_operation_flow.id
```

---

## 五、API 设计

### 5.1 新增 API 端点

#### 买家端 API（`/enagic/buyer/`）

| 端点 | 方法 | 说明 |
|------|------|------|
| `/enagic/buyer/advisor/info` | GET | 获取健康布施者信息 |
| `/enagic/buyer/advisor/my-customers` | GET | 获取我的客户列表（分页） |
| `/enagic/buyer/advisor/invite-qr` | GET | 获取邀请二维码 |
| `/enagic/buyer/vip/info` | GET | 获取 VIP 信息 |
| `/enagic/buyer/vip/open` | POST | 开通 VIP |
| `/enagic/buyer/deduction/info` | GET | 获取抵扣金账户 |
| `/enagic/buyer/deduction/log` | GET | 获取抵扣金流水 |
| `/enagic/buyer/ai/chat` | POST | AI 数字人对话 |
| `/enagic/buyer/ai/history` | GET | AI 对话历史 |
| `/enagic/buyer/operation/my-plans` | GET | 获取我的运维计划 |
| `/enagic/buyer/operation/record` | GET | 获取运维记录 |
| `/enagic/buyer/article/qr/{articleId}` | GET | 获取素材带参数的二维码 |

#### 管理端 API（`/enagic/manager/`）

| 端点 | 方法 | 说明 |
|------|------|------|
| `/enagic/manager/advisor/page` | GET | 健康布施者分页列表 |
| `/enagic/manager/advisor/medal/grant` | POST | 发放勋章 |
| `/enagic/manager/vip/config/page` | GET | VIP 配置分页 |
| `/enagic/manager/vip/config/save` | POST | 保存 VIP 配置 |
| `/enagic/manager/deduction/page` | GET | 抵扣金账户分页 |
| `/enagic/manager/operation/flow/page` | GET | 运维流程模板分页 |
| `/enagic/manager/operation/flow/save` | POST | 保存运维流程模板 |
| `/enagic/manager/operation/plan/page` | GET | 运维计划分页 |
| `/enagic/manager/operation/plan/remind` | POST | 手动触发提醒 |
| `/enagic/manager/transfer/page` | GET | 客户移交记录分页 |
| `/enagic/manager/transfer/process` | POST | 处理移交申请 |
| `/enagic/manager/ai/knowledge/page` | GET | AI 知识库分页 |
| `/enagic/manager/ai/knowledge/save` | POST | 保存 AI 知识库 |
| `/enagic/manager/article/qr/list` | GET | 素材二维码列表 |

### 5.2 复用 Lilishop 的 API

| Lilishop API | 用于 |
|--------------|------|
| `/buyer/passport/member/*` | 用户注册、登录 |
| `/buyer/goods/*` | 商品浏览、搜索 |
| `/buyer/trade/carts/*` | 购物车 |
| `/buyer/order/order/*` | 订单（创建、支付、退款） |
| `/buyer/wallet/*` | 余额、充值、提现 |
| `/buyer/member/memberPointsHistory/*` | 积分 |
| `/buyer/promotion/coupon/*` | 优惠券 |
| `/buyer/distribution/*` | 分销（复用为健康布施者底层） |
| `/buyer/message/*` | 消息中心 |
| `/buyer/broadcast/studio/*` | 直播（AI数字人交互页可复用） |
| `/manager/goods/*` | 商品管理 |
| `/manager/order/*` | 订单管理 |
| `/manager/member/*` | 会员管理 |
| `/manager/page/*` | 页面装修 |

---

## 六、功能模块详细设计

### 6.1 AI 数字人

**架构：**
```
UniApp → enagic-api → AI 大模型（硅基流动/阿里云百炼）
         ↓
   enagic-entity (LiEnagicAiConversation)
```

**知识库分类：**
- 产品知识库（产品功效、使用方法、注意事项）
- 健康知识库（健康信息、营养建议）
- 常见问题库（FAQ）

**对话流程：**
1. 用户发送消息 → `/enagic/buyer/ai/chat`
2. 敏感词过滤 → 知识库检索 → AI 大模型回答
3. 对话记录存储到 `li_enagic_ai_conversation`
4. 返回答案给用户

**触发场景：**
- 小程序「AI 健康顾问」入口 → 进入 AI 数字人对话界面
- 商品详情页 → 快捷咨询按钮 → 调用 AI 接口

### 6.2 健康布施者荣誉体系

**邀请关系建立：**
```
用户扫码注册 → 解析 URL 中的 inviter_id → 写入 health_advisor_id
（永久绑定，即使健康布施者注销也不解除）
```

**勋章机制：**
| 勋章类型 | 触发条件 | 显示 |
|----------|---------|------|
| 布施新星 | 首次成功邀请 | ⭐ |
| 布施达人 | 邀请 5 人 | ⭐⭐ |
| 布施导师 | 邀请 20 人 | ⭐⭐⭐ |
| 布施宗师 | 邀请 50 人 | 🌟 |

**健康布施者权益：**
- 被邀请客户的消费贡献积分
- 专属客服通道
- 荣誉展示（个人中心显示勋章）

### 6.3 客户运维流程引擎

**流程定义：**
```json
{
  "flowName": "产品A 运维流程",
  "productId": 123,
  "nodes": [
    {"day": 1, "name": "发货提醒", "content": "您的订单已发货", "remindType": "WECHAT_MSG"},
    {"day": 3, "name": "收货确认", "content": "请确认收货并指导使用", "remindType": "WECHAT_MSG"},
    {"day": 7, "name": "使用指导", "content": "开始使用产品", "remindType": "AI_REMINDER"},
    {"day": 30, "name": "使用回访", "content": "使用体验如何", "remindType": "WECHAT_MSG"}
  ]
}
```

**自动触发：**
- 订单状态变为「已发货」→ 生成运维计划
- `enagic-consumer` 监听订单事件 → 创建 `li_enagic_operation_plan`
- 定时任务（XXL-Job）扫描 `li_enagic_operation_plan`，到达 `next_remind_time` → 发送微信通知

**客户自动转移：**
- 三次运维节点被跳过（无人服务）→ 触发转移
- 转移时记录 `li_enagic_member_transfer`，原健康布施者归属权和收益权终止

### 6.4 VIP 无到期时间

**原有 Lilishop VIP**：`MemberGrade` 绑定有效期，到期自动失效

**改造方案：**
- 新增 `li_enagic_vip_config.no_expiry = true` 字段
- 新增 `li_enagic_member_vip.gratitude_remind_time` 字段
- 移除到期检查定时任务，改为「分享激励感恩提醒」定时任务
- 触发条件：VIP 客户每 30 天无分享行为 → 发送感恩提醒消息

### 6.5 抵扣金账户

**获取途径：**
- 充值赠送（后台配置赠送比例）
- 活动奖励
- 退款返还（退款时优先退抵扣金）

**使用规则：**
- 订单支付时可使用抵扣金（抵扣部分金额）
- 支持部分抵扣（最低抵扣 1 元）
- 抵扣金不能提现

**冻结机制：**
- 下单时冻结对应抵扣金
- 订单完成/取消时解冻

### 6.6 素材二维码分享

**生成逻辑：**
- 用户打开素材详情页 → 调用 `/enagic/buyer/article/qr/{articleId}`
- 后台生成二维码，内容包含：素材ID + 分享者 memberId + 有效期
- 二维码存储到 `li_enagic_article_qr`

**分享流程：**
1. 分享者打开素材 → 生成分享二维码
2. 被分享者扫码 → 跳转小程序，自动携带分享者信息
3. 被分享者注册后，自动绑定关系（无需手动关联）

### 6.7 素材角色权限

**实现：**
- `li_article.view_role = 'ALL' | 'CONSUMER_ONLY'`
- 商家端上传素材时可设置可见角色
- 用户端 API 查询素材时根据 `view_role` + 用户角色过滤
- 消费商：看全部素材
- 纯用户：只看 `view_role = 'ALL'` 或 `'CONSUMER_ONLY'`

---

## 七、小程序端设计

### 7.1 页面结构

在 `enagic-uniapp` 中新增以下页面（通过分包机制）：

```
pages/
├── tabbar/                          # 已有（首页/分类/购物车/我的）
├── enagic/                          # Enagic 新增页面（分包）
│   ├── ai-chat/                     # AI 数字人对话
│   │   └── index.vue
│   ├── health-advisor/              # 健康布施者中心
│   │   ├── home.vue                 # 推广首页（展示客户、业绩、勋章）
│   │   ├── customers.vue            # 我的客户列表
│   │   ├── invite-qr.vue            # 邀请二维码
│   │   └── medals.vue               # 我的勋章
│   ├── vip/                         # VIP 中心
│   │   ├── index.vue                 # VIP 介绍和开通
│   │   └── my-vip.vue                # 我的 VIP
│   ├── deduction/                   # 抵扣金
│   │   ├── index.vue                 # 抵扣金账户
│   │   └── log.vue                   # 抵扣金明细
│   ├── operation/                   # 运维（消费商视角）
│   │   ├── my-plans.vue              # 我的运维计划
│   │   └── record.vue                # 运维记录
│   └── transfer/                    # 客户移交
│       └── history.vue              # 移交历史
```

### 7.2 既有页面改造

| 页面 | 改造内容 |
|------|---------|
| `pages/tabbar/user/my.vue` | 新增：健康布施者入口、VIP 入口、AI 顾问入口 |
| `pages/mine/msgTips/main.vue` | 新增：运维提醒消息类型 |
| `pages/passport/login.vue` | 新增：健康布施者邀请登录参数解析 |
| `pages/product/goods.vue` | 新增：AI 咨询快捷入口、商品详情页添加运维计划入口 |

### 7.3 API 调用层

新增 `enagic-uniapp/api/enagic.js`：

```javascript
// AI 数字人
export const aiChat = (data) => uni.request({ url: '/enagic/buyer/ai/chat', data })
export const aiHistory = (params) => uni.request({ url: '/enagic/buyer/ai/history', params })

// 健康布施者
export const getAdvisorInfo = () => uni.request({ url: '/enagic/buyer/advisor/info' })
export const getMyCustomers = (params) => uni.request({ url: '/enagic/buyer/advisor/my-customers', params })
export const getInviteQr = () => uni.request({ url: '/enagic/buyer/advisor/invite-qr' })

// VIP
export const getVipInfo = () => uni.request({ url: '/enagic/buyer/vip/info' })
export const openVip = (data) => uni.request({ url: '/enagic/buyer/vip/open', data })

// 抵扣金
export const getDeductionInfo = () => uni.request({ url: '/enagic/buyer/deduction/info' })
export const getDeductionLog = (params) => uni.request({ url: '/enagic/buyer/deduction/log', params })

// 运维
export const getMyOperationPlans = (params) => uni.request({ url: '/enagic/buyer/operation/my-plans', params })
```

---

## 八、实施计划

### 阶段划分

| 阶段 | 时间 | 内容 | 交付物 |
|------|------|------|--------|
| **Phase 0** | Week 1 | 环境搭建 + Lilishop 源码 fork + 项目初始化 | 项目目录结构、Maven 依赖调试通过 |
| **Phase 1** | Week 2-3 | 基础数据层：数据库表创建 + entity + 基础 API（健康布施者、VIP配置） | API 可调用、数据库表就绪 |
| **Phase 2** | Week 4-5 | 核心业务开发：健康布施者体系 + VIP 无到期 + 抵扣金 | 功能完整可用 |
| **Phase 3** | Week 6-7 | 客户运维流程引擎 + 事件监听（RocketMQ） | 运维流程自动触发 |
| **Phase 4** | Week 8-9 | AI 数字人：知识库 + 对话接口 + 小程序页面 | AI 对话可用 |
| **Phase 5** | Week 10-11 | PC 后台管理页面（Vue）+ 素材权限 + 二维码分享 | 后台功能完整 |
| **Phase 6** | Week 12 | 小程序端 UI 改造 + 联调测试 | 小程序可运行 |
| **Phase 7** | Week 13-14 | 系统联调 + 性能优化 + 部署 | 可上线版本 |

**总工期：约 14 周（100-105 人天）**

### 关键依赖路径

```
Phase 0 (项目初始化)
    ↓
Phase 1 (数据层) ───────────────────────────────────────┐
    ↓                                                    │
Phase 2 (核心业务)                                       │
    ↓                                                    │
Phase 3 (运维引擎) ←──────── Phase 2 完成后解锁           │
    ↓                                                    │
Phase 4 (AI数字人) ←── Phase 1 完成后可并行              │
    ↓                                                    │
Phase 5 (后台页面) ←── Phase 1+2 完成后可并行            │
    ↓                                                    │
Phase 6 (小程序) ←────────── Phase 1~5 完成后开始        │
    ↓                                                    │
Phase 7 (联调上线)                                       │
```

### 并行机会

| 并行组合 | 说明 |
|---------|------|
| Phase 2 + Phase 4 | 核心业务和 AI 可同时开发 |
| Phase 2 + Phase 5 | 后台管理和业务逻辑可同时开发 |
| Phase 3 + Phase 5 | 事件监听和后台管理可同时开发 |

---

## 九、技术要点

### 9.1 Lilishop 源码集成

将 `enagic-plugin` 作为 Maven 子模块加入 Lilishop 的 `pom.xml`：

```xml
<modules>
    <module>framework</module>
    <module>buyer-api</module>
    <module>manager-api</module>
    <module>seller-api</module>
    <module>common-api</module>
    <module>consumer</module>
    <module>admin</module>
    <module>im-api</module>
    <!-- 新增 -->
    <module>enagic-plugin</module>
</modules>
```

### 9.2 定时任务

使用 Lilishop 内置的 **XXL-Job**：

| 任务名称 | cron | 说明 |
|---------|------|------|
| `enagic-operation-remind` | `0 0 9 * * ?` | 运维计划提醒扫描 |
| `enagic-gratitude-remind` | `0 0 10 * * ?` | VIP 感恩提醒扫描 |
| `enagic-transfer-check` | `0 0 12 * * ?` | 客户自动转移检查 |
| `enagic-medal-check` | `0 0 8 * * ?` | 勋章发放检查 |

### 9.3 AI 大模型接入

推荐使用 **硅基流动（SiliconFlow）** API：

```java
// 配置：enagic-api/src/main/resources/application.yml
enagic:
  ai:
    provider: siliconflow   # 或 aliyun
    api-key: ${AI_API_KEY}
    model: Qwen/Qwen2.5-7B-Instruct  # 模型名称
    base-url: https://api.siliconflow.cn/v1
```

### 9.4 微信消息通知

利用 Lilishop 已有的消息中心，扩展消息模板：

| 模板类型 | 触发场景 |
|---------|---------|
| 运维提醒 | 到达运维节点时 |
| 客户转移通知 | 客户被自动转移时 |
| 勋章发放通知 | 健康布施者获得新勋章时 |
| VIP 感恩提醒 | VIP 客户长期无分享时 |

---

## 十、注意事项

1. **不修改 Lilishop 核心代码**：所有扩展通过新增模块实现，便于后续 Lilishop 版本升级时合并
2. **数据库表前缀统一使用 `li_enagic_`**：与 Lilishop 原有表（`li_*`）保持一致
3. **API 命名空间隔离**：`/enagic/**` 前缀确保不与 Lilishop 原有 API 冲突
4. **事件驱动解耦**：核心业务逻辑通过 RocketMQ 事件触发，不直接依赖 Lilishop 内部类
5. **AGPL 协议注意**：Lilishop 遵循 AGPL-3.0，商业使用需联系官方授权

---

## 附录：文件清单

```
代码/
├── enagic-lilishop/
│   ├── SPEC.md                          # 本文档
│   ├── lilishop/                        # Lilishop 源码（forked）
│   └── enagic-plugin/                   # Enagic 插件
│       ├── README.md
│       ├── pom.xml                       # 聚合 POM
│       ├── enagic-entity/               # 实体层
│       ├── enagic-api/                  # 业务 API
│       ├── enagic-admin/                # PC 管理插件
│       └── enagic-consumer/              # 事件消费者
└── enagic-uniapp/                        # 小程序
    ├── README.md
    └── pages/enagic/                     # 新增页面
```