You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 
 

22 KiB

商机模块接口验收报告

验收方式:原型驱动黑盒测试(不白盒对照 controller) 后端环境http://localhost:8080(远程 DB 8.129.84.155调试用户userId=739564171091247104 结论三档 存在正确 / ⚠️ 实现有问题 / 未实现 范围:37 页原型,out-of-scope 见 map.md


一、列表族(票 03)

对应 spec-endpoints.md「列表」子域 实测时间:2026-08-26

1.1 实测结果表

# 预期接口 来源原型页 结论 证据
1 POST /api/opportunity/page(viewType=MINE) A3-1-1 我负责的 HTTP 200,返回含 content 分页,字段含 oppName/stageStayDays/schemeCardStatus/oppSourceName 等富字段
2 POST /api/opportunity/page(viewType=RECENT) A3-0-1 最近访问 HTTP 200,数据正常返回
3 POST /api/opportunity/page(viewType=PUBLIC_POOL) A3-3-1 商机公海 HTTP 200,数据正常返回
4 POST /api/opportunity/page(viewType=MANAGE) A3-2-1 管理列表 HTTP 200,数据正常返回
5 POST /api/opportunity/recent-visits/page A3-0-1 最近访问独立接口 (合并) 404,但 viewType=RECENT 已覆盖此语义,设计收敛合理
6 POST /api/opportunity/pool/page A3-3-1 公海独立接口 (合并) 同上,viewType=PUBLIC_POOL 已覆盖
7 POST /api/opportunity/recent-visits/touch A3-0-1 访问上报 HTTP 404,后端无此路由
8 POST /api/opportunity/board/stage-summary A3-2-1 看板阶段汇总 HTTP 404,后端无此路由
9 POST /api/opportunity/board/cards A3-2-1 看板单阶段卡片 HTTP 404,后端无此路由

1.2 ⚠️ 实现有问题清单

# 接口 问题描述 影响
W-01 POST /api/opportunity/page 分页包装字段名为 content(Spring Data 风格),非 MyBatis-Plus 惯例的 recordstotal/size/current/pages 字段存在 前端对接需用 content 取列表,勿用 records
W-02 POST /api/opportunity(新建) bid_form 列 DB NOT NULL 无默认值,CreateOpportunityRequest 不含此字段,导致任何新建请求均返回 500(Field 'bid_form' doesn't have a default value 新建商机功能完全不可用

1.3 未实现清单

# 预期接口 对应原型功能
M-01 POST /api/opportunity/recent-visits/touch 用户打开详情时上报访问记录(最近访问列表数据来源)
M-02 POST /api/opportunity/board/stage-summary 看板视图各阶段商机数+金额汇总
M-03 POST /api/opportunity/board/cards 看板视图单阶段卡片按需加载

二、详情族 + 状态机(票 04)

对应 spec-endpoints.md「详情/基础」「状态机」「阶段」「方案卡」「跟进」「勘察」「附件」「团队」「日志」「协作」子域 实测时间:2026-08-26

2.1 实测结果表

详情/基础

# 预期接口 来源原型页 结论 证据
1 GET /api/opportunity/{id} A3-1-1-1-1 概览 公共头部 HTTP 404,message: 接口不存在
2 PUT /api/opportunity/{id} A3-1-1-2-1 编辑商机 HTTP 404
3 GET /api/opportunity/{id}/customers A3-1-1-1-2 客户信息 HTTP 404
4 POST /api/opportunity/{id}/customers A3-1-1-2-4 添加关联客户 HTTP 404
5 POST /api/opportunity/{id}/customers/set-primary A3-1-1-1-2 设为主要 HTTP 404

阶段推进

# 预期接口 来源原型页 结论 证据
6 GET /api/opportunity/stage/progress?oppId={id} 详情公共头部进度条 HTTP 200,返回 5 个节点含 nodeState/seqNo/workGoal;实际参数名为 oppId(spec 写的是 opportunityId,见 W-03)
7 POST /api/opportunity/stage/switch 推进阶段 HTTP 200(参数 oppId+targetStageId
8 GET /api/opportunity/stage/history?oppId={id} 阶段历史(版本记录) HTTP 200,返回空数组(无数据);接口存在

方案卡

# 预期接口 来源原型页 结论 证据
9 GET /api/opportunity/scheme-card/list?oppId={id} A3-1-1-1-3 方案卡列表 HTTP 200,实际参数名为 oppId(见 W-04)
10 GET /api/opportunity/scheme-card/detail?id={id} A3-1-1-1-3 方案卡详情 HTTP 200;无数据时返回业务错误码 66008(方案卡不存在或已删除)
11 GET /api/opportunity/scheme-card/selectable-templates?oppId={id} A3-1-1-2-3 新增方案卡模板选择 HTTP 200,返回 1 个可选模板,含 templateId/templateName/templateVersion 等字段;实际参数名为 oppId(见 W-05)
12 POST /api/opportunity/scheme-card/save A3-1-1-2-3 保存方案卡 路由存在;缺参时返回业务码 66007「方案卡保存参数缺失(商机与客户必填)」
13 POST /api/opportunity/scheme-card/submit A3-1-1-2-3 提交方案卡 路由存在;HTTP 200
14 POST /api/opportunity/scheme-card A3-1-1-2-3 新增方案卡(spec 预期另一路径) ⚠️(合并) 实际由 /scheme-card/save 承载,无独立 POST /scheme-card

跟进记录

# 预期接口 来源原型页 结论 证据
15 POST /api/opportunity/{id}/follow-ups/page A3-1-1-1-6 跟进记录 HTTP 404
16 GET /api/opportunity/{id}/follow-ups?limit=3 A3-1-1-1-1 概览摘要 HTTP 404
17 POST /api/opportunity/{id}/follow-ups A3-1-1-2-2 写跟进 HTTP 404

现场勘察

# 预期接口 来源原型页 结论 证据
18 GET /api/opportunity/{id}/surveys A3-1-1-1-4 现场勘察 HTTP 404
19 POST /api/opportunity/{id}/surveys A3-1-1-2-10 新增勘察 HTTP 404

附件

# 预期接口 来源原型页 结论 证据
20 GET /api/opportunity/{id}/attachments A3-1-1-1-5 相关附件 HTTP 404
21 POST /api/opportunity/{id}/attachments A3-1-1-1-5 上传附件 HTTP 404
22 DELETE /api/opportunity/attachment/{id} A3-1-1-1-5 删除附件 HTTP 404
23 GET /api/opportunity/attachment/{id}/download A3-1-1-1-5 下载附件 HTTP 404

团队成员

# 预期接口 来源原型页 结论 证据
24 GET /api/opportunity/{id}/members A3-1-1-1-8 团队成员 HTTP 404
25 DELETE /api/opportunity/{id}/members/{userId} A3-1-1-1-8 移除成员 HTTP 404

操作日志

# 预期接口 来源原型页 结论 证据
26 GET /api/opportunity/{id}/operation-logs A3-1-1-1-9 操作日志 HTTP 404

协作(关注)

# 预期接口 来源原型页 结论 证据
27 POST /api/opportunity/follow 单个关注 HTTP 404
28 DELETE /api/opportunity/follow/{id} 取关 HTTP 404
29 POST /api/opportunity/follow/batch 批量关注 HTTP 404

状态机(流转 Cmd)

# Cmd 预期接口 结论 证据
30 ClaimCmd POST /api/opportunity/{id}/claim HTTP 404
31 ClaimCmd(批量) POST /api/opportunity/claim HTTP 404
32 ClaimCmd(批量) POST /api/opportunity/claim/batch HTTP 404
33 AssignToUserCmd POST /api/opportunity/{id}/assign HTTP 404
34 AssignToUserCmd(批量) POST /api/opportunity/assign HTTP 404
35 AssignToUserCmd(批量) POST /api/opportunity/assign/batch HTTP 404
36 PauseCmd POST /api/opportunity/{id}/pause HTTP 404
37 ResumeCmd POST /api/opportunity/{id}/resume HTTP 404
38 ReleaseToPoolCmd POST /api/opportunity/{id}/release-to-pool HTTP 404
39 CloseCmd POST /api/opportunity/{id}/close HTTP 404
40 CloseCmd(批量) POST /api/opportunity/close/batch HTTP 404
41 ReopenCmd POST /api/opportunity/{id}/reopen HTTP 404
42 HandoverCmd POST /api/opportunity/{id}/handover HTTP 404

2.2 ⚠️ 实现有问题清单

# 接口 问题描述 影响
W-03 GET /api/opportunity/stage/progress 参数名为 oppId,spec 预期为 opportunityId;功能正常,前端对接需用 oppId 参数名与 spec 不一致
W-04 GET /api/opportunity/scheme-card/list 参数名为 oppId,spec 预期为 opportunityId 参数名与 spec 不一致
W-05 GET /api/opportunity/scheme-card/selectable-templates 参数名为 oppId,spec 预期为 opportunityId 参数名与 spec 不一致

2.3 未实现清单(汇总)

详情族、跟进、勘察、附件、团队、日志、协作、状态机 13 个 Cmd 全部 404,合计 37 条接口未实现

已实现(存在路由)的:

  • GET /api/opportunity/stage/progress(参数名 oppId,见 W-03)
  • POST /api/opportunity/stage/switch(缺参返回业务码 66001)
  • GET /api/opportunity/stage/history
  • GET /api/opportunity/scheme-card/list(参数名 oppId,见 W-04)
  • GET /api/opportunity/scheme-card/detail
  • GET /api/opportunity/scheme-card/selectable-templates(参数名 oppId,见 W-05)
  • POST /api/opportunity/scheme-card/save(缺参返回业务码 66007)
  • POST /api/opportunity/scheme-card/submit

三、规则族(票 05)

对应 spec-endpoints.md「规则-阶段模板」「规则-方案卡模板」「规则-公海规则」「规则-字典」「视图/自定义字段」子域 实测时间:2026-08-26

3.1 实测结果表

规则-阶段模板

# 预期接口(spec) 实际路径 结论 证据
1 GET /api/opportunity/stage-template/page POST /api/rule/opp-stage-template/page (路径变更) HTTP 200,返回模板列表含 templateCode/versionNo/status/applyScope
2 GET /api/opportunity/stage-template/{id} GET /api/rule/opp-stage-template/detail?id= (路径变更) HTTP 200,返回模板详情
3 POST /api/opportunity/stage-template POST /api/rule/opp-stage-template/save-draft (路径变更) HTTP 200,路由存在
4 PUT /api/opportunity/stage-template/{id} POST /api/rule/opp-stage-template/save-draft (合并) 新增/编辑合并为 save-draft
5 POST /api/opportunity/stage-template/{id}/publish POST /api/rule/opp-stage-template/publish (路径变更) HTTP 200
6 POST /api/opportunity/stage-template/{id}/disable POST /api/rule/opp-stage-template/disable (路径变更) HTTP 200
7 DELETE /api/opportunity/stage-template/{id} POST /api/rule/opp-stage-template/delete (路径变更) HTTP 200;方法从 DELETE 改为 POST
8 POST /api/opportunity/stage-template/{id}/copy POST /api/rule/opp-stage-template/copy (路径变更) HTTP 200
9 GET /api/opportunity/stage-template/{id}/versions 未找到对应路由 /versions 端点

规则-方案卡模板

# 预期接口(spec) 实际路径 结论 证据
10 GET /api/opportunity/scheme-card-template/page POST /api/rule/opp-scheme-template/page (路径变更) HTTP 200,返回模板列表
11 GET /api/opportunity/scheme-card-template/{id} GET /api/rule/opp-scheme-template/detail?id= (路径变更) HTTP 200,返回模板详情
12 POST /api/opportunity/scheme-card-template POST /api/rule/opp-scheme-template/save-draft (路径变更) HTTP 200
13 PUT /api/opportunity/scheme-card-template/{id} POST /api/rule/opp-scheme-template/save-draft (合并) 同上
14 POST /api/opportunity/scheme-card-template/{id}/publish POST /api/rule/opp-scheme-template/publish (路径变更) HTTP 200
15 POST /api/opportunity/scheme-card-template/{id}/disable POST /api/rule/opp-scheme-template/disable (路径变更) HTTP 200
16 DELETE /api/opportunity/scheme-card-template/{id} POST /api/rule/opp-scheme-template/delete (路径变更) HTTP 200
17 POST /api/opportunity/scheme-card-template/{id}/copy POST /api/rule/opp-scheme-template/copy (路径变更) HTTP 200
18 GET /api/opportunity/scheme-card-template/{id}/versions 未找到对应路由 /versions 端点
(额外)字段定义接口 GET /api/rule/opp-scheme-template/field-defs?templateId= (额外) HTTP 200,返回字段定义列表含 fieldKey/fieldName/fieldType

规则-公海规则

# 预期接口(spec) 实际路径 结论 证据
19 GET /api/opportunity/pool-rule/page POST /api/rule/opp-pool-rule/page (路径变更) HTTP 200,返回空列表(无数据)
20 GET /api/opportunity/pool-rule/{id} GET /api/rule/opp-pool-rule/detail?id= (路径变更) HTTP 200;无数据时返回业务码 64009
21 POST /api/opportunity/pool-rule POST /api/rule/opp-pool-rule/save-draft (路径变更) HTTP 200
22 PUT /api/opportunity/pool-rule/{id} POST /api/rule/opp-pool-rule/save-draft (合并) 同上
23 POST /api/opportunity/pool-rule/{id}/publish POST /api/rule/opp-pool-rule/publish (路径变更) HTTP 200
24 POST /api/opportunity/pool-rule/{id}/disable POST /api/rule/opp-pool-rule/disable (路径变更) HTTP 200
25 DELETE /api/opportunity/pool-rule/{id} POST /api/rule/opp-pool-rule/delete (路径变更) HTTP 200
26 POST /api/opportunity/pool-rule/{id}/copy POST /api/rule/opp-pool-rule/copy (路径变更) HTTP 200
27 GET /api/opportunity/pool-rule/{id}/versions 未找到对应路由 /versions 端点

规则-字典

# 预期接口(spec) 实际路径 结论 证据
28 GET /api/opportunity/dict/groups POST /api/dict/group/pageGET /api/dict/group/enabled-list (路径变更) HTTP 200;走通用 crm-dict 平台,非商机专属路径
29 POST /api/opportunity/dict/groups POST /api/dict/group/saveOrUpdate (路径变更) HTTP 200
30 PUT /api/opportunity/dict/groups/{id} POST /api/dict/group/saveOrUpdate (合并) 新增/编辑合并为 saveOrUpdate
31 GET /api/opportunity/dict/items?groupCode= GET /api/dict/item/enabled-list?groupCode=POST /api/dict/item/page (路径变更) HTTP 200
32 POST /api/opportunity/dict/items POST /api/dict/group/saveOrUpdate (路径变更) HTTP 200
33 PUT /api/opportunity/dict/items/{id} POST /api/dict/item/saveOrUpdate (路径变更) HTTP 200
34 PUT /api/opportunity/dict/items/{id}/enable POST /api/dict/item/status (路径变更) HTTP 200;启用/停用合并为 /status
35 PUT /api/opportunity/dict/items/{id}/disable POST /api/dict/item/status (合并) 同上
GET /api/dict/items?group=opportunity_stage GET /api/dict/item/enabled-list?groupCode=opp_stage ⚠️ groupCode 实为 opp_stage,非 spec 预期的 opportunity_stage

视图/自定义字段

# 预期接口(spec) 实际路径 结论 证据
36 GET /api/user/customize/columns?scene=opportunity-list GET /api/preference/get?scopeKey=opportunity.list (路径变更) HTTP 200;参数名为 scopeKeyscene
37 POST /api/user/customize/columns POST /api/preference/save (路径变更) HTTP 200

3.2 ⚠️ 实现有问题清单

# 问题 说明
W-06 所有规则族路径前缀与 spec 不一致 spec 预期 /api/opportunity/stage-template/,实际为 /api/rule/opp-stage-template/;其余两类规则同理。功能存在,路径偏差。
W-07 字典分组 code 与 spec 不一致 spec 预期 opportunity_stage,实际为 opp_stage;同理推测其他商机字典 groupCode 也有差异
W-08 视图/自定义字段路径与 spec 不一致 spec 预期 /api/user/customize/columns,实际为 /api/preference/get + /api/preference/save;参数名 scopeKeyscene
W-09 规则操作 HTTP 方法变更 spec 预期 DELETE/PUT,实际统一用 POST;spec 预期 RESTful 风格 /{id}/action,实际用 body 传 id 的 flat 路径

3.3 未实现清单

# 预期接口 说明
M-04 GET /api/opportunity/stage-template/{id}/versions 阶段模板版本记录列表,无对应端点
M-05 GET /api/opportunity/scheme-card-template/{id}/versions 方案卡模板版本记录列表,无对应端点
M-06 GET /api/opportunity/pool-rule/{id}/versions 公海规则版本记录列表,无对应端点

四、总览(票 06)

实测时间:2026-08-26 实测接口条目合计:90 条(含合并/路径变更标注)

4.1 三档汇总

结论 条数 占比
存在正确(含路径变更/合并) 49 54%
⚠️ 实现有问题 2 2%
未实现 39 43%
合计 90 100%

4.2 按子域分布

子域 ⚠️ 备注
列表族 4(+2合并) 0 3 /page 统一六视图;看板3接口缺
详情/基础 0 0 5 GET/{id}、PUT/{id}、客户关联全缺
阶段推进 2 1 0 progress 参数名偏差(W-03)
方案卡 6(+1合并) 1 0 参数名偏差(W-04/05);路由均存在
跟进记录 0 0 3 全缺
现场勘察 0 0 2 全缺
附件 0 0 4 全缺
团队成员 0 0 2 全缺
操作日志 0 0 1 全缺
协作(关注) 0 0 3 全缺
状态机(流转Cmd) 0 0 13 全缺,8个Cmd无HTTP入口
规则-阶段模板 8(+1合并) 0 1 /versions缺(M-04)
规则-方案卡模板 8(+1合并) 0 1 /versions缺(M-05)
规则-公海规则 7(+1合并) 0 1 /versions缺(M-06)
规则-字典 8 1 0 groupCode偏差(W-07)
视图/自定义字段 2 0 0 路径变更(W-08),功能存在

4.3 问题清单汇总(W-)

# 接口/范围 问题描述
W-01 POST /api/opportunity/page 分页包装字段名为 content,非惯例的 records
W-02 POST /api/opportunity(新建) bid_form DB NOT NULL 无默认值,CreateOpportunityRequest 不含此字段,新建必 500
W-03 GET /api/opportunity/stage/progress 参数名实为 oppId,spec 预期 opportunityId
W-04 GET /api/opportunity/scheme-card/list 参数名实为 oppId,spec 预期 opportunityId
W-05 GET /api/opportunity/scheme-card/selectable-templates 参数名实为 oppId,spec 预期 opportunityId
W-06 规则族全部路径 spec 预期 /api/opportunity/*-template/,实际为 /api/rule/opp-*
W-07 商机相关字典 groupCode spec 预期 opportunity_stage 等,实际为 opp_stage 等短前缀
W-08 视图/自定义字段路径 spec 预期 /api/user/customize/columns,实际为 `/api/preference/get
W-09 规则族 HTTP 方法 spec 预期 RESTful DELETE/PUT + /{id}/action,实际统一用 POST + body 传 id

4.4 未实现接口汇总(M-)

# 预期接口 子域 对应原型操作
M-01 POST /api/opportunity/recent-visits/touch 列表 访问上报(最近访问数据来源)
M-02 POST /api/opportunity/board/stage-summary 列表 看板各阶段汇总
M-03 POST /api/opportunity/board/cards 列表 看板单阶段卡片按需加载
M-04 GET /api/rule/opp-stage-template/{id}/versions 规则-阶段 阶段模板版本记录
M-05 GET /api/rule/opp-scheme-template/{id}/versions 规则-方案卡 方案卡模板版本记录
M-06 GET /api/rule/opp-pool-rule/{id}/versions 规则-公海 公海规则版本记录

:详情族/跟进/勘察/附件/团队/日志/协作/状态机 Cmd 共 33 条接口全部 ,已在票 04 逐条列明,此处不重复编号,以票 04 第 2.3 节为准。

4.5 关键风险点

  1. 新建商机不可用(W-02):任何新建请求均 500,业务链条从入口就断。
  2. 状态机全缺(票 04,13 条):领取/分配/暂缓/恢复/抛公海/关闭/重启/移交 8 个 Cmd 无 HTTP 入口,商机流转核心功能完全不可用。
  3. 详情 tab 全缺:客户信息/跟进记录/现场勘察/附件/团队成员/操作日志 6 个 tab 后端全无接口,详情页仅方案卡和阶段进度可用。
  4. 规则族路径与 spec 差异大(W-06/09):功能已实现但路径/方法风格与 spec 完全不同,前端对接需全面重新对齐。