# 用户使用流程图 — 管家与商家入驻 > **端口说明**: 📱 小程序 | 🖥 管理后台 | 📋 规划师端 | ⚙️ 系统自动 > > **分层说明**: 🏠 页面 → 🔗 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_ADMIN(("🖥 管理员")):::actor %% ================================================================ %% 阶段一：管家服务 — 申请与档案 %% ================================================================ subgraph 阶段一[阶段一：管家服务申请与档案] direction TB P1["🏠 家长端：管家申请页"]:::page P1 -->|"提交申请"| A1["🔗 POST /api/butler/apply"]:::api A1 -->|"userId, tier(等级), description(申请说明)"| S1["⚙️ ButlerService.apply()"]:::service S1 -->|"创建管家申请记录"| D1["📦 butler_applications 表"]:::data D1 -->|"申请通过后"| P2["🏠 家长端：管家档案页"]:::page P2 -->|"查看档案"| A2["🔗 POST /api/butler/profile"]:::api A2 -->|"userId"| S2["⚙️ ButlerService.getProfile()"]:::service S2 -->|"管家等级, 状态, 资料"| D2["📦 butler_profiles 表"]:::data P2 -->|"更新档案"| A3["🔗 POST /api/butler/update-profile"]:::api A3 -->|"userId, 更新字段(简介/头像等)"| S3["⚙️ ButlerService.updateProfile()"]:::service S3 -->|"更新管家资料字段"| D2 end %% ================================================================ %% 阶段二：管家服务 — 成员与服务 %% ================================================================ subgraph 阶段二[阶段二：管家服务管理] D2 -->|"管家ID"| P3["🏠 家长端：管家成员页"]:::page P3 -->|"查看分配家庭成员"| A4["🔗 POST /api/butler/members"]:::api A4 -->|"userId, page, size"| S4["⚙️ ButlerService → UserMapper 查询"]:::service S4 -->|"分页：该管家负责的家庭成员"| D3["📦 users 表（referrerId 关联）"]:::data P3 -->|"查看服务记录"| A5["🔗 POST /api/butler/service-records"]:::api A5 -->|"userId（已废弃）"| S5["⚙️ ButlerController（已废弃）"]:::service S5 -->|"抛出 UnsupportedOperationException"| X1["❌ 功能暂未开放"]:::external P3 -->|"查看佣金"| A6["🔗 POST /api/butler/commissions"]:::api A6 -->|"userId（已废弃）"| S6["⚙️ ButlerController（已废弃）"]:::service S6 -->|"抛出 UnsupportedOperationException"| X2["❌ 功能暂未开放"]:::external end %% ================================================================ %% 阶段三：商家入驻 %% ================================================================ subgraph 阶段三[阶段三：商家入驻] P1 -->|"申请入驻"| P4["🏠 家长端：商家入驻页"]:::page P4 -->|"提交入驻申请"| A7["🔗 POST /api/vendor/apply"]:::api A7 -->|"userId, vendorType(商家类型), vendorInfo(商家信息)"| S7["⚙️ VendorService.apply()"]:::service S7 -->|"创建入驻申请记录, 状态=待审核"| D4["📦 vendor_applications 表"]:::data D4 -->|"审核通过后"| P5["🏠 家长端：入驻状态页"]:::page P5 -->|"查看入驻状态"| A8["🔗 POST /api/vendor/status"]:::api A8 -->|"userId"| S8["⚙️ VendorService.getStatus()"]:::service S8 -->|"申请状态(待审核/通过/驳回)"| D4 P5 -->|"查看商家信息"| A9["🔗 POST /api/vendor/info"]:::api A9 -->|"userId"| S9["⚙️ VendorService.getVendorInfo()"]:::service S9 -->|"商家名称/类型/联系方式等"| D5["📦 vendor_info 表"]:::data end %% ================================================================ %% 阶段四：商家管理（管理后台） %% ================================================================ subgraph 阶段四[阶段四：商家管理（管理后台）] D5 -->|"商家信息"| P6["🖥 管理后台：商家管理页"]:::page P6 -->|"管理商品"| A10["🔗 POST /api/product/manage"]:::api A10 -->|"商家ID, 商品信息"| S10["⚙️ ProductService"]:::service S10 -->|"商品CRUD"| D6["📦 products 表"]:::data P6 -->|"处理订单"| A11["🔗 POST /api/order/process"]:::api A11 -->|"商家ID, 订单ID, 操作"| S11["⚙️ OrderService"]:::service S11 -->|"更新订单状态"| D7["📦 orders 表"]:::data P6 -->|"发货管理"| A12["🔗 POST /api/order/ship"]:::api A12 -->|"订单ID, 物流信息"| S12["⚙️ OrderService.ship()"]:::service S12 -->|"更新物流状态/单号"| D7 end %% ================================================================ %% 角色关联 %% ================================================================ ROLE_PARENT -.- P1 ROLE_PARENT -.- P2 ROLE_PARENT -.- P3 ROLE_PARENT -.- P4 ROLE_PARENT -.- P5 ROLE_ADMIN -.- P6 ``` ## 端点明细 ### 管家服务 | 端点 | 说明 | 端口 | 请求数据 | 响应数据 | |------|------|------|---------|---------| | `POST /api/butler/apply` | 申请成为管家 | 📱小程序 | `{tier, description}` | `{success}` | | `POST /api/butler/profile` | 获取管家档案 | 📱小程序 | Header: `Authorization` | `{tier, status, avatar, ...}` | | `POST /api/butler/update-profile` | 更新管家资料 | 📱小程序 | `{简介/头像/联系方式等}` | `{success}` | | `POST /api/butler/members` | 获取分配的家庭成员 | 📱小程序 | `{page, size}` | `{list, total, page, size}` | | `POST /api/butler/service-records` | 获取服务记录 | 📱小程序 | Header: `Authorization` | ❌ 已废弃，抛出异常 | | `POST /api/butler/commissions` | 获取佣金记录 | 📱小程序 | Header: `Authorization` | ❌ 已废弃，抛出异常 | ### 商家入驻 | 端点 | 说明 | 端口 | 请求数据 | 响应数据 | |------|------|------|---------|---------| | `POST /api/vendor/apply` | 申请入驻 | 📱小程序 | `{vendorType, vendorInfo}` | `{success}` | | `POST /api/vendor/status` | 获取入驻状态 | 📱小程序 | Header: `Authorization` | `{status(待审核/通过/驳回), auditRemark}` | | `POST /api/vendor/info` | 获取商家信息 | 📱小程序 | Header: `Authorization` | `{商家名称/类型/联系方式}` | ## 完整性分析 | # | 维度 | 评估 | 说明 | |---|------|------|------| | 1 | **流程完整性** | ✅ 完整 | 覆盖管家申请→档案→成员管理→商家入驻→商家管理共4个阶段，路径完整 | | 2 | **异常路径** | ✅ 已覆盖 | 管家服务记录和佣金两个端点已废弃，图中明确标注"❌ 功能暂未开放"；入驻申请审核驳回等状态在`/api/vendor/status`中体现 | | 3 | **端点覆盖** | ✅ 完整 | 9个端点全部映射到流程图中，与代码实际暴露的`/api/butler/*`和`/api/vendor/*`一致 | | 4 | **角色覆盖** | ✅ 完整 | 家长可申请管家/入驻商家并管理；管理员在后台管理商家商品和订单 | | 5 | **数据实体** | ⚠️ 部分覆盖 | butler_applications表、butler_profiles表、users表（referrerId关联）、vendor_applications表、vendor_info表已在图中映射；但管家/商家具体业务表（products、orders）在阶段四仅做示意性标注 | | 6 | **一致性** | ✅ 与代码一致 | 所有端点路径与实际Controller（ButlerController、VendorController）中的`@PostMapping`匹配；废弃端点已在代码中标注`@Deprecated`，图中对应 | | 7 | **废弃端点** | ✅ 已标记 | `/api/butler/service-records`和`/api/butler/commissions`已废弃（`@Deprecated`），图中标注"❌ 功能暂未开放"；注意`/api/butler/*`走的是butler包下的ButlerController，而非ai包下的ButlerController（AI管家会话管理） |