# 智价云（药店版） - 架构文档

> **⚠️ MVP 阶段说明**  
> 本项目为**全新项目，尚未上线**，当前处于 **MVP（最小可行产品）阶段**。  
> 本文档描述的是 MVP 版本的架构设计，后续将根据业务发展和技术演进持续优化。
>
> 版本：v1.1-MVP | 更新日期：2026-07-01 | 状态：开发中

---

## 1. 技术栈

| 层次 | 技术 | 版本 | MVP状态 |
|------|------|------|---------|
| 语言 | Java | 17 | ✅ |
| 框架 | Spring Boot | 3.5.14 | ✅ |
| ORM | MyBatis-Plus | 3.5.16 | ✅ |
| 数据库 | MySQL | 8.0+（驱动 9.3.0） | ✅ |
| 缓存 | Redis (Lettuce) | 6.0+ | ✅ 已接入真实Redis |
| 认证 | JWT (jjwt) | 0.12.6 | ✅ |
| 安全 | Spring Security + BouncyCastle | 1.84 | ✅ |
| 短信 | 阿里云 SMS | 4.5.1 | ✅ |
| 二维码 | Google ZXing | 3.5.3 | ✅ |
| 工具库 | Hutool | 5.8.44 | ✅ |
| 构建 | Maven | 3.8+ | ✅ |

---

## 2. 模块架构

### 2.1 模块总览

```
zhijiayun-pharmacy (父工程)
├── zhijiayun-common    # 公共模块：Result、ErrorCode、BusinessException、TraceIdGenerator、ValidateUtil
├── zhijiayun-user      # 用户模块：认证、会员、优惠券、爬虫配额、搜索、关注、入驻信息、审计日志
├── zhijiayun-invite    # 邀请模块：邀请码、裂变、会员奖励、运营配置
├── zhijiayun-payment   # 支付模块：微信/支付宝支付、订单管理、套餐方案、二维码生成、重复支付自动退款
├── zhijiayun-activity  # 活动模块：比价抽奖、签到送会员、邀请有礼、签到打卡
├── zhijiayun-gateway   # 网关模块：聚合启动、请求日志、Redis限流、全局异常处理
└── zhijiayun-test      # 测试模块：集成测试页面、端到端测试
```

### 2.2 模块依赖关系

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

### 2.3 包结构

```
com.xuekairui
├── common/                    # zhijiayun-common
│   ├── Result.java            # 统一响应封装
│   ├── ErrorCode.java         # 错误码枚举（用户/验证码/微信/Token/支付/等级/优惠券/爬虫/邀请/搜索/关注）
│   ├── BusinessException.java # 业务异常
│   ├── TraceIdGenerator.java  # 链路追踪ID生成器
│   └── ValidateUtil.java      # 参数校验工具（IP提取等）
│
├── user/                      # zhijiayun-user
│   ├── config/                # 配置类（6个）
│   │   ├── AliyunSmsProperties.java
│   │   ├── AsyncConfig.java           # 异步任务线程池配置
│   │   ├── MyBatisPlusMetaHandler.java
│   │   ├── RedisConfig.java
│   │   ├── SecurityConfig.java  # Spring Security + RBAC
│   │   └── SuperAdminInitializer.java # 超级管理员初始化
│   ├── controller/            # 控制器（19个）
│   │   ├── AuthController.java           # 认证（短信/密码/微信登录、Token刷新、用户信息）
│   │   ├── CrawlerController.java        # 爬虫配额状态、消耗、日志
│   │   ├── CouponController.java         # 优惠券发放、查询
│   │   ├── UserLevelController.java      # 等级列表、用户等级设置
│   │   ├── MembershipController.java     # 会员信息查询、权益查询
│   │   ├── DrugSearchController.java     # 药品搜索比价、搜索建议
│   │   ├── SearchRecordController.java   # 搜索历史管理
│   │   ├── WatchlistController.java      # 关注/收藏列表管理
│   │   ├── PlatformAccountController.java # B2B平台账号绑定
│   │   ├── PlatformSessionController.java # 平台会话管理
│   │   ├── CrawlerPlatformConfigController.java # 平台配置查询
│   │   ├── BusinessLicenseController.java # 入驻信息提交
│   │   ├── FileUploadController.java     # 文件上传
│   │   ├── TrialQuotaConfigController.java # 体验配额查询
│   │   ├── AdminUserController.java      # 用户管理（SUPER_ADMIN）
│   │   ├── AdminMembershipController.java # 会员发放管理
│   │   ├── AdminLicenseController.java   # 入驻信息审核
│   │   ├── AdminTrialQuotaConfigController.java # 体验配额配置管理
│   │   └── OperationAuditLogController.java # 审计日志查询
│   ├── dto/                   # 数据传输对象（34个）
│   ├── entity/                # 数据库实体（17个）
│   ├── enums/                 # 枚举（MembershipLevel、UserRole、OperationType）
│   ├── event/                 # 事件（UserRegisteredEvent）
│   ├── mapper/                # MyBatis-Plus Mapper（16个）
│   ├── security/              # JWT过滤器
│   ├── service/               # 业务逻辑（19个服务）
│   └── util/                  # 工具类
│
├── invite/                    # zhijiayun-invite
│   ├── controller/            # 控制器（2个）
│   │   ├── InviteController.java  # 邀请码、统计、记录、落地页、解析、下载
│   │   └── AdminController.java   # 邀请配置、爬虫发放、记录查看
│   ├── dto/                   # 数据传输对象（9个）
│   ├── entity/                # 数据库实体（3个：InviteCode、InviteConfig、InviteRelation）
│   ├── listener/              # UserRegisteredListener（事件驱动）
│   ├── mapper/                # MyBatis-Plus Mapper（3个）
│   └── service/
│       ├── InviteService.java       # 邀请核心服务
│       └── InviteConfigService.java # 邀请配置服务
│
├── payment/                   # zhijiayun-payment
│   ├── config/                # PaymentConfig、PaymentProperties（2个）
│   ├── controller/            # 控制器（6个）
│   │   ├── PaymentController.java        # 支付方案、创建订单、查询订单、切换渠道
│   │   ├── PaymentCallbackController.java # 微信/支付宝回调
│   │   ├── AdminPaymentController.java   # 支付方案管理
│   │   ├── AgreementController.java     # 签约协议管理
│   │   ├── AlipayAnxinPayController.java # 安心付管理
│   │   └── AlipayOpenController.java     # 支付宝开放能力回调
│   ├── dto/                   # 数据传输对象（11个）
│   ├── entity/                # 数据库实体（7个）
│   ├── enums/                 # 枚举（5个：PaymentChannel、PaymentStatus、AgreementStatus、OrderType、PeriodType）
│   ├── mapper/                # MyBatis-Plus Mapper（8个）
│   │   ├── PaymentOrderMapper.java
│   │   ├── PaymentOrderExtraPaymentMapper.java  # 重复支付记录
│   │   ├── PaymentAgreementMapper.java   # 签约协议
│   │   ├── PaymentPlanMapper.java        # 支付方案
│   │   ├── AlipayAnxinCardMapper.java    # 安心付卡模板
│   │   ├── AlipayAnxinOrderRecordMapper.java # 安心付订单
│   │   └── AlipayCallbackRecordMapper.java # 支付宝回调记录
│   └── service/
│       ├── PaymentOrderService.java    # 订单管理（含重复支付处理）
│       ├── PaymentPlanService.java     # 方案管理
│       ├── PaymentRefundService.java   # 退款服务（微信/支付宝原路退款）
│       ├── PaymentAgreementService.java # 签约协议服务
│       ├── AlipayAnxinPayService.java   # 安心付服务
│       ├── AlipayCallbackRecordService.java # 支付宝回调记录服务
│       ├── AutoDeductScheduler.java    # 自动续费定时扣款任务（每10分钟）
│       └── QRCodeService.java          # 二维码生成
│
├── activity/                  # zhijiayun-activity
│   ├── controller/            # 控制器（4个）
│   │   ├── ActivityController.java       # 用户端：抽奖状态、奖品列表、执行抽奖、抽奖记录
│   │   ├── AdminActivityController.java  # 运营端：奖品CRUD、活动配置、抽奖记录查询
│   │   ├── CheckInController.java        # 用户端：每日签到、签到状态、日历、统计
│   │   └── AdminCheckInController.java   # 运营端：签到配置、签到记录查询
│   ├── dto/                   # 数据传输对象（16个）
│   │   ├── ActivityLotteryStatusResponse.java   # 抽奖活动状态
│   │   ├── ActivityLotteryResultResponse.java   # 抽奖结果
│   │   ├── ActivityLotteryPrizeRequest.java     # 奖品创建/更新请求
│   │   ├── ActivityLotteryConfigRequest.java    # 抽奖活动配置请求
│   │   ├── ActivityInviteStatusResponse.java    # 邀请有礼活动状态
│   │   ├── ActivityInviteConfigRequest.java     # 邀请有礼配置请求
│   │   ├── ActivityCheckinCycleStatusResponse.java # 签到周期活动状态
│   │   ├── ActivityCheckinCycleConfigRequest.java  # 签到周期配置请求
│   │   ├── ActivityRewardRecordResponse.java    # 奖励记录
│   │   ├── ActivityAvailableResponse.java       # 可用活动列表
│   │   ├── CheckInStatusResponse.java           # 签到状态
│   │   ├── CheckInResultResponse.java           # 签到结果
│   │   ├── CheckInCalendarResponse.java         # 签到日历
│   │   ├── CheckInStatsResponse.java            # 签到统计
│   │   ├── CheckInConfigRequest.java            # 签到配置请求
│   │   └── AdminCheckInRecordResponse.java      # 管理端签到记录
│   ├── entity/                # 数据库实体（10个）
│   │   ├── ActivityLotteryPrize.java    # 抽奖奖品（含库存管理）
│   │   ├── ActivityLotteryRecord.java   # 抽奖记录
│   │   ├── ActivityLotteryChance.java   # 抽奖机会
│   │   ├── ActivityLotteryConfig.java   # 抽奖活动配置
│   │   ├── ActivityInviteConfig.java    # 邀请有礼配置
│   │   ├── ActivityInviteRewardRecord.java # 邀请奖励记录
│   │   ├── ActivityCheckinCycleConfig.java # 签到周期配置
│   │   ├── ActivityCheckinCycleRecord.java # 签到周期记录
│   │   ├── CheckInConfig.java           # 签到配置
│   │   ├── CheckInPeriod.java           # 签到周期
│   │   └── CheckInRecord.java           # 签到记录
│   ├── mapper/                # MyBatis-Plus Mapper（10个）
│   │   ├── ActivityLotteryPrizeMapper.java   # 奖品查询、库存原子扣减
│   │   ├── ActivityLotteryRecordMapper.java
│   │   ├── ActivityLotteryChanceMapper.java
│   │   ├── ActivityLotteryConfigMapper.java
│   │   ├── ActivityInviteConfigMapper.java
│   │   ├── ActivityInviteRewardRecordMapper.java
│   │   ├── ActivityCheckinCycleConfigMapper.java
│   │   ├── ActivityCheckinCycleRecordMapper.java
│   │   ├── CheckInConfigMapper.java
│   │   ├── CheckInPeriodMapper.java
│   │   └── CheckInRecordMapper.java
│   ├── service/               # 业务逻辑（5个服务）
│   │   ├── ActivityLotteryService.java      # 抽奖核心逻辑（加权随机、库存扣减、违规记录）
│   │   ├── ActivityInviteService.java       # 邀请有礼（实现ActivityInviteGate门面）
│   │   ├── ActivityCheckinCycleService.java # 签到送会员（周期制）
│   │   ├── CheckInService.java              # 每日签到
│   │   └── CheckInConfigService.java        # 签到配置管理
│   └── scheduler/
│       └── ActivityEventScheduler.java      # 活动事件定时任务
│
└── gateway/                   # zhijiayun-gateway
    ├── Application.java       # 启动类
    ├── config/
    │   ├── GatewayConfig.java       # 网关配置
    │   └── GatewayProperties.java   # 网关属性（日志、限流规则）
    ├── filter/
    │   ├── RequestLoggingFilter.java # 请求日志+慢请求检测
    │   └── RateLimitFilter.java      # Redis限流过滤器
    └── handler/
        └── GlobalExceptionHandler.java # 全局异常处理
```

---

## 3. 数据库设计

### 3.1 核心表结构

| 表名 | 说明 | 核心字段 |
|------|------|----------|
| t_user | 用户表 | phone, nickname, password, wechat_open_id, role(USER/ADMIN/SUPER_ADMIN), membership_level(PLUS/PRO/ULTRA), pharmacy_name, login_source |
| t_user_membership | 用户会员记录表 | user_id, level(PLUS/PRO/ULTRA), source(ADMIN_GRANT/RECHARGE/SYSTEM), effective_from, effective_to, status |
| t_membership_benefit | 会员权益配置表 | level, benefit_type(DAILY/MONTHLY/YEARLY_QUOTA, MAX_CONCURRENT), benefit_value |
| t_coupon | 优惠券模板表 | name, type(CRAWLER), value, total_count, valid_type, min_level_code |
| t_user_coupon | 用户优惠券表 | user_id, coupon_id, status(0未使用/1已使用/2已过期), expire_time, source |
| t_crawler_usage_log | 爬虫使用记录表 | user_id, usage_date, usage_count, platform, source(QUOTA/COUPON) |
| t_crawler_quota_grant | 爬虫配额发放表 | user_id, grant_type(INVITE/PURCHASE/ADMIN), quota_count, used_count, expire_time, status(1有效/2用完/3过期) |
| t_invite_config | 邀请奖励配置表 | reward_type(MEMBERSHIP/CRAWLER), reward_months, max_daily_reward, 多渠道字段, landing_title |
| t_invite_code | 邀请码表 | user_id, code, max_uses, used_count, click_count, expire_time |
| t_invite_relation | 邀请关系表 | inviter_id, invitee_id, invite_code_id, registered, reward_granted |
| t_payment_plan | 支付方案表 | plan_code, plan_name, membership_level, price(DECIMAL), original_price(DECIMAL), duration_days, status |
| t_payment_order | 支付订单表 | order_no, user_id, plan_id, amount(DECIMAL), channel(WECHAT/ALIPAY), status(PENDING/PAID/EXPIRED/REFUNDED), qr_code_url, trade_no, paid_channel |
| t_payment_order_extra_payment | 重复支付记录表 | order_no, channel, trade_no, amount(DECIMAL), paid_time, refund_status(PENDING/SUCCESS/FAILED), refund_trade_no, refund_time, refund_fail_reason |
| t_payment_agreement | 签约协议表 | user_id, plan_id, channel, period_type(MONTH/YEAR), period_amount, status(PENDING/SIGNED/UNSIGNED/FAILED), agreement_no, next_deduct_time |
| t_alipay_anxin_card | 安心付卡模板表 | plan_id, card_id, card_name, card_type, period_amount, period_days, total_periods, status, appointment_url |
| t_alipay_anxin_order_record | 安心付订单记录表 | user_id, plan_id, card_id, order_id, sub_order_id, out_biz_no, deduct_amount, deduct_status, deduct_time, membership_activated, order_no |
| t_alipay_callback_record | 支付宝开放能力回调记录表 | type, app_id, msg_method, auth_code, source, state, params, status, error_msg |
| t_platform_session | 平台会话快照表 | user_id, platform_code, platform_name, login_url, account_label, cookies_encrypted, version, expires_at |
| t_platform_account | B2B平台账号绑定表 | user_id, platform_code, platform_name, account_encrypted, password_encrypted, enabled, verify_status |
| t_search_record | 搜索记录表（完整比价快照） | user_id, drug_name, searched_at, status_text, platform_results, search_log |
| t_platform_config | 平台配置表 | platform_code, platform_name, enabled, query_cost, priority, official_url, binding_instructions |
| t_business_license | 入驻信息表 | user_id, store_name, terminal_type, province, city, district, store_address, contact_person, contact_phone, license_image_url, drug_license_url, medical_device_url, credit_code, reviewer_id, review_status(PENDING/APPROVED/REJECTED) |
| t_trial_quota_config | 体验配额配置表 | config_name, trial_days, daily_query_limit, monthly_watchlist_limit, config_type(DEFAULT/COUPON/ACTIVITY) |
| t_operation_audit_log | 操作审计日志表 | operator_id, operator_role, module, operation_type, target_type, target_id, before_data, after_data, result, is_sensitive |
| t_search_history | 搜索历史表（轻量关键词日志，无Java实体） | user_id, keyword, platform, result_count, search_time |
| t_watchlist | 关注/收藏表 | user_id, drug_name, spec, manufacturer, min_price, min_price_platform, last_price, price_change |
| t_activity_lottery_config | 抽奖活动配置表 | enabled, start_time, end_time, daily_chance_limit, require_membership_level, require_license_approved |
| t_activity_lottery_prize | 抽奖奖品表 | name, reward_type(MEMBERSHIP/CRAWLER/EMPTY/PHYSICAL), reward_amount, reward_days, reward_level, stock, remaining_stock, probability_weight, enabled, sort |
| t_activity_lottery_chance | 抽奖机会表 | user_id, chance_date, source(FIRST_SEARCH/ADMIN), status(0未使用/1已使用), used_time, record_id |
| t_activity_lottery_record | 抽奖记录表 | user_id, prize_id, prize_name, reward_type, reward_amount, reward_days, reward_level, chance_id, client_ip |
| t_activity_invite_config | 邀请有礼活动配置表 | enabled, start_time, end_time, reward_trigger(REGISTRATION/LICENSE_APPROVED), reward_type, reward_months, reward_days, max_reward_count |
| t_activity_invite_reward_record | 邀请奖励记录表 | inviter_id, invitee_id, reward_type, reward_months, reward_days, trigger_type, granted_time |
| t_activity_checkin_cycle_config | 签到周期活动配置表 | enabled, start_time, end_time, cycle_mode(FRI_THU), required_days, reward_days, max_reward_count |
| t_activity_checkin_cycle_record | 签到周期记录表 | user_id, cycle_start_date, cycle_end_date, signed_days, reward_granted, reward_time |
| t_checkin_config | 签到配置表 | enabled, reward_type, reward_value, consecutive_bonusus |
| t_checkin_period | 签到周期表 | user_id, period_start, period_end, signed_count, last_sign_date |
| t_checkin_record | 签到记录表 | user_id, sign_date, reward_type, reward_value |

### 3.2 ER关系

```
t_user ──1:N──> t_invite_code (每个用户一个邀请码)
t_user ──1:N──> t_invite_relation (作为邀请人)
t_user ──1:N──> t_user_membership (会员记录)
t_user ──1:N──> t_crawler_quota_grant (配额发放)
t_user ──1:N──> t_crawler_usage_log (使用记录)
t_user ──1:N──> t_user_coupon (优惠券)
t_user ──1:N──> t_platform_account (平台账号绑定)
t_user ──1:1──> t_business_license (入驻信息)
t_user ──1:N──> t_search_history (搜索历史/关键词日志)
t_user ──1:N──> t_search_record (搜索记录/比价快照)
t_user ──1:N──> t_watchlist (关注列表)
t_user ──1:N──> t_payment_order (支付订单)
t_coupon ──1:N──> t_user_coupon (模板-实例)
t_invite_code ──1:N──> t_invite_relation (邀请码-关系)
t_membership_benefit ──N:1──> MembershipLevel (等级-权益)
t_payment_plan ──1:N──> t_payment_order (方案-订单)
t_payment_order ──1:N──> t_payment_order_extra_payment (订单-重复支付记录)
t_payment_plan ──1:N──> t_payment_agreement (方案-签约协议)
t_user ──1:N──> t_payment_agreement (用户-签约协议)
t_user ──1:N──> t_platform_session (用户-平台会话)
t_payment_plan ──1:N──> t_alipay_anxin_card (方案-安心付卡模板)
```

---

## 4. 安全架构

### 4.1 认证流程

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

### 4.2 三级RBAC权限模型

| 角色 | 权限范围 | 说明 |
|------|----------|------|
| USER | 用户侧接口 | 比价、搜索、关注、邀请、支付等 |
| ADMIN | 运营后台接口 | 用户管理、配置管理、审核、发放等 |
| SUPER_ADMIN | 全部权限 | 包括角色赋权（/api/admin/users/**） |

### 4.3 接口权限

| 类型 | 路径 | 说明 |
|------|------|------|
| 公开 | /api/auth/sms/send, /api/auth/sms/login | 短信验证码 |
| 公开 | /api/auth/password/login | 密码登录 |
| 公开 | /api/auth/refresh | 刷新Token |
| 公开 | /api/auth/wechat/** | 微信登录相关 |
| 公开 | /api/invite/page/**, /api/invite/click/**, /api/invite/{code} | 邀请落地页 |
| 公开 | /api/invite/resolve-link, /api/invite/validate | 邀请码解析/验证 |
| 公开 | /invite/** | 浏览器直接访问邀请链接（公开） |
| 公开 | /api/platform-config/** | 平台配置查询 |
| 公开 | /api/trial-quota/** | 体验配额查询 |
| 公开 | /api/search/suggestions | 搜索建议 |
| 公开 | /api/payment/plans | 支付方案列表 |
| 公开 | /api/payment/callback/** | 支付回调 |
| 公开 | /api/payment/anxin/notify/** | 安心付通知 |
| 公开 | /api/payment/agreement/notify/** | 签约回调通知 |
| 公开 | /api/payment/alipay/** | 支付宝开放能力回调 |
| 公开 | /api/level/list, /api/level/{id} | 等级列表 |
| 认证 | /api/auth/user/**, /api/auth/password/set, /api/auth/phone/change | 用户信息 |
| 认证 | /api/crawler/**, /api/search/query | 爬虫/搜索 |
| 认证 | /api/platform-session/** | 平台会话管理 |
| 认证 | /api/search-record/** | 搜索历史 |
| 认证 | /api/invite/code, /api/invite/stats, /api/invite/rewards | 邀请操作 |
| 认证 | /api/invite/extra-quota, /api/invite/bind, /api/invite/my-inviter | 邀请操作 |
| 认证 | /api/coupon/**, /api/membership/** | 优惠券/会员 |
| 认证 | /api/platform-account/**, /api/watchlist/** | 账号绑定/关注 |
| 认证 | /api/payment/order/**, /api/payment/agreement/** | 支付订单/签约 |
| 管理 | /api/admin/** (ADMIN + SUPER_ADMIN) | 运营管理 |
| 管理 | /api/admin/payment/anxin/** (ADMIN + SUPER_ADMIN) | 安心付管理 |
| 超管 | /api/admin/users/** (仅SUPER_ADMIN) | 用户角色管理 |
| 管理 | /api/coupon/issue, /api/level/user/** (ADMIN + SUPER_ADMIN) | 散落管理操作 |

### 4.4 限流策略

基于 Redis 固定窗口计数器，按客户端IP + 路径前缀限流：

| 路径前缀 | 窗口 | 限制 | 说明 |
|----------|------|------|------|
| /api/auth/sms | 60s | 10次 | 短信验证码发送 |
| /api/auth/login | 60s | 20次 | 登录接口 |
| /api/crawler | 60s | 60次 | 爬虫操作 |
| 其他 | 60s | 100次 | 默认限制 |

**限流响应**：HTTP 429 + `X-RateLimit-Limit` / `X-RateLimit-Remaining` 响应头

### 4.5 密码安全

- 密码使用 **BCryptPasswordEncoder** 加密存储
- 支持 手机号 + 密码 / 昵称 + 密码 双模登录
- 支持设置/修改密码（需验证旧密码）
- 平台账号密码使用 **AES-256** 加密存储

### 4.6 短信验证码安全

- 开发环境：测试模式（固定验证码 123456，不发送真实短信）
- 生产环境：阿里云SMS真实发送
- IP维度限流：1分钟内同IP最多1次，防止短信轰炸
- 验证码5分钟过期

---

## 5. 爬虫配额架构

### 5.1 配额计算

```
每日总配额 = 会员每日权益配额 + 额外配额之和
每月总配额 = 会员每月权益配额 + 额外配额之和
每年总配额 = 会员每年权益配额 + 额外配额之和

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

### 5.2 消耗优先级

```
1. 优惠券 (COUPON) → 优先使用，避免浪费
2. 额外配额 (EXTRA) → 快过期优先消耗
3. 会员权益配额 (QUOTA) → 兜底
```

### 5.3 过期控制

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

### 5.4 会员权益配置

会员权益通过 `t_membership_benefit` 表配置，支持运营动态调整：

| 会员等级 | 每日配额 | 每月配额 | 每年配额 | 最大并发 |
|----------|----------|----------|----------|----------|
| PLUS | 10 | 300 | 3650 | - |
| PRO | 999 | 29970 | 364635 | 5 |
| ULTRA | 999 | 29970 | 364635 | 10 |

---

## 6. 支付架构

### 6.1 支付流程

```
用户选择套餐 → 创建订单(PENDING) → 生成支付二维码
→ 用户扫码支付 → 第三方异步回调 → 验签
→ 订单状态更新为PAID → 自动发放会员等级 → 配额生效
```

### 6.2 渠道切换与重复支付处理

```
用户创建订单（渠道A）→ 切换为渠道B → 生成渠道B二维码
→ 渠道A先回调 → handlePaymentSuccess → 订单PAID，激活会员
→ 渠道B也回调 → processPaidCallback 检查到已PAID
→ handleDuplicatePayment（幂等：同交易号不重复处理）
→ 记录到 t_payment_order_extra_payment（refund_status=PENDING）
→ doRefund() → PaymentRefundService.refund()
  ├── 微信 → WxPayService.refundV3()
  └── 支付宝 → AlipayClient.execute(AlipayTradeRefundRequest)
→ 退款成功：refund_status=SUCCESS, refund_trade_no=xxx
→ 退款失败：refund_status=FAILED, refund_fail_reason=xxx
```

**退款服务**：`PaymentRefundService` 封装微信/支付宝原路退款逻辑，mock模式下模拟退款成功。

### 6.3 支付渠道

| 渠道 | 编码 | 回调地址 | 说明 |
|------|------|----------|------|
| 微信支付 | WECHAT | /api/payment/callback/wechat | Native扫码支付（API v3） |
| 支付宝 | ALIPAY | /api/payment/callback/alipay | 当面付/扫码支付（RSA2验签） |

### 6.4 模拟支付

开发环境（`payment.mock=true`）支持模拟支付：
- POST /api/payment/order/{orderNo}/pay 直接标记订单为已支付
- 回调接口接收模拟通知，跳过验签

### 6.5 生产环境接入

生产环境需配置：
- 微信支付：app-id、mch-id、api-v3-key、private-key-path、serial-no、notify-url
- 支付宝：app-id、private-key、alipay-public-key、notify-url
- 回调验签：微信需接入SDK实现RSA验签+解密；支付宝需接入SDK实现RSA2验签

---

## 7. 模块间通信

### 7.1 直接依赖

- invite 模块依赖 user 模块的 `CrawlerQuotaGrantService`（配额发放）
- invite 模块依赖 user 模块的 `MembershipService`（会员时长奖励发放）

### 7.2 事件驱动

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

### 7.3 支付与会员联动

- 支付成功回调 → `PaymentOrderService.processPaidCallback` → 调用 `MembershipService` 发放对应会员等级
- 重复支付回调 → `handleDuplicatePayment` → `PaymentRefundService.refund()` → 原路退款（微信/支付宝）

---

## 8. MVP 架构特点与后续演进

### 8.1 MVP 架构特点 ✅

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

1. **Maven 多模块**：common、user、invite、payment、gateway、test 六个模块
2. **直接依赖**：模块间通过接口调用，无消息队列
3. **单数据库**：所有表在同一 MySQL 实例
4. **真实 Redis**：已接入 Redis 缓存（Lettuce 连接池），用于限流、验证码存储
5. **同步处理**：邀请奖励发放为同步操作（事件驱动但同步执行）
6. **RBAC 安全**：三级角色模型 + Spring Security 细粒度权限控制
7. **网关层增强**：请求日志 + 慢请求检测 + Redis IP限流

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

### 8.2 后续架构演进规划 🚀

#### Phase 2：性能优化
- [ ] 数据库读写分离
- [ ] SQL 慢查询优化与索引调优
- [ ] 接口限流细化（按用户维度）
- [ ] Redis 缓存策略优化

#### Phase 3：异步化改造
- [ ] 引入消息队列（RabbitMQ/Kafka）
- [ ] 邀请奖励发放改为异步处理
- [ ] 爬虫日志记录异步化
- [ ] 支付回调异步处理

#### Phase 4：微服务拆分
- [ ] 用户服务独立部署（zhijiayun-user）
- [ ] 配额服务独立部署（新建 zhijiayun-quota）
- [ ] 邀请服务独立部署（zhijiayun-invite）
- [ ] 支付服务独立部署（zhijiayun-payment）
- [ ] API Gateway 替代当前 gateway 模块

#### Phase 5：云原生
- [ ] Docker 容器化
- [ ] Kubernetes 编排
- [ ] CI/CD 自动化流水线
- [ ] 监控告警体系（Prometheus + Grafana）

---

## 9. 扩展点

| 扩展方向 | 预留设计 | MVP状态 |
|----------|----------|---------|
| 支付渠道 | PaymentChannel 枚举可扩展新渠道 | ✅ 已实现微信/支付宝 |
| 新渠道 | t_invite_config 支持 dingtalk/feishu 等渠道字段 | ✅ 已支持 |
| 新配额来源 | t_crawler_quota_grant.grant_type 可扩展新类型 | ✅ 已支持 |
| 会员权益类型 | t_membership_benefit.benefit_type 可扩展 | ✅ 已支持 |
| 平台扩展 | t_platform_config 支持动态启用/禁用平台 | ✅ 已支持 |
| 操作审计 | OperationType 枚举覆盖9大模块 | ✅ 已实现 |
| 分布式 | 当前单体，模块边界清晰，可拆分为微服务 | ⏳ 后续演进 |

---

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