# Daymaster API — 合作伙伴手册

> **本手册适用于谁：** 将 Daymaster 白标 API 集成到自家产品的合作伙伴。直接把这份 Markdown 文件交给你的 AI 编程助手（Claude Code、Cursor、Copilot）或产品团队——它自成体系、可立即落地。

> **一句话介绍 Daymaster：** 业内唯一一个在单次集成中就能返回**八字 + 紫微斗数**融合命盘、结合命盘上下文的 AI 解读、以及塔罗占卜的 API。

---

## 📋 目录

1. [快速开始 — 60 秒内完成首次调用](#quick-start)
2. [API 参考手册](#api-reference) — 每一个接口、请求、响应、错误码
3. [前端设计系统](#frontend-design-system) — 字体、颜色、组件模式
4. [商业模式建议](#business-model) — 定价、订阅、季节性打法
5. [可落地的产品点子](#product-ideas) — 15 个具体方案
6. [运维指引](#operational) — 限频、缓存、支持

---

<a id="quick-start"></a>
## 1. 快速开始 — 60 秒内完成首次调用

```bash
# 将 sk_live_… 替换为发给你的 API 密钥。
curl -X POST https://daymaster.ai/api/v1/readings/generate \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "X-End-User-Id: your_user_42" \
  -H "Content-Type: application/json" \
  -d '{
    "birth_datetime": "1990-05-15T08:00:00+08:00",
    "longitude": 121.47,
    "latitude": 31.23,
    "gender": "male",
    "include_zwds": true,
    "language": "zh"
  }'
```

返回值包含完整的八字 + 紫微斗数命盘，外加一个 `usage` 区块，说明本次计费的模块以及当月累计支出。这就是整个集成面的核心。

---

<a id="api-reference"></a>
## 2. API 参考手册

### 身份验证

每次请求都需带上：`Authorization: Bearer sk_live_…`（由你的客户经理发给你，或在 `/portal/keys` 自助生成）。

可选：`X-End-User-Id: <不透明字符串>` — 你自己的终端用户标识。我们不会把它解析为我们系统里的用户，它只会出现在你的使用事件（usage_events）里，方便你在自己这边做按用户对账。

### 模块与定价

| `module_id` | 接口 | 单次调用典型价格 | 说明 |
|---|---|---|---|
| `bazi_chart` | `POST /api/v1/readings/generate` | $0.10 | 含紫微。设置 `include_zwds: false` 可跳过紫微，价格不变。 |
| `ai_reading` | `POST /api/v1/readings/narrate` | $0.50 | 跨 10+ 生命领域的 LLM 解读，支持语气切换。 |
| `ai_reading_editor` | `POST /api/v1/readings/narrate/editor` | $0.10 | 基于已缓存原稿的纯"语气改写"。价格为 `ai_reading` 的 20%。 |
| `tarot` | `POST /api/v1/tarot` | $0.30 | 传入 `reading_id` 时带命盘上下文，否则为通用解读。 |
| `compatibility` | `POST /api/v1/compatibility` *(即将上线)* | $0.80 | 双盘合参，按用途定制。 |
| `chat` | `POST /api/v1/chat` *(即将上线)* | 每条消息 $0.02 | 围绕某份已存储解读的持续问答。 |

价格在事件发生时**冻结写入** `usage_events.unit_cost_usd` — 后续价格调整不会回溯影响历史账单。

### `POST /api/v1/readings/generate`

计算并持久化一份八字 + 紫微命盘。

**请求体**
```json
{
  "birth_datetime": "1990-05-15T08:00:00+08:00",
  "longitude": 121.47,
  "latitude": 31.23,
  "gender": "male",
  "include_zwds": true,
  "language": "zh"
}
```

| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| `birth_datetime` | 带明确时区的 ISO-8601 字符串 | 必填 | 例：`+08:00`。如果你只有本地时间没有时区，请在客户端先解算好。 |
| `longitude` | number | 必填 | 正值为东经。用于真太阳时校正。 |
| `latitude` | number | 选填 | 在高纬度地区可提升精度。 |
| `gender` | `"male" \| "female"` | 必填 | 决定大运顺逆。 |
| `include_zwds` | boolean | 选填（默认 `true`） | 如果你的产品不需要紫微，可跳过计算。 |
| `language` | `"zh" \| "en"` | 选填（默认 `"en"`） | 仅用于下游的文字解读接口。 |

**响应 `200`**
```json
{
  "chart": {
    "bazi": { "dayMaster": "甲", "year": {...}, "luckPillars": [...] },
    "zwds": { "palaces": [...], "daxians": [...] }
  },
  "reading_id": "abc-123-def",
  "usage": {
    "event_id": 42,
    "module_id": "bazi_chart",
    "unit_cost_usd": 0.10,
    "mtd_revenue_usd": 127.50
  }
}
```

### `POST /api/v1/readings/narrate`

接收一份已通过 `POST /api/v1/readings/generate` 生成的命盘，按请求的语气方案（tone profile）返回完整的 AI 解读。分析层的"原稿"（master transcript）在服务端缓存，后续调用时切换 `tone_profile` 成本很低——只会重跑编辑润色层。

**请求体**
```json
{
  "reading_id": "abc-123-def",
  "language": "zh",
  "tone_profile": "informed"
}
```

| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| `reading_id` | UUID | 必填 | 必须是本租户拥有的命盘（由 `POST /api/v1/readings/generate` 返回）。 |
| `language` | `"zh" \| "en"` | 选填（默认 `"en"`） | 解读输出语言。 |
| `tone_profile` | `"informed" \| "plain" \| "scholar"` | 选填（默认 `"informed"`） | 控制行文语域。`informed`＝术语内嵌解释、语气温和；`plain`＝零术语、偏治疗师＋教练；`scholar`＝古典学者腔，带引据。 |

**响应 `200`**
```json
{
  "reading_id": "abc-123-def",
  "reading": {
    "dayMasterLabel": "...",
    "characterArchetype": "...",
    "diseaseMedicineThesis": "...",
    "personality": "...",
    "fiveElements": "...",
    "tenGods": "...",
    "luckPillars": "...",
    "career": "...",
    "relationships": "...",
    "health": "...",
    "annualForecast": "...",
    "closingSummary": "...",
    "annualCards": "{\"careerFocus\":\"...\",\"overallFortune\":\"...\",\"opportunityArea\":\"...\",\"watchOut\":\"...\"}"
  },
  "master_reading": { /* 原始分析层（全术语、最大深度） */ },
  "tone_profile": "informed",
  "tone_profile_applied": true,
  "tone_profile_error": null,
  "language": "zh",
  "master_prompt_version": 4,
  "editor_prompt_version": 1,
  "usage": {
    "event_id": 42,
    "module_id": "ai_reading",
    "unit_cost_usd": 0.50,
    "mtd_revenue_usd": 623.50
  }
}
```

**延迟**：首次调用约 30–60 秒（四段生成 + 编辑润色）。命中原稿缓存的语气切换约 5–10 秒（仅编辑层）。

**成本优化**：如果你对同一份解读只调用一次 `narrate`，你会为原稿付一次、为编辑付一次。若之后用户切换了语气方案（例如点击"plain"按钮），请用相同的 `reading_id` 再次请求——服务端会复用缓存的 `master_reading_data`，只重跑编辑层。

**编辑层失败语义（部分成功）**：一份解读分两阶段生成——先是原稿（chunks 1–4），然后编辑层把它改写为指定语气。如果原稿成功但编辑层失败，我们会：

1. 把 `tone_profile_applied` 设为 `false`，并在 `tone_profile_error` 写入失败原因（例如 `editor_502:upstream_timeout`）。
2. 把 `reading` 填入原始原稿，保证你的 UI 总能拿到可读内容，而不是空对象。
3. **半额退款**：写入一条 `rollback` 账本条目，`{ partial: true, rollback_of: "ai_reading_tone" }`。原稿阶段成功，所以我们保留生成那一半的费用，退还语气润色那一半。

当你看到 `tone_profile_applied: false` 时，等上游恢复后就单独重试编辑层：对同一个 `reading_id`、同一个 `tone_profile` 再调一次即可——它会命中缓存的原稿，只再收编辑层那一半的费用。

### `POST /api/v1/readings/narrate/editor`

对已经生成了 `master_reading_data` 的命盘，单独跑一次"语气改写"。输出结构与 `narrate` 相同，区别在计费：此接口**拒绝**跑 4 段 master 生成，只调用编辑层，按新模块 `ai_reading_editor` 收费（默认约 $0.10——你 `ai_reading` 价格的 **20%**，开通时自动配置）。

使用场景：用户在看完初版解读后**主动切换**语气档位（例如从"informed"切到"plain"）。虽然用同样的 `reading_id` 再调 `narrate` 也能命中缓存原稿，但那样是按完整 `ai_reading` 单价收费的——本接口用更便宜的价格表达更清晰的意图。

**请求**
```json
{
  "reading_id": "abc-123-def",
  "language": "zh",
  "tone_profile": "plain"
}
```

| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| `reading_id` | UUID | 是 | 必须属于当前租户，**并且**已经存在 `master_reading_data`（即至少调用过一次 `narrate`）。 |
| `language` | `"zh" \| "en"` | 否（默认 `"en"`） | |
| `tone_profile` | `"informed" \| "plain" \| "scholar"` | 否（默认 `"informed"`） | |

**响应 `200`** — 结构与 `narrate` 相同（不含 `chart_data`）。成功时 `tone_profile_applied: true` 且 `tone_profile_error: null`；`usage.module_id` 为 `"ai_reading_editor"`。

**本接口特有的错误**

| 状态码 | `error` 代码 | 含义 |
|---|---|---|
| `403` | `module_disabled` | 你的租户没有开启 `ai_reading_editor`。如果你已经有 `ai_reading`，联系我们跑一次 `supabase/migrations/add-ai-reading-editor-module.sql`（一行 insert，零停机）。 |
| `404` | `not_found` | 该 `reading_id` 在你租户下不存在。 |
| `409` | `master_missing` | 此命盘还没有 `master_reading_data`。先调用一次 `POST /api/v1/readings/narrate` 生成原稿，之后再用本接口做低成本语气切换。 |
| `502` | `editor_failed` | 编辑层自身崩溃（三模型回退链全部返回错误）。**全额退款**——不像 `narrate` 那种"chunks 成功 + 编辑失败"的场景要保留生成部分的费用，本接口没有别的东西运行，因此整单退款。建议退避重试。 |

### `POST /api/v1/tarot`

基于种子（seed）的洗牌与抽牌，可选择性地结合某份已生成命盘作为上下文。

**请求体**
```json
{
  "spread_id": "past_present_future",
  "question": "我该不该接受这份新工作？",
  "reading_id": "abc-123-def",
  "lang": "zh",
  "skip_llm": false
}
```

| 字段 | 类型 | 是否必填 | 说明 |
|---|---|---|---|
| `spread_id` | `"daily" \| "past_present_future" \| "situation_action_outcome" \| "celtic_cross" \| "year_ahead"` | 必填 | |
| `question` | string（≤500 字） | 必填 | 会原样写入 LLM 提示词。 |
| `reading_id` | UUID | 选填 | 若提供，则牌义会结合该用户的日主 + 当前大运 + 流年来诠释。必须是你拥有的命盘。 |
| `seed` | integer | 选填 | 传入以获得可复现的抽牌结果（相同 seed ＝ 相同牌）。未传时自动生成。 |
| `lang` | `"zh" \| "en"` | 选填（默认 `"en"`） | |
| `skip_llm` | boolean | 选填（默认 `false`） | 仅返回确定性抽牌结果，不生成 LLM 叙述。计费价格不变。 |

**响应 `200`** 包含 `tarot_reading_id`、`cards[]`、`llm_response`（叙述文本）、`ai_model`（实际服务的提供商），以及相同的 `usage` 区块。

### 错误码

| 状态码 | 含义 |
|---|---|
| `400` | 请求字段无效或缺失。`error.message` 会说明具体是哪个字段。 |
| `401` | 缺少或无效的 API 密钥。 |
| `402` | 租户钱包余额不足。请充值后重试。 |
| `403` | 密钥已撤销 · 租户已暂停 · 该模块未对你开启。 |
| `404` | `reading_id` 不存在（或不属于你的租户）。 |
| `409` | 前置条件未满足（例如在还没有命盘的 `reading_id` 上调用 `narrate`——请先调 `/generate`）。 |
| `422` | 命盘无法计算（出生信息不合法，例如不存在的日期）。 |
| `502` | 命盘生成失败（LLM 四段在整个降级链（Haiku → DeepSeek → GPT → Kimi）之后仍然崩溃）。全额退款。如果只是编辑层失败，见上文的部分成功语义——调用会返回 `200`，并带 `tone_profile_applied: false`。 |
| `503` | 数据库或内部密钥暂时不可用。请用指数退避重试。 |

每个错误响应都是 JSON：`{ "error": "<code>", "message": "<人类可读的说明>" }`。

### 隐私：解读文本不带姓名保证

AI 解读**严格以第二人称"你"书写**。即便你的请求传入了姓名，我们也不会把终端用户的姓名、别名或昵称嵌入解读正文。这条规则在系统提示词层强制执行，源代码层面有自动化护栏，并通过 `master_prompt_version` 字段对外对账——该保证如有变更会相应提升版本号。

**为什么这对你很重要：** 我们按命盘签名（四柱 + 性别 + 语言 + 年份）缓存解读，可能会把一个合作伙伴生成的解读服务给另一个合作伙伴的同签名终端用户。因为正文里没有姓名，这种复用始终是安全的——不会发生跨租户的 PII 泄漏。如果你需要在解读之外做姓名相关的个性化（例如在 UI 里插入用户的称呼），请在收到我们的返回后在你这边处理。

当前保证：`NARRATIVE_PROMPT_VERSION = 4`。未来任何改变这条规则的版本升级，都会在变更日志里提前 30 天公告。

### 版本化策略

`/api/v1/*` 稳定。我们**绝不会**在不升级版本的前提下改动已有接口的返回结构。v1 内的新增接口属于增量变更——我们发布新模块时你的既有集成永远不会被打破。

你可以针对两个提示词版本戳（prompt-version stamps）做对账：

- `master_prompt_version` — 分析原稿（chunks 1–4）。当前为 `4`。
- `editor_prompt_version` — 语气改写层。当前为 `1`。

两个字段都会出现在每一次 `/narrate` 响应里，便于你检测底层模型何时升级、需要重跑时自行触发。

### 限频

默认**每租户 60 req/min**（所有模块合计）。可按需上调；我们在租户上按模块维度保存了 `rate_limit_per_min`，可以后台调整而无需你改代码。触发限频时返回 `429`，并带 `Retry-After` 头。

### 当月累计用量

每个成功响应都会带 `usage.mtd_revenue_usd`，方便你在客户端直接做预算控制，无需再请求一次。要看详细用量，请登录合作伙伴门户 `https://daymaster.ai/portal`：可用你的 API 密钥（只读模式）或受邀的邮箱账号。

---

<a id="frontend-design-system"></a>
## 3. 前端设计系统

这一节是**建议，不是约束**。我们的 API 返回干净的 JSON，从不限制你的 UI 怎么做。下列指引记录了我们在自家 B2C 产品上验证过、并且在命理 / 塔罗 / 身心健康领域经得起迁移的模式。

### 3.1 字体

命理内容配衬线字体（serif）阅读体验最好。我们推荐两种字族：

| 用途 | 字体 | 字重 | 字号阶梯 |
|---|---|---|---|
| 标题 / 牌名 | **思源宋体**（或 Cormorant Garamond、Playfair Display） | 300–400 | 28 / 36 / 48 / 64 |
| 正文 / 牌义 | 同一衬线字体的 300 字重 | 300 | 13 / 14 / 15 |
| UI / 按钮 / 标签 | **Inter** 或系统无衬线 | 400–500 | 10 / 11 / 12 |
| 强调（序号、字符饰） | **Georgia** 或数字风衬线 | 400 | 14 / 18 / 28 |

一种衬线 + 一种无衬线，就是整个字体系统的全部。请抵住加第三个字族的冲动。

### 3.2 色板

核心中性色 + 一个品牌重色，就足够撑起整个产品。

```css
/* Daymaster 品牌色板 — CSS 自定义属性 */
:root {
  /* 中性色 */
  --bg:            #FCFBF7;   /* 暖米色背景，永远不要用纯白 */
  --surface:       #FFFFFF;
  --ink:           #0A0A0A;   /* 正文 */
  --ink-soft:      #3A3A3A;
  --muted:         #888888;
  --hairline:      rgba(0,0,0,0.08);

  /* 品牌重色 — 古金 */
  --gold:          #B8860B;
  --gold-tint:     #F5D98A;
  --gold-bg:       rgba(184,134,11,0.08);

  /* 五行色 — 仅用于卡片点缀，切忌滥用 */
  --wood:          #2D8B4E;   /* 木 翠绿 */
  --fire:          #C4382A;   /* 火 朱红 */
  --earth:         #B8860B;   /* 土 赭黄（＝古金） */
  --metal:         #8C8C8C;   /* 金 银白 */
  --water:         #2563EB;   /* 水 靛蓝 */

  /* 语义色 — 命理产品里不要用刺眼红做错误提示， */
  /* 使用沉稳的中性色，不要触发用户的警觉疲劳。 */
  --error:         #A03020;
  --error-bg:      #FFF4F0;
  --success:       #2E7D32;
}
```

### 3.3 间距与节奏

用 4px 基线网格。卡片内留白建议 16/20/24；区块之间 40/56/80。

### 3.4 组件模式

四个原型基本覆盖塔罗 / 八字 / 紫微的 UI 需求。

**A. 统计卡片** — 用于当月消费、余额、分数等。
```
┌──────────────────────────────┐
│ 标签（大写, 10px, 金色）      │
│                              │
│ 1,247         (28-36px, 300) │
│                              │
│ 副标题（11-12px, 灰）        │
└──────────────────────────────┘
```

**B. 网格卡片** — 用于塔罗牌、命盘摘要、合参配对。2:3 纵横比 + 五行色发丝描边 + 四角装饰。

**C. 华丽分隔** — 一条金色水平线，居中放一个 `✦`。用于大块之间的分隔，不要在块内乱用。

**D. 折叠面板 / 可展开区块** — 八字解读里每个生命领域（事业 / 财富 / 感情 / 健康 / …）都应该支持折叠。解读本来就长，一次性平铺会把读者劝退。

### 3.5 移动端

- **栅格规则**：使用 `minmax(min(100%, Xpx), 1fr)` 模式（而不是 `minmax(Xpx, 1fr)`），这样窄屏上列会自动堆叠，不需要 JS 断点钩子。
- **触控目标**：图标按钮最小 40×40。关键 UI（退出登录、侧栏开关）在移动端应该比桌面端**更大**而不是更小。
- **表格**：移动端永远不要渲染原生 `<table>`。把每行转换为带键值对的堆叠卡片。

### 3.6 要避开的

- **在中文市场之外用红色代表吉** — 读者会把它解读为警告 / 报警。
- **写实的"玄学"插画**（水晶球、发光的手）。过时、廉价、劝退现代买家。
- **紫色霓虹渐变**。2018 年代占星 app 的默认配色；会把男性和严肃买家直接劝退。
- **正文里用 emoji**。用在标签 / CTA 里可以，用在段落里就是噪音。
- **三种或以上的字族**。严格两种。

---

<a id="business-model"></a>
## 4. 商业模式建议

一份深度个性化解读的 COGS（营业成本）通常在 $0.10–$0.50，取决于用了哪些模块。而同样这份体验在多数市场里的**客户愿付价**是 **$15–$100**。这中间的差价就是生意——你如何结构化地把它收走，决定了你的单位经济到底是 10% 毛利还是 90% 毛利。

### 4.1 四种定价原型

**选一个。**第一年不要同时跑两种——那样会切碎客户的认知，也会让 LTV 对比数据失效。

#### 原型 A — 单份报告定价（每份 $29–$149）

**运作方式：** 客户进来，填入生辰，花 $29 买一份性格报告，或花 $99 买一份人生大方向的高阶套餐。一次性交易。

**单位经济：** $29 零售价 · $0.50 COGS · 3% Stripe 费率 + 15% 广告 + 5% 客服 ≈ **75% 毛利**。资本效率极高。

**最适合：** 有强获客能力的合作伙伴（已有受众、邮件列表、创作者流量）。内容营销友好，因为每份报告都能生成可分享的成品。

**短板：** 没有复购收入。LTV ＝ 每客户 1–2 次交易。你会被获客跑步机永远追赶。

#### 原型 B — 订阅制（每月 $9.99–$24.99）

**运作方式：** 每月固定费用换取无限解读 + 每日指引 + 塔罗抽牌。替代"我最近想查查命盘怎么说"的一次性冲动消费。

**单位经济：** 每月 $14.99 · 平均 6 次解读 + 10 次塔罗 · COGS ≈ $3.50/月 ≈ **76% 毛利**。更关键的是混合 LTV 能到 8–14 个月，即每客户 $120–$210，比单份报告高出 **4–8 倍**。

**最适合：** 有轻量级持续运营能力的合作伙伴（社媒沉淀、邮件培育、推送通知）。CHANI、Sanctuary、Bazi.ai 都在这一层。

**短板：** 流失是全部的胜负手。"每天都有价值"必须真能做到，不能假装。

#### 原型 C — 咨询 / 专业服务（每次 $200–$2,000+）

**运作方式：** 你用 API 给一位真人顾问装上命盘分析的"雷达"，然后这位顾问在 Zoom 上做 60–90 分钟的深度解读。API 是你的助研，顾问才是产品。

**单位经济：** 每次 $500 · API 成本 $2 · 顾问分成 50% ≈ 净利 $248。低频、高毛利。

**最适合：** 手里有可培训顾问网络的合作伙伴（八字师傅、占星师、生命教练）。李居明、Joey Yap 的门徒体系就是范本。

**短板：** 无法线性放大；每位顾问都是瓶颈。但这也是整个品类里**最难被攻破**的位次——人 + 技术一定赢过二者择一。

#### 原型 D — 在非命理产品里的嵌入功能

**运作方式：** 约会 app 加一个"合参解锁"付费功能。情侣治疗 app 在引导流程里加一个"爱的语言 + 命理画像"。育儿 app 加一个"中文起名建议"。命理不是你的主产品，而是能提升主产品留存的一个功能。

**单位经济：** API 成本被计入 CAC / 留存成本。ROI 用主产品的 KPI（DAU、LTV）来衡量，而不是直接的解读收入。

**最适合：** 有现成产品、希望在不重建团队的情况下做差异化的合作伙伴。

**短板：** 发现路径只在你现有用户池内部，拿不到命理品类的自然搜索流量。

### 4.2 免费层架构

无论选哪个原型，B2C 场景下**某种形式的免费层都是必要的**。

**可以免费送的：**
- ✅ 基础八字命盘（四柱、日主、不含文字解读）。你的成本：$0.10。
- ✅ 一小段解读"味觉样品"（"你的核心驱动力是……"）。一次小 LLM 调用，约 $0.02。
- ✅ 五行分布条形图。免费——已包含在命盘里。
- ✅ 一段生肖合参结论（免费，纯确定性算法）。

**绝不要免费送的：**
- ❌ 横跨 10+ 生命领域的完整 AI 解读——这是 $29 的产品本体。
- ❌ 带年龄标记的大运时间轴——"我人生的黄金十年什么时候开始"这一瞬间，是你最强的付费墙。
- ❌ 塔罗抽牌——每次抽牌都是一次真实 LLM 调用；免费塔罗＝烧钱篝火。

**"战争迷雾"技巧：** 把完整解读的**结构**（章节标题、运势峰值年龄、时间轴坐标）展示给用户，但把**实际内容**模糊或锁起来，直到付费解锁。这样能传达"内容很全"，又不会把价值给出去。

### 4.3 季节性收入规律

这些是真实存在的规律。请围绕它们来规划你的发布、促销和备货。

| 时间窗 | 峰值月份 | 用户想要什么 | 价格敏感度 |
|---|---|---|---|
| **中国新年** | 1–2 月 | 全年运势、年度飞星报告 | 低（文化刚需） |
| **情人节 / Q1** | 2 月 | 合参 + 感情解读 | 中 |
| **婚庆旺季** | 5–8 月（西历） / 10–12 月（华人） | 合参 + 择日 | 低 |
| **开学季** | 8–9 月 | 儿童命盘、起名、职业指引 | 中 |
| **Q4 节庆** | 11–12 月 | 礼物解读、亲友套餐 | 中高（礼物品类） |
| **年度新愿** | 12/26 – 1/15 | 人生方向、事业转型、健康年运 | 中 |

**仅中国新年一项，就可能占这个品类 Q1 全年收入的 40%**——不是开玩笑。你的中国新年产品要在**10 月**就上线，这样到 1 月内容才来得及被搜索引擎收录。

### 4.4 真正能跑通的定价阶梯

如果你决定做阶梯定价，下面这个结构能可靠地做出"中间档 70% 转化"的金发姑娘效应：

| 档位 | 价格 | 包含 | 倍率 |
|---|---|---|---|
| **基础** | $29 | 命盘 + 一个生命领域解读 | 1× |
| **完整** *(主推)* | $79 | 完整 10 领域 + 年运 + 3 张塔罗 | 2.7× |
| **大师** | $199 | 完整 + 30 分钟真人咨询 + 后续塔罗包 | 6.9× |

中间档是锚点。底档的存在是为了让中间档显得大方；顶档的存在是为了让中间档显得划算。绝大多数买家会选完整。

### 4.5 分销 / 联盟分成

如果你通过创作者（占星 YouTuber、身心健康达人、生命教练）分销：

- **基础佣金**：首单 25–35%。低于 20%＝创作者懒得推；高于 40%＝毛利崩盘，还会吸引垃圾 affiliate。
- **终身分成**（可选）：订阅的 10%，持续 12 个月。能让创作者把你当长期伙伴而不是一锤子买卖。
- **结算周期**：每月通过 Stripe Connect 或 PayPal 结算。Net-30 会毁掉创作者的信任。

### 4.6 高吞吐量场景的成本控制

如果你每月做到 10k+ 次解读：

- **在你这边按出生三元组缓存命盘数据**。相同的 `(datetime, longitude, gender)` 产生相同的命盘——在你自己的数据库里重算一次，而不是调两次我们的 API。
- **夜间批量生成**，适用于可预测的需求场景（如每日指引邮件）。我们底层由 Anthropic 支撑的接口在延迟允许时会使用 Batch API。
- **谈判量价**。每月调用 50k+ 次时，价格可谈——把预估量发到 `api@daymaster.ai`。

---

<a id="product-ideas"></a>
## 5. 可基于 API 构建的产品点子

具体可落地的思路。每一条都指定了会用到的模块、一个目标价、以及我们认为可行（或者自己有受众的话也会做）的理由。

### 消费者 app

**1. Daymaster — 每日个性化指引（iOS / Android）**
每天早上推一条根据用户日主×当天日柱生成的一段式解读。前 7 天免费，之后 $4.99/月。用到的模块：`bazi_chart`（注册时一次）+ `chat`（每天一次）。留存对标：Co-Star / Calm。

**2. Mingpan — 极简命盘钱包**
给用户建一个"命盘图书馆"，放他在意的每一个亲友的八字 + 紫微。核心使用循环是："我姐最近的工作焦虑，命盘怎么说？" 免费层：3 张命盘；付费 ($7.99/月)：无限 + 每人每月运势更新。模块：`bazi_chart` + `ai_reading`。

**3. Bond — 情侣合参订阅**
双方各上传自己的生辰。app 生成一份合参报告，标出六个摩擦点（沟通、吵架方式、亲密、金钱、育儿、姻亲），并按合参盘每月推送关系复盘。$19.99/月。模块：`bazi_chart`（×2）+ `compatibility` + `chat`。

**4. 塔罗日记 — 每日抽牌习惯**
早上抽一张。晚上反思提示词。每周打卡。每月一次年度牌阵。$9.99/月。模块：`tarot`（每天 1 次，30/月，$9 COGS，单做毛利仅 10%——必须叠加风水或合参模块才能拉到 60%+ 混合毛利）。

**5. 择吉日 — 婚期 / 搬家 / 启动的择日工具**
提交两份命盘（或单人），app 返回未来 180 天内按吉利程度排序的日期并给出理由。每次查询 $29，一次性。模块：`bazi_chart` + 在其之上的定制计算（`auspicious_date` 接口 2026 年 Q2 发布）。

### B2B / 嵌入式功能

**6. 企业福利平台的身心健康插件**
已有 HR SaaS（Headspace、Lyra、Modern Health）接入一个"性格与人生路径"模块供员工使用。企业按员工 $2–$5/月付费，员工通过 SSO 访问。留存即服务——让 HR 工具变得更难卸载。模块：`bazi_chart` + `ai_reading`。

**7. 约会 app 的合参解锁**
已有约会 app（Hinge、Bumble、下一个 Hinge）加一个站内购买：$2.99 看到你与某个匹配对象的"命理契合度"。按每轮滑动的边际收入计。模块：`compatibility`，用 Hinge 的 profile ID 传 `X-End-User-Id`。约会 app 这边无需新基建——我们的 API 负责持久化。

**8. 育儿 / 起名服务**
中国家长想要平衡宝宝八字的名字。一个 API 驱动的生成器产出候选名字，每一个都按宝宝的日主打分。白标给华人海外育儿站。模块：`bazi_chart` + 即将上线的 `name_suggestion` 模块。

**9. 财务顾问的差异化获客**
财富管理或理财顾问给潜在客户提供一份免费的"财务人格报告"，用事业宫 + 财帛宫做破冰话题。转化率比通用的 MBTI 高 30%，因为它既新奇又个性化。模块：`bazi_chart` + `ai_reading`。

### 代运营 / 创作者服务

**10. 占星创作者的入门 SaaS**
一位 YouTuber 或 TikTok 占星师为自己的粉丝上线一款 $9.99/月的订阅 app。每月订阅者收到：个性化月度运势 + 一次塔罗 + 创作者的 Q&A 直播。创作者分 70%，我们拿每订阅者 $0.50–$2 的 API 成本。模块：全栈。

**11. 企业团建工作坊套装**
打包内容：10 名员工的命盘团建报告 + 90 分钟 Zoom 带教。每团 $2,000。卖给 HR / 组织发展买家。模块：`bazi_chart` + `ai_reading` + `compatibility`（用于团队动力学）。真人顾问层捕获大部分毛利。

**12. 内容农场 — SEO 落地页**
做 60 个按日柱划分的落地页（甲子 / 乙丑 / … / 癸亥），每页是一份深度人格画像。围绕 "甲子日 特点" / "Jia Zi personality" 等关键词做 SEO。通过联盟链接回你的解读产品变现。模块：每个落地页调一次 `bazi_chart`（60 次总共 $6 内容成本）。

**13. 礼物装 — "命理解读礼品卡"**
零售产品：$49 礼品卡，为收卡人解锁一份完整解读。在礼品店、企业礼赠平台、婚庆场景销售。实体盒子 + 二维码。礼品品类毛利普遍 60%+，因为价格弹性几乎为零。模块：兑换时的 `bazi_chart` + `ai_reading`。

### 小众垂直

**14. 宠物八字（是的，真的可以做）**
面向爱宠人群。同一套八字算法对宠物照样生效（用出生时间即可）。"你的猫是火旺戏精，这是她凌晨 3 点嚎叫的原因。" 每只 $12.99。纯 LTV 玩法——爱猫人士愿意为她的猫付钱。模块：`bazi_chart` + `ai_reading`（用针对宠物调过的系统提示词）。

**15. 冥想 app 的个性化引导**
已有冥想 app（Calm、Waking Up、Ten Percent Happier）加一个"按你的命盘定制的冥想会话"功能。用户的主导五行决定会话类型（火旺→舒缓呼吸；金旺→结构化清明冥想）。模块：一次性的 `bazi_chart`；内容是你已有音频库的重新打标。

### 我们不会帮你做的

**反理想客户（anti-ICP）——不要用我们的 API 做这些：**
- **预测股票 / 彩票号码**。不在我们的赛道。监管风险对所有人都危险。
- **医学或心理诊断**。命盘是一个反思工具，不是诊断工具。
- **不择手段的留存黑模式产品**。无限期订阅陷阱会连累整个品类。
- **把我们的输出冒充为你自家专有模型**。我们的服务条款要求在至少一个用户可见的位置标注 "Powered by Daymaster" 或同等表述。

---

<a id="operational"></a>
## 6. 运维指引

### 支持

- **技术问题**（API 报错、限频、新接口）：`api@daymaster.ai` — 24 小时内回复。
- **财务 / 发票问题**：`billing@daymaster.ai` — 每月 1 号开具月度发票。
- **商务 / 合作**（联合市场、量价、功能请求）：你的专属客户经理。

### SLA

- **`/api/v1/readings/generate`**：可用性目标 99.9%。p95 延迟 < 500ms（命盘计算确定性，无 LLM）。
- **`/api/v1/tarot`**：可用性目标 99.5%。p95 延迟 < 6s（含 LLM 调用）。降级链：Claude Haiku → DeepSeek → GPT-4o → Kimi。响应里的 `fellBack: true` 会告诉你实际由哪个 provider 服务的。
- **计划内维护**：至少提前 48 小时通过邮件告知你的联系地址。维护窗口安排在 UTC 凌晨 6am–2am 之外。

### 你这边建议的监控

至少要布这三个报警：

1. **5xx 突增** —— 从你的边缘打到我们的 API 的错误率（阈值：5 分钟内 > 1%）。
2. **成本异常** —— 当月累计预估到达常态 2 倍时——可能是你这边的某条未封顶的滥用路径。
3. **限频触发**（429 响应）—— 说明你需要申请上调限频额度。

### 署名要求

你的产品必须在至少一个用户可见的位置标注 "Powered by Daymaster" 或 "Chart intelligence by Daymaster"（页脚、关于页、credits、设置页都可以，你自选）。如果需要 logo 素材，在任意与你客户经理的邮件里回复 `LOGO` 即可。

---

## 附录 — 术语表

| 术语 | 含义 |
|---|---|
| **八字** / Bazi | "八个字"——以年柱、月柱、日柱、时柱为基础的中国命盘。 |
| **日主** / Day Master | 日柱的天干；命盘的中心参照点。 |
| **大运** / Da Yun | 大运柱——一段 10 年的人生时期，有自己的干支组合。 |
| **流年** / Liu Nian | 年柱——每个公历年都有一对干支与命盘发生互动。 |
| **紫微斗数** / ZWDS | Zi Wei Dou Shu — "紫微斗数"。十二宫命盘，十四主星。 |
| **宫** / Palace | 紫微盘中十二个生命领域之一（命、财帛、官禄、夫妻等）。 |
| **五行** / Wu Xing | 木、火、土、金、水。驱动合参与元素桥接。 |
| **用神 / 忌神** | 对命局有益 / 有害的五行。 |
| **塔罗牌阵** / Tarot spread | 由若干牌位组成的命名式布局（例如过去/现在/未来＝3 位）。 |

---

## 变更日志

- **v1.2** (2026-04-24) — 上线 `POST /api/v1/readings/narrate/editor`。在缓存原稿之上做显式语气切换的独立接口，按新模块 `ai_reading_editor` 计费（约 $0.10，`ai_reading` 的 20%）。在 `narrate` 之前调用会返回 `409 master_missing`；`502` 触发**全额**退款（不是半额，因为本接口里 chunks 根本没跑）。所有已开通 `ai_reading` 的租户在接入时都会自动开启 `ai_reading_editor`。
- **v1.1** (2026-04-21) — 上线 `POST /api/v1/readings/narrate`，支持三种语气方案（informed / plain / scholar）、缓存原稿的语气切换、以及部分成功语义：编辑层失败时返回 `tone_profile_applied: false`、在 `reading` 中回退到原稿、并半额退款。正式文档化了"解读不带姓名"保证，`master_prompt_version` 提升至 `4`。错误码表新增 `402`（钱包余额不足）与 `409`（前置条件未满足）。
- **v1.0** (2026-04-20) — 初版手册：API 参考、设计系统、商业模式、产品点子。

*本手册未覆盖的问题请发邮件到 `api@daymaster.ai`。*