# 收益归属矩阵（业务报表模式）

> **适用场景**: 需要按人×项目维度展示收益归属矩阵
> **创建日期**: 2026-06-24

---

## 业务含义

行 = 人员，列 = 项目，交叉单元格 = 该人在该项目的收益贡献。类似 Excel 透视表。

```
        项目A    项目B    项目C    小计
郑明义  ¥14,983  ¥4,142  ¥1,839  ¥20,964
薛文    ¥11,600  ¥884   ¥3,678  ¥16,162
总计    ¥82,031  ¥7,070  ¥9,196  ¥98,297
```

---

## 计算逻辑

### 数据源

- `project_monthly_income` — 项目月度总收益（按项目×月份）
- `personnel_projects` — 人员-项目关联（含 `allocation_ratio` 分配比例）

### 核心公式

```
个人在项目的收益 = 项目总收益 × (该人的分配比例 / 100)
```

### 特殊情况

| 情况 | 处理方式 |
|------|---------|
| 人员有关联比例 | 按比例分摊项目总收益 |
| 人员无关联比例 | 收益为 0（不显示在矩阵中） |
| 项目无收益记录 | 收益为 0（不显示在矩阵中） |
| 月份筛选 | 只计算该月的收益记录 |

### API 设计

```
GET /api/reports/income-matrix?month=2026-06

Response:
{
  "rows": [
    {
      "name": "郑明义",
      "group_name": "四组",
      "projects": {"南方医科大学珠江医院": 9666.67, "苏州市立医院": 1325.58},
      "subtotal": 12831.38
    }
  ],
  "project_totals": {"南方医科大学珠江医院": 82031.34, ...},
  "grand_total": 442598.68,
  "month": null
}
```

---

## 前端实现要点

### 动态列

项目列是动态的（随数据变化），需要用 `v-for` 在 `<el-table-column>` 上渲染：

```vue
<el-table-column v-for="proj in projectNames" :key="proj" :label="proj" min-width="140" align="right">
  <template #default="{ row }">
    {{ row.projects[proj] > 0 ? '¥' + row.projects[proj].toLocaleString() : '—' }}
  </template>
</el-table-column>
```

### 总计行

用 `<el-descriptions>` 展示项目总计，放在表格下方：

```vue
<el-descriptions :column="4" border size="small">
  <el-descriptions-item label="总计">
    ¥{{ grandTotal.toLocaleString() }}
  </el-descriptions-item>
  <el-descriptions-item v-for="(val, key) in projectTotals" :key="key" :label="key">
    ¥{{ val.toLocaleString() }}
  </el-descriptions-item>
</el-descriptions>
```

### 月份筛选

提供月份下拉框，不传参时汇总所有月份。筛选在 API 层完成，前端只传参数。

---

## 常见问题

### Q: 为什么矩阵中的项目总收益不等于项目列表中的预期收益？

A: 矩阵中的收益来自 `project_monthly_income`（实际实现的月度收益），不等于项目的预期收益（合同金额）。两者是不同概念。

### Q: 为什么某些人没有出现在矩阵中？

A: 只有 `subtotal > 0` 的行才会显示。如果人员有关联项目但项目没有收益记录，该人员不会出现。

### Q: 分配比例从哪里来？

A: 从 `personnel_projects.allocation_ratio` 字段读取。初始导入时从 Excel 工作描述中的"占比 N%"正则提取，无比例时按项目关联人数均分。