智价云药店 - 架构文档

⚠️ MVP 阶段说明
本项目为全新项目，尚未上线，当前处于 MVP（最小可行产品）阶段。
本文档描述的是 MVP 版本的架构设计，后续将根据业务发展和技术演进持续优化。

版本：v1.0-MVP | 更新日期：2026-06-16 | 状态：开发中

1. 技术栈

层次	技术	版本	MVP说明
语言	Java	17	✅
框架	Spring Boot	3.5.14	✅
ORM	MyBatis-Plus	3.5.16	✅
数据库	MySQL	8.0+	✅
缓存	Redis (Lettuce)	6.0+	⚠️ Mock实现，生产环境需接入真实Redis
认证	JWT (jjwt)	0.12.6	✅
短信	阿里云 SMS	4.5.1	✅
工具库	Hutool	5.8.44	✅
安全	Spring Security + BouncyCastle	1.84	✅
构建	Maven	3.8+	✅

2. 模块架构

2.1 模块总览

zhijiayun-pharmacy (父工程)
├── zhijiayun-common    # 公共模块：Result、ErrorCode、BusinessException
├── zhijiayun-user      # 用户模块：认证、等级、优惠券、爬虫配额
├── zhijiayun-invite    # 邀请模块：邀请码、裂变、运营配置
├── zhijiayun-payment   # 支付模块（预留）
└── zhijiayun-gateway   # 网关模块：聚合启动、请求日志、限流

2.2 模块依赖关系

zhijiayun-gateway (聚合启动入口)
├── zhijiayun-user
│   └── zhijiayun-common
├── zhijiayun-invite
│   ├── zhijiayun-user (依赖 CrawlerQuotaGrantService)
│   └── zhijiayun-common
└── zhijiayun-payment
    └── zhijiayun-common

2.3 包结构

com.xuekairui
├── common/                    # zhijiayun-common
│   ├── Result.java            # 统一响应封装
│   ├── ErrorCode.java         # 错误码枚举
│   └── BusinessException.java # 业务异常
│
├── user/                      # zhijiayun-user
│   ├── config/                # 配置类
│   │   ├── AliyunSmsProperties.java
│   │   ├── MyBatisPlusMetaHandler.java
│   │   ├── RedisConfig.java
│   │   └── SecurityConfig.java
│   ├── controller/            # 控制器
│   │   ├── AuthController.java
│   │   ├── CrawlerController.java
│   │   ├── CouponController.java
│   │   └── UserLevelController.java
│   ├── dto/                   # 数据传输对象
│   ├── entity/                # 数据库实体
│   ├── mapper/                # MyBatis-Plus Mapper
│   ├── security/              # JWT过滤器
│   ├── service/               # 业务逻辑
│   └── util/                  # 工具类
│
├── invite/                    # zhijiayun-invite
│   ├── controller/
│   │   ├── InviteController.java
│   │   └── AdminController.java
│   ├── dto/
│   ├── entity/
│   ├── mapper/
│   └── service/
│
└── gateway/                   # zhijiayun-gateway
    ├── Application.java       # 启动类
    ├── handler/
    │   └── GlobalExceptionHandler.java
    ├── filter/                # 请求日志、限流过滤器
    └── config/

3. 数据库设计

3.1 核心表结构

表名	说明	核心字段
t_user	用户表	phone, nickname, avatar, wechat_open_id, level_id, status
t_user_level	等级配置表	level_name, level_code, crawler_quota, monthly_quota, max_concurrent
t_coupon	优惠券模板表	name, type, value, total_count, valid_type, min_level_code
t_user_coupon	用户优惠券表	user_id, coupon_id, status, expire_time, source
t_crawler_usage_log	爬虫使用记录表	user_id, usage_date, usage_count, source(QUOTA/COUPON)
t_crawler_quota_grant	爬虫配额发放表	user_id, grant_type(INVITE/PURCHASE/ADMIN), quota_count, used_count, expire_time
t_invite_config	邀请奖励配置表	reward_crawler_count, app_download_url, landing_title, 多渠道字段
t_invite_code	邀请码表	user_id, code, max_uses, used_count, click_count
t_invite_relation	邀请关系表	inviter_id, invitee_id, invite_code_id, registered, reward_granted

3.2 ER关系

t_user ──1:N──> t_invite_code (每个用户一个邀请码)
t_user ──1:N──> t_invite_relation (作为邀请人)
t_user ──1:N──> t_crawler_quota_grant (配额发放)
t_user ──1:N──> t_crawler_usage_log (使用记录)
t_user ──N:1──> t_user_level (等级)
t_user ──1:N──> t_user_coupon (优惠券)
t_coupon ──1:N──> t_user_coupon (模板-实例)
t_invite_code ──1:N──> t_invite_relation (邀请码-关系)

4. 安全架构

4.1 认证流程

客户端 → POST /api/auth/sms/login → 验证成功
→ 生成 JWT (Access Token 24h + Refresh Token 7d)
→ 后续请求携带 Authorization: Bearer <token>
→ JwtAuthenticationFilter 校验 → 放行/拒绝

4.2 接口权限

类型	路径	说明
公开	/api/auth/sms/, /api/auth/wechat/	登录注册
公开	/api/invite/page/, /api/invite/click/	邀请落地页
公开	/api/level/list, /api/level/{id}	等级列表
认证	/api/auth/user/**	用户信息
认证	/api/crawler/**	爬虫操作
认证	/api/invite/**	邀请操作
认证	/api/coupon/**	优惠券
管理	/api/admin/**	运营管理

4.3 限流策略

基于 Redis 滑动窗口计数器：

路径	窗口	限制
/api/auth/sms	60s	10次
/api/auth/login	60s	20次
/api/crawler	60s	60次
其他	60s	100次

5. 爬虫配额架构

5.1 配额计算

每日总配额 = 等级每日配额 + 额外配额之和
每月总配额 = 等级每月配额 + 额外配额之和

额外配额 = SUM(所有有效 grant 的 quota_count - used_count)

5.2 消耗优先级

1. 优惠券 (COUPON) → 优先使用，避免浪费
2. 额外配额 (EXTRA) → 快过期优先消耗
3. 等级基础配额 (QUOTA) → 兜底

5.3 过期控制

每笔发放独立设置 expire_time
定时任务每小时扫描标记过期记录（status = 3）
消耗时自动跳过已过期记录

6. 模块间通信

6.1 直接依赖

invite 模块依赖 user 模块的 CrawlerQuotaGrantService（配额发放）

6.2 事件驱动

用户注册事件 → 检查邀请码 → 建立邀请关系 → 发放奖励
避免循环依赖，保持模块边界清晰

7. MVP 架构特点与后续演进

7.1 MVP 架构特点 ✅

当前采用单体架构，模块边界清晰：

Maven 多模块：common、user、invite、payment、gateway 五个模块
直接依赖：模块间通过接口调用，无消息队列
单数据库：所有表在同一 MySQL 实例
Mock Redis：测试环境使用 Mock，生产需接入真实 Redis
同步处理：邀请奖励发放为同步操作

优势：

部署简单，运维成本低
开发效率高，调试方便
适合 MVP 阶段快速验证

7.2 后续架构演进规划 🚀

Phase 2：性能优化

接入真实 Redis 缓存
数据库连接池优化（HikariCP 调优）
SQL 慢查询优化

Phase 3：异步化改造

引入消息队列（RabbitMQ/Kafka）
邀请奖励发放改为异步处理
爬虫日志记录异步化

Phase 4：微服务拆分

用户服务独立部署（zhijiayun-user）
配额服务独立部署（新建 zhijiayun-quota）
邀请服务独立部署（zhijiayun-invite）
API Gateway 替代当前 gateway 模块

Phase 5：云原生

Docker 容器化
Kubernetes 编排
CI/CD 自动化流水线
监控告警体系（Prometheus + Grafana）

8. 扩展点

扩展方向	预留设计	MVP状态
支付模块	zhijiayun-payment 已预留，待实现微信/支付宝支付	⏳ 未实现
新渠道	t_invite_config 支持 dingtalk/feishu 等渠道字段	✅ 已支持
新配额来源	t_crawler_quota_grant.grant_type 可扩展新类型	✅ 已支持
分布式	当前单体，模块边界清晰，可拆分为微服务	⏳ 后续演进

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

02-架构文档.md 8.4 KB 文件歷史 原始文件

智价云药店 - 架构文档

1. 技术栈

2. 模块架构

2.1 模块总览

2.2 模块依赖关系

2.3 包结构

3. 数据库设计

3.1 核心表结构

3.2 ER关系

4. 安全架构

4.1 认证流程

4.2 接口权限

4.3 限流策略

5. 爬虫配额架构

5.1 配额计算

5.2 消耗优先级

5.3 过期控制

6. 模块间通信

6.1 直接依赖

6.2 事件驱动

7. MVP 架构特点与后续演进

7.1 MVP 架构特点 ✅

7.2 后续架构演进规划 🚀

Phase 2：性能优化

Phase 3：异步化改造

Phase 4：微服务拆分

Phase 5：云原生

8. 扩展点

02-架构文档.md 8.4 KB

文件歷史原始文件