# 维度参数获取与筛选设计分析

## 概述

四个核心实体（活动、商品、文章、任务）都有"五维归属"的概念，但存储和查询方式各不相同。当前设计目标是：**根据维度筛选时，只要该实体在对应维度的权重 > 0 就命中**。

## 实体维度字段对比

| 实体 | 表名 | 旧字段 | 新字段 | 维度筛选方式 |
|------|------|--------|--------|-------------|
| **Activity** | activities | `dimension_code` (单值) | `dimension_weights` (JSON) | `JSON_EXTRACT(dimension_weights, '$.{dim}') > 0` OR `dimension_code = {dim}` |
| **Product** | products | `domain` (单值) | `dimension_weights` (JSON) | `JSON_EXTRACT(dimension_weights, '$.{dim}') > 0` OR `domain = {dim}` |
| **Article** | articles | `related_dimensions` (逗号分隔) | `dimension_weights` (JSON) | `JSON_EXTRACT(dimension_weights, '$.{dim}') > 0` OR `related_dimensions LIKE %{dim}%` |
| **Task** | tasks | 无 | 无 | ❌ 不支持维度筛选 |

## 逐项分析

### 1. Activity（活动）✅ 已实现

**实体字段：**
```java
private String dimensionCode;        // 旧: 单值, 如 "body"
private String dimensionWeights;     // 新: JSON, 如 {"body":30,"mind":0,"wisdom":0,"action":70,"wealth":0}
```

**筛选逻辑（ActivityService.list() 第53-63行）：**
```java
if (dimensionCode != null && !dimensionCode.isEmpty()) {
    query.and(w -> w
        .apply("COALESCE(JSON_EXTRACT(dimension_weights, '$." + dimensionCode + "'), 0) > 0")
        .or().eq(Activity::getDimensionCode, dimensionCode)
    );
}
```

**状态：** ✅ 已实现权重感知筛选，兼容旧版 `dimensionCode`

### 2. Product（商品）✅ 已实现

**实体字段：**
```java
private String domain;               // 旧: 单值, 如 "body"
private String dimensionWeights;     // 新: JSON, 如 {"body":30,"mind":0,"wisdom":0,"action":70,"wealth":0}
```

**筛选逻辑（ProductService.list() 第56-62行）：**
```java
if (query.getDomain() != null && !query.getDomain().isEmpty()) {
    String domain = query.getDomain();
    wrapper.and(w -> w
        .apply("COALESCE(JSON_EXTRACT(dimension_weights, '$." + domain + "'), 0) > 0")
        .or().eq(Product::getDomain, domain)
    );
}
```

**注意：** 查询参数名为 `domain`（ProductListQueryDTO 中定义），前端传的是 `dimensionCode` 还是 `domain` 需要确认对齐。

**状态：** ✅ 已实现权重感知筛选，兼容旧版 `domain`

### 3. Article（文章）✅ 已实现

**实体字段：**
```java
private String relatedDimensions;    // 旧: 逗号分隔, 如 "body,mind"
private String dimensionIds;         // 维度ID列表JSON
private String dimensionWeights;     // 新: JSON, 如 {"body":30,"mind":0,...}
```

**筛选逻辑（ArticleService.getPublicList() 第93-98行）：**
```java
if (dimensionCode != null && !dimensionCode.trim().isEmpty()) {
    wrapper.and(w -> w
        .apply("COALESCE(JSON_EXTRACT(dimension_weights, '$." + dimensionCode.trim() + "'), 0) > 0")
        .or().like(Article::getRelatedDimensions, dimensionCode.trim())
    );
}
```

**自动生成权重的逻辑（ArticleService 第702-706行）：**
当管理员设置 `relatedDimensions` 时，自动调用 `buildEqualWeights()` 生成等比例权重：
```java
private String buildEqualWeights(String relatedDimensions) {
    String[] parts = relatedDimensions.split(",");
    int equalWeight = 100 / parts.length;
    // 为每个维度分配 equalWeight
}
```

**状态：** ✅ 已实现权重感知筛选，兼容旧版 `relatedDimensions`

### 4. Task（任务）❌ 不支持维度筛选

**实体字段：** 无维度相关字段

Task 实体没有 `dimensionCode`、`domain`、`dimensionWeights` 等任何维度字段。任务通过 `category` 字段分类（如"学习类""行动类"），但分类与五维维度没有直接映射关系。

**状态：** ❌ 不支持维度筛选

## 架构设计

### JSON 权重格式

所有实体统一使用 JSON 格式存储五维权重：
```json
{
  "body": 0,
  "mind": 30,
  "wisdom": 20,
  "action": 50,
  "wealth": 0
}
```

- 权重值范围：0-100（整数）
- 0 = 不关联该维度
- > 0 = 关联该维度，值越大关联度越高
- 所有权重之和不一定等于 100（可以只设置部分维度）

### 筛选原理

使用 MySQL 的 `JSON_EXTRACT` 函数：
```sql
COALESCE(JSON_EXTRACT(dimension_weights, '$.body'), 0) > 0
```

- 如果 `dimension_weights` 为 NULL 或 JSON 中不含该 key，返回 0
- 如果权重 > 0，表示该实体关联此维度，命中筛选

### 兼容旧数据

三种实体都保留了旧字段的兼容查询：
- Activity: `dimension_code` 精确匹配
- Product: `domain` 精确匹配
- Article: `related_dimensions` LIKE 模糊匹配

## 前端调用方式

| 实体 | 列表接口 | 维度参数名 | 示例 |
|------|---------|-----------|------|
| 活动 | `POST /api/activity/list` | `dimensionCode` | `{"dimensionCode":"body"}` |
| 商品 | `POST /api/product/list` | `domain` | `{"domain":"body"}` |
| 文章 | `POST /api/articles/list` | `dimensionCode` | `{"dimensionCode":"body"}` |
| 任务 | `POST /api/tasks/today` | 不支持 | — |

## 建议

### 统一参数名
商品列表使用 `domain` 而非 `dimensionCode`，与其他三个不统一。建议在 `ProductListQueryDTO` 中增加 `dimensionCode` 别名，内部映射到 `domain`。

### Task 增加维度支持
如果任务需要按维度筛选，有两种方案：
1. **轻量方案**：在 Task 实体增加 `dimensionCode` 字段（单值），通过 `category` → `dimensionCode` 映射表自动填充
2. **完整方案**：增加 `dimensionWeights` JSON 字段，与活动/商品/文章保持一致

### 创建/编辑时的维度设置
| 实体 | 创建接口 | 维度参数 | 说明 |
|------|---------|---------|------|
| 活动 | `POST /api/admin/activity/create` | `dimensionCode` + `dimensionWeights` | 管理后台设置 |
| 商品 | `POST /api/product/create` | `domain` + `dimensionWeights` | 管理后台设置 |
| 文章 | `POST /api/admin/articles/create` | `relatedDimensions` | 自动生成 `dimensionWeights` |
| 任务 | `POST /api/tasks/create` | 不支持 | 通过 category 间接关联 |