cfc/docs/flows/shop-flow.md

用户使用流程图 — 商城交易

端口说明: 📱 小程序 | 🖥 管理后台 | 📋 规划师端 | ⚙️ 系统自动

分层说明: 🏠 页面 → 🔗 API → ⚙️ Service → 📦 数据实体

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_BUYER(("👤 买家")):::actor
    ROLE_VENDOR(("🏪 商家")):::actor
    ROLE_ADMIN(("🖥 管理员")):::actor
    ROLE_PAY(("💳 微信支付")):::actor

    %% ================================================================
    %% 阶段一：商品浏览
    %% ================================================================
    subgraph 阶段一[阶段一：商品浏览]
        direction TB

        P1["🏠 小程序：商城首页"]:::page
        P1 -->|"选择操作"| P1_choice{"浏览分类 / 搜索商品"}:::page

        P1_choice -->|"浏览分类"| P1a["🏠 分类树"]:::page
        P1a -->|""| A1["🔗 POST /api/shop/category/tree"]:::api
        A1 -->|""| S1["⚙️ ProductCategoryService.tree()"]:::service
        S1 -->|"商品分类层级树"| D1["📦 product_categories 表"]:::data

        P1_choice -->|"查看分类商品"| P1b["🏠 分类商品列表"]:::page
        P1b -->|"categoryId"| A2["🔗 POST /api/shop/category/products"]:::api
        A2 -->|"分类ID"| S2["⚙️ ProductCategoryService.products()"]:::service
        S2 -->|"该分类下的商品列表"| D2["📦 products 表（按分类筛选）"]:::data

        P1_choice -->|"商品列表"| P1c["🏠 商品列表页"]:::page
        P1c -->|"关键词, 分类, 排序, 分页"| A3["🔗 POST /api/product/list"]:::api
        A3 -->|"查询参数"| S3["⚙️ ProductService.list()"]:::service
        S3 -->|"分页商品数据"| D2

        P1c -->|"查看详情"| P1d["🏠 商品详情页"]:::page
        P1d -->|"商品ID"| A4["🔗 POST /api/product/detail"]:::api
        A4 -->|"商品ID"| S4["⚙️ ProductService.detail()"]:::service
        S4 -->|"商品完整信息（含规格）"| D2

        P1d -->|"查看规格映射"| P1e["🏠 规格选择弹窗"]:::page
        P1e -->|"商品ID列表"| A5["🔗 POST /api/product/spec/map"]:::api
        A5 -->|"商品IDs"| S5["⚙️ ProductSkuService.listByProductId()"]:::service
        S5 -->|"SKU规格分组与选项"| D3["📦 product_skus 表"]:::data
    end

    %% ================================================================
    %% 阶段二：购物车
    %% ================================================================
    subgraph 阶段二[阶段二：购物车]
        D3 -->|"选定SKU"| P2["🏠 购物车页"]:::page
        P2 -->|"添加商品"| P2a["🏠 添加到购物车"]
        P2a -->|"商品ID, 数量, SKU ID"| A6["🔗 POST /api/cart/add"]:::api
        A6 -->|"用户ID, 商品ID, 数量"| S6["⚙️ CartService.addToCart()"]:::service
        S6 -->|"写入购物车项"| D4["📦 cart 表"]:::data

        D4 -->|"购物车数据"| P2b["🏠 购物车列表"]
        P2b -->|"用户ID"| A7["🔗 POST /api/cart/list"]:::api
        A7 -->|"用户ID"| S7["⚙️ CartService.getCartList()"]:::service
        S7 -->|"购物车商品列表"| D4

        P2b -->|"修改数量"| P2c["🏠 编辑数量"]
        P2c -->|"商品ID, 新数量"| A8["🔗 POST /api/cart/update"]:::api
        A8 -->|"商品ID, 数量"| S8["⚙️ CartService.updateQuantity()"]:::service
        S8 -->|"更新数量"| D4

        P2b -->|"移除商品"| P2d["🏠 移除"]
        P2d -->|"商品ID"| A9["🔗 POST /api/cart/remove"]:::api
        A9 -->|"商品ID"| S9["⚙️ CartService.removeItem()"]:::service
        S9 -->|"删除购物车项"| D4

        P2b -->|"查看数量"| P2e["🏠 购物车角标"]
        P2e -->|"用户ID"| A10["🔗 POST /api/cart/count"]:::api
        A10 -->|"用户ID"| S10["⚙️ CartService.getCartCount()"]:::service
        S10 -->|"购物车商品总数"| D4
    end

    %% ================================================================
    %% 阶段三：下单支付
    %% ================================================================
    subgraph 阶段三[阶段三：下单支付]
        D4 -->|"选中商品"| P3["🏠 确认订单页"]:::page
        P3 -->|"提交订单"| A11["🔗 POST /api/product/order/create"]:::api
        A11 -->|"收货地址ID, 商品列表, 备注"| S11["⚙️ ProductOrderService.create()"]:::service
        S11 -->|"写入订单, 状态=待支付"| D5["📦 product_orders 表"]:::data

        D5 -->|"订单号"| P3a["🏠 支付页"]
        P3a -->|"发起支付"| A12["🔗 POST /api/product/order/pay"]:::api
        A12 -->|"订单号"| S12["⚙️ ProductOrderService.pay()"]:::service
        S12 -->|"微信支付参数(预支付ID)"| PAY["💳 微信支付收银台"]:::external

        PAY -->|"用户完成支付"| A13["🔗 POST /api/product/order/notify"]:::api
        A13 -->|"微信异步通知密文"| S13["⚙️ PaymentService.handleWechatNotify()"]:::service
        S13 -->|"解密+验证签名"| S13a["⚙️ ProductOrderService.handlePaymentSuccess()"]:::service
        S13a -->|"更新订单状态=已支付"| D5
    end

    %% ================================================================
    %% 阶段四：订单管理
    %% ================================================================
    subgraph 阶段四[阶段四：订单管理]
        D5 -->|"用户ID"| P4["🏠 我的订单页"]:::page
        P4 -->|"按状态筛选"| A14["🔗 POST /api/product/order/my"]:::api
        A14 -->|"用户ID, 状态"| S14["⚙️ ProductOrderService.myOrders()"]:::service
        S14 -->|"用户订单列表"| D5

        P4 -->|"数量统计"| P4a["🏠 订单角标"]
        P4a -->|"用户ID"| A15["🔗 POST /api/product/order/my/counts"]:::api
        A15 -->|"用户ID"| S15["⚙️ ProductOrderService.myOrderCounts()"]:::service
        S15 -->|"各状态订单数量"| D5

        P4 -->|"查看详情"| P4b["🏠 订单详情页"]
        P4b -->|"订单号"| A16["🔗 POST /api/product/order/detail"]:::api
        A16 -->|"订单号"| S16["⚙️ ProductOrderService.detail()"]:::service
        S16 -->|"订单完整信息"| D5

        P4b -->|"取消订单"| P4c{"状态=待支付?"}:::page
        P4c -->|"是"| P4d["🏠 取消订单"]
        P4d -->|"订单号"| A17["🔗 POST /api/product/order/cancel"]:::api
        A17 -->|"订单号"| S17["⚙️ ProductOrderService.cancel()"]:::service
        S17 -->|"更新状态=已取消"| D5

        P4b -->|"确认收货"| P4e{"状态=已发货?"}:::page
        P4e -->|"是"| P4f["🏠 确认收货"]
        P4f -->|"订单号"| A18["🔗 POST /api/product/order/confirm"]:::api
        A18 -->|"订单号"| S18["⚙️ ProductOrderService.confirmReceive()"]:::service
        S18 -->|"更新状态=已完成"| D5

        P4b -->|"申请退款"| P4g{"已支付且未完成?"}:::page
        P4g -->|"是"| P4h["🏠 申请退款"]
        P4h -->|"订单号, 退款原因"| A19["🔗 POST /api/product/order/refund/apply"]:::api
        A19 -->|"订单号, 原因"| S19["⚙️ ProductOrderService.applyRefund()"]:::service
        S19 -->|"更新状态=退款中"| D5
    end

    %% ================================================================
    %% 阶段五：商家发货
    %% ================================================================
    subgraph 阶段五[阶段五：商家发货]
        D5 -->|"待发货订单"| P5["🖥 商家端：订单管理页"]:::page
        P5 -->|"查看商家订单"| A20["🔗 POST /api/product/order/vendor"]:::api
        A20 -->|"商家ID, 状态"| S20["⚙️ ProductOrderService.vendorOrders()"]:::service
        S20 -->|"商家订单列表"| D5

        P5 -->|"发货"| P5a["🖥 发货表单"]
        P5a -->|"订单号, 快递公司, 运单号"| A21["🔗 POST /api/product/order/ship"]:::api
        A21 -->|"快递信息"| S21["⚙️ ProductOrderService.ship()"]:::service
        S21 -->|"更新状态=已发货, 记录物流"| D5

        D5 -->|"物流信息"| P5b["📱 小程序：物流查询"]
        P5b -->|"订单ID"| A22["🔗 POST /api/shop/logistics/query"]:::api
        A22 -->|"订单ID"| S22["⚙️ ProductOrderService.queryLogistics()"]:::service
        S22 -->|"物流跟踪信息"| D5
    end

    %% ================================================================
    %% 阶段六：售后
    %% ================================================================
    subgraph 阶段六[阶段六：售后]
        D5 -->|"退款中的订单"| P6["📱 小程序：售后申请页"]:::page
        P6 -->|"提交申请"| A23["🔗 POST /api/shop/after-sales/create"]:::api
        A23 -->|"订单ID, 售后类型, 原因, 描述"| S23["⚙️ AfterSalesService.create()"]:::service
        S23 -->|"创建售后记录, 订单状态=退款中"| D6["📦 after_sales_requests 表"]:::data

        D6 -->|"售后列表"| P6a["📱 售后列表页"]
        P6a -->|"用户ID, 状态筛选"| A24["🔗 POST /api/shop/after-sales/list"]:::api
        A24 -->|"状态"| S24["⚙️ AfterSalesService.list()"]:::service
        S24 -->|"售后申请列表"| D6

        P6a -->|"查看详情"| P6b["📱 售后详情页"]
        P6b -->|"售后单ID"| A25["🔗 POST /api/shop/after-sales/detail"]:::api
        A25 -->|"售后单ID"| S25["⚙️ AfterSalesService.detail()"]:::service
        S25 -->|"售后单完整信息"| D6
    end

    %% ================================================================
    %% 阶段七：评价
    %% ================================================================
    subgraph 阶段七[阶段七：评价]
        D5 -->|"已完成订单"| P7["📱 发表评价页"]:::page
        P7 -->|"提交评价"| A26["🔗 POST /api/review/order"]:::api
        A26 -->|"订单ID, 评分, 内容, 图片"| S26["⚙️ ReviewOrderService.createReview()"]:::service
        S26 -->|"写入评价记录"| D7["📦 review_orders 表"]:::data

        D7 -->|"评价数据"| P7a["📱 评价详情"]
        P7a -->|"订单ID"| A27["🔗 POST /api/review/order/detail"]:::api
        A27 -->|"订单ID"| S27["⚙️ ReviewOrderService.findByOrder()"]:::service
        S27 -->|"评价详情"| D7

        P7a -->|"评价状态"| A28["🔗 POST /api/review/order/status"]:::api
        A28 -->|"订单ID"| S28["⚙️ ReviewOrderService.getStats()"]:::service
        S28 -->|"评价统计数据"| D7
    end

    %% ================================================================
    %% 阶段八：收货地址
    %% ================================================================
    subgraph 阶段八[阶段八：收货地址]
        P3 -->|"管理地址"| P8["📱 地址管理页"]:::page
        P8 -->|"地址列表"| A29["🔗 POST /api/consignee/list"]:::api
        A29 -->|"用户ID"| S29["⚙️ ConsigneeService.list()"]:::service
        S29 -->|"用户收货地址列表"| D8["📦 consignees 表"]:::data

        P8 -->|"新增/编辑"| P8a["📱 地址表单"]
        P8a -->|"收货人, 手机号, 省市区, 详细地址"| A30["🔗 POST /api/consignee/save"]:::api
        A30 -->|"地址对象"| S30["⚙️ ConsigneeService.save()"]:::service
        S30 -->|"写入/更新地址"| D8

        P8 -->|"地址详情"| P8b["📱 地址详情"]
        P8b -->|"地址ID"| A31["🔗 POST /api/consignee/detail"]:::api
        A31 -->|"地址ID"| S31["⚙️ ConsigneeService.detail()"]:::service
        S31 -->|"地址完整信息"| D8

        P8 -->|"删除地址"| P8c["📱 删除确认"]
        P8c -->|"地址ID"| A32["🔗 POST /api/consignee/delete"]:::api
        A32 -->|"地址ID, 用户ID"| S32["⚙️ ConsigneeService.delete()"]:::service
        S32 -->|"删除地址记录"| D8
    end

    %% ================================================================
    %% 阶段九：商家商品管理
    %% ================================================================
    subgraph 阶段九[阶段九：商家商品管理]
        P5 -->|"管理商品"| P9["🖥 商家端：商品管理页"]:::page
        P9 -->|"创建商品"| P9a["🖥 商品发布表单"]
        P9a -->|"商品名称, 价格, 库存, 图片, 类目"| A33["🔗 POST /api/product/create"]:::api
        A33 -->|"商品对象"| S33["⚙️ ProductService.create()"]:::service
        S33 -->|"写入新商品, 状态=待审核"| D2

        P9 -->|"编辑商品"| P9b["🖥 编辑表单"]
        P9b -->|"商品ID, 更新字段"| A34["🔗 POST /api/product/update"]:::api
        A34 -->|"商品对象"| S34["⚙️ ProductService.update()"]:::service
        S34 -->|"更新商品信息"| D2

        P9 -->|"我的商品"| P9c["🖥 我的商品列表"]
        P9c -->|"商家ID"| A35["🔗 POST /api/product/my"]:::api
        A35 -->|"商家ID"| S35["⚙️ ProductService.myProducts()"]:::service
        S35 -->|"该商家的所有商品"| D2

        P9 -->|"上架/下架"| P9d["🖥 上架/下架操作"]
        P9d -->|"商品ID, 动作(on/off)"| A36["🔗 POST /api/product/shelve"]:::api
        A36 -->|"商品ID, 动作"| S36["⚙️ ProductService.shelve()"]:::service
        S36 -->|"更新商品状态"| D2

        P9 -->|"更新图片"| P9e["🖥 图片管理"]
        P9e -->|"商品ID, 图片列表"| A37["🔗 POST /api/product/images/update"]:::api
        A37 -->|"商品ID, 图片URL列表"| S37["⚙️ ProductService.updateImages()"]:::service
        S37 -->|"更新商品图片字段"| D2
    end

    %% ================================================================
    %% 角色关联
    %% ================================================================
    ROLE_BUYER -.- P1
    ROLE_BUYER -.- P2
    ROLE_BUYER -.- P3
    ROLE_BUYER -.- P4
    ROLE_BUYER -.- P6
    ROLE_BUYER -.- P7
    ROLE_BUYER -.- P8
    ROLE_VENDOR -.- P5
    ROLE_VENDOR -.- P9
    ROLE_ADMIN -.- P5
    ROLE_PAY -.- PAY

端点明细

商品浏览

端点	说明	端口	请求数据	响应数据
POST /api/product/list	获取商品列表	📱小程序	{keyword, categoryId, sort, page, size, ...}	分页商品列表（含价格, 库存, 封面）
POST /api/product/detail	获取商品详情	📱小程序	{id}	商品完整信息（含规格, 描述, 图片）
POST /api/product/spec/map	获取规格映射	📱小程序	{productIds: [id1, id2]}	每个商品的分组规格（颜色, 尺寸等）及SKU价格库存
POST /api/shop/category/tree	获取分类树	📱小程序	—	商品分类层级树
POST /api/shop/category/products	获取分类下商品	📱小程序	{categoryId}	该分类下的商品列表

购物车

端点	说明	端口	请求数据	响应数据
POST /api/cart/add	添加购物车	📱小程序	{productId, quantity, skuId}	CartItemDTO（含商品名称, 数量, 价格）
POST /api/cart/list	获取购物车列表	📱小程序	Header: userId	购物车商品列表（含规格信息）
POST /api/cart/update	更新购物车数量	📱小程序	{productId, quantity}	成功/失败
POST /api/cart/remove	移除购物车商品	📱小程序	{productId}	成功/失败
POST /api/cart/count	获取购物车数量	📱小程序	Header: userId	购物车商品总数

下单支付

端点	说明	端口	请求数据	响应数据
POST /api/product/order/create	创建订单	📱小程序	{productId, quantity, skuId, consigneeId, remark, ...}	ProductOrderDTO（含订单号, 金额, 状态）
POST /api/product/order/pay	发起支付	📱小程序	{orderNo}	微信支付参数（prepay_id, sign等）
POST /api/product/order/notify	微信支付回调	⚙️系统自动	微信异步通知密文	{code, message}
POST /api/product/order/handlePaymentSuccess	手动处理支付成功	⚙️系统自动	{orderNo}	成功/失败

订单管理

端点	说明	端口	请求数据	响应数据
POST /api/product/order/my	获取我的订单	📱小程序	{status, keyword}	订单列表（含商品快照, 状态）
POST /api/product/order/my/counts	订单数量统计	📱小程序	Header: userId	各状态订单数量
POST /api/product/order/detail	订单详情	📱小程序	{orderNo}	订单完整信息（含地址快照, 物流）
POST /api/product/order/cancel	取消订单	📱小程序	{orderNo}	成功/失败
POST /api/product/order/confirm	确认收货	📱小程序	{orderNo}	成功/失败
POST /api/product/order/refund/apply	申请退款	📱小程序	{orderNo, reason}	成功/失败
POST /api/product/order/vendor	商家订单列表	🖥管理后台	{status}	商家订单列表
POST /api/product/order/ship	商家发货	🖥管理后台	{orderNo, trackingNumber, expressCompany}	成功/失败

物流

端点	说明	端口	请求数据	响应数据
POST /api/shop/logistics/query	查询物流	📱小程序	{orderId}	物流跟踪信息

售后

端点	说明	端口	请求数据	响应数据
POST /api/shop/after-sales/create	创建售后申请	📱小程序	{orderId, type, reason, description, images}	AfterSalesRequest对象
POST /api/shop/after-sales/list	售后列表	📱小程序	{status}	售后申请列表
POST /api/shop/after-sales/detail	售后详情	📱小程序	{id}	售后申请完整信息

评价

端点	说明	端口	请求数据	响应数据
POST /api/review/order	发表评价	📱小程序	{orderId, rating, content, images}	成功/失败
POST /api/review/order/detail	评价详情	📱小程序	{orderId}	评价内容及回复
POST /api/review/order/status	评价状态	📱小程序	{orderId}	评价统计数据

收货地址

端点	说明	端口	请求数据	响应数据
POST /api/consignee/list	地址列表	📱小程序	Header: userId	收货地址列表
POST /api/consignee/save	添加/保存地址	📱小程序	{id, name, phone, province, city, district, street, detail}	地址ID
POST /api/consignee/detail	地址详情	📱小程序	{id}	地址完整信息
POST /api/consignee/delete	删除地址	📱小程序	{id}	成功/失败

商家商品管理

端点	说明	端口	请求数据	响应数据
POST /api/product/create	创建商品	🖥管理后台	{name, price, stock, coverImage, categoryId, ...}	ProductDTO
POST /api/product/update	更新商品	🖥管理后台	{id, name, price, stock, ...}	ProductDTO
POST /api/product/my	我的商品	🖥管理后台	Header: userId	商品列表
POST /api/product/shelve	上架/下架	🖥管理后台	{productId, action: "on"/"off"}	成功/失败
POST /api/product/images/update	更新商品图片	🖥管理后台	{productId, images: [url1, url2]}	成功/失败

数据实体关系

erDiagram
    ProductCategory ||--o{ Product : "一个分类多个商品"
    Vendor ||--o{ Product : "一个商家多个商品"
    Product ||--o{ ProductSku : "一个商品多个规格"
    Product ||--o{ Cart : "一个商品可被多次加入"
    User ||--o{ Cart : "一个用户多个购物车项"
    User ||--o{ ProductOrder : "一个用户多笔订单"
    User ||--o{ Consignee : "一个用户多个地址"
    Product ||--o{ ProductOrder : "一个商品对多笔订单"
    ProductOrder ||--o{ AfterSalesRequest : "一笔订单多个售后"
    ProductOrder ||--o{ ReviewOrder : "一笔订单一个评价"

    Product {
        Long id PK
        string name
        int price
        int stock
        string productType "physical / assessment"
        string status "pending / approved / rejected / on / off"
        Long vendorId FK
        string dimensionWeights
    }

    ProductSku {
        Long id PK
        Long productId FK
        string specs "JSON规格选项"
        int price
        int stock
    }

    Cart {
        Long id PK
        Long userId FK
        Long productId FK
        Long skuId FK
        int quantity
    }

    ProductOrder {
        Long id PK
        string orderNo
        Long buyerId FK
        Long productId FK
        int totalAmount
        string status "pending_pay / paid / shipped / completed / cancelled / refunding"
        string logisticsNo
        string trackingNumber
    }

    Consignee {
        Long id PK
        Long userId FK
        string name
        string phone
        string province
        string city
        string district
        string street
        string detail
    }

    AfterSalesRequest {
        Long id PK
        Long orderId FK
        string type
        string status "pending / approved / rejected / completed"
    }

    ReviewOrder {
        Long id PK
        Long orderId FK
        int rating
        string content
        string images
    }

完整性分析

#	维度	评估	说明
1	流程完整性	✅ 完整	覆盖商品浏览→购物车→下单支付→订单管理→发货→售后→评价→地址管理→商家商品管理9个阶段，包含买家与商家双视角
2	异常路径	⚠️ 部分覆盖	支付失败/取消订单/退款申请已覆盖；库存不足/价格变动/支付超时等边界情况在前端校验，未在图里展开
3	端点覆盖	✅ 完整	32个端点全部映射到流程图中，与代码中ProductController、CartController、ProductOrderController、ConsigneeController、ReviewController、AfterSalesController、ProductCategoryController、LogisticsController一致
4	角色覆盖	✅ 完整	买家（小程序）、商家（管理后台）、管理员（管理后台）、微信支付（外部系统）三种视角均已覆盖
5	数据实体	✅ 完整	products、product_skus、cart、product_orders、consignees、after_sales_requests、review_orders、product_categories 8张表均在图中映射
6	一致性	✅ 与代码一致	所有端点路径与实际Controller中的@PostMapping匹配，Service方法名与代码中的业务方法一致（create/detail/list/ship等）