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

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

## 1. 模块目标

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

## 2. 业务场景

1. 运营或销售负责人在 CRM 中配置获客策略（行业、规模、地域、行为标签、预算偏好等）。
2. 系统将策略与基础画像组装为标准请求，调用 Python 智能匹配服务。
3. Python 服务返回候选客户列表及匹配分、标签、推荐理由。
4. 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` 负责。