unis_crm/全量商机查询接口文档.md

全量商机查询接口文档

提供 CRM 全量商机精简字段清单，包含已归档/已签单商机，不分页。

基本信息

项目	内容
接口路径	GET /api/opportunities/all
调用方	内部系统 / 系统间集成（不面向前端用户）
请求头鉴权	X-Internal-Secret（内部接口密钥）
数据范围	全量商机（含已归档/已签单），不做数据权限过滤
排序	按创建时间倒序，创建时间相同按 id 倒序
分页	无（一次性返回全部）

鉴权方式

与商机集成更新接口 PUT /api/opportunities/integration/update、OMS 退单回调接口保持一致，使用 unisbase.internal-auth 配置的密钥校验。

• 请求头字段：X-Internal-Secret（可通过 unisbase.internal-auth.header-name 覆盖）
• 秘钥值：unisbase.internal-auth.secret
• 校验逻辑：
  • 当 unisbase.internal-auth.enabled=true 时强制校验，头信息与配置密钥不一致则返回 401（内部接口鉴权失败）；
  • 当 enabled=false 时跳过鉴权（仅用于本地开发）。
• 该路径已加入 unisbase.security.permit-all-urls，不需要 Authorization: Bearer 登录态。

请求

GET /api/opportunities/all
X-Internal-Secret: <配置的secret>

无查询参数、无请求体。

响应

统一响应结构 ApiResponse<List<OpportunityFullDTO>>：

字段	类型	说明
code	string	状态码，"0" 表示成功，"-1" 表示失败
msg	string	提示信息，成功为 success
data	array	商机列表

data 元素字段：

字段	类型	对应库表字段	说明
opportunityCode	string	crm_opportunity.opportunity_code	商机编号
opportunityName	string	crm_opportunity.opportunity_name	商机名称
stageCode	string	crm_opportunity.stage	商机阶段编码（取自字典 sj_xmjd，未匹配时回退原值）
stage	string	字典 sj_xmjd.item_label	商机阶段名称（未匹配字典时按内置映射回退）
confidence	string	crm_opportunity.confidence_pct	把握度等级：A / B / C
pushedToOms	boolean	crm_opportunity.pushed_to_oms	是否已推送 OMS
omsPushTime	string	crm_opportunity.oms_push_time	推送 OMS 时间，格式 yyyy-MM-dd HH:mm，未推送为空串
createdAt	string	crm_opportunity.created_at	创建时间，格式 yyyy-MM-dd HH:mm
ownerUserId	long	crm_opportunity.owner_user_id	商机负责人 ID
ownerName	string	sys_user.display_name / username	商机负责人姓名

响应示例：

{
  "code": "0",
  "msg": "success",
  "data": [
    {
      "opportunityCode": "OPP-20260916-001",
      "opportunityName": "某某医院云桌面项目",
      "stageCode": "bidding",
      "stage": "招投标",
      "confidence": "A",
      "pushedToOms": true,
      "omsPushTime": "2026-09-16 10:30",
      "createdAt": "2026-09-10 09:12",
      "ownerUserId": 1001,
      "ownerName": "张三"
    }
  ]
}

实现说明

层	文件
Controller	backend/src/main/java/com/unis/crm/controller/OpportunityController.java（GET /all）
Service	OpportunityService#listAllOpportunities / OpportunityServiceImpl
Mapper	OpportunityMapper#selectAllOpportunities
SQL	backend/src/main/resources/mapper/opportunity/OpportunityMapper.xml
DTO	backend/src/main/java/com/unis/crm/dto/opportunity/OpportunityFullDTO.java

要点：

• 查询语句未加 archived 过滤，返回包含已归档/已签单在内的全部商机；
• 未拼接数据权限条件（opportunityVisibilityCondition），即不受当前用户数据可见范围限制，因此仅允许内部系统调用；
• 鉴权由 OpportunityController#validateInternalSecret 完成，并在 application.yml / application-prod.yml 的 unisbase.security.permit-all-urls 中放开 /api/opportunities/all；
• 已添加 @Log(type = "商机集成", value = "查询全量商机") 审计日志，记录调用留痕；
• 阶段名称通过 sys_dict_item（type_code = 'sj_xmjd'）关联获取，归档商机即使字典项被禁用也能取到名称；
• 时间字段统一由数据库格式化后返回字符串，未推送 OMS 时 omsPushTime 返回空串。