# 商机模块 · 原型 → 预期接口 总清单

> 来源：`.scratch/opportunity-verify/lanhu-cache/scope-to-txt.json` 里 37 页原型的 `.txt` 抽取（+ 必要时 OCR fallback）。
>
> 本文件只做**原型 → 预期接口**推断，**不映射到后端已有 Controller、不判断实现正确性**——那是票 03/04/05 的活。
>
> **约定**：
> - path 使用 **REST 惯例路径**（可能与后端实际不一致，实测时对齐）
> - 每条接口末尾用 `[子域]` 标注：`列表` / `详情` / `状态机` / `阶段` / `方案卡` / `勘察` / `跟进` / `附件` / `团队` / `日志` / `视图` / `规则-阶段` / `规则-方案卡` / `规则-公海` / `规则-字典` / `字典查询` / `协作`

---

## 子域：列表族（A3-0/1/2/3 列表 + 视图）

### 页面：A3-0-1 最近访问列表 （txt: `a3-0-1_最近访问列表.txt`）

- **顶层元素**：
  - 顶部系统栏（AI助手 / 消息提醒 / 当前用户）
  - 左侧一级/二级菜单（商机管理 > 销售机会）
  - 面包屑（商机 > 销售机会）
  - 标题栏 + 视图入口下拉「最近访问 ▾」（可切到我负责的 / 我关注的 / 公海 / 自定义保存过的筛选方案）
  - 视图切换（列表 / 分屏 / 看板）
  - 查询筛选区（项目名称、甲方、地区、来源、行业……）
  - 「查询」「重置」按钮
  - 批量操作：批量关注、批量领取
  - 列表操作区：行高调整、刷新、自定义显示字段
  - 列表表格 + 分页

- **表格列**（14 列，字段定义见 txt）：NO / 选择框 / 商机名称 / 甲方 / 意向客户 / 行业 / 地区 / 预计金额 / 当前工作节点 / 节点停留时间 / 当前负责人 / 最近跟进 / 下一节点 / 操作

- **行操作**（依商机状态动态展示）：详情 / 写跟进 / 关注 / 取关 / 领取 / 转项目

- **业务规则**：
  - 仅展示当前用户「近期打开过详情页」的销售机会；默认按最近访问时间倒序
  - 节点停留时间由后端算并返回（= 当前日期 − 进入当前工作节点日期）
  - 未领取时「当前负责人」显示 `--` 或「待领取」
  - 未勾选批量操作时前端拦提示（无需后端）

- **预期接口**：
  - `POST /api/opportunity/recent-visits/page` — 最近访问分页；入参含 `keyword`, `filters{industry, region, source, party}`, `page`, `size`, `sort`；出参列 14 字段全  `[列表]`
  - `POST /api/opportunity/recent-visits/touch` **或** `POST /api/opportunity/{id}/visit` — 用户打开详情时上报访问记录（前端进详情自动打）  `[列表]`
  - `GET /api/dict/industry` — 行业下拉候选  `[字典查询]`
  - `GET /api/dict/region` **或** `GET /api/region/tree` — 地区下拉  `[字典查询]`
  - `GET /api/dict/source` — 来源下拉  `[字典查询]`
  - `GET /api/user/customize/columns?scene=opportunity-list` **或** `POST .../save` — 自定义显示字段读/写  `[视图]`
  - `POST /api/opportunity/follow/batch` — 批量关注；body `{opportunityIds: [...]}`  `[协作]`
  - `POST /api/opportunity/claim/batch` — 批量领取；body `{opportunityIds: [...]}`；返回失败明细  `[状态机]`
  - `POST /api/opportunity/follow` — 单个关注（行操作「关注」）；`{opportunityId}`  `[协作]`
  - `DELETE /api/opportunity/follow/{opportunityId}` **或** `POST /api/opportunity/unfollow` — 取关  `[协作]`
  - `POST /api/opportunity/claim` — 单个领取（行操作「领取」）；`{opportunityId}`  `[状态机]`
  - （「写跟进」跳弹窗，接口归 A3-1-1-2-2 页；「详情」跳详情，无独立接口）

- **备注**：
  - 「自定义保存过的筛选方案」暗示有**保存视图 CRUD**，实际这页只展示切换入口，视图 CRUD 归下一页 A3-1-1 承载；此处仅登记读接口需求。

### 页面：A3-1-1 销售机会列表 （txt: `a3-1-1_销售机会列表.txt`）

一页承载三个视图（“结构完全一致的页面”）：我负责的 / 我参与的 / 全部销售机会（个人）。

- **顶层元素**：
  - 视图下拉切换（与 A3-0-1 共用）
  - 查询筛选区（商机名、甲方、地区、行业……）
  - 「+新增商机」按钮
  - 列表工具区（刷新 / 密度 / 自定义字段）
  - 表格 13 列（相对最近访问**新增「方案卡状态」**，**隐藏「当前负责人」**）
  - 行操作：详情 / 写跟进

- **业务规则**：
  - 数据范围 = 当前用户为负责人（或团队成员 / 无限制，看视图）
  - 新增商机默认归当前用户（若无分配规则干预）
  - 方案卡状态：未创建 / 填写中 / 已推送
  - 分页切换保留筛选条件

- **预期接口**：
  - `POST /api/opportunity/page` — 主列表分页；入参 `viewType: OWNED|PARTICIPATED|ALL_PERSONAL`, `keyword`, `filters{...}`, `page`, `size`, `sort`；若后端缺 `viewType` 语义入报告  `[列表]`
  - `POST /api/opportunity` — 新增商机（body 定义见 A3-1-1-2-1）  `[详情]`
  - `GET /api/dict/industry`, `/region`, `/party-type` — 筛选下拉  `[字典查询]`
  - `GET /api/user/customize/columns?scene=opportunity-list` — 自定义字段读  `[视图]`
  - `POST /api/user/customize/columns` — 自定义字段写  `[视图]`

- **备注**：「写跟进」弹窗接口归 A3-1-1-2-2；「详情」跳 A3-1-1-1-1。

### 页面：A3-2-1 全部销售机会管理列表 （txt: `a3-2-1_全部销售机会管理列表.txt`）

**管理视角**（领导/管理员权限），支持三种视图：传统列表 / 看板 / 分屏。

- **顶层元素**：
  - 筛选区（行业、地区等，无新增按钮）
  - 列表视图列（与 A3-1-1 相同 13 列）+ 行操作：**详情 / 分配 / 督办 / 关闭**（督办 out-of-scope）
  - 批量操作：**批量关闭 / 批量催办 / 批量分配**
  - 看板视图：每阶段显示商机数+金额汇总，首批 5 条，「加载更多」按需追加
  - 分屏视图：左侧列表+右侧详情
  - 统计卡片：团队商机总数 / 各阶段分布

- **业务规则**：
  - 数据范围 = 当前用户权限范围内所有商机（非仅本人）
  - 看板各阶段独立分页加载（offset+limit 而非全局 page）
  - 筛选/切换视图后各阶段重置为首批

- **预期接口**：
  - `POST /api/opportunity/page` — 管理列表分页；入参 `viewType: MANAGED`, `filters{assignee,industry,region,stage}`, `page`, `size`  `[列表]`
  - `POST /api/opportunity/board/stage-summary` — 看板各阶段数量+金额汇总  `[列表]`
  - `POST /api/opportunity/board/cards` — 看板单阶段卡片列表（按需加载）；入参 `stageId`, `offset`, `limit`, `filters`  `[列表]`
  - `POST /api/opportunity/assign` — 单个分配负责人  `[状态机]`
  - `POST /api/opportunity/assign/batch` — 批量分配  `[状态机]`
  - `POST /api/opportunity/close/batch` — 批量关闭  `[状态机]`
  - `GET /api/user/assignable` — 分配时选人候选  `[字典查询]`

- **备注**：督办（催办）接口 out-of-scope，不实测。看板视图 txt 明确描述"各阶段独立加载"，需要按阶段查询接口。

### 页面：A3-3-1 商机公海列表 （txt: `a3-3-1_商机公海列表.txt`）

**公海视图**，展示已进入公海的商机，所有人可见可领取。

- **顶层元素**：
  - 筛选区：**进入公海原因**（销售主动释放 / 特殊原因暂停 / 领导释放 / 超期回收）、行业、地区
  - 批量操作：**批量领取 / 批量关注**
  - 表格 12 列：NO / 商机名称 / 甲方 / 意向客户 / 行业 / 地区 / 方案预算 / **入池前工作节点** / 节点停留时间 / **当前负责人**（原负责人）/ 最近跟进 / **进入公海原因** / 操作
  - 行操作：**详情 / 关注 / 领取**

- **业务规则**：
  - 进入公海原因枚举：销售主动释放 / 特殊原因暂停 / 领导释放 / 超期回收
  - 领取后商机退出公海，归属领取人

- **预期接口**：
  - `POST /api/opportunity/pool/page` 或 `POST /api/opportunity/page` 含 `viewType: POOL` — 公海列表分页；入参含 `entryReason`, `industry`, `region`, `page`, `size`  `[列表]`
  - `GET /api/dict/pool-entry-reason` — 进入公海原因枚举  `[字典查询]`
  - `POST /api/opportunity/claim` — 单个领取  `[状态机]`
  - `POST /api/opportunity/claim/batch` — 批量领取  `[状态机]`
  - `POST /api/opportunity/follow` — 单个关注  `[协作]`
  - `POST /api/opportunity/follow/batch` — 批量关注  `[协作]`

## 子域：详情族（A3-1-1-1-* tab + 详情操作）

> 所有详情 tab 页共用**详情公共头部**，包含：商机名称、招标形式、负责人、所属团队/部门、行业标签、项目阶段、商机状态、方案预算、「写跟进」「编辑」按钮、主要意向客户、「新增方案卡」、推进阶段进度条（节点+勾选状态）、tab 导航（概览/客户信息/方案卡/现场勘察/相关附件/跟进记录/工作计划/团队成员/操作日志）、顶部操作区（添加关联客户 / 推送方案 / 暂缓商机 / 抛公海 / 添加团队成员 / 关闭商机）。

**公共头部预期接口**：
- `GET /api/opportunity/{id}` — 详情主体查询（名称/状态/负责人/阶段/预算等所有头部字段）  `[详情]`
- `GET /api/opportunity/stage/progress?opportunityId={id}` — 推进阶段进度条（节点+完成状态）  `[阶段]`

### 页面：A3-1-1-1-1 商机详情_概览 （txt: `a3-1-1-1-1__个人_商机详情_概览.txt`）

- **概览区元素**：基础信息（项目名称、项目类型、行业、阶段、区域、招标形式、负责人、属地、团队、部门、金额、概况）、跟进记录摘要（最近 N 条，「查看更多」跳跟进记录 tab）、近期工作计划摘要、方案卡摘要

- **预期接口**：
  - `GET /api/opportunity/{id}` — 基础信息（公共头部同）  `[详情]`
  - `GET /api/opportunity/{id}/follow-ups?limit=3` 或 `POST /api/opportunity/{id}/follow-ups/page` — 跟进记录摘要（首页概览只取最近几条）  `[跟进]`
  - `GET /api/opportunity/{id}/scheme-cards` 或 `GET /api/opportunity/scheme-card/list?opportunityId={id}` — 方案卡摘要列表  `[方案卡]`

### 页面：A3-1-1-1-2 商机详情_客户信息 （txt: `a3-1-1-1-2_个人_商机详情_客户信息.txt`）

- **客户信息列表字段**：客户名称 / 客户类型（总包/工程商/集成商）/ 关键联系人 / 联系方式（脱敏）/ 联系人职务 / 关系标记（主要意向客户/普通关联）/ 操作（查看客户详情/设为主要）

- **预期接口**：
  - `GET /api/opportunity/{id}/customers` — 关联客户列表  `[详情]`
  - `POST /api/opportunity/{id}/customers/set-primary` 或 `PUT /api/opportunity/customer/{relId}/set-primary` — 设为主要意向客户  `[详情]`
  - `GET /api/customer/{id}` — 跳转客户详情（crm-customer 域，不属于本模块，不深测）  `[字典查询]`
  - （「添加关联客户」归操作族 A3-1-1-2-4）

### 页面：A3-1-1-1-3 商机详情_方案卡 + A3-1-1-1-3-1 编辑方案卡 （txt: 同名）

- **方案卡列表字段**：关联客户 / 客户类型 / 介入阶段 / 招标形式 / 预算 / 状态（未创建/草稿/已创建/已推送）
- **方案卡详情字段**：客户名称、客户类型、联系人、联系方式、项目阶段、招标形式、预算金额、预计成交概率、预计投标时间、设计配置、品牌要求、是否可换品牌、投标编号、标底方、客户需求描述、方案卡填写时间、期望方案设计完成时间、现场勘察资料（系统自动提取）、是否看现场、是否电话沟通、是否百万级、预算是否明确

- **预期接口**：
  - `GET /api/opportunity/scheme-card/list?opportunityId={id}` — 方案卡列表  `[方案卡]`
  - `GET /api/opportunity/scheme-card/detail?id={schemeId}` — 方案卡详情  `[方案卡]`
  - `POST /api/opportunity/scheme-card/save` — 保存/编辑方案卡  `[方案卡]`
  - `POST /api/opportunity/scheme-card/submit` — 提交方案卡  `[方案卡]`
  - `GET /api/opportunity/scheme-card/selectable-templates?opportunityId={id}` — 可选模板  `[方案卡]`
  - （「新增方案卡」弹窗归操作族 A3-1-1-2-3）

### 页面：A3-1-1-1-4 商机详情_现场勘察 （txt: `a3-1-1-1-4_个人_商机详情_现场勘察.txt`）

- **勘察记录字段**：申请单号 / 看现场日期 / 次数 / 工程师 / 联系方式（工单）/ 勘察说明 / 相关附件

- **预期接口**：
  - `GET /api/opportunity/{id}/surveys` 或 `POST /api/opportunity/{id}/surveys/page` — 现场勘察记录列表  `[勘察]`
  - （「新增勘察记录」归操作族 A3-1-1-2-10）

### 页面：A3-1-1-1-5 商机详情_相关附件 （txt: `a3-1-1-1-5_个人_商机详情_相关附件.txt`）

- **附件列表字段**：资料类型（现场资料/设计清单图纸/客户需求资料/招投标相关资料/其它）/ 附件内容 / 操作人 / 操作时间 / 说明 / 操作（查看/下载/删除）

- **预期接口**：
  - `GET /api/opportunity/{id}/attachments` — 附件列表  `[附件]`
  - `POST /api/opportunity/{id}/attachments` — 上传附件  `[附件]`
  - `DELETE /api/opportunity/attachment/{attachId}` — 删除附件  `[附件]`
  - `GET /api/opportunity/attachment/{attachId}/download` — 下载  `[附件]`

### 页面：A3-1-1-1-6 商机详情_跟进记录 （txt: `a3-1-1-1-6_个人_商机详情_跟进记录.txt`）

- **跟进记录字段**：跟进时间 / 跟进方式（微信/电话/拜访）/ 关联客户/联系人 / 跟进内容 / 下次跟进安排 / 记录人 / 附件（拜访打卡图等）
- 支持分页

- **预期接口**：
  - `POST /api/opportunity/{id}/follow-ups/page` 或 `GET /api/opportunity/{id}/follow-ups` — 跟进记录分页查询  `[跟进]`
  - （「写跟进」归操作族 A3-1-1-2-2）

### 页面：A3-1-1-1-8 商机详情_团队成员 （txt: `a3-1-1-1-8_个人_商机详情_团队成员.txt`）

- **团队成员表格字段**：成员名称 / 所属部门 / 职位 / 项目角色 / 职责 / 加入时间 / 操作
- 顶部按钮：「+添加成员」「一键拉群」（一键拉群 out-of-scope）

- **预期接口**：
  - `GET /api/opportunity/{id}/members` — 团队成员列表  `[团队]`
  - `DELETE /api/opportunity/{id}/members/{userId}` 或 `POST /api/opportunity/{id}/members/remove` — 移除成员  `[团队]`
  - （「添加团队成员」弹窗归操作族 A3-1-1-2-8）
  - 「一键拉群」out-of-scope

### 页面：A3-1-1-1-9 商机详情_操作日志 （txt: `a3-1-1-1-9_个人_商机详情_操作日志.txt`）

- **操作日志字段**：操作时间 / 操作人 / 实体对象 / 字段名称 / 旧值 / 新值 / 操作说明
- 系统自动记录：商机状态变更、节点变更、推送方案创建等

- **预期接口**：
  - `GET /api/opportunity/{id}/operation-logs` 或 `POST /api/opportunity/{id}/operation-logs/page` — 操作日志分页  `[日志]`

### 页面：A3-0-1-1 商机详情（最近访问跳转）/ A3-2-1-1 管理商机详情 （txt: 同名）

- **与 A3-1-1-1-1 差异**：
  - A3-0-1-1：与个人详情相同结构，仅入口不同
  - A3-2-1-1（管理详情）：顶部操作区增加「分配」「督办」，无「暂缓/抛公海」等个人操作（管理员视角）

- **预期接口**：复用 `GET /api/opportunity/{id}` + 各 tab 接口，无新增接口；行为差异由权限控制。



## 子域：状态机 / 操作族（A3-1-1-2-* + A3-3 领取分配）

> 这里是本验收最关键的子域：domain 层 `OpportunityTransition` 有 9 个 Cmd，但**已知没有 HTTP 入口**，逐一确认。

### 新增/编辑商机 A3-1-1-2-1 （txt: `a3-1-1-2-1__新增_编辑商机.txt`）

- **表单字段**：商机名称*、商机来源*（线索转入/线下挖掘/客户转介绍）、商机行业*（多级枚举：普教/高校/党校/公安…）、甲方、意向客户、地区、招标形式、方案预算、项目阶段、描述等

- **预期接口**：
  - `POST /api/opportunity` — 新增商机  `[详情]`
  - `PUT /api/opportunity/{id}` — 编辑商机  `[详情]`
  - `GET /api/dict/opportunity-source` — 商机来源枚举  `[字典查询]`
  - `GET /api/dict/industry` — 行业多级枚举  `[字典查询]`
  - `GET /api/dict/bidding-type` — 招标形式枚举  `[字典查询]`
  - `GET /api/dict/region/tree` — 地区树  `[字典查询]`

### 写跟进 A3-1-1-2-2 （txt: `a3-1-1-2-2_____.txt`）

- **表单字段**：跟进内容*、跟进时间、跟进方式*（电话沟通/上门拜访/微信对接/线上会议/展会沟通）、客户名称*（从关联客户选）、客户联系人、客户联系电话、跟进结果标签（暂无进展/需求确认/方案推进…）、计划下次跟进时间、附件（最多10个）

- **预期接口**：
  - `POST /api/opportunity/{id}/follow-ups` — 新增跟进记录  `[跟进]`
  - `POST /api/file/upload` 或 `POST /api/attachment/upload` — 附件上传（先传文件拿 fileId）  `[附件]`
  - `GET /api/dict/follow-up-method` — 跟进方式枚举  `[字典查询]`
  - `GET /api/dict/follow-up-result` — 跟进结果标签枚举  `[字典查询]`

### 新增方案卡 A3-1-1-2-3 （txt: `a3-1-1-2-3_______.txt`）

- **表单结构**：公司标准字段（关联客户*、介入阶段*、招标形式*、预算金额、是否百万级、预算是否明确、设计配置、品牌要求、是否可换品牌、客户需求…）+ 部门级补充字段（动态模板）

- **预期接口**：
  - `POST /api/opportunity/scheme-card` — 新增方案卡；body 含 `opportunityId`, 各字段  `[方案卡]`
  - `GET /api/opportunity/scheme-card/template?deptId={deptId}` — 获取部门级动态模板  `[方案卡]`
  - `GET /api/dict/intro-stage` — 介入阶段枚举（标前设计/标前抢单/投标阶段…）  `[字典查询]`
  - `GET /api/dict/bidding-type` — 招标形式（同上，复用）  `[字典查询]`

### 添加关联客户 A3-1-1-2-4 （txt: `a3-1-1-2-4________.txt`）

- **表单结构**：搜索框（搜客户名）+ 客户类型筛选（总包/工程商/投资方/设计院/集成商/投标公司）+ 搜索结果表（客户名/类型/地区/联系人/联系电话/客户负责人/选择按钮）

- **预期接口**：
  - `POST /api/customer/search` 或 `GET /api/customer/list?keyword=&type=` — 搜索/查询客户  `[字典查询]`
  - `POST /api/opportunity/{id}/customers` — 将选中客户关联到商机；body `{customerId, customerRole}`  `[详情]`

### 暂缓商机 A3-1-1-2-6 （txt: `a3-1-1-2-6______.txt`）

- **弹窗字段**：暂缓原因*（客户项目延期/预算冻结/招标暂停/政策与其他不可抗力因素/个人原因/其他）、预计重启日期*、补充说明
- **业务规则**：暂缓后商机保留归属（不进公海、不被领取）；仅个人暂缓用途

- **预期接口（状态机）**：
  - `POST /api/opportunity/{id}/pause` 或 `POST /api/opportunity/transition` body `{cmd:"PAUSE", id, reason, restartDate, remark}` — **PauseCmd**  `[状态机]`
  - `GET /api/dict/pause-reason` — 暂缓原因枚举  `[字典查询]`

### 抛公海 A3-1-1-2-7 （txt: `a3-1-1-2-7_____.txt`）

- **弹窗字段**：进入公海原因*（长期未有效跟进/客户暂无预算/项目暂停或延期/介入时机不成熟/其他）、进入公海范围*（所属部门公海/公司公海）、补充说明
- **业务规则**：抛公海后原负责人失去跟进权限；历史数据保留

- **预期接口（状态机）**：
  - `POST /api/opportunity/{id}/release-to-pool` 或 `POST /api/opportunity/transition` body `{cmd:"RELEASE_TO_POOL", ...}` — **ReleaseToPoolCmd**  `[状态机]`
  - `GET /api/dict/pool-entry-reason` — 进入公海原因枚举（同公海列表筛选，复用）  `[字典查询]`
  - `GET /api/dict/pool-scope` — 公海范围枚举（所属部门/公司）  `[字典查询]`

### 关闭商机 A3-1-1-2-9 （txt: `a3-1-1-2-9______.txt`）

- **弹窗字段**：关闭原因*（项目取消/客户放弃/竞争失败/重复商机/无效商机/其他）、补充说明、「已确认」checkbox*
- **业务规则**：关闭后停止推进，需管理员权限才能重新开启

- **预期接口（状态机）**：
  - `POST /api/opportunity/{id}/close` 或 `POST /api/opportunity/transition` body `{cmd:"CLOSE", ...}` — **CloseCmd**  `[状态机]`
  - `GET /api/dict/close-reason` — 关闭原因枚举  `[字典查询]`

### 新增现场勘察记录 A3-1-1-2-10 （txt: `a3-1-1-2-10________.txt`）

- **弹窗字段**：申请方式、勘察次数*（第一次/第二次/第三次/三次以上）、现场勘察日期*、申请单号、工程师选择（跨部门选人）、勘察补充说明、相关附件

- **预期接口**：
  - `POST /api/opportunity/{id}/surveys` — 新增现场勘察记录  `[勘察]`
  - `GET /api/user/list?dept=` 或 `GET /api/user/engineer-list` — 工程师候选人  `[字典查询]`

### 领取公海商机 A3-3-1-1-2 （txt: `a3-3-1-1-2____.txt`）

- **弹窗字段**：领取说明（选填）+ 确认提示（商机名称、领取后效果说明）
- **业务规则**：领取成功后成为负责人，商机退出公海

- **预期接口（状态机）**：
  - `POST /api/opportunity/{id}/claim` 或 `POST /api/opportunity/claim` body `{opportunityId, remark}` — **ClaimCmd**  `[状态机]`

### 分配公海商机 A3-3-1-1-4 （txt: `a3-3-1-1-4____.txt`）

- **弹窗字段**：人员搜索+筛选（部门/姓名/当前参与商机数），分配对象*、是否发送提示通知*（是/否）、分配说明（选填）
- **业务规则**：管理员/领导分配；商机退出公海归被分配人

- **预期接口（状态机）**：
  - `POST /api/opportunity/{id}/assign` 或 `POST /api/opportunity/assign` body `{opportunityId, assigneeId, notify, remark}` — **AssignToUserCmd**  `[状态机]`
  - `GET /api/user/list?dept=` — 候选用户列表（同添加团队成员，复用）  `[字典查询]`

### 已知缺失（白盒事实，在此预登记）

以下 domain Cmd **原型有对应操作入口**，但目前无 HTTP 路由映射：

| Cmd | 对应原型操作 | 预期 HTTP | 状态 |
|-----|------------|-----------|------|
| ClaimCmd | A3-3-1-1-2 领取 | `POST /api/opportunity/{id}/claim` | ❓待实测 |
| AssignToUserCmd | A3-3-1-1-4 分配 | `POST /api/opportunity/{id}/assign` | ❓待实测 |
| ReleaseToPoolCmd | A3-1-1-2-7 抛公海 | `POST /api/opportunity/{id}/release-to-pool` | ❓待实测 |
| PauseCmd | A3-1-1-2-6 暂缓 | `POST /api/opportunity/{id}/pause` | ❓待实测 |
| ResumeCmd | 暂缓后「恢复」按钮 | `POST /api/opportunity/{id}/resume` | ❓待实测 |
| CloseCmd | A3-1-1-2-9 关闭 | `POST /api/opportunity/{id}/close` | ❓待实测 |
| ReopenCmd | 关闭后「重新开启」 | `POST /api/opportunity/{id}/reopen` | ❓待实测 |
| HandoverCmd | 移交（详情页操作）| `POST /api/opportunity/{id}/handover` | ❓待实测 |
| ConvertToProjectCmd | 转项目（out-of-scope）| — | ⊘ 不测 |



## 子域：规则族（A7-3-2-* 阶段/方案卡/公海/字典）

> 设置后台路径：商机 > 商机管理设置。左侧 tab：商机阶段设置 / 方案卡模板 / 方案推送规则(out-of-scope) / 查重规则(out-of-scope) / 公海与提醒 / 商机相关字典。

---

### A7-3-2-1 商机阶段设置（列表页）

- **列表字段**：序号 / 模板名称 / 模板编码(code) / 版本号 / 状态（草稿/发布中/已停用）/ 适用范围 / 最近更新 / 绑定商机数 / 操作（详情/编辑/删除/复制）
- 同一 code 可有多版本，只有一个版本"发布中"

- **预期接口**：
  - `GET /api/opportunity/stage-template/page` 或 `GET /api/opportunity/stage-template/list` — 阶段模板列表  `[规则-阶段]`
  - `DELETE /api/opportunity/stage-template/{id}` — 删除（草稿态）  `[规则-阶段]`
  - `POST /api/opportunity/stage-template/{id}/copy` — 复制模板  `[规则-阶段]`

### A7-3-2-1-1 商机阶段设置（详情页）

- **详情区**：版本号 / 模板编码 / 适用范围 / 适用对象 / 状态 / 绑定商机 / 是否默认 / 概览tab / 版本记录tab / 阶段节点配置（节点列表，可点选查看工作目标；节点有：字典值+自定义名称+阶段工作目标+是否固定节点）
- 阶段节点字典从 `商机阶段` 字典分组中选，节点支持拖拽排序

- **预期接口**：
  - `GET /api/opportunity/stage-template/{id}` — 模板详情  `[规则-阶段]`
  - `GET /api/opportunity/stage-template/{id}/versions` — 版本记录列表  `[规则-阶段]`
  - `GET /api/dict/items?group=opportunity_stage` — 商机阶段字典条目（供节点选择）  `[规则-字典]`

### A7-3-2-1-2 商机阶段设置（新增/编辑页）

- **表单字段**：模板名称*、模板编码（系统生成只读）、适用范围*（所有商机/指定部门）、适用对象（范围=指定部门时）、是否默认*（是/否）、版本号（只读）、模板说明、阶段编辑区（可添加/删除/排序节点；每节点含字典值*、自定义节点名称、阶段工作目标）
- 操作按钮：保存草稿 / 保存并发布 / 取消

- **预期接口**：
  - `POST /api/opportunity/stage-template` — 新增模板  `[规则-阶段]`
  - `PUT /api/opportunity/stage-template/{id}` — 编辑模板  `[规则-阶段]`
  - `POST /api/opportunity/stage-template/{id}/publish` — 发布模板  `[规则-阶段]`
  - `POST /api/opportunity/stage-template/{id}/disable` — 停用模板  `[规则-阶段]`
  - `GET /api/dept/list` — 适用对象部门选择  `[字典查询]`

---

### A7-3-2-2 方案卡模板（列表页）

- **列表字段**：序号 / 模板名称 / 模板编码 / 版本号 / 状态 / 适用范围 / 最近更新 / 绑定商机数 / 操作（详情/编辑/删除/复制）
- 右侧有**预览区**：展示模板对应的方案卡字段（客户名称/客户角色/联系人/项目阶段/招标形式/是否看现场/是否电话沟通/勘察资料/是否百万级/预算金额/预算是否明确/设计配置/品牌要求/客户需求描述/业务需求等）

- **预期接口**：
  - `GET /api/opportunity/scheme-card-template/page` 或 `/list` — 方案卡模板列表  `[规则-方案卡]`
  - `DELETE /api/opportunity/scheme-card-template/{id}` — 删除  `[规则-方案卡]`
  - `POST /api/opportunity/scheme-card-template/{id}/copy` — 复制  `[规则-方案卡]`

### A7-3-2-2-1 方案卡模板（详情页）

- **详情区**：版本号 / 模板编码 / 适用范围 / 适用对象 / 状态 / 绑定商机 / 是否默认 / 字段配置详情（公司标准字段 + 部门补充字段，每字段含名称/是否必填/字段类型/选项值等）

- **预期接口**：
  - `GET /api/opportunity/scheme-card-template/{id}` — 模板详情  `[规则-方案卡]`
  - `GET /api/opportunity/scheme-card-template/{id}/versions` — 版本记录  `[规则-方案卡]`

### A7-3-2-2-2 方案卡模板（新增/编辑页）

- **表单字段**：模板名称* / 模板编码（只读）/ 适用范围* / 适用对象 / 是否默认* / 版本号（只读）/ 字段配置编辑区（可添加/删除/排序字段；每字段含字段名*、是否必填、字段类型、选项配置）
- 操作：保存草稿 / 保存并发布 / 取消

- **预期接口**：
  - `POST /api/opportunity/scheme-card-template` — 新增  `[规则-方案卡]`
  - `PUT /api/opportunity/scheme-card-template/{id}` — 编辑  `[规则-方案卡]`
  - `POST /api/opportunity/scheme-card-template/{id}/publish` — 发布  `[规则-方案卡]`
  - `POST /api/opportunity/scheme-card-template/{id}/disable` — 停用  `[规则-方案卡]`

---

### A7-3-2-5 公海与提醒规则（列表页）

- **列表字段**：序号 / 规则名称 / 规则编码 / 版本号 / 状态 / 适用范围 / 自动回收（天数）/ 提前提醒（天数）/ 最近更新 / 操作（详情/编辑/删除/复制）

- **预期接口**：
  - `GET /api/opportunity/pool-rule/page` 或 `/list` — 公海规则列表  `[规则-公海]`
  - `DELETE /api/opportunity/pool-rule/{id}` — 删除  `[规则-公海]`
  - `POST /api/opportunity/pool-rule/{id}/copy` — 复制  `[规则-公海]`

### A7-3-2-5-1 公海与提醒规则（详情页）

- **详情字段**：规则名称 / 规则编码 / 适用范围 / 适用对象 / 是否默认 / 版本号 / 规则说明 / 允许负责人手动转入公海（是/否）/ 连续未有效跟进自动回收（开关+天数）/ 允许自由领取（是/否）/ 提前提醒天数
- **有效跟进定义**：产生跟进记录/附件上传/业务字段编辑，均视为有效跟进

- **预期接口**：
  - `GET /api/opportunity/pool-rule/{id}` — 规则详情  `[规则-公海]`
  - `GET /api/opportunity/pool-rule/{id}/versions` — 版本记录  `[规则-公海]`

### A7-3-2-5-2 公海与提醒规则（新增/编辑页）

- **表单字段**：规则名称* / 适用范围* / 适用对象 / 是否默认* / 规则说明 / 允许手动转入公海*（是/否）/ 连续未有效跟进自动回收*（开关）/ 自动回收天数（开关打开后必填）/ 允许自由领取*（是/否）/ 提前提醒天数*
- 操作：保存草稿 / 保存并发布 / 取消

- **预期接口**：
  - `POST /api/opportunity/pool-rule` — 新增  `[规则-公海]`
  - `PUT /api/opportunity/pool-rule/{id}` — 编辑  `[规则-公海]`
  - `POST /api/opportunity/pool-rule/{id}/publish` — 发布  `[规则-公海]`
  - `POST /api/opportunity/pool-rule/{id}/disable` — 停用  `[规则-公海]`

---

### A7-3-2-6 商机相关字典（txt: `a3-4-6_商机相关字典.txt`）

- **字典分组**（已知启用的分组）：

| 分组名称 | 分组编码 | 用途 |
|---------|---------|------|
| 商机阶段 | opportunity_stage | 供阶段模板节点选择 |
| 商机状态 | opportunity_status | 商机当前业务状态枚举 |
| 暂缓原因 | opportunity_pause_reason | 暂缓弹窗选项 |
| 关闭原因 | opportunity_close_reason | 关闭弹窗选项 |

- **字典操作**：新增/编辑分组、新增/编辑/启用/停用字典条目、分页查询

- **预期接口**：
  - `GET /api/opportunity/dict/groups` — 字典分组列表  `[规则-字典]`
  - `POST /api/opportunity/dict/groups` — 新增分组  `[规则-字典]`
  - `PUT /api/opportunity/dict/groups/{id}` — 编辑分组  `[规则-字典]`
  - `GET /api/opportunity/dict/items?groupCode={code}` — 分组下条目列表  `[规则-字典]`
  - `POST /api/opportunity/dict/items` — 新增条目  `[规则-字典]`
  - `PUT /api/opportunity/dict/items/{id}` — 编辑条目  `[规则-字典]`
  - `PUT /api/opportunity/dict/items/{id}/enable` — 启用  `[规则-字典]`
  - `PUT /api/opportunity/dict/items/{id}/disable` — 停用  `[规则-字典]`

- **备注**：若字典走通用 `crm-dict` 平台而非商机专属，路径可能是 `/api/dict/groups?module=opportunity`；实测时按实际路径判定，本 spec 只登记需求侧预期。



---


---

# 接口聚合（按子域去重）

共 0 条唯一预期接口。

---

# 接口聚合（按子域去重）

共 2 条唯一预期接口。其中 **状态机** 子域是本次验收的"未实现高风险区"。


## 详情/基础 (1 条)

- `GET /api/opportunity/{id}` — 详情主体查询（名称/状态/负责人/阶段/预算等所有头部字段）

## 阶段推进 (1 条)

- `GET /api/opportunity/stage/progress?opportunityId={id}` — 推进阶段进度条（节点+完成状态）

---

# 接口聚合（按子域去重）

共 103 条唯一预期接口。**状态机** 子域是本次验收的"未实现高风险区"（已知 domain 层有 9 个 Cmd，仅 ConvertToProject out-of-scope）。


## 列表 (6 条)

- `POST /api/opportunity/recent-visits/page`
- `POST /api/opportunity/recent-visits/touch`
- `POST /api/opportunity/page`
- `POST /api/opportunity/board/stage-summary`
- `POST /api/opportunity/board/cards`
- `POST /api/opportunity/pool/page`

## 详情/基础 (6 条)

- `POST /api/opportunity`
- `GET /api/opportunity/{id}`
- `GET /api/opportunity/{id}/customers`
- `POST /api/opportunity/{id}/customers/set-primary`
- `PUT /api/opportunity/{id}`
- `POST /api/opportunity/{id}/customers`

## 状态机（流转） (10 条)

- `POST /api/opportunity/claim`
- `POST /api/opportunity/assign`
- `POST /api/opportunity/assign/batch`
- `POST /api/opportunity/close/batch`
- `POST /api/opportunity/claim/batch`
- `POST /api/opportunity/{id}/pause`
- `POST /api/opportunity/{id}/release-to-pool`
- `POST /api/opportunity/{id}/close`
- `POST /api/opportunity/{id}/claim`
- `POST /api/opportunity/{id}/assign`

## 阶段推进 (1 条)

- `GET /api/opportunity/stage/progress?opportunityId={id}`

## 方案卡 (8 条)

- `GET /api/opportunity/{id}/scheme-cards`
- `GET /api/opportunity/scheme-card/list?opportunityId={id}`
- `GET /api/opportunity/scheme-card/detail?id={schemeId}`
- `POST /api/opportunity/scheme-card/save`
- `POST /api/opportunity/scheme-card/submit`
- `GET /api/opportunity/scheme-card/selectable-templates?opportunityId={id}`
- `POST /api/opportunity/scheme-card`
- `GET /api/opportunity/scheme-card/template?deptId={deptId}`

## 跟进记录 (3 条)

- `GET /api/opportunity/{id}/follow-ups?limit=3`
- `POST /api/opportunity/{id}/follow-ups/page`
- `POST /api/opportunity/{id}/follow-ups`

## 现场勘察 (2 条)

- `GET /api/opportunity/{id}/surveys`
- `POST /api/opportunity/{id}/surveys`

## 附件 (5 条)

- `GET /api/opportunity/{id}/attachments`
- `POST /api/opportunity/{id}/attachments`
- `DELETE /api/opportunity/attachment/{attachId}`
- `GET /api/opportunity/attachment/{attachId}/download`
- `POST /api/file/upload`

## 团队成员 (2 条)

- `GET /api/opportunity/{id}/members`
- `DELETE /api/opportunity/{id}/members/{userId}`

## 操作日志 (1 条)

- `GET /api/opportunity/{id}/operation-logs`

## 协作（关注/领取） (3 条)

- `POST /api/opportunity/follow`
- `DELETE /api/opportunity/follow/{opportunityId}`
- `POST /api/opportunity/follow/batch`

## 视图/自定义字段 (2 条)

- `GET /api/user/customize/columns?scene=opportunity-list`
- `POST /api/user/customize/columns`

## 字典查询/候选 (18 条)

- `GET /api/dict/industry`
- `GET /api/dict/region`
- `GET /api/dict/source`
- `GET /api/user/assignable`
- `GET /api/dict/pool-entry-reason`
- `GET /api/customer/{id}`
- `GET /api/dict/opportunity-source`
- `GET /api/dict/bidding-type`
- `GET /api/dict/region/tree`
- `GET /api/dict/follow-up-method`
- `GET /api/dict/follow-up-result`
- `GET /api/dict/intro-stage`
- `POST /api/customer/search`
- `GET /api/dict/pause-reason`
- `GET /api/dict/pool-scope`
- `GET /api/dict/close-reason`
- `GET /api/user/list?dept=`
- `GET /api/dept/list`

## 规则-阶段模板 (9 条)

- `GET /api/opportunity/stage-template/page`
- `DELETE /api/opportunity/stage-template/{id}`
- `POST /api/opportunity/stage-template/{id}/copy`
- `GET /api/opportunity/stage-template/{id}`
- `GET /api/opportunity/stage-template/{id}/versions`
- `POST /api/opportunity/stage-template`
- `PUT /api/opportunity/stage-template/{id}`
- `POST /api/opportunity/stage-template/{id}/publish`
- `POST /api/opportunity/stage-template/{id}/disable`

## 规则-方案卡模板 (9 条)

- `GET /api/opportunity/scheme-card-template/page`
- `DELETE /api/opportunity/scheme-card-template/{id}`
- `POST /api/opportunity/scheme-card-template/{id}/copy`
- `GET /api/opportunity/scheme-card-template/{id}`
- `GET /api/opportunity/scheme-card-template/{id}/versions`
- `POST /api/opportunity/scheme-card-template`
- `PUT /api/opportunity/scheme-card-template/{id}`
- `POST /api/opportunity/scheme-card-template/{id}/publish`
- `POST /api/opportunity/scheme-card-template/{id}/disable`

## 规则-公海规则 (9 条)

- `GET /api/opportunity/pool-rule/page`
- `DELETE /api/opportunity/pool-rule/{id}`
- `POST /api/opportunity/pool-rule/{id}/copy`
- `GET /api/opportunity/pool-rule/{id}`
- `GET /api/opportunity/pool-rule/{id}/versions`
- `POST /api/opportunity/pool-rule`
- `PUT /api/opportunity/pool-rule/{id}`
- `POST /api/opportunity/pool-rule/{id}/publish`
- `POST /api/opportunity/pool-rule/{id}/disable`

## 规则-字典 (9 条)

- `GET /api/dict/items?group=opportunity_stage`
- `GET /api/opportunity/dict/groups`
- `POST /api/opportunity/dict/groups`
- `PUT /api/opportunity/dict/groups/{id}`
- `GET /api/opportunity/dict/items?groupCode={code}`
- `POST /api/opportunity/dict/items`
- `PUT /api/opportunity/dict/items/{id}`
- `PUT /api/opportunity/dict/items/{id}/enable`
- `PUT /api/opportunity/dict/items/{id}/disable`