# 用户使用流程图 — 会员与订阅 > **端口说明**: 📱 小程序 | 🖥 管理后台 | 📋 规划师端 | ⚙️ 系统自动 > > **分层说明**: 🏠 页面 → 🔗 API → ⚙️ Service → 📦 数据实体 ```mermaid flowchart TD %% ============ 颜色定义 ============ classDef page fill:#e3f2fd,stroke:#1565c0,stroke-width:2px classDef api fill:#fff3e0,stroke:#f57c00,stroke-width:1px classDef service fill:#e8f5e9,stroke:#388e3c,stroke-width:1px classDef data fill:#f3e5f5,stroke:#7b1fa2,stroke-width:1px classDef external fill:#fce4ec,stroke:#d32f2f,stroke-width:1px,stroke-dasharray:3 2 classDef actor fill:#e1f5fe,stroke:#0288d1,stroke-width:2px,stroke-dasharray:5 3 %% ============ 角色 ============ ROLE_PARENT(("👤 家长")):::actor ROLE_PAY(("💳 微信支付")):::external ROLE_SYS(("⚙️ 定时任务")):::actor %% ================================================================ %% 阶段一：会员信息查看 %% ================================================================ subgraph 阶段一[阶段一：会员信息查看] direction TB P1["🏠 小程序：会员中心页"]:::page P1 -->|"查看等级列表"| A1["🔗 POST /api/membership/levels"]:::api A1 -->|"无参数"| S1["⚙️ MembershipService.getAllLevels()"]:::service S1 -->|"查询所有等级配置"| D_LEVELS["📦 membership_levels 表"]:::data P1 -->|"查看我的会员"| A2["🔗 POST /api/membership/my"]:::api A2 -->|"userId（从token提取）"| S2["⚙️ 组装会员信息"]:::service S2 -->|"用户等级, 过期时间"| D_USER["📦 users 表（memberLevel, memberExpireTime）"]:::data S2 -->|"家庭会员记录"| D_FAM["📦 family_memberships 表"]:::data P1 -->|"查看当前等级"| A3["🔗 POST /api/membership/level"]:::api A3 -->|"userId"| S3["⚙️ MembershipService.getMemberLevel()"]:::service S3 -->|"FREE/FAMILY/PREMIUM + 过期校验"| D_USER P1 -->|"查看等级详情"| A4["🔗 POST /api/membership/current"]:::api A4 -->|"familyId"| S4["⚙️ MembershipService.getCurrentLevel()"]:::service S4 -->|"查询家庭当前有效等级"| D_LEVELS S4 -->|"无会员则返回免费版"| D_LEVELS P1 -->|"查看升级记录"| A5["🔗 POST /api/membership/records"]:::api A5 -->|"userId, page, size"| S5["⚙️ MemberUpgradeRecordMapper 分页查询"]:::service S5 -->|"用户升级记录"| D_REC["📦 member_upgrade_records 表"]:::data P1 -->|"查看价格方案"| A6["🔗 POST /api/membership/plans"]:::api A6 -->|"无参数"| S6["⚙️ 组装定价方案"]:::service S6 -->|"等级配置 + sys_config定价"| D_LEVELS S6 -->|"FAMILY/PREMIUM价格"| D_CFG["📦 sys_config 表"]:::data end %% ================================================================ %% 阶段二：会员购买与升级 %% ================================================================ subgraph 阶段二[阶段二：会员购买与升级] D_LEVELS -->|"等级+价格"| P2["🏠 会员升级选择页"]:::page P2 -->|"选择套餐"| P2a{"选择付费方式"}:::page P2a -->|"创建升级订单"| A7["🔗 POST /api/membership/upgrade"]:::api A7 -->|"userId, familyId, levelCode, paymentType, period, couponId"| S7["⚙️ MembershipService.createOrder()"]:::service S7 -->|"从sys_config读取定价"| D_CFG S7 -->|"应用优惠券折扣"| S7a["⚙️ CouponService.apply()"]:::service S7a -->|"优惠后金额"| D_COUPON["📦 user_coupons 表"]:::data S7 -->|"写入订单, 状态=pending"| D_ORD["📦 payment_orders 表"]:::data A7 -->|"orderNo, amount, status"| P2b["🏠 确认订单页"]:::page P2b -->|"调起微信支付"| PAY["💳 微信支付"]:::external PAY -->|"支付结果通知"| A8["🔗 POST /api/membership/notify"]:::api A8 -->|"orderNo, transactionId, payMethod"| S8["⚙️ MembershipService.processPaymentCallback()"]:::service S8 -->|"更新订单状态=paid"| D_ORD S8 -->|"插入家庭会员记录"| D_FAM S8 -->|"升级用户等级, 设置过期时间"| D_USER S8 -->|"创建升级记录"| D_REC S8 -->|"结算两级佣金"| S8a["⚙️ CommissionService.settleTwoLevel()"]:::service S8a -->|"佣金记录"| D_COMM["📦 commission_records 表"]:::data P2a -->|"创建任意订单"| A9["🔗 POST /api/membership/orders"]:::api A9 -->|"levelCode, paymentType, period, couponId"| S7 P2a -->|"试用会员"| A10["🔗 POST /api/membership/trial"]:::api A10 -->|"userId, familyId"| S9["⚙️ MembershipService.createOrder(trial)"]:::service S9 -->|"创建金额=0的订单, 状态=paid"| D_ORD S9 -->|"激活试用期"| S9a["⚙️ 写入TrialMembership + FamilyMembership"]:::service S9a -->|"试用记录"| D_TRIAL["📦 trial_memberships 表"]:::data S9a -->|"家庭会员记录（试用）"| D_FAM S9a -->|"用户等级= FAMILY, expireTime=7天后"| D_USER S9a -->|"试用升级记录"| D_REC end %% ================================================================ %% 阶段三：会员权益 %% ================================================================ subgraph 阶段三[阶段三：会员权益] D_USER -->|"会员等级"| P3["🏠 会员权益页"]:::page P3 -->|"检查功能权限"| A11["🔗 POST /api/membership/can-use"]:::api A11 -->|"familyId, feature"| S10["⚙️ MembershipService.canUseFeature()"]:::service S10 -->|"按FREE/FAMILY/PREMIUM判定功能白名单"| D_USER P3 -->|"应用会员折扣"| A12["🔗 POST /api/membership/discount"]:::api A12 -->|"userId, amount"| S11["⚙️ MembershipService.applyMemberDiscount()"]:::service S11 -->|"从sys_config读取折扣率"| D_CFG S11 -->|"FREE无折扣, FAMILY/PREMIUM按折扣bps计算"| D_CFG end %% ================================================================ %% 阶段四：订阅管理 %% ================================================================ subgraph 阶段四[阶段四：订阅管理] P1 -->|"订阅管理"| P4["🏠 订阅管理页"]:::page P4 -->|"查看订阅状态"| A13["🔗 POST /api/subscription/status"]:::api A13 -->|"familyId"| S12["⚙️ MemberSubscriptionService.getActiveSubscription()"]:::service S12 -->|"活跃订阅 + 过期时间校验"| D_SUB["📦 member_subscriptions 表"]:::data P4 -->|"查看订阅方案"| A14["🔗 POST /api/subscription/plans"]:::api A14 -->|"无参数"| S13["⚙️ 硬编码L1/L2方案"]:::service S13 -->|"L1=36500/年, L2=131400/年"| D_MOCK["📦 内存数据（L1_BENEFITS, L2_BENEFITS）"]:::data P4 -->|"创建订阅"| A15["🔗 POST /api/subscription/create"]:::api A15 -->|"familyId, level, amount, paymentType"| S14["⚙️ 创建微信预支付"]:::service S14 -->|"openid, 金额"| PAY S14 -->|"订阅服务激活"| S14a["⚙️ MemberSubscriptionService.subscribe()"]:::service S14a -->|"写入订阅记录, 状态=active"| D_SUB P4 -->|"确认订阅"| A16["🔗 POST /api/subscription/subscribe"]:::api A16 -->|"familyId, level, amount, paymentType, transactionId"| S14a P4 -->|"取消订阅"| A17["🔗 POST /api/subscription/cancel"]:::api A17 -->|"familyId"| S15["⚙️ MemberSubscriptionService.cancelSubscription()"]:::service S15 -->|"更新订阅状态=cancelled"| D_SUB P4 -->|"设置自动续费"| A18["🔗 POST /api/subscription/auto-renew"]:::api A18 -->|"familyId, enabled(0/1)"| S16["⚙️ MemberSubscriptionService.setAutoRenew()"]:::service S16 -->|"更新自动续费标记"| D_SUB end %% ================================================================ %% 阶段五：订阅权益与推广等级 %% ================================================================ subgraph 阶段五[阶段五：订阅权益与推广等级] D_SUB -->|"订阅记录"| P5["🏠 订阅权益页"]:::page P5 -->|"查看我的权益"| A19["🔗 POST /api/subscription/benefits/my"]:::api A19 -->|"familyId"| S17["⚙️ 查询权益使用记录"]:::service S17 -->|"订阅下的所有权益日志"| D_BEN["📦 subscription_benefit_logs 表"]:::data P5 -->|"使用/检查权益"| A20["🔗 POST /api/subscription/benefit/check"]:::api A20 -->|"familyId, benefitCode"| S18["⚙️ 创建权益使用记录"]:::service S18 -->|"写入一条权益使用日志"| D_BEN P5 -->|"查看推广等级"| A21["🔗 POST /api/subscription/tier"]:::api A21 -->|"userId"| S19["⚙️ PromotionTierService.getCurrentTier()"]:::service S19 -->|"用户当前推广等级"| D_TIER["📦 promotion_tiers 表"]:::data P5 -->|"更新推广等级（管理员）"| A22["🔗 POST /api/subscription/tier/update"]:::api A22 -->|"userId, tierCode, role=admin"| S20["⚙️ PromotionTierService.updateTier()"]:::service S20 -->|"更新推广等级"| D_TIER end %% ================================================================ %% 阶段六：定时任务 %% ================================================================ subgraph 阶段六[阶段六：系统定时任务] ROLE_SYS -->|"每日3:30"| T1["⚙️ 消费达标自动升级"]:::service T1 -->|"查询消费≥threshold的FREE用户"| D_USER T1 -->|"升级为FAMILY"| D_USER T1 -->|"创建升级记录"| D_REC ROLE_SYS -->|"每日4:00"| T2["⚙️ 过期会员降级"]:::service T2 -->|"查询已过期FAMILY用户"| D_USER T2 -->|"降级为FREE"| D_USER end %% ================================================================ %% 角色关联 %% ================================================================ ROLE_PARENT -.- P1 ROLE_PARENT -.- P2 ROLE_PARENT -.- P3 ROLE_PARENT -.- P4 ROLE_PARENT -.- P5 ROLE_PAY -.- PAY ``` ## 端点明细 ### 会员信息 | 端点 | 说明 | 端口 | 请求数据 | 响应数据 | |------|------|------|---------|---------| | `POST /api/membership/levels` | 获取所有会员等级列表 | 📱小程序 | — | `[MembershipLevelDTO]` | | `POST /api/membership/my` | 获取我的会员信息 | 📱小程序 | Header: `Authorization` | `{memberLevel, memberExpireTime, membership, totalConsumption}` | | `POST /api/membership/level` | 获取当前有效会员等级 | 📱小程序 | Header: `Authorization` | `{memberLevel, memberExpireTime}` | | `POST /api/membership/current` | 获取当前等级详情 | 📱小程序 | Header: `Authorization` | `MembershipLevelDTO（含功能权限列表）` | | `POST /api/membership/records` | 获取升级记录 | 📱小程序 | `{page, size}` | `Page` | | `POST /api/membership/plans` | 获取会员方案价格列表 | 📱小程序 | — | `[{levelCode, levelName, levelDesc, monthly, quarterly, yearly}]` | ### 会员购买与升级 | 端点 | 说明 | 端口 | 请求数据 | 响应数据 | |------|------|------|---------|---------| | `POST /api/membership/upgrade` | 创建会员升级订单 | 📱小程序 | `{levelCode, paymentType, period, couponId}` | `PaymentOrderDTO` | | `POST /api/membership/orders` | 创建支付订单 | 📱小程序 | `{levelCode, paymentType, period, couponId}` | `PaymentOrderDTO` | | `POST /api/membership/trial` | 激活试用会员 | 📱小程序 | Header: `Authorization` | `PaymentOrderDTO（金额=0）` | | `POST /api/membership/notify` | 支付回调 | ⚙️系统自动 | `{orderNo, transactionId, payMethod}` | `boolean` | ### 会员权益 | 端点 | 说明 | 端口 | 请求数据 | 响应数据 | |------|------|------|---------|---------| | `POST /api/membership/can-use` | 检查功能权限 | 📱小程序 | `{feature}` | `boolean` | | `POST /api/membership/discount` | 应用会员折扣 | 📱小程序 | `{amount}` | `{originalPrice, discountedPrice}` | ### 订阅管理 | 端点 | 说明 | 端口 | 请求数据 | 响应数据 | |------|------|------|---------|---------| | `POST /api/subscription/status` | 获取当前家庭订阅状态 | 📱小程序 | Header: `familyId` | `{subscription, hasActiveSubscription}` | | `POST /api/subscription/plans` | 获取订阅方案列表 | 📱小程序 | — | `{L1: {name, price, benefits}, L2: {name, price, benefits}}` | | `POST /api/subscription/create` | 创建订阅订单（JSON） | 📱小程序 | `{level, amount, paymentType}` | `{orderNo, amount, paymentUrl}` | | `POST /api/subscription/subscribe` | 确认订阅（参数式） | 📱小程序 | `{level, amount, paymentType, transactionId}` | `null` | | `POST /api/subscription/cancel` | 取消订阅 | 📱小程序 | Header: `familyId` | `null` | | `POST /api/subscription/auto-renew` | 设置自动续费 | 📱小程序 | `{enabled}` | `null` | ### 订阅权益与推广 | 端点 | 说明 | 端口 | 请求数据 | 响应数据 | |------|------|------|---------|---------| | `POST /api/subscription/benefits/my` | 获取我的权益列表 | 📱小程序 | Header: `familyId` | `[{code, used, usedAt, detail}]` | | `POST /api/subscription/benefit/check` | 使用/检查权益 | 📱小程序 | `{benefitCode}` | `{success, logId}` | | `POST /api/subscription/tier` | 获取推广等级 | 📱小程序 | Header: `userId` | `PromotionTier` | | `POST /api/subscription/tier/update` | 更新推广等级（管理员） | 🖥管理后台 | `{tierCode}`, role=admin | `null` | ## 数据实体关系 ```mermaid erDiagram MembershipLevel ||--o{ FamilyMembership : "等级配置" User ||--o{ FamilyMembership : "家庭（通过familyId）" User ||--o{ MemberUpgradeRecord : "userId" FamilyMembership ||--o{ PaymentOrder : "订单" TrialMembership ||--o{ User : "试用" MemberSubscription ||--o{ SubscriptionBenefitLog : "权益使用" PromotionTier ||--o{ User : "userId" MembershipLevel { Long id PK string levelCode "FREE/FAMILY/PREMIUM/PROVIDER" string levelName string levelDesc int priceMonthly "月费（分）" int priceQuarterly "季费（分）" int priceYearly "年费（分）" text features "功能权限列表JSON" int maxChildren "可添加孩子数" int maxTasksPerDay "每日任务上限" } FamilyMembership { Long id PK Long familyId FK string levelCode "FREE/FAMILY/PREMIUM" date startDate date endDate string paymentStatus "paid/pending" string paymentMethod "wechat/trial" string orderNo } PaymentOrder { Long id PK String orderNo "ORD+时间戳" Long familyId FK string levelCode string paymentType "trial/yearly/monthly" string period int amount "分" string status "pending/paid" string transactionId "微信交易号" } MemberUpgradeRecord { Long id PK Long userId FK string fromLevel string toLevel string upgradeType "pay/trial/consumption" date expireTime } TrialMembership { Long id PK Long userId FK Long familyId FK date startDate date endDate int trialDays string status "ACTIVE/EXPIRED" } MemberSubscription { Long id PK Long familyId FK string level "L1/L2" string status "active/cancelled" date expireTime int autoRenew "0/1" } SubscriptionBenefitLog { Long id PK Long subscriptionId FK string benefitCode date usedAt text detail } PromotionTier { Long id PK Long userId FK string tierCode } ``` ## 完整性分析 | # | 维度 | 评估 | 说明 | |---|------|------|------| | 1 | **流程完整性** | ✅ 完整 | 覆盖会员信息查看（5种查询）、购买升级（付费/试用/优惠券）、会员权益（权限检查+折扣）、订阅管理（创建/取消/自动续费）、订阅权益与推广等级、系统定时任务（自动升级/过期降级）6个阶段，路径完整 | | 2 | **异常路径** | ⚠️ 部分覆盖 | 会员过期自动降级由定时任务处理（图中阶段六已体现）；支付失败/取消场景未画入（支付回调仅处理成功通知）；试用只能激活一次（代码中无防重复判断） | | 3 | **端点覆盖** | ✅ 完整 | 22个端点全部映射到流程图中，与代码实际暴露的`/api/membership/*`（MembershipController）和`/api/subscription/*`（SubscriptionController）一致 | | 4 | **角色覆盖** | ✅ 完整 | 购买/查看为📱家长端（`role=parent`）；tier/update为🖥管理后台（`role=admin`）；notify为⚙️微信支付回调；定时任务为⚙️系统自动 | | 5 | **数据实体** | ✅ 完整 | membership_levels、family_memberships、payment_orders、member_upgrade_records、trial_memberships、member_subscriptions、subscription_benefit_logs、promotion_tiers、user_coupons、commission_records、sys_config共11张表均在图中映射 | | 6 | **一致性** | ✅ 与代码一致 | 所有端点路径与实际Controller中的`@PostMapping`匹配；等级代码（FREE/FAMILY/PREMIUM）和功能白名单与代码逻辑一致；订阅方案（L1=36500/年, L2=131400/年）与硬编码值一致 |