DanShop 电商模块集成设计方案

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task.

Goal: 将电商商城（DanShop）作为独立 Spring Boot 模块集成到 cfc 浠艾福平台，实现商品分类与五维能量对应、购物车、下单、支付、物流跟踪、利润留存与返利等完整电商功能。

Architecture: DanShop 定位为 cfc 生态中的电商子域（Bounded Context），采用独立 Maven 模块部署，与 cfc-backend 共享 MySQL 数据库（通过不同表名前缀隔离），通过 REST API（Feign 客户端）进行跨域通信。前端（uni-app小程序 + Vue Web管理端）通过统一网关调用 DanShop 和 cfc-backend 的接口。

Tech Stack: Spring Boot 2.7.18, MyBatis-Plus, MySQL 8.0, Redis (cart/cache), Feign (跨服务调用), xxl-job/Quartz (结算定时任务)

总体架构

┌────────────────────────────────────────────────────────────────────┐
│                         cfc-frontend (uni-app)                      │
│   pages/shop/* → /api/danshop/*   |  其他页面 → /api/cfc/*       │
└──────────────────────┬─────────────────────────────────────────────┘
                       │ 请求路由
┌──────────────────────▼─────────────────────────────────────────────┐
│                    Gateway / API 路由层                              │
├──────────────────────┬─────────────────────────────────────────────┤
│  /api/danshop/**     │          /api/**                            │
├──────────────────────┼─────────────────────────────────────────────┤
│  dan/danshop/        │          cfc-backend/                       │
│  (Spring Boot 9081)  │          (Spring Boot 9082)                 │
├──────────────────────┼─────────────────────────────────────────────┤
│  商品/分类/购物车    │                                                │
│  订单/支付/物流      │   用户/家庭/任务/积分/能量/成长              │
│  返利/结算           │                                                │
└──────────────────────┴─────────────────────────────────────────────┘
                               │ 共享数据库
┌──────────────────────────────▼─────────────────────────────────────┐
│                          MySQL 8.0 (cfc)                          │
│  cfc-backend tables: users, families, tasks, energy_* ...        │
│  danshop tables: danshop_categories, danshop_products,            │
│                  danshop_cart, danshop_orders, danshop_*           │
└────────────────────────────────────────────────────────────────────┘

模块位置

cfc/
├── dan/danshop/                    # DanShop 电商模块（新）
│   ├── pom.xml                     # Maven 模块
│   ├── src/main/java/com/etotem/danshop/
│   │   ├── DanShopApplication.java
│   │   ├── config/
│   │   ├── common/
│   │   ├── controller/
│   │   │   ├── buyer/              # 买家端 API
│   │   │   ├── seller/             # 卖家端 API（服务商）
│   │   │   └── admin/              # 管理端 API
│   │   ├── service/
│   │   ├── entity/
│   │   ├── mapper/
│   │   ├── dto/
│   │   └── feign/                  # Feign 客户端调用 cfc-backend
│   └── src/main/resources/
│       └── application.yml
├── cfc-backend/                    # 现有后端（需 Feign 接口）
├── cfc-frontend/                   # 现有小程序前端（需新页面）
└── cfc-web/                        # 现有 Web 管理端（需新页面）

跨域通信

DanShop 与 cfc-backend 的通信方式：

场景	通信方式	说明
用户认证	Feign → AuthController	DanShop 通过 Feign 调用 cfc-backend 验证 JWT Token
用户/家庭信息	Feign → UserService	获取买家信息、家庭ID、推荐关系
能量维度映射	共享 DB 只读	DanShop 直接读取 energy_dimension 表
发放能量	Feign → EnergyService	购物后发放能量值到孩子账户
佣金结算	Feign → CommissionService	订单支付后调用佣金结算
积分发放	Feign → PointsService	购物赠送积分

数据库隔离策略

DanShop 使用独立的表名前缀 danshop_，不与 cfc-backend 现有表冲突
DanShop 通过共享只读方式访问 cfc 的 users、families、energy_dimension 表
DanShop 有自己的 MyBatis-Plus 配置和数据源（共享同一个 MySQL 数据库 cfc，但扫描不同的 mapper 路径）

模块一：商品分类与五维能量映射（P0）

数据模型

-- 商品分类表（支持多级树形结构）
CREATE TABLE danshop_categories (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    parent_id BIGINT DEFAULT NULL COMMENT '父分类ID（null=一级）',
    name VARCHAR(64) NOT NULL COMMENT '分类名称',
    image VARCHAR(512) DEFAULT NULL COMMENT '分类图标',
    sort_order INT DEFAULT 0 COMMENT '排序',
    energy_dimension_id BIGINT DEFAULT NULL COMMENT '关联五维维度ID(energy_dimension.id)',
    status INT DEFAULT 1 COMMENT '1启用/0禁用',
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 商品表（扩展现有 products 表）
CREATE TABLE danshop_products (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    category_id BIGINT NOT NULL COMMENT '所属分类',
    name VARCHAR(128) NOT NULL COMMENT '商品名称',
    description TEXT COMMENT '商品描述',
    cover_image VARCHAR(512) COMMENT '封面图',
    images TEXT COMMENT '多图(JSON数组)',
    price DECIMAL(10,2) NOT NULL COMMENT '售价(元)',
    member_price DECIMAL(10,2) DEFAULT NULL COMMENT '会员价',
    cost_price DECIMAL(10,2) DEFAULT NULL COMMENT '成本价(用于利润计算)',
    stock INT DEFAULT 0 COMMENT '库存',
    sales_count INT DEFAULT 0 COMMENT '销量',
    product_type VARCHAR(32) NOT NULL COMMENT '类型: physical/virtual/coupon/course',
    vendor_id BIGINT DEFAULT NULL COMMENT '供应商ID(users.id)',
    vendor_name VARCHAR(64) COMMENT '供应商名称',
    status VARCHAR(16) NOT NULL DEFAULT 'pending' COMMENT 'pending/approved/rejected/on_shelf/off_shelf',
    reject_reason VARCHAR(255) DEFAULT NULL,
    profit_rate DECIMAL(5,2) DEFAULT 0.00 COMMENT '平台利润率(%)',
    external_source VARCHAR(32) COMMENT '外部商品来源',
    external_id VARCHAR(64) COMMENT '外部商品ID',
    external_data TEXT COMMENT '外部商品数据(JSON)',
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_category (category_id),
    INDEX idx_vendor (vendor_id),
    INDEX idx_status (status)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

分类与五维维度关联逻辑

每个分类可以关联一个 energy_dimension.id（身/心/智/行/富）
父分类设定维度后，子分类默认继承父分类的维度
子分类可单独指定维度，覆盖父分类继承值
商品所属分类决定了购买后能量发放的目标维度
分类-维度映射在 EnergySourceConfig 中自动创建

能量发放规则

当用户购买商品后，系统根据商品分类关联的维度发放能量：

商品 → 分类 → energy_dimension_id → EnergySourceConfig[{dimensionId, ratio: 1.0}]
                                     ↓
                            EnergyService.awardEnergy(childId, "product", productId, amount, desc)

发放对象：家庭中关联的每个孩子（或指定孩子）
发放量 = 订单金额的特定比例（可配置，如每1元=1能量点）
日发能量上限受 EnergyService 已有规则限制

模块二：购物车（P0）

数据模型（Redis 实现）

购物车使用 Redis Hash 存储，不落数据库，以保持高性能和灵活性：

Redis Key: danshop:cart:{userId}
Hash Field: {productId}:{sku} → JSON(CartItem)

{
    "productId": 1,
    "productName": "儿童营养套餐",
    "coverImage": "https://...",
    "price": 199.00,
    "quantity": 2,
    "selected": true,
    "stock": 100,
    "productType": "physical"
}

购物车 API

POST   /api/danshop/buyer/cart/add          # 加入购物车
POST   /api/danshop/buyer/cart/list         # 购物车列表
POST   /api/danshop/buyer/cart/update       # 更新数量
POST   /api/danshop/buyer/cart/select       # 选择/取消选择
POST   /api/danshop/buyer/cart/remove       # 删除商品
POST   /api/danshop/buyer/cart/clear        # 清空购物车

购物车校验

库存校验：加入购物车时检查库存
价格同步：每次获取购物车列表时，从 danshop_products 同步最新价格
商品状态：已下架/已删除商品自动标记为"失效"

模块三：订单系统（P0）

订单状态机

         ┌──────────────────────────────────────┐
         │              pending                 │
         │          (待支付/已创建)               │
         └──────────┬───────────────────────────┘
                    │ 支付成功
         ┌──────────▼───────────────────────────┐
         │              paid                     │
         │          (已支付/待发货)               │
         └──────────┬───────────────────────────┘
                    │ 卖家发货（实物商品）
         ┌──────────▼───────────────────────────┐
         │            shipped                    │
         │          (已发货/待收货)               │
         └──────────┬───────────────────────────┘
                    │ 买家确认收货 / 自动确认
         ┌──────────▼───────────────────────────┐
         │           completed                   │
         │          (已完成/已收货)               │
         └──────────┬───────────────────────────┘
                    │ 发起退款
         ┌──────────▼───────────────────────────┐
         │           refunding                   │
         │          (退款中)                      │
         └──────────┬───────────────────────────┘
                    │ 管理员审核退款
         ┌──────────▼───────────────────────────┐
         │           refunded                    │
         │          (已退款)                      │
         └──────────────────────────────────────┘

         虚拟商品跳过 shipped 阶段：paid → completed
         取消（仅 pending 状态可取消）：pending → cancelled

数据模型

-- 主订单表
CREATE TABLE danshop_orders (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    order_no VARCHAR(32) NOT NULL UNIQUE COMMENT '订单号',
    buyer_id BIGINT NOT NULL COMMENT '买家ID(users.id)',
    family_id BIGINT COMMENT '家庭ID',
    total_amount DECIMAL(10,2) NOT NULL COMMENT '订单总金额',
    discount_amount DECIMAL(10,2) DEFAULT 0.00 COMMENT '优惠金额',
    actual_amount DECIMAL(10,2) NOT NULL COMMENT '实付金额',
    status VARCHAR(20) NOT NULL DEFAULT 'pending' COMMENT 'pending/paid/shipped/completed/refunding/refunded/cancelled',
    payment_method VARCHAR(16) DEFAULT 'wechat' COMMENT 'wechat/alipay',
    transaction_id VARCHAR(64) COMMENT '支付平台交易号',
    paid_at DATETIME COMMENT '支付时间',
    shipped_at DATETIME COMMENT '发货时间',
    completed_at DATETIME COMMENT '完成时间',
    remark VARCHAR(255) COMMENT '买家备注',
    cancel_reason VARCHAR(255) COMMENT '取消原因',
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_buyer (buyer_id),
    INDEX idx_family (family_id),
    INDEX idx_status (status),
    INDEX idx_created (created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 订单明细表
CREATE TABLE danshop_order_items (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    order_id BIGINT NOT NULL COMMENT '订单ID',
    product_id BIGINT NOT NULL COMMENT '商品ID',
    product_name VARCHAR(128) NOT NULL COMMENT '商品名称(快照)',
    cover_image VARCHAR(512) COMMENT '封面图(快照)',
    unit_price DECIMAL(10,2) NOT NULL COMMENT '单价(快照)',
    quantity INT NOT NULL DEFAULT 1 COMMENT '数量',
    subtotal DECIMAL(10,2) NOT NULL COMMENT '小计',
    product_type VARCHAR(32) COMMENT '商品类型(快照)',
    vendor_id BIGINT COMMENT '供应商ID(快照)',
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_order (order_id),
    INDEX idx_product (product_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

-- 订单操作日志表
CREATE TABLE danshop_order_logs (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    order_id BIGINT NOT NULL,
    action VARCHAR(32) NOT NULL COMMENT '操作: create/pay/ship/confirm/refund/cancel',
    operator_id BIGINT COMMENT '操作人ID',
    operator_type VARCHAR(16) COMMENT 'buyer/vendor/admin/system',
    detail TEXT COMMENT '操作详情(JSON)',
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_order (order_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

下单流程

1. 买家请求创建订单
   → 校验商品库存、状态、价格
   → 锁定库存
   → 创建订单 + 订单明细
   → 记录操作日志
   → 返回订单信息（含支付参数）

2. 买家发起支付
   → 调用 PaymentService 创建支付订单
   → 返回微信支付参数（prepay_id/timestamp/nonceStr/package/signType/paySign）
   → 小程序调起微信支付

3. 支付回调处理
   → 验证签名
   → 更新订单状态为 paid
   → 记录 transaction_id
   → 异步：减库存(已预减)、发能量、算佣金

4. 发货（实物商品）
   → 卖家填写物流信息
   → 订单状态改为 shipped

5. 确认收货
   → 买家确认 / 7天自动确认
   → 订单完成
   → 触发放能量和佣金结算

订单号生成规则

格式: DS + yyyyMMdd + HHmmss + 6位随机数
示例: DS20260612143029123456

模块四：支付集成（P0）

支付流程

小程序端                      DanShop                      微信支付
  │                            │                             │
  │  1. POST /order/pay       │                             │
  │  {orderNo: "DS..."}      │                             │
  │ ─────────────────────────►│                             │
  │                            │  2. 查询订单 + 金额         │
  │                            │                             │
  │                            │  3. 调用统一下单API         │
  │                            │ ──────────────────────────►│
  │                            │                             │
  │                            │  4. prepay_id               │
  │                            │ ◄──────────────────────────│
  │                            │                             │
  │  5. 返回支付参数           │                             │
  │ ◄─────────────────────────│                             │
  │                            │                             │
  │  6. 调起 wx.requestPayment│                             │
  │ ───────────────────────────────────────────────────────►│
  │                            │                             │
  │  7. 支付结果回调           │                             │
  │ ◄───────────────────────────────────────────────────────│
  │                            │                             │
  │  8. 调用支付结果查询       │                             │
  │ ─────────────────────────►│                             │
  │                            │  9. 更新订单状态             │
  │                            │                             │
  │  10. 支付成功通知          │                             │
  │ ◄─────────────────────────│                             │

PaymentService 改造

现有的 cfc-backend 中 PaymentService.createWechatPayOrder() 是桩代码，需要在 DanShop 中实现完整的微信支付集成：

// dan/danshop/src/main/java/com/etotem/danshop/service/PaymentService.java
@Service
public class PaymentService {
    // 微信支付统一下单
    public Map<String, Object> createWechatPayOrder(String orderNo, String description, Integer totalFee) {
        // 1. 调用微信支付 API v3 统一下单
        // 2. 获取 prepay_id
        // 3. 生成小程序调起支付所需的参数
        //    {appId, timeStamp, nonceStr, package: "prepay_id=xxx", signType: "RSA", paySign}
        // 4. 返回给前端
    }

    // 处理支付回调通知
    public String handlePayNotify(String requestBody, String signature) {
        // 1. 验证签名
        // 2. 解析回调数据
        // 3. 更新订单状态
        // 4. 触发后续流程（CommissionSettlementJob等）
    }

    // 退款
    public Map<String, Object> refund(String orderNo, BigDecimal amount, String reason) {
        // 调用微信支付退款API
    }
}

支付配置

# dan/danshop/src/main/resources/application.yml
danshop:
  payment:
    wechat:
      app-id: wx5ba8038ef16fb245
      mch-id: ${WX_MCH_ID}
      api-v3-key: ${WX_API_V3_KEY}
      private-key-path: ${WX_PRIVATE_KEY_PATH}
      notify-url: https://danshop.etotem.com.cn/api/danshop/payment/wechat/notify
      refund-notify-url: https://danshop.etotem.com.cn/api/danshop/payment/wechat/refund-notify

模块五：物流跟踪（P0）

数据模型

-- 物流信息表
CREATE TABLE danshop_logistics (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    order_id BIGINT NOT NULL COMMENT '订单ID',
    order_item_id BIGINT COMMENT '订单明细ID(null=整个订单发货)',
    logistics_no VARCHAR(64) NOT NULL COMMENT '物流单号',
    logistics_company VARCHAR(32) NOT NULL COMMENT '物流公司编码: sf/yto/zt/sto/yd/ttkd',
    logistics_name VARCHAR(32) COMMENT '物流公司名称',
    sender_name VARCHAR(32) COMMENT '发货人',
    sender_phone VARCHAR(16) COMMENT '发货人电话',
    sender_address VARCHAR(256) COMMENT '发货地址',
    receiver_name VARCHAR(32) COMMENT '收件人',
    receiver_phone VARCHAR(16) COMMENT '收件人电话',
    receiver_address VARCHAR(256) COMMENT '收件地址',
    status VARCHAR(16) NOT NULL DEFAULT 'pending' COMMENT 'pending/shipped/signing/completed',
    tracking_data TEXT COMMENT '物流轨迹(JSON数组)',
    shipped_at DATETIME COMMENT '发货时间',
    signed_at DATETIME COMMENT '签收时间',
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_order (order_id),
    INDEX idx_logistics_no (logistics_no)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

物流跟踪实现

对接快递鸟/快递100等第三方物流查询API
定时任务每30分钟更新一次运输中订单的轨迹

自动签收检测：轨迹显示"已签收"时更新订单状态

// dan/danshop/src/main/java/com/etotem/danshop/service/LogisticsService.java
@Service
public class LogisticsService {
// 发货 - 创建物流信息
public void ship(Long orderId, String logisticsNo, String company, String addressId) { }

// 查询物流轨迹
public List<TrackingItem> queryTracking(Long orderId) {
    // 1. 查本地数据库
    // 2. 如无或过期，调用第三方API刷新
    // 3. 缓存结果
}

// 定时刷新物流状态
@Scheduled(fixedRate = 1800000) // 30分钟
public void refreshTracking() {
    // 查询所有运输中的物流单
    // 批量调用第三方API更新状态
}
}

模块六：利润留存与返利系统（P0）

返利模型

                  商品售价 ¥100.00 (actual_amount)
                         │
           ┌─────────────┴─────────────┐
           │                           │
     成本价 30%             利润 70% = ¥70.00
  (cost_price)                    │
          │               ┌───────┴───────┐
          │          平台留存         服务商分成
          │       (profit_rate)    (100% - profit_rate)
          │           ¥21.00           ¥49.00
          │       = 70*30%          = 70*70%
          │                           │
          │                   ┌───────┴───────┐
          │              推荐人L1返利     平台留存
          │              (20%利润)        (80%利润)
          │               ¥14.00           ¥35.00
          │              = 70*20%
          │
     供应商收入 ¥30.00
     (实际入账)

返利配置表

-- 返利规则配置表
CREATE TABLE danshop_profit_rules (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    rule_name VARCHAR(64) NOT NULL COMMENT '规则名称',
    rule_type VARCHAR(32) NOT NULL COMMENT '规则类型: product_category/vendor_level/global',
    target_id BIGINT COMMENT '关联目标ID(category_id/vendor_id/null=全局)',
    platform_profit_rate DECIMAL(5,2) NOT NULL COMMENT '平台利润率(%)',
    referrer_l1_rate DECIMAL(5,2) DEFAULT 0.00 COMMENT '直接推荐人返利比例(占利润%)',
    referrer_l2_rate DECIMAL(5,2) DEFAULT 0.00 COMMENT '间接推荐人返利比例(占利润%，仅会员)',
    platform_service_rate DECIMAL(5,2) DEFAULT 0.00 COMMENT '平台服务费率(占订单金额%)',
    is_active INT DEFAULT 1 COMMENT '1启用/0禁用',
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    INDEX idx_type (rule_type, target_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

返利计算流程

订单完成（completed）时触发：
  │
  1. 计算利润 = actual_amount - cost_price (或 actual_amount × profit_rate 取大)
  2. 计算平台留存 = 利润 × (100% - referrer_l1_rate - referrer_l2_rate)
  3. 查找买家推荐关系链
  4. 计算 L1 推荐人佣金 = 利润 × referrer_l1_rate
  5. 计算 L2 推荐人佣金 = 利润 × referrer_l2_rate（仅会员订单/推荐人是 FAMILY 会员）
  6. 写入 commission_records 表（重用现有表结构）
  7. 更新推荐人的 totalCommissionEarned
  8. 记录返利流水到 danshop_profit_logs

返利规则查找优先级：
  1. product_category（商品分类关联）
  2. vendor_level（卖家等级关联）
  3. global（全局默认）

返利流水表

-- 返利流水表
CREATE TABLE danshop_profit_logs (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    order_id BIGINT NOT NULL COMMENT '订单ID',
    order_no VARCHAR(32) NOT NULL COMMENT '订单号',
    order_amount DECIMAL(10,2) NOT NULL COMMENT '订单金额',
    cost_amount DECIMAL(10,2) DEFAULT 0.00 COMMENT '成本金额',
    profit_amount DECIMAL(10,2) NOT NULL COMMENT '利润金额',
    platform_retained DECIMAL(10,2) NOT NULL COMMENT '平台留存金额',
    vendor_income DECIMAL(10,2) NOT NULL COMMENT '供应商收入',
    commission_l1 DECIMAL(10,2) DEFAULT 0.00 COMMENT 'L1推荐佣金',
    commission_l2 DECIMAL(10,2) DEFAULT 0.00 COMMENT 'L2推荐佣金',
    rule_id BIGINT COMMENT '使用的返利规则ID',
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_order (order_id, order_no)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

与现有 CommissionService 的集成

现有 CommissionService.settleTwoLevel() 处理两级佣金，DanShop 的返利系统将：

复用 commission_records 表：写入时 orderType 使用 danshop_product
扩展返利粒度：原系统只计算 L1/L2 佣金，DanShop 增加成本、平台留存、服务商收入等字段
提供 Feign 接口：DanShop 通过 Feign 调用 CommissionService 写入佣金记录
结算定时任务：新增结算任务，在订单完成后触发放能量和返利处理

Feign 接口定义

// cfc-backend 提供的 Feign 接口
@FeignClient(name = "cfc-backend", url = "${cfc.backend.url}")
public interface CfcCommissionClient {
    @PostMapping("/internal/commission/settle")
    Result<Void> settleCommission(
        @RequestBody CommissionSettleRequest request
    );
}

@FeignClient(name = "cfc-backend", url = "${cfc.backend.url}")
public interface CfcEnergyClient {
    @PostMapping("/internal/energy/award")
    Result<Map<String, Integer>> awardEnergy(
        @RequestBody EnergyAwardRequest request
    );
}

// cfc-backend 内部 Controller（仅内部调用）
@RestController
@RequestMapping("/internal/commission")
public class InternalCommissionController {
    @PostMapping("/settle")
    public Result<Void> settle(@RequestBody CommissionSettleRequest request) {
        // 调用 CommissionService.settleTwoLevel(...)
    }
}

模块七：前端页面规划

小程序端（cfc-frontend）新增/修改页面

页面	路径	功能	P0
商品分类页	`pages/shop/index.vue`	已有，需改造对接 DanShop API	✅
商品详情页	`pages/shop/detail.vue`	商品信息、规格选择、加入购物车	✅
购物车页	`pages/shop/cart/cart.vue`	购物车列表、数量编辑、结算	✅
确认订单页	`pages/shop/checkout/checkout.vue`	地址选择、商品确认、优惠	✅
支付页	`pages/shop/payment/payment.vue`	支付方式选择、调起支付	✅
订单列表	`pages/shop/order-list/order-list.vue`	已有，需改订单状态机	✅
订单详情	`pages/shop/order-detail/order-detail.vue`	已有，增加物流信息	✅
物流跟踪	`pages/shop/logistics/logistics.vue`	物流轨迹展示	✅
地址管理	`pages/shop/address/address.vue`	收货地址CRUD	✅
我的订单入口	`pages/profile/profile.vue`	个人中心增加订单入口（已有）	✅
返利统计	`pages/shop/profit/profit.vue`	卖家返利数据面板	❌

Web管理端（cfc-web）新增/修改页面

页面	路径	功能	P0
商品管理	`src/views/admin/ProductManage.vue`	已有，需适配 DanShop 分类体系	✅
订单管理	`src/views/admin/OrderManage.vue`	已有，增加物流操作列	✅
分类管理	`src/views/admin/CategoryManage.vue`	新增：商品分类CRUD + 能量维度映射	✅
返利规则配置	`src/views/admin/ProfitRuleConfig.vue`	新增：返利规则配置页面	✅
提现审核	`src/views/admin/WithdrawAudit.vue`	已有，可复用	✅
商品利润率	`src/views/admin/ProductProfitRate.vue`	已有，可复用	✅
物流管理	`src/views/admin/LogisticsManage.vue`	新增：发货操作 + 物流跟踪	✅

前端 API 调整

现有 cfc-frontend/utils/api.js 中的 DANSHOP_BASE 配置需调整为指向 DanShop 模块的地址：

开发环境：http://localhost:9081（DanShop 独立端口）
体验版：https://dev.iwintrue.com/danshop
正式版：https://danshop.etotem.com.cn

同时将 /buyer/goods/category/get/{parentId} 和 /buyer/goods/list 等接口改造为符合 Spring Boot @PostMapping 约定的接口（项目规范）。

任务分解

Task 1: Maven 模块初始化

Files:

Create: dan/danshop/pom.xml
Create: dan/danshop/src/main/java/com/etotem/danshop/DanShopApplication.java
Create: dan/danshop/src/main/resources/application.yml
Modify: pom.xml（父POM添加 <module>dan/danshop</module>）

步骤：

创建 Maven 模块结构，pom.xml 依赖 cfc-backend 的 common 包（复用 Result、JwtUtil 等）
配置独立端口 9081，数据源指向 cfc 库
配置 MyBatis-Plus 扫描 com.etotem.danshop.mapper

Task 2: 商品分类实体、Mapper、Service（含能量维度关联）

Files:

Create: dan/danshop/src/main/java/com/etotem/danshop/entity/Category.java
Create: dan/danshop/src/main/java/com/etotem/danshop/mapper/CategoryMapper.java
Create: dan/danshop/src/main/java/com/etotem/danshop/dto/CategoryDTO.java
Create: dan/danshop/src/main/java/com/etotem/danshop/service/CategoryService.java
Create: dan/danshop/src/main/java/com/etotem/danshop/controller/admin/AdminCategoryController.java
Create: dan/danshop/src/main/java/com/etotem/danshop/controller/buyer/CategoryController.java
Modify: cfc-backend/.../DatabaseInitializer.java（添加 dan 相关表初始化）

Task 3: 商品实体、Mapper、Service（迁移现有 Product 到 DanShop）

Files:

Create: dan/danshop/src/main/java/com/etotem/danshop/entity/Product.java
Create: dan/danshop/src/main/java/com/etotem/danshop/mapper/ProductMapper.java
Create: dan/danshop/src/main/java/com/etotem/danshop/dto/ProductDTO.java
Create: dan/danshop/src/main/java/com/etotem/danshop/dto/ProductQueryDTO.java
Create: dan/danshop/src/main/java/com/etotem/danshop/service/ProductService.java
Create: dan/danshop/src/main/java/com/etotem/danshop/controller/buyer/ProductController.java
Create: dan/danshop/src/main/java/com/etotem/danshop/controller/seller/SellerProductController.java
Create: dan/danshop/src/main/java/com/etotem/danshop/controller/admin/AdminProductController.java

Task 4: 购物车（Redis + Service）

Files:

Create: dan/danshop/src/main/java/com/etotem/danshop/service/CartService.java
Create: dan/danshop/src/main/java/com/etotem/danshop/dto/CartItemDTO.java
Create: dan/danshop/src/main/java/com/etotem/danshop/controller/buyer/CartController.java
Create: dan/danshop/src/main/java/com/etotem/danshop/config/RedisConfig.java

Task 5: 订单系统（实体 + Service + 状态机）

Files:

Create: dan/danshop/src/main/java/com/etotem/danshop/entity/Order.java
Create: dan/danshop/src/main/java/com/etotem/danshop/entity/OrderItem.java
Create: dan/danshop/src/main/java/com/etotem/danshop/entity/OrderLog.java
Create: dan/danshop/src/main/java/com/etotem/danshop/mapper/OrderMapper.java
Create: dan/danshop/src/main/java/com/etotem/danshop/mapper/OrderItemMapper.java
Create: dan/danshop/src/main/java/com/etotem/danshop/mapper/OrderLogMapper.java
Create: dan/danshop/src/main/java/com/etotem/danshop/dto/CreateOrderDTO.java
Create: dan/danshop/src/main/java/com/etotem/danshop/dto/OrderDTO.java
Create: dan/danshop/src/main/java/com/etotem/danshop/service/OrderService.java
Create: dan/danshop/src/main/java/com/etotem/danshop/controller/buyer/OrderController.java
Create: dan/danshop/src/main/java/com/etotem/danshop/controller/seller/SellerOrderController.java
Create: dan/danshop/src/main/java/com/etotem/danshop/controller/admin/AdminOrderController.java

Task 6: 微信支付集成

Files:

Create: dan/danshop/src/main/java/com/etotem/danshop/config/WechatPayConfig.java
Create: dan/danshop/src/main/java/com/etotem/danshop/service/PaymentService.java
Create: dan/danshop/src/main/java/com/etotem/danshop/service/WechatPayService.java
Create: dan/danshop/src/main/java/com/etotem/danshop/controller/PaymentController.java

Task 7: 物流跟踪

Files:

Create: dan/danshop/src/main/java/com/etotem/danshop/entity/Logistics.java
Create: dan/danshop/src/main/java/com/etotem/danshop/mapper/LogisticsMapper.java
Create: dan/danshop/src/main/java/com/etotem/danshop/service/LogisticsService.java
Create: dan/danshop/src/main/java/com/etotem/danshop/controller/LogisticsController.java

Task 8: 返利规则 + 结算系统

Files:

Create: dan/danshop/src/main/java/com/etotem/danshop/entity/ProfitRule.java
Create: dan/danshop/src/main/java/com/etotem/danshop/entity/ProfitLog.java
Create: dan/danshop/src/main/java/com/etotem/danshop/mapper/ProfitRuleMapper.java
Create: dan/danshop/src/main/java/com/etotem/danshop/mapper/ProfitLogMapper.java
Create: dan/danshop/src/main/java/com/etotem/danshop/service/ProfitSettlementService.java
Create: dan/danshop/src/main/java/com/etotem/danshop/controller/admin/ProfitRuleController.java
Create: dan/danshop/src/main/java/com/etotem/danshop/controller/seller/SellerProfitController.java

Task 9: Feign 跨调用接口（cfc-backend 侧）

Files:

Create: cfc-backend/src/main/java/com/etotem/cfc/controller/InternalCommissionController.java
Create: cfc-backend/src/main/java/com/etotem/cfc/controller/InternalEnergyController.java
Create: cfc-backend/src/main/java/com/etotem/cfc/dto/CommissionSettleRequest.java
Create: cfc-backend/src/main/java/com/etotem/cfc/dto/EnergyAwardRequest.java

Task 10: 前端小程序新页面

Files:

Create: cfc-frontend/pages/shop/detail.vue
Create: cfc-frontend/pages/shop/cart/cart.vue
Create: cfc-frontend/pages/shop/checkout/checkout.vue
Create: cfc-frontend/pages/shop/payment/payment.vue
Create: cfc-frontend/pages/shop/logistics/logistics.vue
Create: cfc-frontend/pages/shop/address/address.vue
Modify: cfc-frontend/pages/shop/index.vue（改造对接 DanShop API）
Modify: cfc-frontend/pages/shop/order-list/order-list.vue（适配新订单状态）
Modify: cfc-frontend/pages/shop/order-detail/order-detail.vue（增加物流追踪入口）
Modify: cfc-frontend/pages.json（注册新页面）
Modify: cfc-frontend/utils/api.js（添加 DanShop API封装）

Task 11: Web管理端新页面

Files:

Create: cfc-web/src/views/admin/CategoryManage.vue
Create: cfc-web/src/views/admin/ProfitRuleConfig.vue
Create: cfc-web/src/views/admin/LogisticsManage.vue
Modify: cfc-web/src/views/admin/ProductManage.vue（适配 DanShop 分类）
Modify: cfc-web/src/views/admin/OrderManage.vue（增加物流操作/发货功能）
Modify: cfc-web/src/router/index.js（注册新路由）
Modify: cfc-web/src/api/index.js（添加 DanShop API封装）

Task 12: 数据库初始化 + 种子数据

Files:

Modify: cfc-backend/src/main/java/com/etotem/cfc/config/DatabaseInitializer.java（添加 danshop 表创建）
Create: dan/danshop/src/main/resources/schema.sql（建表语句）
Create: dan/danshop/src/main/resources/seed.sql（默认分类、返利规则）

数据库表总览

表名	所属模块	说明
`danshop_categories`	DanShop	商品分类（树形多级）
`danshop_products`	DanShop	商品（替代现有products表）
`danshop_orders`	DanShop	主订单
`danshop_order_items`	DanShop	订单明细
`danshop_order_logs`	DanShop	订单操作日志
`danshop_logistics`	DanShop	物流信息
`danshop_profit_rules`	DanShop	返利规则配置
`danshop_profit_logs`	DanShop	返利流水
`commission_records`	cfc-backend	佣金记录（复用现有）
`withdrawal_requests`	cfc-backend	提现申请（复用现有）
`energy_dimension`	cfc-backend	五维维度（共享只读）
`energy_source_config`	cfc-backend	能量来源配置（共享只读）
`users`	cfc-backend	用户（共享只读）

安全与权限

角色	DanShop 权限
`buyer` (任意登录用户)	浏览商品、加购物车、下单、查看订单、收货
`seller` (vendorStatus=approved)	管理自家商品、查看/处理订单、发货、查看返利
`admin` (role=admin)	分类管理、审核商品、管理订单、配置返利规则、审核提现
未登录	浏览商品分类和列表

鉴权方式与 cfc-backend 一致：JWT Bearer Token，通过 @RequestAttribute("userId") 获取当前用户。

与现有系统的关键集成点

用户认证：DanShop 使用相同的 JWT Token 认证机制，共享 cfc-backend 的 JwtUtil
推荐佣金：DanShop 订单完成时，通过 Feign 调用 cfc-backend 的 CommissionService
能量发放：DanShop 订单完成时，通过分类→维度映射，调用 EnergyService 发放能量
用户家庭：DanShop 读取用户的 familyId，将订单归属于家庭
供应商系统：复用现有的 vendorType/vendorStatus 字段，服务商审核流程不变
提现系统：复用现有的 withdrawal_requests 表和审核流程

2026-06-12-danshop-integration-design.md 39 KB Bezpośredni odnośnik Historia Czysty

DanShop 电商模块集成设计方案

总体架构

模块位置

跨域通信

数据库隔离策略

模块一：商品分类与五维能量映射（P0）

数据模型

分类与五维维度关联逻辑

能量发放规则

模块二：购物车（P0）

数据模型（Redis 实现）

购物车 API

购物车校验

模块三：订单系统（P0）

订单状态机

数据模型

下单流程

订单号生成规则

模块四：支付集成（P0）

支付流程

PaymentService 改造

支付配置

模块五：物流跟踪（P0）

数据模型

物流跟踪实现

模块六：利润留存与返利系统（P0）

返利模型

返利配置表

返利计算流程

返利流水表

与现有 CommissionService 的集成

Feign 接口定义

模块七：前端页面规划

小程序端（cfc-frontend）新增/修改页面

Web管理端（cfc-web）新增/修改页面

前端 API 调整

任务分解

Task 1: Maven 模块初始化

Task 2: 商品分类实体、Mapper、Service（含能量维度关联）

Task 3: 商品实体、Mapper、Service（迁移现有 Product 到 DanShop）

Task 4: 购物车（Redis + Service）

Task 5: 订单系统（实体 + Service + 状态机）

Task 6: 微信支付集成

Task 7: 物流跟踪

Task 8: 返利规则 + 结算系统

Task 9: Feign 跨调用接口（cfc-backend 侧）

Task 10: 前端小程序新页面

Task 11: Web管理端新页面

Task 12: 数据库初始化 + 种子数据

数据库表总览

安全与权限

与现有系统的关键集成点

2026-06-12-danshop-integration-design.md 39 KB

Bezpośredni odnośnik Historia Czysty