453 lines
20 KiB
Markdown
453 lines
20 KiB
Markdown
# 首屏卡片聊天式生时校正设计
|
||
|
||
日期：2026-07-20
|
||
|
||
状态：设计已确认，等待书面审核
|
||
|
||
## 1. 背景
|
||
|
||
产品当前存在两条名称相同、业务职责却不同的“生时校正”路径：
|
||
|
||
1. 初始化流程调用 `/api/birth-time-journey`，以动态选择题推进持久化案例；
|
||
2. 首页卡片把“生时校正”或“再次校正”放入输入框，发送后调用普通 `/api/consult`，由咨询工作流和 Agent 生成有星盘依据的自然语言分析。
|
||
|
||
初始化路径具备案例、轮次、候选、恢复和确认记录，但其宽泛年份区间选择题无法承载真实人生证据，也把高认知成本的专业服务变成了首次使用门槛。首页卡片路径能够生成专业的候选解释、技术边界和高区分度事件追问，却只形成普通聊天消息，不能持久化正式校正进度或安全更新当前排盘时间。
|
||
|
||
本设计将两条路径合并为一条：
|
||
|
||
> 首屏卡片和自然聊天是唯一用户校正流程；真实星盘推算负责判断；账户级校正案例负责保存证据、候选、费用、版本和最终确认。
|
||
|
||
## 2. 与既有设计的关系
|
||
|
||
本设计对现有文档作如下收敛：
|
||
|
||
- 取代 `2026-07-18-agent-guided-birth-time-rectification-design.md` 中“动态选择题是默认用户主流程”的决策；
|
||
- 保留该设计中的确定性候选计算、服务端证据边界、幂等动作、轮次版本、评分任务和终态安全门；
|
||
- 扩展 `2026-07-19-private-consultation-entrypoints-design.md`：`birth_time_rectification` 不再只是普通咨询提示词入口，而是正式校正案例入口；
|
||
- 取代 `2026-07-19-birth-time-terminal-completion-design.md` 中“低置信代表时间可直接采用”的新流程规则；新流程只能在明确候选确认协议成功后替换当前排盘时间；
|
||
- 历史案例和审计记录不删除。尚未完成的旧协议案例通过新修订案例承接，不原地改写历史协议和原始证据。
|
||
|
||
## 3. 目标
|
||
|
||
- 初始化只采集用户实际知道的出生事实，不强制完成生时校正；
|
||
- 未校正用户可以进入首页并自由选择使用未校正时间咨询，或先校正再咨询；
|
||
- 首屏卡片成为开始、继续和再次校正的唯一产品入口；
|
||
- 保留现有卡片咨询能够生成的专业候选解释、技术依据和动态事件追问；
|
||
- 将每轮自然语言对话归一化为正式事件证据，并持久化候选变化和推算依据；
|
||
- 支持刷新、换设备、新对话、暂停和网络重试后的安全恢复；
|
||
- 再次校正期间继续使用原确认时间，只有用户明确确认新候选后才替换；
|
||
- 一次校正案例固定收费，同一案例内的所有追问和恢复不重复收费；
|
||
- 校正完成后恢复用户之前保存的普通咨询问题。
|
||
|
||
## 4. 非目标与硬边界
|
||
|
||
- 不让大模型直接决定、写入或确认出生分钟；
|
||
- 不把普通聊天消息当作唯一校正记录；
|
||
- 不用尚未发生的未来窗口作为校正评分证据；
|
||
- 不以性格描述、情绪标签或宽泛年份区间作为默认高质量证据；
|
||
- 不要求每轮只能点击固定选项；
|
||
- 不因用户选择“都不符合”而产生异常或强迫其补充；
|
||
- 不在新校正完成前覆盖当前已确认时间；
|
||
- 不删除历史案例、旧候选、原始填报和用户确认记录；
|
||
- 不在本设计中改变普通咨询的模型选择和常规扣点价格。
|
||
|
||
## 5. 已确认的业务规则
|
||
|
||
### 5.1 初始化与软引导
|
||
|
||
初始化只采集：
|
||
|
||
- 出生日期；
|
||
- 出生地点；
|
||
- 用户知道的具体时间或大致时段；
|
||
- 时间来源；
|
||
- 用户声明的不确定范围或文字线索。
|
||
|
||
用户无需完成校正即可进入首页。未校正用户发起依赖本命盘的普通咨询时，界面提供两种选择：
|
||
|
||
1. `先用未校正时间询问`：在当前对话内继续，所有相关回答标明时间未经校正并降低分钟敏感结论的置信度；
|
||
2. `先校正再询问`：保存原始问题，启动或恢复校正案例，校正完成后再接续原问题。
|
||
|
||
“先用未校正时间询问”的选择只在当前聊天会话有效。新建聊天时重新温和提示一次，不逐条消息重复打断。用户只有时段或完全不知道具体分钟时，不得虚构工作时间；可以进入校正，或进行不依赖精确出生时间的一般咨询。
|
||
|
||
### 5.2 卡片状态
|
||
|
||
- 没有历史案例：显示 `开始生时校正`；
|
||
- 存在未完成案例：显示 `继续上次校正`，并提供次级操作 `重新开始`；
|
||
- 已有确认时间且没有未完成修订：显示 `再次校正`；
|
||
- 新修订进行中：继续使用旧确认时间，并标记 `新校正进行中`；
|
||
- 暂停、失败或放弃新修订不影响旧确认时间；
|
||
- 删除或新建聊天不删除、不重置校正案例。
|
||
|
||
### 5.3 计费
|
||
|
||
- 固定点数由服务端产品配置提供，并在卡片启动操作旁明确显示；客户端不得硬编码或自行提交价格；
|
||
- 启动全新校正案例时预留一次固定点数；
|
||
- 正式案例创建成功并展示第一轮有效专业分析后完成扣点；
|
||
- 案例创建失败、服务不可用或第一轮有效分析未生成时释放预留点数；
|
||
- 暂停、刷新、换设备和继续同一案例不重复收费；
|
||
- 同一案例中的追问、事件提取、候选重算和最终确认均包含在本次固定费用内；
|
||
- 已完成或用户明确放弃后发起全新案例，重新收取一次固定费用；
|
||
- 校正前保存的普通咨询问题不提前扣咨询点数。校正完成后，用户确认继续回答时才按普通咨询规则扣点。
|
||
- 上线前已经存在的未完成旧协议案例免费承接一次新对话式修订，避免用户为历史缺陷和协议迁移再次付费；承接后的新案例仍使用标准费用回执标记为迁移豁免。
|
||
|
||
## 6. 目标架构
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
UI["首屏卡片与聊天界面"] --> ORCH["校正对话编排器"]
|
||
ORCH --> CALC["确定性星盘与候选计算"]
|
||
CALC --> PACKET["技术差异与证据请求包"]
|
||
PACKET --> AGENT["专业解释与动态追问 Agent"]
|
||
AGENT --> VALIDATE["输出契约校验"]
|
||
VALIDATE --> UI
|
||
ORCH --> CASE["账户级校正案例"]
|
||
CASE --> EVIDENCE["事件证据与候选修订"]
|
||
EVIDENCE --> CALC
|
||
CASE --> CONFIRM["原子候选确认"]
|
||
CONFIRM --> PROFILE["账户当前排盘时间"]
|
||
```
|
||
|
||
### 6.1 首屏卡片与聊天界面
|
||
|
||
该层只负责呈现和用户输入：
|
||
|
||
- 展示完整专业解释；
|
||
- 展示事件方向按钮，例如事业、学业、搬迁；
|
||
- 始终保留自由输入；
|
||
- 展示结构化事件摘要并允许纠正；
|
||
- 展示暂停、继续、放弃和最终确认；
|
||
- 不在客户端计算候选、设置置信度或决定状态转换。
|
||
|
||
聊天会话是呈现载体，不是校正事实来源。聊天删除后，案例仍可从任意新聊天继续。
|
||
|
||
### 6.2 校正对话编排器
|
||
|
||
编排器是每轮业务动作的统一入口，负责：
|
||
|
||
- 创建、恢复或修订账户级案例；
|
||
- 读取当前声明时间、旧确认时间、候选范围和既往证据；
|
||
- 调用确定性计算生成候选差异；
|
||
- 调用 Agent 生成面向用户的专业解释和下一步事件请求；
|
||
- 校验 Agent 输出与计算包一致；
|
||
- 保存用户原文、事件提取、技术回执、可见解释和候选修订；
|
||
- 用 `actionId` 与 `turnVersion` 保证幂等和并发安全；
|
||
- 管理固定费用、暂停、恢复、放弃和原始咨询问题接续。
|
||
|
||
### 6.3 确定性计算与 Agent 的边界
|
||
|
||
确定性计算负责：
|
||
|
||
- 建立和扫描候选时间范围；
|
||
- 计算 D1 稳定性、上升边界距离和分钟敏感结构；
|
||
- 比较 D9、D10 等分盘及当前支持的技术层；
|
||
- 生成不同候选之间可验证的差异；
|
||
- 根据已经发生的事件证据重新评分；
|
||
- 产生候选范围、代表时间、可信边界和停止条件。
|
||
|
||
Agent 负责：
|
||
|
||
- 把技术包解释成自然、可理解的中文；
|
||
- 说明当前时间为何只能作为填报时间或待验证候选；
|
||
- 选择当前最有区分度且用户容易回答的事件领域；
|
||
- 询问具体、已发生、可给出日期精度的人生事件；
|
||
- 根据用户回答调整下一轮问题方向；
|
||
- 在信息不足时诚实说明，而不是生成虚假精确分钟。
|
||
|
||
Agent 不得发明技术包中不存在的盘面事实、候选时间、置信度、评分权重或确认状态。
|
||
|
||
## 7. 领域模型与持久化
|
||
|
||
### 7.1 `RectificationCase`
|
||
|
||
账户级校正案例至少包含：
|
||
|
||
```ts
|
||
type RectificationCase = {
|
||
id: string;
|
||
userId: string;
|
||
protocol: "conversational-evidence-v3";
|
||
status: "starting" | "active" | "paused" | "confirming" | "completed" | "abandoned";
|
||
turnVersion: number;
|
||
revisionOfCaseId: string | null;
|
||
importedFromCaseId: string | null;
|
||
baselineActiveTime: string | null;
|
||
declaredBirthInput: DeclaredBirthInput;
|
||
currentCandidate: CandidateRevision | null;
|
||
pendingConsultationQuestion: string | null;
|
||
billingState: "reserved" | "charged" | "released" | "migration_waived";
|
||
billingReservationId: string | null;
|
||
billingReceiptId: string | null;
|
||
};
|
||
```
|
||
|
||
`baselineActiveTime` 在再次校正期间保持为账户当前时间。候选结果保存在案例内部，不得在确认前写入账户当前排盘时间。
|
||
|
||
### 7.2 `RectificationTurn`
|
||
|
||
每轮保存：
|
||
|
||
- 当前案例版本；
|
||
- 用户可见专业解释；
|
||
- 结构化技术依据和计算版本；
|
||
- 推荐事件方向；
|
||
- 请求的日期精度；
|
||
- 用户原始回答；
|
||
- 事件提取结果；
|
||
- 本轮前后候选范围；
|
||
- Agent、模型和输出校验回执；
|
||
- 幂等动作标识与时间戳。
|
||
|
||
用户可见解释需要保留，以便恢复后理解为何进入当前问题；技术包使用结构化字段存储，不能依赖重新调用模型复原历史理由。
|
||
|
||
### 7.3 `LifeEventEvidence`
|
||
|
||
事件证据包含：
|
||
|
||
```ts
|
||
type LifeEventEvidence = {
|
||
id: string;
|
||
caseId: string;
|
||
rawText: string;
|
||
domain: "career" | "education" | "relocation" | "relationship" | "family" | "other";
|
||
eventSummary: string;
|
||
dateValue: string | null;
|
||
datePrecision: "day" | "month" | "year" | "range" | "unknown";
|
||
extractionStatus: "clear" | "needs_clarification" | "corrected";
|
||
sourceTurnId: string;
|
||
};
|
||
```
|
||
|
||
系统先保存用户原文，再保存提取结果。信息清楚时无需增加强制二次确认，但必须在下一轮以可见摘要回显并允许用户纠正；信息模糊时先追问，不进入评分。
|
||
|
||
## 8. 每轮响应契约
|
||
|
||
新校正响应必须同时包含用户可见解释与机器控制数据：
|
||
|
||
```ts
|
||
type ConversationalRectificationTurn = {
|
||
caseId: string;
|
||
turnVersion: number;
|
||
narrative: string;
|
||
candidate: {
|
||
status: "declared" | "pending_validation" | "ready_for_confirmation" | "confirmed";
|
||
representativeTime: string | null;
|
||
rangeStart: string | null;
|
||
rangeEnd: string | null;
|
||
};
|
||
technicalReceipt: {
|
||
calculationVersion: string;
|
||
stableLayers: string[];
|
||
sensitiveLayers: string[];
|
||
candidateDifferenceRefs: string[];
|
||
};
|
||
evidenceRequest: {
|
||
domains: EvidenceDomain[];
|
||
datePrecision: "month_preferred" | "year_accepted";
|
||
freeTextAllowed: true;
|
||
} | null;
|
||
actions: RectificationAction[];
|
||
};
|
||
```
|
||
|
||
界面先展示 `narrative`，再展示事件方向按钮和自由输入框。按钮只表示用户希望从哪个领域开始，不直接代表支持某个候选的评分证据。
|
||
|
||
### 8.1 回答节奏
|
||
|
||
- 首轮：完整解释当前候选、可用边界、稳定层、敏感层和最有区分度的事件方向；
|
||
- 中间轮：聚焦新证据导致的候选变化、已记录事件摘要和下一步；
|
||
- 最终轮：完整总结候选时间、支持证据、残余不确定性、确认影响和旧时间替换规则。
|
||
|
||
未来窗口可以作为背景解释，但必须标记为技术候选窗口，且不能计入校正评分。
|
||
|
||
## 9. 业务流程
|
||
|
||
### 9.1 从卡片主动开始
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
A["用户点击开始或再次校正"] --> B["创建案例并预留固定点数"]
|
||
B --> C["计算当前候选与敏感差异"]
|
||
C --> D["生成并校验首轮专业解释"]
|
||
D -->|"成功"| E["保存首轮并完成扣点"]
|
||
D -->|"失败"| F["释放点数并保留原状态"]
|
||
E --> G["用户选择事件方向或自由描述"]
|
||
G --> H["保存原文并提取事件证据"]
|
||
H --> I{"证据是否清楚"}
|
||
I -->|"否"| J["自然语言追问"]
|
||
I -->|"是"| K["重新评分候选"]
|
||
K --> L{"是否达到确认条件"}
|
||
L -->|"否"| C
|
||
L -->|"是"| M["展示完整候选确认"]
|
||
M --> N["用户明确确认"]
|
||
N --> O["原子更新当前排盘时间"]
|
||
```
|
||
|
||
### 9.2 从普通问题分流
|
||
|
||
用户选择“先校正再询问”后：
|
||
|
||
1. 原始问题保存到案例；
|
||
2. 普通咨询不扣点、不生成回答；
|
||
3. 启动或恢复校正并按固定校正费用处理；
|
||
4. 校正完成后提示 `使用新确认时间继续回答原问题`；
|
||
5. 用户确认继续时，创建普通咨询扣点并使用新确认时间回答；
|
||
6. 校正暂停时，原始问题继续保留。
|
||
|
||
### 9.3 旧案例承接
|
||
|
||
旧 `dynamic-choice-v2` 和 legacy 案例不原地改写。用户继续旧未完成案例时：
|
||
|
||
1. 读取旧案例最新候选范围、原始资料和已经形成的有效证据；
|
||
2. 创建 `conversational-evidence-v3` 修订案例，设置 `importedFromCaseId`；
|
||
3. 保留旧案例为只读历史；
|
||
4. 新案例首轮解释当前继承的候选范围，并从真实技术差异生成新的事件追问；
|
||
5. 不再向用户恢复宽泛年份区间选择题。
|
||
|
||
该承接属于同一未完成任务，使用一次 `migration_waived` 费用回执，不收取固定费用；只有明确放弃或完成后开启全新案例才按当前价格收费。
|
||
|
||
## 10. 异常恢复与一致性
|
||
|
||
### 10.1 启动与计费失败
|
||
|
||
- 案例创建、第一轮计算或第一轮有效解释失败时释放预留点数；
|
||
- 不显示成功状态，不创建无法继续的收费案例；
|
||
- 同一启动 `actionId` 重试时返回同一案例和费用结果。
|
||
|
||
### 10.2 网络错误
|
||
|
||
- 502、连接中断和非 JSON 响应使用同一幂等动作进行有限重试；
|
||
- 重试失败显示稳定中文错误和可追踪诊断分类；
|
||
- 保留用户刚输入的事件，不泄漏 WebKit 原始英文 `DOMException` 文案；
|
||
- 部署切换期间未到达业务服务的请求不得产生扣费或轮次推进。
|
||
|
||
### 10.3 并发与恢复
|
||
|
||
- 所有推进动作校验案例所有权、`turnVersion` 和 `actionId`；
|
||
- 两台设备同时操作时，旧版本返回“进度已更新”，客户端加载最新一轮；
|
||
- 刷新、换设备和新聊天根据账户未完成案例恢复；
|
||
- “都不符合”是正常答案：可以直接换事件方向，也可选填说明，不作为错误；
|
||
- 删除聊天不级联删除校正案例。
|
||
|
||
### 10.4 Agent 输出不一致
|
||
|
||
- `narrative` 中的候选时间、盘面事实和敏感层必须能映射到 `technicalReceipt`；
|
||
- 输出契约解析失败或事实不一致时，本轮不持久化为已推进状态；
|
||
- 可以重试表达生成，但不能重新计算或重复扣费；
|
||
- 多次表达失败时展示结构化安全回退，允许稍后继续。
|
||
|
||
### 10.5 原子候选确认
|
||
|
||
最终确认在单个数据库事务或等价原子 RPC 中完成：
|
||
|
||
1. 校验用户所有权；
|
||
2. 校验案例仍处于最新 `confirming` 轮次；
|
||
3. 校验候选结果、代表时间和技术版本未变化；
|
||
4. 写入用户确认和动作回执；
|
||
5. 更新账户当前排盘时间及状态；
|
||
6. 关闭本次案例；
|
||
7. 保留旧时间、原始填报、候选历史和完整证据链；
|
||
8. 返回待接续的普通咨询问题。
|
||
|
||
任一步失败均不得修改账户当前排盘时间。
|
||
|
||
## 11. 安全与隐私
|
||
|
||
- 案例、事件、候选和费用记录只能由服务端以经过身份验证的用户上下文访问；
|
||
- 用户只能读取自己的案例和用户可见解释，内部候选分区、评分权重和系统提示不下发；
|
||
- 不在日志、设计文档、测试夹具或错误消息中保存访问令牌、刷新令牌、Cookie、邮箱、用户 UUID 或真实出生资料；
|
||
- 生产问题复现使用脱敏夹具和请求形状，不复用用户粘贴的认证凭据；
|
||
- 聊天删除策略与校正案例生命周期独立，二者都必须具有所有者级 RLS 或等价服务端所有权校验。
|
||
|
||
## 12. 测试与验收
|
||
|
||
### 12.1 核心业务场景
|
||
|
||
1. 新用户只填写基础出生资料即可进入首页；
|
||
2. 未校正用户可选择使用未校正时间，或先校正再询问；
|
||
3. 使用未校正时间的选择仅在当前聊天有效；
|
||
4. 卡片能开始、继续和再次校正；
|
||
5. 第一轮有效解释生成后只扣一次固定费用；
|
||
6. 第一轮失败自动释放点数；
|
||
7. 暂停、刷新、换设备、新聊天和旧案例承接不重复收费；
|
||
8. 聊天删除不删除校正案例；
|
||
9. 再次校正期间旧确认时间持续生效；
|
||
10. 最终确认原子替换当前时间；
|
||
11. 校正完成后恢复原普通问题，并在用户确认继续时按普通咨询收费。
|
||
|
||
### 12.2 回答质量契约
|
||
|
||
首轮专业解释必须包含：
|
||
|
||
- 当前时间属于填报时间还是待验证候选；
|
||
- 当前候选可使用到什么程度；
|
||
- 真实星盘中的稳定部分和分钟敏感部分；
|
||
- 为什么选择当前事件领域；
|
||
- 至少两个适合验证的已发生事件方向；
|
||
- 对具体年月和事件描述的请求；
|
||
- 未来窗口不属于既成验证证据的边界。
|
||
|
||
建立一份完全脱敏、使用合成出生资料的专业首轮基准夹具。回归测试验证系统升级后仍能生成候选解释、技术依据和具体事件追问，而不是退化为无依据的宽泛年份按钮。
|
||
|
||
以下形式不得作为默认有效证据流程：
|
||
|
||
```text
|
||
哪一个时间段更接近一次持续的生活压力变化？
|
||
2006–2011
|
||
2011–2016
|
||
不确定
|
||
都不符合
|
||
```
|
||
|
||
只有当区间来自当前候选的真实技术差异、已解释区分目的，并且后续仍收集具体已发生事件时，区间按钮才可作为辅助入口。
|
||
|
||
### 12.3 技术与异常测试
|
||
|
||
- 重复请求不重复扣费、建案例或推进轮次；
|
||
- 旧 `turnVersion` 不能覆盖最新进度；
|
||
- “都不符合”正常换方向；
|
||
- 502、非 JSON 和 WebKit 返回稳定中文错误；
|
||
- 部署切换失败不产生费用或半完成轮次；
|
||
- Agent 事实与技术回执不一致时拒绝推进；
|
||
- 模糊事件不进入评分，用户纠正后使用修订证据；
|
||
- 未来事件不进入评分；
|
||
- 动态和新协议候选均走各自正确的确认路径；
|
||
- 确认任一步失败时保留旧时间；
|
||
- 所有者隔离、聊天删除 RLS 和案例读取权限通过认证端到端测试。
|
||
|
||
### 12.4 浏览器验收
|
||
|
||
至少覆盖桌面和 390px 移动宽度：
|
||
|
||
- 初始化可跳过校正并进入首页；
|
||
- 未校正软分流；
|
||
- 卡片的开始、继续和再次校正文案；
|
||
- 首轮完整专业解释、事件方向按钮和自由输入；
|
||
- 中间轮候选变化解释；
|
||
- 暂停、恢复、网络失败和中文错误；
|
||
- 最终候选依据、确认影响和原问题接续；
|
||
- 键盘、触屏和屏幕阅读器可完成全流程。
|
||
|
||
## 13. 分阶段交付边界
|
||
|
||
1. 先补齐候选确认、聊天删除、非 JSON 错误和部署瞬时失败等现有闭环问题；
|
||
2. 建立 `conversational-evidence-v3` 案例、轮次、事件与固定费用契约；
|
||
3. 将卡片接入正式案例和专业解释双层响应；
|
||
4. 把初始化改为事实采集和软分流，停止创建新的选择式案例；
|
||
5. 为旧未完成案例增加只读导入的新修订承接；
|
||
6. 完成认证端到端、移动端和生产可观测性验证后，再移除旧选择式用户界面。
|
||
|
||
旧协议数据、迁移代码和读取兼容在确认没有活跃依赖前保留，不以删除历史实现作为首发条件。
|
||
|
||
## 14. 成功标准
|
||
|
||
- 用户不再因生时校正被阻塞在初始化；
|
||
- 首屏卡片是唯一可见校正入口；
|
||
- 第一轮仍具备当前专业咨询式候选解释和真实事件追问能力；
|
||
- 每个专业解释都能追溯到技术回执，每个评分证据都能追溯到用户原文；
|
||
- 同一案例跨聊天、刷新和设备恢复且只收费一次；
|
||
- 未校正时间可由用户主动选择临时使用，但不会被自动标记为已确认；
|
||
- 再次校正不会提前覆盖旧确认时间；
|
||
- 最终确认原子完成，并能接续用户原普通问题；
|
||
- “都不符合”、候选确认、删除聊天和部署瞬时失败均有稳定、可恢复的生产行为。
|