# 智价云药店 - 架构文档

> **⚠️ 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 架构特点 ✅

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

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

**优势：**
- 部署简单，运维成本低
- 开发效率高，调试方便
- 适合 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 可扩展新类型 | ✅ 已支持 |
| 分布式 | 当前单体，模块边界清晰，可拆分为微服务 | ⏳ 后续演进 |

---

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