# 营销管理 - 销售计划（销售目标）前端联调方案

## 涉及页面

- 营销管理 → 销售计划（菜单 1065000，组件 `crm/salesTarget/index`）
- 营销管理 → 达成分析（菜单 1065100，组件 `crm/salesTarget/analysis/index`）

## 业务流程与数据带入

1. **设定目标**：管理员在「销售计划」页按周期（年/季/月）+ 维度（个人/部门/产品）设定销售目标。目标对象（用户/部门/物料）从系统下拉选择，目标指标（合同金额、回款金额、商机金额、新增客户数、新增合同数）手工录入。
2. **周期自动换算**：前端只提交 `periodType`（1年/2季度/3月）与 `periodValue`（如 `2026`、`2026-Q1`、`2026-07`），后台自动换算周期起止时间并落库；列表/详情展示换算后的起止时间。
3. **状态自动判定**：后台保存时按当前时间与周期自动判定状态（未生效/已生效/已结束），前端展示即可；仅「作废/恢复」由用户手动触发。
4. **达成统计自动带入**：列表、详情、达成分析均返回实际达成（合同金额、回款金额、商机金额、新增客户数、新增合同数）与达成率，前端直接展示，无需另行调用统计接口。
5. **达成分析**：用户在「达成分析」页选择周期（必选）+ 维度（可选）+ 状态（可选），后台按周期过滤返回目标列表（含实际达成与达成率）。

## API

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/crm/sales-target/create` | 创建销售目标 |
| PUT | `/crm/sales-target/update` | 更新销售目标 |
| PUT | `/crm/sales-target/change-status` | 变更目标状态（作废/恢复/生效） |
| DELETE | `/crm/sales-target/delete?id=` | 删除销售目标 |
| GET | `/crm/sales-target/get?id=` | 目标详情（含实际达成+达成率） |
| GET | `/crm/sales-target/page` | 目标分页（含实际达成+达成率） |
| GET | `/crm/sales-target/export-excel` | 导出 Excel |
| GET | `/crm/sales-target/get-achievement-analysis` | 达成分析 |

### 创建/更新请求参数（CrmSalesTargetSaveReqVO）

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | Long | 更新时必填 | 目标编号 |
| name | String | 是 | 目标名称 |
| periodType | Integer | 是 | 周期类型（字典 crm_sales_target_period_type：1年/2季度/3月） |
| periodValue | String | 是 | 周期值，如 `2026` / `2026-Q1` / `2026-07` |
| targetDimension | Integer | 是 | 目标维度（字典 crm_sales_target_dimension：1个人/2部门/3产品） |
| targetUserId | Long | 维度=个人时必填 | 目标用户编号 |
| targetDeptId | Long | 维度=部门时必填 | 目标部门编号 |
| targetItemId | Long | 维度=产品时必填 | 目标物料编号（关联 MDM） |
| contractTarget | BigDecimal | 否 | 合同金额目标（元） |
| receivableTarget | BigDecimal | 否 | 回款金额目标（元） |
| businessTarget | BigDecimal | 否 | 商机金额目标（元） |
| customerTarget | Integer | 否 | 新增客户数目标 |
| contractCountTarget | Integer | 否 | 新增合同数目标 |
| remark | String | 否 | 备注 |

### 状态变更请求参数（CrmSalesTargetChangeStatusReqVO）

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| id | Long | 是 | 目标编号 |
| status | Integer | 是 | 目标状态（字典 crm_sales_target_status：0未生效/1已生效/2已结束/3已作废） |

### 达成分析请求参数（CrmSalesTargetAnalysisReqVO）

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| periodType | Integer | 是 | 周期类型 |
| periodValue | String | 是 | 周期值 |
| targetDimension | Integer | 否 | 目标维度，为空查全部 |
| status | Integer | 否 | 状态，为空查全部 |

### 响应字段（CrmSalesTargetRespVO）

目标基础字段（name/periodType/periodValue/startTime/endTime/targetDimension/status/remark/createTime/creator）之上，新增以下字段：

| 字段 | 类型 | 说明 |
|------|------|------|
| targetUserName | String | 目标对象名称（维度=个人时为昵称） |
| targetDeptName | String | 目标部门名称（维度=部门） |
| targetItemName | String | 目标物料名称（维度=产品） |
| actualContractPrice | BigDecimal | 实际合同金额（元） |
| actualReceivablePrice | BigDecimal | 实际回款金额（元） |
| actualBusinessPrice | BigDecimal | 实际商机金额（元） |
| actualCustomerCount | Long | 实际新增客户数 |
| actualContractCount | Long | 实际新增合同数 |
| contractRate | BigDecimal | 合同金额达成率（%） |
| receivableRate | BigDecimal | 回款金额达成率（%） |
| businessRate | BigDecimal | 商机金额达成率（%） |
| customerRate | BigDecimal | 新增客户数达成率（%） |
| contractCountRate | BigDecimal | 新增合同数达成率（%） |
| creatorName | String | 创建人名称 |

**响应示例：**

```json
{
  "code": 0,
  "data": {
    "id": 1,
    "name": "2026年度销售目标-张三",
    "periodType": 1,
    "periodValue": "2026",
    "startTime": "2026-01-01 00:00:00",
    "endTime": "2027-01-01 00:00:00",
    "targetDimension": 1,
    "targetUserId": 1,
    "targetUserName": "张三",
    "contractTarget": 500000.00,
    "actualContractPrice": 32377.00,
    "contractRate": 6.48,
    "status": 1
  }
}
```

## 字段展示规则

| 字段 | 展示位置 | 说明 |
|------|----------|------|
| 目标名称 | 列表、详情 | 主标题 |
| 周期 | 列表、详情 | 周期类型字典转文本 + 周期值，如「年度 2026」 |
| 目标对象 | 列表、详情 | 按维度展示目标用户/部门/物料名称（targetUserName/targetDeptName/targetItemName） |
| 目标指标 | 列表、详情、分析 | 合同金额/回款金额/商机金额/新增客户数/新增合同数目标 |
| 实际达成 | 列表、详情、分析 | 与目标指标一一对应的实际值 |
| 达成率 | 列表、详情、分析 | 百分比，保留两位小数；目标为 0 或空时达成率为空（展示为 `-`） |
| 状态 | 列表、详情 | 字典转文本，已作废需置灰/禁止编辑 |
| 创建人 | 列表、详情 | 创建人昵称 |

## 业务规则说明

| 场景 | 规则 |
|------|------|
| 达成率计算 | 实际值 ÷ 目标值 × 100，保留 2 位小数；目标为空或 ≤0 时达成率返回 null |
| 周期换算 | 前端无需计算起止时间，后台按 periodValue 换算；年 `2026`、季 `2026-Q1`、月 `2026-07` |
| 状态判定 | 后台按当前时间自动判定 未生效/已生效/已结束；前端新增编辑时无需手动选状态 |
| 作废/恢复 | 已作废的目标被编辑后仍保持作废状态，需先「恢复」再编辑生效 |
| 统计口径 | 合同金额/数量只统计审核通过（audit_status=20）的合同；回款只统计审核通过的回款；商机只统计赢单（end_status=1）；客户按创建时间统计 |
| 产品维度 | 仅统计合同金额与合同数，回款/商机/客户数为 0 |
| 部门维度 | 含子部门下所有用户的数据 |
| 数据权限 | 目标为管理配置，不接入 CRM 数据权限，列表展示全部（可按需按创建人过滤） |

## 注意事项

- 达成率字段可能为 null，前端展示需兜底为 `-`，避免显示 0。
- 周期值格式严格：年 `YYYY`、季 `YYYY-Q1`~`YYYY-Q4`、月 `YYYY-MM`，前端表单校验需按此约束。
- 目标维度与目标对象互斥：维度=个人填 userId，部门填 deptId，产品填 itemId，其余留空；前端按维度切换表单项。
- 达成分析接口的 periodType + periodValue 为必填，未选周期时不应发起请求。
- 达成统计查询为逐条目标计算（约 5 条小 SQL），目标数量级几十~几百时性能可接受；若后续目标量级增大需改造为聚合统计，需提前知会后端。
- 「销售计划」页排序建议按创建时间倒序，与后台返回顺序一致（按 id 倒序）。