# 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）

### 数据模型

```sql
-- 商品分类表（支持多级树形结构）
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)
```

```json
{
    "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
```

### 数据模型

```sql
-- 主订单表
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 中实现完整的微信支付集成：

```java
// 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
    }
}
```

### 支付配置

```yaml
# 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）

### 数据模型

```sql
-- 物流信息表
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分钟更新一次运输中订单的轨迹
- 自动签收检测：轨迹显示"已签收"时更新订单状态

```java
// 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
     (实际入账)
```

### 返利配置表

```sql
-- 返利规则配置表
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（全局默认）
```

### 返利流水表

```sql
-- 返利流水表
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 的返利系统将：

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

### Feign 接口定义

```java
// 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>`）

**步骤：**
1. 创建 Maven 模块结构，`pom.xml` 依赖 `cfc-backend` 的 `common` 包（复用 Result、JwtUtil 等）
2. 配置独立端口 9081，数据源指向 cfc 库
3. 配置 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")` 获取当前用户。

---

## 与现有系统的关键集成点

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