# 智价云（药店版） - 产品文档

> **⚠️ MVP阶段说明**  
> 本项目为**全新项目，尚未上线**，当前处于 **MVP（最小可行产品）阶段**。  
> **核心业务**：面向终端药店的B2B采购**聚合比价工具**，用户绑定自有B2B平台账号，智价云（药店版）并行查询同款报价。  
> **产品形态**：**多端交付策略** - MVP首选Windows独立桌面应用（.exe），后续扩展微信小程序、APP、公众号等多渠道。  
> **目标用户**：药店采购人员、药师，目标日活20万+。
>
> 📅 版本：v1.2-MVP | 📆 更新日期：2026-07-11 | ✅ 状态：开发中

---

## 📋 目录

- [1. 产品概述](#1-产品概述)
- [2. 功能模块](#2-功能模块)
- [3. 核心业务流程](#3-核心业务流程)
- [4. 多端交付策略](#4-多端交付策略)
- [5. 灵活配置策略](#5-灵活配置策略)
- [6. 非功能性需求](#6-非功能性需求)
- [7. MVP范围与规划](#7-mvp范围与规划)
- [8. 业务指标](#8-业务指标)

---

## 1. 产品概述

### 1.1 产品定位

智价云（药店版）是一款面向**终端药店**的**B2B采购聚合比价工具**，核心价值：

| 价值点 | 说明 | 收益 |
|--------|------|------|
| 💰 降低采购成本 | 聚合查询已绑平台报价 | 平均节省10%-30% |
| 🔒 安全可控 | Windows独立桌面应用，自建安全策略 | 不依赖系统浏览器 |
| ⚡ 高效便捷 | 一键启动，并行查询多平台 | 提升采购效率50%+ |
| 🎯 精准比价 | 基于用户自有账号查询 | 价格真实可靠 |
| 👥 裂变增长 | 邀请其他药店注册获得会员时长奖励 | 快速扩大用户规模 |
| 💳 会员变现 | 支持微信/支付宝购买会员套餐 | 商业闭环 |

**🎯 MVP目标**：验证核心业务流程（注册→绑定账号→聚合查询→跳转购买→购买会员），快速上线获取种子药店用户，收集真实使用反馈。

### 1.2 目标用户与角色

| 角色 | 系统角色 | 说明 | 核心需求 |
|------|----------|------|----------|
| 药店采购员 | USER | 负责药店日常药品采购 | 快速找到最低价格，生成采购链接 |
| 执业药师 | USER | 审核药品质量和供应商资质 | 查看药品详细信息、供应商信誉 |
| 药店老板 | USER | 控制采购成本，优化供应链 | 采购数据分析、成本控制报表 |
| 运营人员 | ADMIN | 管理邀请配置、发放优惠券、审核资质 | 提高用户注册率和活跃度 |
| 超级管理员 | SUPER_ADMIN | 系统全局管理、角色赋权 | 用户管理、数据统计、风控监控 |

**三级RBAC权限模型**：
- **USER**：仅可访问用户侧接口（比价、关注、搜索历史等）
- **ADMIN**：可访问运营后台接口（用户管理、配置管理、审核等）
- **SUPER_ADMIN**：拥有全部权限，可管理用户角色赋权

### 1.3 关键特点

- **多端覆盖**：Windows桌面应用起步，逐步扩展移动端和社交渠道
- **自建安全策略**：Windows客户端内置WebView2，Cookie管理、Session隔离、加密存储均由应用自行管理
- **用户绑定账号**：用户输入自己在药师帮/药帮忙/1药城的账号密码（AES-256加密存储）
- **聚合查询**：并行查询已绑平台，展示比价结果
- **跳转原平台**：点击"去购买"跳转到原平台完成交易，智价云（药店版）不提供交易服务
- **会员体系**：PLUS/PRO/ULTRA三档会员，权益驱动爬虫配额
- **支付闭环**：支持微信/支付宝扫码支付购买会员套餐
- **裂变增长**：邀请奖励为会员时长，邀请人获赠1个月高级会员(PRO)
- **用户粘性**：通过多渠道触达，提高用户使用频次和留存率

---

## 2. 功能模块

### 2.1 用户认证模块

| 功能 | 说明 |
|------|------|
| 短信验证码登录 | 手机号 + 6位验证码，新用户自动注册 |
| 密码登录 | 手机号/昵称 + 密码（BCrypt加密），支持设置/修改密码 |
| 微信扫码登录 | 微信开放平台扫码，首次登录需绑定手机号 |
| 修改手机号 | 已登录用户通过验证码验证后修改绑定手机号 |
| Token 管理 | Access Token（管理员12h / 普通用户1h）+ Refresh Token（7d），支持多设备登录控制 |
| 用户信息 | 昵称、头像、手机号、会员等级、药店名称、地区信息 |
| 登录来源追踪 | 记录登录设备、登录IP、登录来源（WINDOWS/MINIAPP/ANDROID/IOS/WECHAT） |

### 2.2 会员体系

系统采用**三级会员体系**，会员等级驱动爬虫配额权益：

| 会员等级 | 编码 | 权重 | 每日配额 | 每月配额 | 每年配额 | 最大并发 | 过期时间 | 适用场景 |
|----------|------|------|----------|----------|----------|----------|----------|----------|
| 普通会员 | PLUS | 1 | 10次 | 300次 | 3650次 | 1 | 无（永久） | 注册即得，限时免费 |
| 高级会员 | PRO | 2 | 999次 | 29970次 | 364635次 | 5 | 有（购买/赠送） | 付费会员，核心变现 |
| 超级会员 | ULTRA | 3 | 999次 | 29970次 | 364635次 | 10 | 有（运营发放） | 连锁专用，待开放购买 |

**获取方式**：

| 等级 | 获取方式 |
|------|---------|
| PLUS | 用户注册即自动获得，不限时长，永久免费 |
| PRO | ① 付费购买（月卡30天/年卡365天）② 邀请奖励（1个月）③ 入驻信息审核通过（1个月）④ 运营手动发放 |
| ULTRA | 运营手动发放（购买入口待开放） |

**互斥与叠加规则**：

- 普通会员、高级会员、超级会员**不可同时生效**，同一时间只有一个活跃等级
- 高等级权限优先级更高：`ULTRA > PRO > PLUS`
- **同等级续期**：在原到期时间基础上叠加天数（购买月卡+邀请奖励 → 60天）
- **升级**：低等级→高等级时停用旧会员，创建新记录（PLUS→PRO 或 PRO→ULTRA）
- **不降级保护**：已是高等级时，赠送的低等级奖励自动转为续期高等级（ULTRA用户获得邀请奖励 → 续期ULTRA 30天，不降为PRO）

**到期与降级**：

- 高级会员到期后，账号自动降级为普通会员(PLUS)，不再享有不限量配额
- 定时任务每5分钟扫描过期会员记录，自动执行降级
- `t_user` 表与 `t_user_membership` 表通过 `membership_expire_at` 字段实时同步

**会员数据存储**：

| 表 | 关键字段 | 说明 |
|----|---------|------|
| `t_user` | `membership_level`, `membership_expire_at` | 用户当前等级与过期时间（冗余，实时同步） |
| `t_user_membership` | `level`, `effective_from`, `effective_to`, `status`, `source` | 会员记录权威来源 |

**会员来源(source)**：

| 来源 | 说明 |
|------|------|
| `RECHARGE` | 用户付费购买 |
| `INVITE` | 邀请奖励赠送 |
| `LICENSE` | 入驻信息审核通过赠送 |
| `ADMIN_GRANT` | 运营手动发放 |
| `SYSTEM` | 系统默认（普通会员PLUS） |

**付费套餐（当前开放）**：

| 方案编码 | 方案名称 | 会员等级 | 价格 | 原价 | 有效天数 |
|----------|----------|----------|------|------|----------|
| MONTHLY_PRO | 高级会员·月卡 | PRO | ¥29.90 | ¥59.90 | 30天 |
| YEARLY_PRO | 高级会员·年卡 | PRO | ¥299.90 | ¥599.90 | 365天 |
| ULTRA | 超级会员·连锁专享 | ULTRA | - | - | 敬请期待 |

> **说明**：普通会员(PLUS)免费开放，无付费套餐。高级会员(PRO)提供月卡和年卡两种套餐。超级会员(ULTRA)暂未开放购买。

**用户侧接口**：

| 接口 | 说明 |
|------|------|
| GET /api/membership/my | 查询我的会员信息（等级、到期时间、来源等） |
| GET /api/membership/benefits?level=PLUS | 查询指定等级的权益配置详情 |
| GET /api/membership/levels | 获取所有会员等级列表（公开，含定价方案） |
| GET /api/membership/levels/{id} | 获取等级详情（公开） |

### 2.3 爬虫配额体系

用户总配额 = **会员权益配额** + **额外配额**

额外配额来源：

| 来源 | 类型标识 | 过期策略 | 说明 |
|------|----------|----------|------|
| 邀请奖励 | INVITE | 永不过期 | 运营配置的额外爬虫次数（当前默认0，仅送会员不送配额） |
| 购买会员 | PURCHASE | 可配置 | 购买/升级会员时发放 |
| 运营发放 | ADMIN | 可配置 | 运营手动为指定用户发放 |

**配额周期**：日配额（每日重置）+ 月配额（每月重置）+ 年配额（每年重置）

**消耗优先级**：优惠券 > 额外配额（快过期优先）> 会员权益配额

**过期控制**：每笔发放独立设置 `expire_time`，定时任务每小时扫描标记过期记录。

**用户侧接口**：

| 接口 | 说明 |
|------|------|
| GET /api/crawler/status | 获取爬虫配额状态（今日/本月/本年 已用、剩余、来源明细） |
| POST /api/crawler/consume | 消耗爬虫次数（前端启动爬虫前调用） |
| GET /api/crawler/logs?days=7 | 获取爬虫使用记录（最近N天） |
| GET /api/invite/extra-quota | 查询我的可用额外配额总数（邀请奖励 + 运营发放） |

### 2.4 药品比价核心功能

#### 业务流程

```
输入药品名称 → 选择比价平台（药师帮/药帮忙/1药城） 
→ 并行查询已绑平台账号 
→ 展示比价结果（按价格从低到高排序）
→ 点击"去XX平台购买"跳转到原平台完成交易
```

#### 药品搜索接口

| 接口 | 说明 |
|------|------|
| POST /api/search/query | 药品搜索比价，消耗1次爬虫配额，返回各平台报价 |
| GET /api/search/suggestions | 获取热门药品搜索建议（公开，无需登录） |

#### 支持的医药平台（MVP首期3个核心平台）

**B2B批发平台（3个 - MVP启用）：**
- ✅ 药师帮 - 国内领先医药B2B平台
- ✅ 药帮忙 - 医药B2B采购平台
- ✅ 1药城 - B2B医药批发平台

**后续扩展平台（通过运营配置动态启用）：**
- Phase 2：药京采、健之佳、1药网等7个B2B平台
- Phase 3：珍诚医药、药易通等6个区域B2B平台
- Phase 4-6：B2C零售、电商医药频道、垂直医疗平台等24个

**说明**：代码支持34个平台，但MVP首期仅启用3个核心平台，后续通过运营配置逐步开放。

#### 平台账号绑定

| 接口 | 说明 |
|------|------|
| POST /api/platform-account/bind | 绑定B2B平台账号（AES-256加密存储） |
| DELETE /api/platform-account/unbind/{platformCode} | 解绑平台账号 |
| GET /api/platform-account/list | 查询已绑定的平台账号列表 |
| POST /api/platform-account/verify/{platformCode} | 验证平台账号有效性 |

#### 平台配置查询

| 接口 | 说明 |
|------|------|
| GET /api/platform-config/enabled | 查询所有启用的平台列表（公开） |
| GET /api/platform-config/{platformCode} | 查询指定平台配置（公开） |

#### 比价结果展示

| 字段 | 说明 |
|------|------|
| 平台名称 | 药师帮、药帮忙、1药城（带彩色Badge） |
| 供应商 | 药品批发公司名称 |
| 规格 | 药品规格（如：0.25g×24片） |
| 价格 | 单价（元），最低价红色标注 |
| 最小起订量 | 最少购买数量 |
| 库存状态 | 有货/缺货 |
| 效期 | 药品有效期，近效期橙色标注 |
| 操作 | 「去XX平台购买」按钮 → WebView跳转原平台 |

### 2.5 邀请裂变系统

#### 用户侧流程

```
药店A获取邀请链接 → 分享给其他药店B 
→ B打开落地页（显示A的药店名称和奖励说明）
→ B下载客户端并注册（自动填入邀请码）
→ A获得奖励：1个月高级会员(PRO) + 可选额外爬虫配额
→ B注册即得普通会员(PLUS)，永久免费
```

#### 奖励机制

| 角色 | 奖励内容 | 说明 |
|------|----------|------|
| 邀请人 | 1个月高级会员(PRO) + 可选额外爬虫配额 | 每成功邀请1家药店注册即发放，奖励立即到账 |
| 被邀请人 | 普通会员(PLUS) | 注册即获得，不限时长，永久免费 |

**邀请奖励规则**：
- 老用户邀请新用户，完成注册后邀请人立即获得1个月高级会员时长
- 奖励会员等级固定为PRO（高级会员），与邀请人当前等级无关
- **不降级保护**：若邀请人已是ULTRA，自动续期ULTRA 30天，不降为PRO
- 额外爬虫配额由运营后台配置（`rewardCrawlerCount`），默认0=不额外发放
- 单个账号获得会员时长奖励上限30人（超限可继续邀请但不再发放奖励）
- **被邀请人限制**：注册30天内可输入邀请码，每人仅能填写一次，二次无效
- **补填邀请码**：注册时未填，30天内可在个人中心补填，邀请人同样获得奖励

#### 支持渠道

| 渠道 | channel | 打开方式 | 说明 |
|------|---------|----------|------|
| Windows App | windows | download | 直接下载客户端（默认渠道） |
| 微信公众号 | wechat | redirect | 跳转公众号/H5 |
| 小程序 | miniapp | miniapp | 打开小程序 |
| 钉钉 | dingtalk | deeplink | 应用内深度链接 |
| 飞书 | feishu | deeplink | 应用内深度链接 |

#### 邀请码安全生成与智能解析

- 邀请码采用安全随机生成算法，支持链接和码双模式呈现
- 落地页支持URL Scheme（`zhijiayun://invite?code=XXX`）和DeepLink自动填入邀请码
- 支持链接/邀请码双模式智能解析与注册自动绑定
- 落地页标题支持 `{inviter}` 和 `{pharmacy}` 动态占位符替换

#### 分享文案示例

```
我是用户6917，在这里发现了一个药店采购神器——智价云（药店版）！它聚合比价功能特别方便，能快速查到最低价，帮你节省采购成本。下载链接https://priceapi.kailin.com.cn/api/invite/2XKADABS填我的邀请码 2XKADABS 完成注册，你也会获得会员权益！
```

#### 邀请统计

- 摘要文本：`已邀请5家药店，3家注册，累计获得3个月会员`
- 每条记录显示：被邀请药店名称、注册状态（已注册/待注册）、奖励次数
- 统计数据：总邀请数、已注册数、累计奖励、链接点击次数、今日邀请数/剩余次数

#### 用户侧接口

| 接口 | 说明 |
|------|------|
| GET /api/invite/code | 获取我的邀请码和邀请链接（含分享文案） |
| GET /api/invite/stats | 获取邀请统计（邀请人数、注册人数、累计奖励） |
| GET /api/invite/rewards | 获取邀请记录列表（含注册状态） |
| GET /api/invite/extra-quota | 获取可用额外爬虫次数 |
| GET /api/invite/my-inviter | 查询我的邀请人 |
| POST /api/invite/bind | 补填邀请码 |
| GET /api/invite/page/{code}?channel=windows | 邀请落地页数据（公开，无需登录） |
| GET /invite/{code}?channel=wechat | 邀请链接直接访问入口（公开，自动计入点击数） |
| POST /api/invite/click/{code} | 追踪邀请链接被打开（公开） |
| GET /api/invite/resolve-link?link=xxx | 智能解析邀请链接或邀请码（公开，适用于粘贴文本场景） |

### 2.6 入驻信息提交（可选）

**设计原则**：
- ✅ 用户可以自愿提交入驻信息（含营业执照、药品经营许可证、医疗器械备案等）
- ✅ 不提交不影响基本使用（注册、查询、购买）
- ✅ 提交后运营审核，通过后显示"已认证"标识
- ✅ 认证标识增强用户信任度

**审核流程**：
```
用户提交入驻信息 → 运营后台查看待审队列 
→ 运营审核（通过/驳回）→ 通过后显示"已认证"标识
```

**入驻信息**：店铺名称、经营终端类型、所在地区、营业执照、药品经营许可证、医疗器械备案（二类/三类）等。

**审核通过奖励**：首次入驻信息审核通过，自动赠送30天高级会员(PRO)，来源标记为 `LICENSE`。

**用户侧接口**：

| 接口 | 说明 |
|------|------|
| POST /api/business-license/upload | 提交入驻信息（JSON方式，传图片URL） |
| POST /api/business-license/upload-file | 提交入驻信息（文件方式，multipart） |
| GET /api/business-license/info | 查询我的入驻信息及审核状态 |

### 2.7 优惠券系统

| 功能 | 说明 |
|------|------|
| 发放 | 运营指定已有优惠券，批量发放给指定用户 |
| 使用 | 爬虫消耗时优先使用优惠券 |
| 类型 | CRAWLER（爬虫次数券） |

**用户侧接口**：

| 接口 | 说明 |
|------|------|
| GET /api/coupon/my?status=0 | 获取我的优惠券列表（可按状态筛选） |
| GET /api/coupon/my/available?type=CRAWLER | 获取我当前可用的优惠券列表 |

### 2.8 文件上传

| 接口 | 说明 |
|------|------|
| POST /api/upload | 上传单个文件（multipart/form-data），返回文件访问路径 |

**说明**：支持入驻信息图片、用户头像等文件上传，文件存储在服务器 `/opt/uploads` 目录。

### 2.9 支付与会员购买系统

| 功能 | 接口 | 说明 |
|------|------|------|
| 支付方案列表 | GET /api/payment/plans | 获取可用会员套餐（公开） |
| 创建支付订单 | POST /api/payment/order/create | 选择套餐+支付渠道创建订单 |
| 查询订单 | GET /api/payment/order/{orderNo} | 查询单个订单状态 |
| 我的订单 | GET /api/payment/orders | 查询用户所有订单 |
| 模拟支付 | POST /api/payment/order/{orderNo}/pay | 开发测试用模拟支付（当前仅支持此模式） |
| 切换渠道 | POST /api/payment/order/{orderNo}/switch-channel | 切换支付渠道并重新生成二维码 |
| 微信回调 | POST /api/payment/callback/wechat | 微信支付异步通知（公开，当前仅模拟模式） |
| 支付宝回调 | POST /api/payment/callback/alipay | 支付宝异步通知（公开，当前仅模拟模式） |

**支付渠道**：微信支付（Native扫码）、支付宝（当面付/扫码）

**重复支付自动退款**：用户切换支付渠道后，多个渠道都可能支付成功。系统以第一次支付成功为准激活会员，后续重复支付自动记录到 `t_payment_order_extra_payment` 表，并原路退款（微信退款API v3 / 支付宝退款接口）。退款状态记录为 PENDING → SUCCESS/FAILED，支持退款失败原因追踪。

> **⚠️ 当前状态**：生产环境微信/支付宝回调接口为占位实现（含TODO），当前仅模拟支付模式可用。上线前需接入微信支付SDK和支付宝SDK完成验签与解密。

**支付方案（当前开放）**：

| 方案编码 | 方案名称 | 会员等级 | 价格 | 原价 | 有效天数 |
|----------|----------|----------|------|------|----------|
| MONTHLY_PRO | 高级会员·月卡 | PRO | ¥29.90 | ¥59.90 | 30天 |
| YEARLY_PRO | 高级会员·年卡 | PRO | ¥299.90 | ¥599.90 | 365天 |
| ULTRA | 超级会员·连锁专享 | ULTRA | - | - | 敬请期待 |

> **说明**：普通会员(PLUS)免费开放，注册即得，不提供付费套餐。月卡自付款日起算30天，年卡自付款日起算365天。

**运营管理**：

| 接口 | 说明 |
|------|------|
| POST /api/admin/payment/plans | 创建支付方案 |
| PUT /api/admin/payment/plans/{id} | 更新支付方案 |
| PUT /api/admin/payment/plans/{id}/status | 上架/下架方案 |

### 2.10 平台会话管理

| 接口 | 说明 |
|------|------|
| PUT /api/platform-session/{platformCode} | 更新平台会话 |
| GET /api/platform-session/list | 查询平台会话列表 |
| DELETE /api/platform-session/{platformCode} | 删除平台会话 |

### 2.11 搜索历史与关注列表

#### 搜索历史

| 接口 | 说明 |
|------|------|
| POST /api/search-record/history | 保存一次比价搜索记录（桌面端调用） |
| GET /api/search-record/history | 分页获取用户搜索历史 |
| GET /api/search-record/history/{id} | 获取指定搜索记录详情 |

#### 关注/收藏列表

| 接口 | 说明 |
|------|------|
| GET /api/watchlist | 获取关注列表 |
| POST /api/watchlist | 添加关注药品 |
| DELETE /api/watchlist/{id} | 取消关注 |
| GET /api/watchlist/stats | 获取关注统计 |

**关注信息**：药品名称、规格、厂家、关注时最低价、最低价平台、上次查询价格、价格变动、最后检查时间。

### 2.12 活动中心

活动中心统一管理三类运营活动：**邀请有礼**、**签到有礼**、**比价抽奖**。

#### 2.12.1 邀请有礼活动

基于邀请裂变系统（见 2.5）的增强版，由活动配置驱动：

- 活动时间窗口内，邀请人成功邀请新用户并通过入驻审核后，双方各获得会员天数奖励
- 支持运营端配置奖励天数、邀请上限、活动开关
- 支持撤销邀请奖励（反作弊）和活动窗口内补发

**用户侧接口**：

| 接口 | 说明 |
|------|------|
| GET /api/activity/invite/status | 查询邀请有礼活动状态（已获奖励次数、剩余次数等） |

#### 2.12.2 签到有礼活动

每日签到 + 周期达标奖励机制：

- **活动时间**：运营可配置活动开始和结束时间
- **周期模式**：支持两种周期模式
  - FRI_THU：周五至下周四（7天）
  - MON_SUN：周一至周日（7天）
- **自动生成周期**：配置活动时间后，系统自动根据周期模式生成所有活动周期
- **周期管理**：
  - PENDING周期：可自动删除重建（当活动时间或周期模式变更时）
  - ACTIVE/CLOSED周期：保留（已有用户签到数据）
- **签到规则**：
  - 用户每天可签到一次
  - 每个活动周期内累计签到达到要求天数，自动获得会员天数奖励
  - 支持累计模式（CUMULATIVE）和连续模式（CONSECUTIVE）
- **数据统计**：
  - 总体统计：今日/昨日/近7天/近30天签到人数、累计签到次数、累计签到用户数、累计发放奖励
  - 周期维度统计：每个周期的签到人数、达标人数、达标率、已发放奖励人数
  - 药店名称：签到记录关联用户药店名称

**用户侧接口**：

| 接口 | 说明 |
|------|------|
| GET /api/checkin/status | 查询今日签到状态（含当前周期进度） |
| POST /api/checkin | 执行签到 |
| GET /api/checkin/calendar?year=2026&month=7 | 查询当月签到日历 |
| GET /api/checkin/records | 分页查询签到记录 |

#### 2.12.3 比价抽奖活动

面向高级会员的抽奖运营活动，用户每日首次比价后获得一次抽奖机会。

**参与条件**：高级会员(PRO)及以上 + 入驻信息审核通过，活动时间可配置。

**奖品池示例**：

| 奖项 | 奖品 | 份数 | 权重 | 中奖概率 |
|------|------|------|------|----------|
| 特等奖 | iPhone 17 | 0 | 0 | 0%（仅展示） |
| 一等奖 | 30天高级会员 | 20 | 20 | 0.25% |
| 二等奖 | 15天高级会员 | 100 | 100 | 1.25% |
| 三等奖 | 7天高级会员 | 150 | 150 | 1.875% |
| 四等奖 | 3天高级会员 | 250 | 250 | 3.125% |
| 五等奖 | 1天高级会员 | 1080 | 1080 | 13.5% |
| 谢谢惠顾 | 无 | 6400 | 6400 | 80% |

**抽奖限制**：每日仅限抽奖1次，重复抽奖记录违规审计日志。

**用户侧接口**：

| 接口 | 说明 |
|------|------|
| GET /api/activity/lottery/status | 查询抽奖活动状态（今日可用机会、资格） |
| GET /api/activity/lottery/prizes | 获取可抽奖品列表（不含概率权重等敏感信息） |
| POST /api/activity/lottery/draw | 执行抽奖 |
| GET /api/activity/lottery/records?limit=20 | 我的抽奖记录 |

#### 2.12.4 统一活动接口

| 接口 | 说明 |
|------|------|
| GET /api/activity/available | 获取当前用户可参加的所有活动摘要（三类活动一次返回） |
| GET /api/activity/rewards?type=INVITE\|CHECKIN\|LOTTERY | 按活动类型分页查询奖励记录 |
| GET /api/activity/checkin-cycle/status | 签到送会员周期状态 |
| GET /api/activity/checkin-cycle/rewards | 签到周期奖励记录 |

#### 运营端活动管理接口

| 接口 | 说明 |
|------|------|
| GET /api/admin/activity/invite/config | 查询邀请有礼活动配置 |
| PUT /api/admin/activity/invite/config | 更新邀请有礼活动配置 |
| POST /api/admin/activity/invite/revoke | 撤销邀请奖励（反作弊） |
| POST /api/admin/activity/invite/retroactive-grant | 活动窗口内补发邀请奖励 |
| GET /api/admin/activity/checkin-cycle/config | 查询签到送会员配置 |
| PUT /api/admin/activity/checkin-cycle/config | 更新签到送会员配置 |
| GET /api/admin/activity/lottery/config | 查询比价抽奖活动配置 |
| PUT /api/admin/activity/lottery/config | 更新比价抽奖活动配置 |
| GET /api/admin/activity/lottery/prizes | 奖品池列表 |
| POST /api/admin/activity/lottery/prizes | 新增奖品 |
| PUT /api/admin/activity/lottery/prizes/{id} | 更新奖品 |
| DELETE /api/admin/activity/lottery/prizes/{id} | 删除奖品 |
| GET /api/admin/activity/lottery/records | 分页查询所有用户抽奖记录 |
| GET /api/admin/activity/rewards?type=INVITE\|CHECKIN\|LOTTERY | 按活动类型分页查询奖励记录 |

### 2.13 运营管理后台

#### 用户管理

| 接口 | 说明 |
|------|------|
| GET /api/admin/users | 分页查询用户列表（支持按手机号/昵称筛选） |
| POST /api/admin/users/{userId}/kick | 强制踢出用户（使所有 Token 失效） |

#### 管理员账号管理

| 接口 | 说明 |
|------|------|
| GET /api/admin/admins | 管理员列表（分页） |
| GET /api/admin/admins/{id} | 查询单个管理员 |
| POST /api/admin/admins | 创建管理员 |
| PUT /api/admin/admins/{id} | 更新管理员信息 |
| DELETE /api/admin/admins/{id} | 禁用管理员 |
| PUT /api/admin/admins/{id}/password | 重置管理员密码 |
| PUT /api/admin/admins/password | 当前管理员修改自己的密码 |
| POST /api/admin/admins/{adminId}/kick | 强制退出管理员 |

#### 系统配置管理

| 接口 | 说明 |
|------|------|
| GET /api/admin/system-config/list | 分页查询系统配置列表（按类型筛选） |
| GET /api/admin/system-config/enabled | 查询启用的配置列表 |
| GET /api/admin/system-config/{id} | 查询单个配置 |
| GET /api/admin/system-config/by-key | 按配置键精确查询 |
| POST /api/admin/system-config | 新增配置 |
| PUT /api/admin/system-config/{id} | 更新配置 |
| DELETE /api/admin/system-config/{id} | 删除配置 |

> 系统配置支持管理外部 API Key、业务开关等全局参数，按 configType 分组（如 EXTERNAL_API、GENERAL），修改后立即生效。

#### 邀请管理

| 接口 | 说明 |
|------|------|
| GET /api/admin/invite/config | 获取当前生效的邀请配置 |
| PUT /api/admin/invite/config | 更新邀请配置 |
| GET /api/admin/invite/configs | 分页获取邀请配置列表 |
| GET /api/admin/invite/config/{id} | 根据ID获取邀请配置 |
| POST /api/admin/invite/config | 创建新的邀请配置 |
| PUT /api/admin/invite/config/{id} | 更新指定ID的邀请配置 |
| DELETE /api/admin/invite/config/{id} | 删除邀请配置 |
| GET /api/admin/invite/rewards | 查看邀请记录（分页） |
| GET /api/admin/invite/conversion-stats | 查看邀请转化统计 |

#### 爬虫配额管理

| 接口 | 说明 |
|------|------|
| POST /api/admin/crawler/grant | 运营手动发放爬虫次数 |
| GET /api/admin/crawler/grants | 查看发放记录（分页） |
| GET /api/admin/crawler/user-detail | 查看用户爬虫使用详情（含平台分布） |

#### 会员管理

| 接口 | 说明 |
|------|------|
| POST /api/admin/membership/grant | 发放/调整用户会员等级 |
| GET /api/admin/membership/memberships | 分页查询会员记录（支持多条件筛选） |
| GET /api/admin/membership/users | 会员用户快照列表（用户维度） |

#### 入驻信息审核

| 接口 | 说明 |
|------|------|
| GET /api/admin/license/review | 审核列表查询（支持按状态/关键词筛选） |
| POST /api/admin/license | 管理员代填入驻信息 |
| PUT /api/admin/license/{licenseId} | 管理员编辑入驻信息 |
| POST /api/admin/license/review | 审核入驻信息（通过/驳回） |

#### 支付方案管理

| 接口 | 说明 |
|------|------|
| GET /api/admin/payment/plans | 查询所有支付方案（含已下架） |
| POST /api/admin/payment/plans | 创建支付方案 |
| PUT /api/admin/payment/plans/{id} | 更新支付方案 |
| PUT /api/admin/payment/plans/{id}/status | 上架/下架方案 |

#### 优惠券发放

| 接口 | 说明 |
|------|------|
| POST /api/coupon/issue | 发放优惠券（指定已有券批量发放给用户） |

#### 签到管理

| 接口 | 说明 |
|------|------|
| GET /api/admin/checkin/config | 获取签到全局配置 |
| PUT /api/admin/checkin/config | 更新签到全局配置 |
| GET /api/admin/checkin/stats | 签到统计概览 |
| GET /api/admin/checkin/records | 分页查询签到记录 |
| GET /api/admin/checkin/user/{userId}/records | 查询指定用户签到记录 |
| GET /api/admin/checkin/periods | 签到周期列表 |
| POST /api/admin/checkin/periods | 创建签到周期 |
| PUT /api/admin/checkin/periods/{id} | 更新签到周期 |
| DELETE /api/admin/checkin/periods/{id} | 删除签到周期 |

### 2.14 操作审计日志系统

系统对所有关键操作进行审计记录，支持追溯：

- **记录维度**：操作人、操作时间、IP地址、设备信息、操作模块、操作类型、目标对象、操作前后数据快照、耗时
- **敏感操作标记**：禁用用户、审核操作、配置变更等标记为敏感操作
- **操作模块覆盖**：用户管理、平台配置、账号绑定、入驻信息、邀请系统、优惠券、爬虫配额、系统管理

**运营侧接口**：

| 接口 | 说明 |
|------|------|
| GET /api/admin/audit-log | 分页查询审计日志（支持按模块、操作类型、操作人、时间范围、是否敏感筛选） |
| GET /api/admin/audit-log/sensitive | 查询敏感操作日志 |
| GET /api/admin/audit-log/user/{userId} | 查询指定用户的操作历史 |
| GET /api/admin/audit-log/target/{type}/{id} | 查询指定目标对象的操作历史 |
| GET /api/admin/audit-log/stats | 按模块统计操作次数 |

### 2.15 采购台账

手动记录采购信息，便于药店管理采购流水：

| 接口 | 说明 |
|------|------|
| GET /api/procurement-ledgers | 分页查询我的采购台账列表 |
| POST /api/procurement-ledgers | 新增一条采购记录（关联比价查询ID、药品名称、数量、价格、平台等） |
| PATCH /api/procurement-ledgers/{id} | 更新采购记录（状态、数量、价格、备注） |
| DELETE /api/procurement-ledgers/{id} | 删除采购记录 |

### 2.16 跳转购买记录

记录用户从比价结果页点击"去购买"跳转到第三方平台的行为：

| 接口 | 说明 |
|------|------|
| GET /api/purchase-intents | 分页查询跳转购买记录列表 |
| GET /api/purchase-intents/{id} | 查询跳转购买详情 |
| POST /api/purchase-intents | 写入跳转购买记录（桌面端/Android 调用） |

**记录信息**：药品名称、规格、厂家、平台、参考价格、跳转链接、来源客户端。

### 2.17 帮助与内容

提供面向用户的静态内容服务：

| 接口 | 说明 |
|------|------|
| GET /api/content/help | 帮助与常见问题（FAQ），返回帮助标题和问答列表 |
| GET /api/content/download | 获取桌面客户端下载链接、版本号、更新日志 |

### 2.18 管理员认证

| 接口 | 说明 |
|------|------|
| POST /api/admin/auth/login | 管理员密码登录（操作 t_admin 表，支持用户名/手机号+密码） |

---

## 3. 核心业务流程

### 3.1 用户注册登录流程

```
药店采购员打开App → 选择登录方式
├── 短信登录：输入手机号 → 获取验证码 → 输入验证码 → 登录/注册
│   └── 如有邀请码，自动建立邀请关系并发放会员奖励
├── 密码登录：输入手机号/昵称 + 密码 → 验证通过 → 登录
└── 微信登录：扫码 → 授权 → 绑定手机号 → 登录
```

### 3.2 药品比价流程

```
输入药品名称（如：阿莫西林）
→ 选择比价平台（可多选：药师帮、药帮忙、1药城）
→ 点击"开始比价"
→ 系统逐个平台爬取价格（消耗配额）
→ 展示比价结果表格（按价格从低到高排序）
→ 点击"去采购"跳转到对应平台购买页面
→ 可关注药品，持续追踪价格变动
```

### 3.3 爬虫消耗流程

```
用户发起比价请求
→ 校验日/月/年配额（会员权益 + 额外配额）
→ 配额充足 → 扣减额外配额（快过期优先）→ 记录日志（含平台信息）
→ 配额不足 → 尝试使用优惠券补充 → 仍不足则拒绝
```

### 3.4 邀请裂变流程

```
药店A获取邀请链接 → 复制链接分享到微信群/朋友圈
→ 药店B浏览器打开 → 展示落地页（A的药店名称 + 奖励说明 + 下载链接）
→ B下载注册 → 携带邀请码 → 建立邀请关系 → 发放奖励
  ├── 邀请人A：获赠1个月高级会员(PRO) + 可选额外爬虫配额（立即到账）
  └── 被邀请人B：注册即得普通会员(PLUS)，永久免费
→ A查看统计："已邀请X家药店，Y家注册，累计获得Y个月高级会员"
→ A同时可在邀请页查看邀请贡献的爬虫配额明细
```

### 3.5 会员购买流程

```
用户查看会员套餐 → 选择方案（月卡/年卡）
→ 选择支付渠道（微信/支付宝）→ 创建订单 → 生成二维码
→ 用户扫码支付 → 第三方回调通知 → 订单状态更新为已支付
→ 自动激活高级会员(PRO) → t_user 会员等级与过期时间实时同步 → 配额立即生效
→ 同等级续期叠加天数，低等级升级切换
```

### 3.6 重复支付与自动退款流程

```
用户创建订单（渠道A）→ 切换渠道为B → 生成渠道B二维码
→ 渠道A先支付成功 → 订单标记为PAID，激活会员
→ 渠道B也支付成功 → 回调到达，发现订单已PAID
→ 记录重复支付到 t_payment_order_extra_payment（幂等：同交易号不重复记录）
→ 自动发起原路退款（渠道B原路退回）
→ 退款状态更新：PENDING → SUCCESS/FAILED
```

**退款渠道**：
- 微信：调用 WxPayService.refundV3()（API v3 退款接口）
- 支付宝：调用 AlipayClient.execute(AlipayTradeRefundRequest)（统一收单交易退款）
- 模拟模式：直接返回模拟退款单号，不调用真实SDK

---

## 4. 多端交付策略

### 4.1 核心策略："Windows优先，多渠道扩展"

智价云（药店版）采用**渐进式多端交付策略**：

1. **MVP阶段**：聚焦Windows桌面应用，验证核心业务流程
2. **Phase 2**：扩展移动端（小程序 + Android APP），提高用户便利性
3. **Phase 3**：完善社交渠道（公众号 + iOS APP），增强用户粘性
4. **Phase 4+**：企业集成（钉钉/飞书）+ 生态建设，构建行业壁垒

**目标**：通过多渠道触达，实现日活20万+的目标。

### 4.2 各端详细规划

#### Windows桌面应用（MVP核心 - P0）

- **角色**：专业采购工具，功能最完整
- **场景**：药店办公室日常采购、深度比价、批量查询
- **用户占比目标**：60%
- **技术特点**：WebView2浏览器引擎、自建安全策略、离线缓存

#### 微信小程序（Phase 2 - P1）

- **角色**：轻量级查询工具，快速比价
- **场景**：外出采购、临时查询、分享比价结果
- **用户占比目标**：25%
- **核心功能**：快速查询、关注列表、分享结果、扫码查询

#### Android APP（Phase 2 - P1）

- **角色**：移动端完整功能
- **场景**：移动办公、仓库盘点、现场比价
- **用户占比目标**：8%
- **核心功能**：完整比价、扫码查询、拍照识别、Push通知

#### 微信公众号（Phase 3 - P2）

- **角色**：消息推送和服务入口
- **场景**：降价提醒、审核结果通知、活动推送
- **用户占比目标**：5%
- **核心功能**：模板消息推送、菜单入口、H5页面嵌入

#### iOS APP（Phase 3 - P2）

- **角色**：覆盖iOS用户群体
- **用户占比目标**：2%

#### 钉钉/飞书集成（Phase 4 - P3）

- **角色**：企业内部协同工具
- **场景**：连锁药店内部采购协同、审批流程
- **用户占比目标**：< 1%

### 4.3 数据同步机制

所有端共享同一套账号体系，云端同步数据：

| 数据类型 | 同步方式 | 更新频率 |
|---------|---------|---------|
| 用户基本信息 | REST API | 实时 |
| 会员权益 | REST API | 实时 |
| 查询历史 | REST API + 本地缓存 | 实时上传，按需下载 |
| 关注列表 | REST API | 实时 |
| 平台账号绑定 | REST API（加密传输） | 实时 |
| 邀请关系 | REST API | 实时 |

---

## 5. 灵活配置策略

### 5.1 核心设计理念

智价云（药店版）采用**"代码预留扩展 + 运营动态配置"**的设计策略：

1. **平台扩展性**：代码支持34个平台，MVP首期启用3个，后续通过运营配置逐步开放
2. **入驻信息可选**：用户可以自愿提交，非强制要求，审核后显示认证标识
3. **会员体系灵活**：会员权益配置表支持运营动态调整各等级配额加成
4. **支付方案可配**：运营可创建/上架/下架会员套餐方案
5. **系统配置灵活**：运营可通过系统配置管理界面调整全局参数（API Key、业务开关等），修改后立即生效

### 5.2 平台配置策略

#### MVP首期（Phase 0）- 3个核心平台

| 平台 | 代码 | Badge颜色 | 状态 |
|------|------|----------|------|
| 药师帮 | yaoshibang | #FF6B00 | ✅ 已启用 |
| 药帮忙 | yaobangmang | #1890FF | ✅ 已启用 |
| 1药城 | yiyaocheng | #52C41A | ✅ 已启用 |

#### 后续扩展计划

- **Phase 2**：7个扩展B2B平台（药京采、健之佳、1药网等）
- **Phase 3**：6个区域B2B平台（珍诚医药、药易通等）
- **Phase 4**：8个B2C零售平台（叮当快药、老百姓大药房等）
- **Phase 5**：7个综合电商医药频道（京东健康、天猫医药等）
- **Phase 6**：4个垂直医药平台（微医、平安好医生等）

### 5.3 会员权益配置

**会员权益配置表**支持运营动态调整各等级权益加成：

| 权益类型 | 说明 |
|----------|------|
| DAILY_QUOTA | 每日爬虫配额加成 |
| MONTHLY_QUOTA | 每月爬虫配额加成 |
| YEARLY_QUOTA | 每年爬虫配额加成 |
| MAX_CONCURRENT | 最大并发数加成 |

运营可通过数据库管理界面调整各会员等级的权益数值，修改后立即生效。

---

## 6. 非功能性需求

| 维度 | MVP要求 | 生产环境目标 |
|------|---------|-------------|
| 性能 | 接口响应 < 500ms（P95），单次比价 < 3s | 接口响应 < 200ms（P95），单次比价 < 1s |
| 安全 | JWT 认证、三级RBAC、参数校验、AES-256加密 | 增加接口限流、SQL注入防护、慢请求告警 |
| 可用性 | 单体部署，HikariCP 连接池，Redis缓存 | 集群部署、负载均衡 |
| 扩展性 | Maven 多模块架构 | 微服务拆分、事件驱动架构 |
| 兼容性 | JDK 17+，MySQL 8.0+，Windows 10/11 | 容器化部署、云原生支持 |
| 数据准确性 | 价格误差 < 5% | 价格误差 < 1%，实时同步 |
| 目标日活 | 1万+ | 20万+ |

---

## 7. MVP范围与规划

### 7.1 MVP 已实现功能 ✅

**核心功能**：
- [x] **Windows独立桌面应用**（.exe格式，内置WebView2浏览器引擎）
- [x] 用户认证（短信验证码登录、密码登录、微信扫码登录、小程序登录、Token刷新、心跳保活）
- [x] 密码管理（设置/修改密码、修改手机号）
- [x] 入驻信息提交（可选，审核后显示认证标识）
- [x] B2B平台账号绑定（药师帮/药帮忙/1药城，密码AES-256加密存储）
- [x] 药品搜索比价功能（消耗配额查询，返回各平台报价）
- [x] 跳转原平台购买（WebView内嵌跳转，不依赖系统浏览器）
- [x] 搜索历史记录管理（保存、分页查询、详情查看）
- [x] 药品关注/收藏列表（价格变动追踪）
- [x] 会员体系（PLUS/PRO/ULTRA三档，权益驱动配额）
- [x] 爬虫配额管理（日/月/年三周期 + 额外配额 + 优惠券）
- [x] 邀请裂变系统（多渠道落地页、URL Scheme自动填入邀请码、会员时长奖励）
- [x] 支付系统（模拟支付、支付方案管理、渠道切换、重复支付自动退款、签约协议；微信/支付宝回调为占位实现，待接入SDK）
- [x] 优惠券系统（批量发放、配额消耗优先使用）
- [x] 活动中心（邀请有礼、签到送会员、比价抽奖三类活动，含统一摘要接口）
- [x] 每日签到（签到日历、周期管理、签到统计）
- [x] 采购台账（手动记录采购流水，增删改查）
- [x] 跳转购买记录（追踪用户跳转第三方平台行为）
- [x] 运营管理后台（用户管理、管理员管理、系统配置、配置管理、入驻审核、会员管理、支付方案管理、签到管理）
- [x] 平台配置管理（34个平台预留，MVP启用3个，运营动态配置）
- [x] 操作审计日志系统（记录所有关键操作，支持追溯）
- [x] 网关层请求日志与限流（基于Redis的IP+路径限流）
- [x] 帮助内容服务（FAQ、下载链接）

**多端扩展准备**：
- [x] 统一账号体系设计（支持多端登录）
- [x] API接口标准化（RESTful，便于多端调用）
- [x] 数据同步机制设计（查询历史、关注列表云端同步）
- [ ] 微信小程序开发（Phase 2）
- [ ] Android APP开发（Phase 2）
- [ ] 微信公众号接入（Phase 3）
- [ ] iOS APP开发（Phase 3）

### 7.2 后续迭代规划 🚀

#### Phase 2：性能优化与多端扩展（上线后1-3个月）

**技术优化**：
- [ ] 数据库读写分离
- [ ] SQL慢查询优化与索引调优
- [ ] 接口限流细化（按用户维度限流）
- [ ] 慢请求监控与告警

**多端扩展**：
- [ ] **微信小程序开发**（轻量级查询工具）
- [ ] **Android APP开发**（移动端完整功能）
- [ ] 数据同步服务（查询历史、关注列表云端同步）
- [ ] 统一消息推送服务

#### Phase 3：功能增强与渠道完善（上线后3-6个月）

**功能增强**：
- [ ] 国家集采数据爬取（增强权威性）
- [ ] 价格趋势图表（近30天价格走势）
- [ ] 供应商评分系统
- [ ] 邀请排行榜与阶梯奖励
- [ ] 海报生成与分享

**渠道完善**：
- [ ] **微信公众号接入**（服务号消息推送）
- [ ] **iOS APP开发**（覆盖iOS用户）
- [ ] 小程序/APP扫码查询功能
- [ ] 拍照识别药品功能

#### Phase 4：智能推荐与企业集成（上线后6-9个月）

**智能功能**：
- [ ] AI价格预测（基于历史数据预测价格波动）
- [ ] 智能供应商推荐（综合价格、信誉、配送速度）
- [ ] 采购清单优化（批量采购最优组合）
- [ ] 个性化推荐（根据药店历史采购习惯）

**企业集成**：
- [ ] **钉钉工作台集成**（企业内部协同）
- [ ] **飞书工作台集成**（企业内部协同）
- [ ] 企业账号管理（多员工统一管理）
- [ ] 采购审批流程

#### Phase 5：架构升级与生态建设（上线后9-12个月）

**架构升级**：
- [ ] 微服务拆分（用户服务、配额服务、邀请服务、爬虫服务独立部署）
- [ ] 消息队列（异步处理爬虫任务和邀请奖励发放）
- [ ] 容器化部署（Docker + K8s）
- [ ] CI/CD自动化流水线
- [ ] 多地域部署（降低延迟）

**生态建设**：
- [ ] 开放API平台（第三方开发者接入）
- [ ] 插件市场（自定义功能扩展）
- [ ] 数据 marketplace（脱敏数据交易）
- [ ] 行业解决方案（连锁药店、单体药店差异化方案）

---

## 8. 业务指标

### 8.1 MVP阶段目标（上线后3个月）

| 指标 | 目标值 | 说明 |
|------|--------|------|
| 注册用户数 | 1万+ | 药店采购人员 |
| 日活跃用户（DAU） | 1000+ | 日均使用比价的药店数 |
| 日均比价次数 | 5000+ | 所有用户的比价操作总和 |
| 邀请转化率 | 15%+ | 被邀请人注册比例 |
| 用户留存率（7日） | 40%+ | 注册后7天内再次使用 |
| 付费转化率 | 5%+ | 购买会员套餐的比例 |

### 8.2 长期目标（1年内）

| 指标 | 目标值 | 说明 |
|------|--------|------|
| 注册用户数 | 50万+ | 覆盖全国主要药店 |
| 日活跃用户（DAU） | 20万+ | **核心目标** |
| 日均比价次数 | 100万+ | 高频使用场景 |
| 付费转化率 | 10%+ | 升级为PRO/ULTRA的比例 |
| 平均采购成本降低 | 15%+ | 相比单平台采购 |

---

**📝 说明**：本文档会随着项目迭代持续更新，请以最新版本为准。