# 02 — 客户联系人级联接口 stub

**What to build:** 前端在商机新增/编辑页（字段17）及"添加关联客户"弹窗中，选中关联客户后"客户联系人"下拉会按已选客户级联刷新。当前该接口无实现，前端打请求 404、级联联动无契约可对。本票在商机侧补一个降级 stub 端点（对齐现有快照池降级套路，如 `GET /api/opportunity/customer/{customerId}/contacts`），返回空列表或固定 mock，让前端级联逻辑能对上出参契约、不 404。真实联系人数据待 A4 客户模块建成后补真源，本票不建快照子表、不接真数据。

**Blocked by:** None — can start immediately

**Status:** resolved

- [ ] 商机侧新增按客户查联系人的 stub 端点，路径风格对齐 `OpportunitySubController` 现有客户 Tab 端点
- [ ] 出参契约字段齐备（至少 contactId / name / phone / company / position），返回空列表或固定 mock
- [ ] 端点在 Swagger 分组下可见，前端可自描述联调
- [ ] 代码注释标注"降级 stub，A4 就位后切真源"，与快照池现状口径一致
- [ ] 空客户 / 不存在客户 id 时返回空列表而非报错

## Answer

新增 `CustomerContactDTO`（contactId/name/phone/company/position）+ 服务方法 `listCustomerContacts(customerId)`（impl 返回空 ArrayList，注释标注降级 stub、A4 切真源、签名不变）+ 控制器端点 `GET /api/opportunity/customer/{customerId}/contacts`（Swagger「A3 商机管理/商机详情/客户」分组可见）。空/不存在 customerId 返回空列表不报错。crm-opportunity 编译通过（BUILD SUCCESS）。

## 路由更正（20260901）

初版误用 REST 路径参数 `GET /customer/{customerId}/contacts`，违反本 Controller 既定规范（类注释白纸黑字：「GET 查询，id 走 @RequestParam」，全域客户/跟进/勘察/团队端点一致）。已改为 **`GET /api/opportunity/customer/contacts?customerId=`**（`@RequestParam`），对齐 `/customer/list?oppId=` 风格。重编译 + 重打 jar + 回归全绿（新路由 200/空数组/边界不报错），demo 与 verify-03.py 调用同步改址。