# Lead · 意向客户（Phase 3）

> 自主问卷用户信息采集的统一入口，落到 `leads` 表，供管理后台跟进。

## 接口表

| Method | Path | 鉴权 | 说明 |
|---|---|---|---|
| POST | `/api/v1/leads` | - | 提交（小程序自测问卷、首页落地等） |
| GET | `/api/v1/leads/stats` | ✅ | 统计：总数 / 24h / 按 source 分组 |
| GET | `/api/v1/admin/leads` | ✅ | 列表，支持 phone / source / keyword / 时间过滤 |
| GET | `/api/v1/admin/leads/:id` | ✅ | 详情 |
| PUT | `/api/v1/admin/leads/:id/remark` | ✅ | 修改备注 |
| DELETE | `/api/v1/admin/leads/:id` | ✅ | 删除 |

## POST /api/v1/leads

**请求体**
```json
{
  "name": "张三",
  "phone": "13800138000",
  "symptom": "便血近 1 周，伴有肛门坠胀",
  "questionnaire": {
    "total": 5,
    "answers": { "0": "sometimes", "1": "no" },
    "createdAt": "2026-06-14T08:30:00.000Z"
  },
  "source": "self-test",
  "score": 5
}
```

**校验规则**
- `name` 必填，1-20 字符
- `phone` 必填，匹配 `^1[3-9]\d{9}$`
- `symptom` 可选，≤ 500 字
- `questionnaire` 必填，任意 JSON 对象
- `source` 可选，枚举 `self-test` / `home` / `appointment` / `other`，默认 `self-test`
- `score` 可选，0-100

**响应**
```json
{ "code": 0, "message": "提交成功", "data": { "id": "lead-1781398800000", "createdAt": "2026-06-14 16:30:00" } }
```

**错误码**
| HTTP | code | message |
|---|---|---|
| 400 | 1 | 姓名必填 / 姓名长度需在 1-20 字符 |
| 400 | 1 | 手机号必填 / 手机号格式不正确 |
| 400 | 1 | 症状描述不超过 500 字 |
| 400 | 1 | 问卷答案 questionnaire 必填且为对象 |
| 400 | 1 | source 仅支持：self-test / home / appointment / other |
| 400 | 1 | 该手机号在同渠道已提交过，请勿重复 |
| 500 | 500 | 服务器内部错误 |

## GET /api/v1/admin/leads

**Query**
- `phone` 手机号精确匹配
- `source` 渠道
- `keyword` 姓名模糊匹配
- `startDate` / `endDate` 时间范围（`YYYY-MM-DD`）
- `limit` 默认 50,最大 200
- `offset` 默认 0

**响应**
```json
{
  "code": 0,
  "message": "ok",
  "data": {
    "list": [
      {
        "id": "lead-1781398800000",
        "name": "张三",
        "phone": "13800138000",
        "symptom": "便血近 1 周",
        "questionnaire": { "total": 5, "answers": {} },
        "source": "self-test",
        "score": 5,
        "remark": "",
        "createdAt": "2026-06-14 16:30:00",
        "updatedAt": "2026-06-14 16:30:00"
      }
    ],
    "total": 1,
    "limit": 50,
    "offset": 0
  }
}
```

## 数据表

```sql
CREATE TABLE leads (
  id              VARCHAR(32)  PRIMARY KEY,
  name            VARCHAR(50)  NOT NULL,
  phone           VARCHAR(20)  NOT NULL,
  symptom         TEXT,
  questionnaire   JSON         NOT NULL,
  source          VARCHAR(20)  NOT NULL DEFAULT 'self-test',
  score           INT          DEFAULT 0,
  remark          VARCHAR(500),
  created_at      DATETIME     DEFAULT CURRENT_TIMESTAMP,
  updated_at      DATETIME     DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  UNIQUE KEY uniq_phone_source (phone, source)
);
```

唯一约束 `(phone, source)`：同手机号在同一渠道只保留一条。