## 1. 项目概述

金鹿商城是一个面向微信生态的鹿酒销售电商小程序，在标准电商能力基础上叠加了三大特色模块：限时抢签（摇号）、活动币体系、积分商城组合支付。项目以 CRMEB Java 多端电商系统为基座，需进行增量开发。

### 1.1 核心业务模块

模块 | 核心能力 | 优先级
--- | --- | ---
商品销售 | 小程序商品浏览、下单、支付、物流、售后 | P0 — 基础
限时抢签 | 定时开放、实名摇号、中签后购买 | P0 — 核心特色
活动币 | 购买赠币、中签赠币、48h 过期 | P1 — 增强粘性
积分商城 | 活动币 + 积分组合支付、实名发货 | P1 — 积分消耗闭环

### 1.2 关键约束

- 仅面向微信小程序，不独立开发 App / H5
- 积分商城不支持单独支付，仅支持活动币 + 积分组合
- 活动币强制 48 小时过期，不可手动延期
- 积分商城下单必须实名认证（身份证）
- 限时抢签仅在规定时间段内可报名参与

## 2. 差异总览

需求项 | CRMEB 现有 | 覆盖度 | 说明
--- | --- | --- | ---
商品管理 | 有 | 完全覆盖 | 商品 CRUD、分类、品牌、规格、库存均已具备
订单流程 | 有 | 完全覆盖 | 下单、支付、发货、收货、退款退货完整
微信支付 | 有 | 完全覆盖 | 小程序微信支付已接入
微信登录 | 有 | 完全覆盖 | 小程序微信授权登录已实现
用户管理 | 有 | 完全覆盖 | 用户信息、等级、地址管理已具备
现有积分体系 | 有 | 部分覆盖 | 已有积分获取/消费/记录，需扩展组合支付
用户身份证字段 | 部分 | 部分覆盖 | 数据库有相关字段但缺少实名认证校验逻辑
限时抢签（摇号） | 无 | 完全缺失 | 全新模块，需从零开发
活动币体系 | 无 | 完全缺失 | 全新虚拟货币，含过期机制
积分商城 + 组合支付 | 无 | 完全缺失 | 需新建独立商城入口与结算逻辑
48 小时定时过期 | 无 | 完全缺失 | 需定时任务清理过期活动币
身份证实名校验 | 无 | 完全缺失 | 需接入公安实名验证或第三方 API

核心结论
基础电商能力（商品、订单、支付、物流）100% 复用 CRMEB 现有模块。新增工作量集中在三大模块：限时抢签、活动币、积分商城组合支付，属于增量开发而非系统重写。

## 3.1 商品销售（基础电商）

### 需求描述

小程序端支持用户浏览商品、加入购物车、下单支付、查看物流、申请售后。

### 现有能力匹配

- `StoreProduct` — 商品模型：SPU/SKU、分类、品牌、详情图文、库存、价格
- `StoreOrder` — 订单模型：下单、支付状态、物流跟踪、售后退款
- `Cart` — 购物车：添加、修改数量、删除、结算
- `WeChatPaymentService` — 微信支付统一下单、回调、退款
- `ExpressService` — 物流查询（阿里云接口）

结论：无需开发
CRMEB 已覆盖完整电商交易链路，小程序端前端代码在 `single_uniapp` 中已有现成实现。

## 3.2 限时抢签（摇号抽签）

### 需求描述

类似茅台抢签模式，在指定时间段内用户可报名参与抢购摇号，中签后获得购买资格。

#### 核心规则

- 每个商品配置抢签时间段，如 09:00–09:30、17:00–17:30
- 用户在开放时段内可报名参与（需微信登录授权）
- 报名截止后系统自动摇号，按配置的中签率计算中签用户
- 中签用户获得限时购买资格（通常 30 分钟内有效）
- 未中签用户不产生订单，不影响后续批次

#### 后台管理

- 抢签活动管理：创建/编辑/删除活动，关联商品、时间段、中签率
- 报名记录查看：用户列表、报名状态、中签结果
- 中签率配置：可手动设置固定中签率，也可按报名人数自动计算

### 现有能力匹配

CRMEB 无任何秒杀/抢购/摇号相关模块。现有的优惠券、限时折扣与抢签业务模式完全不同，无法复用。

结论：全新开发
需从 0 到 1 开发抢签系统，涉及前端报名界面、后台活动管理、定时摇号算法、中签结果通知等多个子系统。核心难点在于摇号公平性（随机算法）与高并发报名处理。

## 3.3 活动币体系

### 需求描述

活动币是一种临时性虚拟货币，用于积分商城的组合支付，与现有积分系统独立。

#### 获取规则

- 购买指定商品：每完成一笔符合条件的订单，赠送 1 个活动币
- 抢签中签成功：摇号中签后额外赠送 1 个活动币

#### 过期规则

- 从获得时刻起，48 小时后自动过期
- 过期后活动币数量清零，不可恢复
- 不可手动延期或兑换

#### 使用场景

- 仅在积分商城中使用，与普通订单支付无关
- 与积分组合支付，无单独使用场景

### 现有能力匹配

CRMEB 已有 `IntegralRecord` 积分记录表和积分获取/消费机制，但活动币在业务含义、过期机制、使用场景上与积分完全不同，不可复用积分模块，需独立建表。

结论：全新开发
需新建活动币账户表、流水记录表、48 小时定时清理任务（Quartz），并在订单完成支付/中签时触发赠送逻辑。可参考积分模块的架构模式但需独立实现。

## 3.4 积分商城（组合支付）

### 需求描述

独立的积分商城入口，商品仅支持「活动币 + 积分」组合兑换，不支持现金支付。

#### 核心规则

- 积分获取：仅通过普通订单购买获得（消费 100 元 = 1 积分）
- 积分商城商品必须同时消耗活动币 + 积分，二者缺一不可
- 积分商城不支持现金支付，无微信支付入口
- 下单时强制校验身份证信息（姓名 + 身份证号），未实名用户不可下单

### 现有能力匹配

- 积分体系已有：积分获取（下单赠送）、积分消费（积分商品兑换）、积分记录
- 积分商品模型 `StoreIntegral` 已存在
- 缺少：组合支付逻辑（活动币 + 积分）、身份证实名校验、独立积分商城入口

结论：需改造现有积分模块
现有积分商城的下单流程需增加活动币校验与扣减逻辑，同时新增身份证实名校验环节。前端需改造小程序端积分商城页面 UI，明确组合支付方式。

## 3.5 硬性规则汇总

规则 | 约束类型 | 影响范围
--- | --- | ---
活动币 48 小时强制过期 | 定时任务 | 活动币清理、用户资产展示
积分商城不可单独支付 | 结算逻辑 | 订单创建、支付页面
积分商城下单必须实名 | 校验逻辑 | 结算页面、用户中心
抢签仅定时段报名 | 时间控制 | 前端按钮显隐、后端接口校验
中签率后台可配 | 配置管理 | 抢签活动编辑页面
仅微信小程序 | 平台限制 | 无需适配 App/H5/PC

## 4.1 完全覆盖的功能

以下功能在 CRMEB 中已完整实现，可直接复用：

功能 | 后端文件 | 前端文件 | 备注
--- | --- | --- | ---
商品 CRUD | `StoreProductController/Service` | `single_uniapp/pages/goods` | 含 SPU/SKU、分类、品牌、图文详情
购物车 | `StoreCartController/Service` | `single_uniapp/pages/users/cart` | 增删改查、选中结算
订单流程 | `StoreOrderController/Service` | `single_uniapp/pages/users/order` | 创建、支付、发货、收货、退款
微信支付 | `WeChatPaymentService` | uni-app 支付组件 | 统一下单、回调处理、退款
微信登录 | `WeChatLoginService` | `single_uniapp/pages/login` | 小程序授权登录
物流查询 | `LogisticsService` | 订单详情页 | 阿里云物流 API 对接
用户中心 | `UserCenterController` | `single_uniapp/pages/users/user` | 个人信息、地址、订单列表
优惠券 | `CouponController/Service` | 领券中心、我的优惠券 | 可预留后续活动使用

## 4.2 部分覆盖的功能

### 4.2.1 积分体系

维度 | CRMEB 现有 | 金鹿需求 | 差异
--- | --- | --- | ---
积分获取 | 订单赠送（比例可配） | 消费 100 元 = 1 积分 | 配置调整
积分消费 | 积分商品兑换（纯积分） | 活动币 + 积分组合 | 需改造 新增组合支付逻辑
积分记录 | `IntegralRecord` 表 + 流水 | 同现有 | 可复用
积分商品 | `StoreIntegral` 模型 | 同现有 | 可复用

### 4.2.2 用户实名认证

维度 | CRMEB 现有 | 金鹿需求 | 差异
--- | --- | --- | ---
身份证字段 | 用户表可能有预留字段 | 姓名 + 身份证号 | 字段确认 确认数据库是否有现成字段
实名校验 | 无 | 身份证号合法性校验 | 需开发 校验算法 + 可选第三方 API
实名状态 | 无 | 未实名不可下单 | 需开发 下单前置校验

## 4.3 完全缺失的功能

### 4.3.1 限时抢签系统

子模块 | 说明 | 复杂度
--- | --- | ---
抢签活动管理 | CRUD、关联商品、时间段配置、中签率配置 | 中
用户报名 | 微信小程序端报名界面、报名状态展示 | 低
摇号算法 | 基于中签率的随机分配，需保证公平性 | 高
定时任务 | 报名截止后自动触发摇号（Quartz） | 中
购买资格 | 中签用户在有效期内拥有专属购买通道 | 中
结果通知 | 微信订阅消息通知中签/未中签结果 | 低

### 4.3.2 活动币体系

子模块 | 说明 | 复杂度
--- | --- | ---
活动币账户 | 用户维度的活动币余额管理 | 低
流水记录 | 获取/消费/过期的完整流水 | 低
赠送触发 | 订单完成支付后赠币、中签后赠币 | 中
48h 过期 | 定时任务扫描过期并清零（Quartz） | 中
前端展示 | 用户中心显示活动币余额及明细 | 低

### 4.3.3 积分商城组合支付

子模块 | 说明 | 复杂度
--- | --- | ---
组合结算 | 活动币 + 积分联合扣减，余额不足拦截 | 高
实名校验 | 下单前校验身份证号，未实名拦截 | 中
订单类型 | 新建积分商城订单类型，与普通订单区分 | 中
前端改造 | 积分商城商品详情页、结算页、支付方式页 | 中

## 5. 新增数据表设计

以下为需要新增的核心数据表（基于 CRMEB 现有命名规范 `eb_` 前缀）：

### 5.1 限时抢签模块

表名 | 说明 | 核心字段
--- | --- | ---
`eb_lottery_activity` | 抢签活动主表 | id, product_id, activity_name, start_time, end_time, lottery_time, win_rate, status, create_time, update_time
`eb_lottery_record` | 用户报名记录表 | id, activity_id, uid, status(报名/中签/未中签), lottery_result, order_id(中签后下单的订单), create_time
`eb_lottery_purchase_qualification` | 中签购买资格表 | id, record_id, uid, activity_id, expire_time, used(是否已使用)

### 5.2 活动币模块

表名 | 说明 | 核心字段
--- | --- | ---
`eb_activity_coin_account` | 用户活动币账户表 | id, uid, balance, total_earned, total_spent, total_expired
`eb_activity_coin_record` | 活动币流水记录表 | id, uid, change_amount, balance_after, type(获取/消费/过期), source(订单/抢签/兑换), expire_time, source_id, create_time

### 5.3 积分商城改造

表名 | 说明 | 核心字段
--- | --- | ---
`eb_store_integral_order` | 积分商城订单表（扩展现有或新建） | 增加 activity_coin_amount 字段，记录消耗活动币数量
`eb_user_identity` | 用户实名信息表 | id, uid, real_name, id_card, verified(是否已校验), verify_time, create_time

设计建议
活动币流水表采用与现有积分流水表类似的设计模式，便于后续维护和审计。每条流水记录包含 expire_time 字段，定时任务基于此字段批量清理过期活动币。

## 6. 分阶段实施计划

### Phase 1：基础电商能力确认（1-2 天）

- 确认 CRMEB 小程序端商品浏览、下单、支付、物流流程正常运行
- 确认微信支付、微信登录正常
- 确认现有积分获取/消费机制正常工作
- 品牌替换（CRMEB → 金鹿商城），清除遗留的一号通等无用功能

### Phase 2：活动币体系（3-5 天）

- 新建活动币账户表 + 流水记录表
- 实现活动币赠送逻辑：订单完成支付后触发、中签后触发
- 实现 48 小时定时清理任务（Quartz 定时任务）
- 用户中心展示活动币余额及明细
- 后台活动币管理：查看用户流水、统计数据

### Phase 3：限时抢签系统（5-8 天）

- 抢签活动管理后台：CRUD、商品关联、时间段/中签率配置
- 小程序端抢签页面：活动列表、报名按钮、报名状态展示
- 摇号算法实现（基于随机数 + 中签率计算）
- 定时摇号任务（Quartz 在报名截止时自动执行）
- 中签购买资格管理：有效期、专属购买通道
- 微信订阅消息通知：中签/未中签结果推送

### Phase 4：积分商城改造（3-5 天）

- 积分商城订单增加活动币消耗逻辑
- 组合支付结算：校验活动币 + 积分余额，联合扣减
- 用户实名认证：身份证录入 + 合法性校验
- 积分商城下单强制实名校验拦截
- 小程序端积分商城页面改造：组合支付展示

### Phase 5：联调测试与上线（3-5 天）

- 端到端功能测试：商品浏览 → 下单支付 → 获得活动币 → 抢签报名 → 摇号中签 → 积分商城兑换
- 活动币过期定时任务验证
- 高并发报名场景压测
- 小程序提审准备

## 7. 工作量评估

阶段 | 后端（天） | 前端（天） | 联调（天） | 合计（天）
--- | --- | --- | --- | ---
Phase 1：基础确认 | 1 | 1 | 0.5 | 1.5
Phase 2：活动币 | 3 | 1.5 | 1 | 5.5
Phase 3：限时抢签 | 5 | 2.5 | 1.5 | 9
Phase 4：积分商城 | 3 | 2 | 1 | 6
Phase 5：联调上线 | 1 | 1 | 2 | 4
合计 | 13 | 8 | 6 | 26

说明
以上为单人开发预估，基于 CRMEB 现有代码基础之上增量开发。若对 CRMEB 代码不够熟悉，需额外增加 3-5 天的熟悉时间。

## 8. 风险与建议

### 8.1 技术风险

风险项 | 影响 | 缓解措施
--- | --- | ---
抢签高并发 | 大量用户同时报名可能导致数据库压力 | 报名接口使用 Redis 队列削峰，异步写入数据库；摇号在低峰期执行
摇号公平性 | 随机算法被质疑不公正 | 使用 JDK SecureRandom + 公示摇号逻辑；可引入第三方随机种子
活动币过期清理 | 大批量过期数据导致定时任务执行时间过长 | 分页批量处理，每次处理 1000 条；设置合理的 Cron 频率（每 10 分钟执行一次）
身份证信息安全 | 身份证号属于敏感信息，存储需符合法规 | 身份证号加密存储（AES），展示时脱敏（如 3301***********1234）；数据库访问权限控制
积分商城订单与普通订单区分 | 现有订单逻辑可能受到改造影响 | 新建独立的积分商城订单处理流程，复用现有订单模型但不修改核心逻辑

### 8.2 合规风险

- 摇号活动合规：需确保抢签活动不构成"抽奖/赌博"性质，建议在用户协议中明确说明为"限量商品公平购买方式"
- 个人信息保护：身份证号收集需在小程序中取得用户明确授权，符合《个人信息保护法》要求
- 虚拟资产合规：活动币虽有过期机制，但应在用户协议中明确说明其非货币属性

### 8.3 架构建议

- 抢签、活动币模块应作为独立的 Service 层实现，与现有电商模块解耦
- 定时任务统一由现有的 Quartz 调度器 管理，避免重复引入调度框架
- 所有新增 Controller 统一在 `crmeb-admin`（后台管理）和 `crmeb-front`（小程序 API）中按模块分包
- 小程序前端代码在 `single_uniapp` 中新增独立页面目录：`pages/lottery`、`pages/integral-mall`

### 8.4 可选优化方向

- Redis 缓存：抢签活动的报名名单可缓存在 Redis Set 中，摇号时一次性读取，减少数据库压力
- 消息队列：订单完成支付后通过消息队列异步赠送活动币，避免阻塞订单主流程
- 第三方实名校验：如需要严格实名验证，可接入阿里云/腾讯云的身份证实名认证 API
- 数据看板：后台增加抢签活动数据看板（报名人数、中签率趋势、活动币发放/消耗统计）

## 9. 总结

金鹿商城电商小程序项目基于 CRMEB 现有电商系统进行增量开发，核心差异在于 限时抢签、活动币、积分商城组合支付 三大模块。

维度 | 评估
--- | ---
复用程度 | 基础电商 80%+ 复用
新增工作量 | 约 26 人天
技术难度 | 中等偏高（摇号算法 + 高并发）
合规要求 | 中等（个人信息保护 + 活动合规）

建议按照 基础确认 → 活动币 → 抢签 → 积分商城 → 联调上线 的顺序分阶段推进，每个阶段完成后进行回归测试，确保新增模块不影响现有电商核心功能。