获客（storlead-acquisition）功能需求文档

对应目录：storlead-acquisition · Maven artifactId：storlead-acquisition · Java 包根：com.storlead.crm.acquisition

1. 模块目标

本模块核心能力不是渠道投放，而是将业务侧定义的策略和基础画像传给 Python 服务，由 Python 服务执行客户匹配与检索，再将候选客户返回 CRM，供后续入池和跟进。

2. 业务场景

运营或销售负责人在 CRM 中配置获客策略（行业、规模、地域、行为标签、预算偏好等）。
系统将策略与基础画像组装为标准请求，调用 Python 智能匹配服务。
Python 服务返回候选客户列表及匹配分、标签、推荐理由。
CRM 侧落库匹配结果，支持人工筛选、批量入客户池、建立跟进任务。

3. 功能范围

3.1 策略管理

新建/编辑/启停策略。
支持策略版本管理（每次变更形成版本快照）。
支持策略试跑（不入正式结果，仅返回预览）。

3.2 业务画像管理

维护基础画像模板（行业、企业规模、岗位、地区、关键词、负向关键词等）。
支持画像参数与策略参数合并规则（策略优先、模板兜底）。
支持画像校验（必填项、取值范围、枚举合法性）。

3.3 Python 服务对接

提供统一调用网关（HTTP/HTTPS）。
支持同步调用（小批量）与异步任务调用（大批量）。
记录请求体、响应体摘要、耗时、状态码、错误码、重试次数。
支持超时控制、重试策略、熔断与降级（避免阻塞主业务）。

3.4 匹配结果管理

存储候选客户基础信息、匹配得分、命中标签、推荐理由、来源策略版本。
去重与合并（同一客户跨任务命中时保留最新和最高分）。
支持结果筛选（分值区间、标签、区域、时间）与导出。
支持批量转入 storlead-customer 模块。

3.5 任务与流程

支持手动触发与定时触发（如每天 09:00）。
任务状态：待执行、执行中、成功、部分成功、失败、已取消。
失败任务支持重跑，并保留历史执行记录。

3.6 权限与多租户

按租户隔离策略、画像、任务、匹配结果。
仅授权角色可创建/修改策略与触发任务。
跨租户数据访问严格禁止。

4. 外部接口需求（CRM -> Python）

建议统一定义请求对象：

tenantId：租户标识
strategyId / strategyVersion
portrait：业务画像参数
limit：期望返回条数
traceId：链路追踪 ID

Python 返回建议包含：

taskId（同步可选）
candidates：候选客户集合
score：匹配分
tags：命中标签
reason：推荐理由
status / errorCode / errorMessage

5. 数据与审计需求

所有策略变更要留痕（谁在何时改了什么）。
任务执行要可追踪（入参快照、响应摘要、执行日志）。
对外返回敏感信息需脱敏或按权限控制展示。

6. 非功能需求

性能：单次同步请求建议 3-5 秒内返回；异步任务支持分页回传。
可用性：Python 服务不可用时，不影响 CRM 其他模块运行。
可观测性：提供任务成功率、平均耗时、失败原因分布监控。

7. 与其他模块边界

本模块负责“策略/画像编排 + Python 匹配调用 + 结果回收”。
客户入池后的分配与跟进由 storlead-customer 负责。
订单、邮件、营销执行分别由 storlead-order、storlead-email、storlead-marketing 负责。