> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# Rules 规格说明

定义 Rules 页面的所有配置项、默认值和约束范围。Rules 页面用于管理者自定义店铺运营参数。

***

## 一、页面结构

Rules 页面分 4 个**可配置**区块 + 1 个**系统约束说明**区块，从上到下排列：

| # | 区块                            | 类型                                           | 说明                                           |
| - | ----------------------------- | -------------------------------------------- | -------------------------------------------- |
| 1 | Lead Temperature Time Windows | 可配置                                          | Lead 温度阶段时长                                  |
| 2 | Lead Thresholds               | 可配置（V1 仅 Attempt Threshold）                  | Cold 时 Lead 终态判定阈值（Neglected vs Unreachable） |
| 3 | Lead First Response Time      | 可配置                                          | 新 Lead 首次联系时限                                |
| 4 | Task Deadline by Priority     | 可配置                                          | AI 生成 task 的截止时间窗口                           |
| 5 | Quiet Hours                   | TCPA 硬约束（只读）+ Custom Restrictions（可配置）+ 免责声明 | TCPA 9 PM-8 AM 不可改 + 店铺可自加更严限制               |
| 6 | Revenue Benchmarks            | 可配置                                          | 营收归因假设值（单价/系数）                               |

页面顶部有两个按钮：**Reset to Defaults**（恢复默认）和 **Save Changes**（保存）。

***

## 二、Lead Temperature Time Windows

控制 Lead 温度自动降温的时间窗口。

| 配置项           | 默认值    | 范围          | 说明                       |
| ------------- | ------ | ----------- | ------------------------ |
| Hot Duration  | 1 day  | 1 – 3 days  | Hot 阶段持续时长，从 Lead 进入系统开始 |
| Warm Duration | 4 days | 2 – 14 days | Warm 阶段持续时长，Hot 结束后开始    |

> Cold = Hot + Warm 结束后自动进入。详见 [Lead Temperature](/product-design/v1/lead-tracker-feature/lead-temperature-v1.md)。

***

## 三、Lead Thresholds

控制 Lead 状态自动转换的次数阈值——一个判**意向减退**（隐性退出），一个判**失联**（已尝试足够多次未接通）。

| 配置项               | 默认值           | 范围     | 性质          | 说明                                                                                                                                        |
| ----------------- | ------------- | ------ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Stall Threshold   | 3 connections | 2 – 10 | 意向推断 / 隐性退出 | 成功接通但未推进到下一阶段的次数。触发：`bad_timing`（无拒绝信号）或 `not_interested`（负面情绪）                                                                           |
| Attempt Threshold | 3 attempts    | 2 – 10 | 联系次数边界      | **接通前**：未接通的 lead 尝试 ≥ 阈值视为已尽力 → Cold 时判 `unreachable`（客户问题）/ `neglected`（\< 阈值，员工失职）。**接通后**：曾接通过的 lead 又多次无回应 ≥ 阈值 → `lost_contact`（失联） |

### Attempt Threshold 两种应用

```
┌── 接通前 ──────────────────────────────────────┐
│ Cold 时 → 看 Status                             │
│   ├─ Status = New      → Neglected（员工没打） │
│   └─ Status = Attempted                         │
│        ├─ 次数 ≥ 3 → Unreachable（已尽力）     │
│        └─ 次数 < 3 → Neglected（员工没尽力）   │
└─────────────────────────────────────────────────┘

┌── 接通后 ──────────────────────────────────────┐
│ 曾接通过 + 后续 follow-up 多次 overdue         │
│   └─ 累计无回应 ≥ 3 → Lost Contact（失联）     │
└─────────────────────────────────────────────────┘
```

> 详见 [Lead Temperature §4](/product-design/v1/lead-tracker-feature/lead-temperature-v1.md) 和 [Lead Funnel Status](/product-design/v1/lead-tracker-feature/lead-funnel-status.md)。

***

## 四、Lead First Response Time

控制新 Lead 到达后的首次联系时限。

| 配置项                    | 默认值   | 范围         | 说明                                    |
| ---------------------- | ----- | ---------- | ------------------------------------- |
| Lead Outreach Deadline | 5 min | 1 – 30 min | Lead 必须在此时间窗口内被首次联系。Quiet Hours 自动排除  |
| Lead Outreach Due Soon | 2 min | 1 – 5 min  | Lead Outreach 到期前提前多久显示 "Due Soon" 预警 |

> 详见 [Lead Contact Cadence](/product-design/v1/lead-tracker-feature/lead-contact-cadence-v1.md)。

***

## 五、Task Deadline by Priority

控制 AI 根据通话生成的所有 task（Lead Follow-up / Booked Not Converted / Cancellation Risk / Retention / Win-back / Upgrade / Freeze Recovery / Payment Recovery / Event Promotion / Special Promotion 等 10 种 category）的截止时间，按 AI 分配的 priority 分档管理。

> ⚠️ **Lead Outreach task 不在此列** —— 由 §四 Lead First Response Time 单独管（固定 5 min，不分 priority）。

| 配置项                      | 默认值   | 范围          | 说明                                                     |
| ------------------------ | ----- | ----------- | ------------------------------------------------------ |
| High Priority Deadline   | 4 hr  | 1 – 24 hr   | 高优先级 task（如 cancellation\_risk、booked\_not\_converted） |
| Medium Priority Deadline | 24 hr | 12 – 72 hr  | 中优先级 task（如 lead\_follow\_up、upgrade）                  |
| Low Priority Deadline    | 72 hr | 48 – 168 hr | 低优先级 task（如 referral、event\_promotion）                 |
| Task Due Soon            | 1 hr  | 0.5 – 4 hr  | task 到期前提前多久显示 "Due Soon" 预警                           |

> `dueAt = createdAt + priority deadline`。员工可手动修改 dueAt。

***

## 六、Quiet Hours

由 **TCPA 硬约束（不可改）+ Custom Restrictions（店铺自定义可加可删）+ 免责声明** 三部分组成。系统强制执行 TCPA 底线，店铺可在此基础上**自加更严**的限制。

### 6.1 TCPA Mandatory（系统硬约束）

| 项目     | 状态                             |
| ------ | ------------------------------ |
| 夜间静默时段 | 9:00 PM \~ 8:00 AM（按客户当地时区）    |
| 是否可关闭  | ❌ 否（平台硬约束）                     |
| 法律依据   | TCPA 联邦法 47 U.S.C. § 227(b)(1) |
| 违规后果   | 单次 $500–$1,500，集体诉讼累积可达数百万美元   |

UI 表现：toggle 显示为 disabled + checked + ENFORCED 标签，用户**看得到但点不动**。

### 6.2 免责（州级合规不在系统范围内）

各州可能有附加要求，例如：

- 州级 Do Not Call 注册（如 NY GBL § 399-pp）
- 强制开场披露（如 NY GBL § 399-z）
- Sunday outreach 限制（FL、AL、MS、LA、SD、UT 等）
- prior express written consent（按 contact 字段管理，非店铺级开关）

请店铺根据所在州 / 客户分布情况自行咨询法律顾问。本说明不构成法律意见。

### 6.3 Custom Restrictions（店铺自定义额外限制）

店铺可在 TCPA 之外额外添加静默时段（如周日全天禁打、周六晚 6 点后禁打）。

**核心原则**：

| 原则        | 含义                                                                   |
| --------- | -------------------------------------------------------------------- |
| 只能加严，不能放松 | 系统取 TCPA + Custom 的**并集**，更严的胜出。任何试图让 9 PM-8 AM 变得允许联系的规则都拒绝保存       |
| 责任在店铺     | UI 明确标注 "Configured by store owner"。SaaS 不验证规则是否符合任何州法               |
| 数据结构      | 单条规则 = `{label, weekdays[], start_time, end_time}`，不做 per-state 自动匹配 |

**字段定义**：

| 字段           | 类型           | 说明                             |
| ------------ | ------------ | ------------------------------ |
| `label`      | string       | 规则名称（如 "Sunday All-Day"）       |
| `weekdays`   | array        | 适用星期（如 `[Sun]` 或 `[Sat, Sun]`） |
| `start_time` | time (HH:mm) | 起始时间（24h 制，按客户当地时区）            |
| `end_time`   | time (HH:mm) | 结束时间（跨午夜用 23:59）               |

**默认值**：空数组（V1 不预置任何 Custom 规则，由店铺按需添加）。

### 6.4 系统行为（应用）

**横切约束**：对所有 task 的 `dueAt` 都生效——Lead Outreach（首次外联）和 AI 生成的 10 种 task category（Lead Follow-up / Booked Not Converted / Cancellation Risk / Retention / Win-back / Upgrade / Freeze Recovery / Payment Recovery / Event Promotion / Special Promotion）全都受它约束。

- 所有 task `dueAt` 计算自动避开 **TCPA + Custom 的并集**（按**客户当地时区**判定）
- 落入静默时段的 task 自动延迟到下一个可联系时段
- TCPA 部分不可关闭；Custom 部分可由店铺管理者增删

retaintive 提供 Custom Restrictions 工具让店铺**自行配置**这些限制（如自加 "Sunday All-Day" 规则覆盖 FL 周日营销限制），但**不验证规则正确性**，也不替店铺判断哪些州法适用。请店铺根据所在州 / 客户分布情况自行咨询法律顾问。

***

## 七、Revenue Benchmarks

控制营收归因的假设值。每个配置项用于 Dashboard Impacted Revenue 的计算。

### 7.1 价格配置

| 配置项                            | 默认值  | 单位                  | 用于                                                                                                 | 说明                              |
| ------------------------------ | ---- | ------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------- |
| Customer Avg. Price            | $149 | / mo / person       | Conversion / Win-back / Cancel Save / Complaint Retention / Payment Recovery / Freeze Recovery MRR | 客单价 — 用于所有 MRR 类计算的核心 benchmark |
| Promotion Avg. Price           | $129 | / mo / person       | Promotion Revenue                                                                                  | 推广活动客单价                         |
| Upgrade Avg. Incremental Price | $40  | / mo / person       | Upgrade MRR                                                                                        | 升级方案的增量月收入                      |
| Event Avg. Registration Fee    | $30  | / person · one-time | Event Revenue                                                                                      | 活动/挑战赛平均报名费（一次性）                |

### 7.2 观察期 + 归因系数

| 配置项                                      | 默认值     | 范围            | 用于                      | 说明                     |
| ---------------------------------------- | ------- | ------------- | ----------------------- | ---------------------- |
| Complaint Retention Window               | 90 days | 30 – 180 days | Complaint Retention MRR | 投诉解决后观察期，未流失才计入归因      |
| Complaint Attribution Coefficient        | 0.60    | 0 – 1         | Complaint Retention MRR | 投诉解决 ≠ 必然留存，系数反映实际贡献度  |
| Freeze Recovery Attribution Coefficient  | 0.70    | 0 – 1         | Freeze Recovery MRR     | 冻结到期自动恢复扣款，扣除自然恢复部分    |
| Payment Recovery Attribution Coefficient | 0.75    | 0 – 1         | Payment Recovery MRR    | 部分失败支付通过自动重试自行恢复，扣除该部分 |

> 营收计算公式详见 [Dashboard Specification](/product-design/v1/dashboard-feature/dashboard-spec.md) 和 [任务与营收归因](/product-design/v1/tasks-feature/revenue-attribution.md)。

***

## 参考文档

- [Rules Feature Design](/product-design/v1/rules-feature/rules-feature.md)
- [Lead Temperature](/product-design/v1/lead-tracker-feature/lead-temperature-v1.md)
- [Lead Contact Cadence](/product-design/v1/lead-tracker-feature/lead-contact-cadence-v1.md)
- [任务与营收归因](/product-design/v1/tasks-feature/revenue-attribution.md)
- [Dashboard Specification](/product-design/v1/dashboard-feature/dashboard-spec.md)