摘要
FR-3.6-03（溯源 AI-3.6-03，Should · P2）要求为每位实体在岗经营人员配置专属 AI 数字员工分身：客户接待、商品讲解、需求咨询、订单查询、售后跟进、数据统计、多语应答；后台实时查看服务状态、对话记录、客流与成交转化。PRD 验收要点原文：「AI 身份明示；服务数据看板与人工接管可用；成交确认走人工确认流程；对话数据处理方案经合规评估」。PRD 现状说明明示「系统中暂无数字员工相关能力」，建议两步走落地并绑定试用期/付费开通机制（FR-3.2-04）同步商业化。
本 TDD 以两段式组织：底座段（对话引擎架构、digital_employee 实体首切片、TalkJS 会话维度改造、看板架构三区+对话记录占位、AI 未配置降级人类客服）无门控、立即可开工（p2-b），对话内容持久化默认关闭；接入段受三重独立门控（C-c6-dialog 对话数据留存与话术场景生产、DEP-3.9-04 成交确认钩子启用、D-dec4 商业化检查点），底座段不受阻。现状判定：对话引擎/分身配置/看板零实现（六端 src 检索 0 命中），但三块可复用底座在位——TalkJS 人类聊天骨架、唯一 LLM 通路（translation client）、实体→customer link 挂载模式。
验收要点
4 条
AI 身份明示 / 看板与人工接管可用 / 成交确认走人工流程 / 对话数据合规评估——逐条转译见方案设计
底座段子任务
7 项 · 11.5d
D1 实体+Workflow(1.5d) / D2 对话引擎+通道(3d) / D3 会话维度+明示 UI(2d) / D4 接管(1d) / D5 看板(2d) / D6 降级(1d) / D7 钩子挂接(1d)
前置 blocker
3 个（各闸独立）
D-dec4 产品边界/定价 · C-c6-dialog 对话数据评估 · DEP-3.9-04 把关框架——均不阻塞底座段
负证据（本 run 复核）
0 命中
rg -i "digital.?employee|数字员工|digital.?human" 六端 src 0 命中——对话引擎/分身配置/看板从零新建关键概念
digital_employee（命名硬约束 RK-11）
数字员工实体。employee 命名已被 B2B 组织成员占用（
company/types/common.ts:21 EmployeeDTO extends CustomerDTO）——TDD 内定 digital_employee（模块 backend/src/modules/digital-employee/），实现裁量可整体换 ai_agent，一经实现冻结不得混用。两步走（platform → seller）
PRD §7.4 原文「智能客服（平台级）→ 数字员工（个人级）」。实体
owner_type 双态（platform/seller）同构承载：Phase 1 平台级智能客服（全店单一实体），Phase 2 个人级分身（DEC-4 边界定稿后启用 seller 态生产录入）。AI 身份明示三通道
①会话开场明示文案（welcome_message 必含 AI 声明，三语内置默认）；②会话内持续标识（参与者名带 AI 标记 + 消息字段
is_ai: true）；③prompt 身份约束段（软约束，不替代前两者）。硬验收——不得伪装自然人应答（《AI 事業者ガイドライン》参考口径）。C-c6-dialog 门控
对话记录属个人信息（FR-3.6-03 合规挂钩②），APPI 影响评估清单未出。评估关闭前对话内容零留存（仅计数/状态指标，
dialog_log 表评估前不建）；留存/利用目的告知/保存期限设计标注评估前置（接入段 A）。references_only 边界
⑤把关框架（AI-3.9-04 owns，禁止两套状态机）；⑥entitlement 试用/付费机制（AI-3.2-04 owns）；⑦多语应答翻译管道与话术场景（AI-3.5-02/03 owns）；⑧产品边界划分（DEC-4 管理层决策，仅标注不预设）。
entitlement 预检
消费 AI-3.2-04 冻结签名
checkEntitlement({tool_code:"digital_employee", customer_id})——digital_employee 为首个预期绑定工具；entitled=false 走付费引导消息；机制 flag 关闭=免费态直通（承其 A8）。计费事实源在 tool_entitlement，本卡 entitlement_state 字段仅缓存展示态。人工接管（handoff）
「服务数据看板与人工接管可用」验收点：人类员工（vendor-panel 触发）以自身 TalkJS 身份
setParticipant 加入同一 conversation，接管生效=digital_employee 静默（metadata.handoff 标记）；交还为显式动作（防双应答冲突），不自动恢复。conversationId 前缀族
现状
product-/order- 前缀（ChatBox.tsx:47-49）——本卡新增 digital-employee-${digital_employee_id}-${customer_id} 前缀族（商品讲解等场景可复合 product_id）；参与者=买家 me + digital_employee 系统参与者。降级范式（NFR-3.8-01）
「未配置/故障即跳过不阻断主业务」——主业务=买卖沟通（人类通道恒可用），AI 接待为增强层。AI 未配置/LLM 失败超时/flag 关闭三态下均回退人类客服承接。
方案设计
两段式总览与设计红线
| 分段 | 门控 | 内容 | 开工条件 |
|---|---|---|---|
| 底座段 | 无门控 | ①对话引擎架构（通路复用+身份明示触点）②digital_employee 实体 ③TalkJS 会话维度改造 ④看板架构（服务状态/客流/成交转化三区+对话记录占位）⑤AI 未配置降级人类客服 | 立即可开工（p2-b）；对话内容持久化默认关闭 |
| 接入段 | 三重门控 | A 对话数据留存与利用目的告知（C-c6-dialog）B 话术场景注入生产启用（同源门控，AI-3.5-03 batch2）C 成交确认钩子生产启用（DEP-3.9-04）D 商业化检查点生产开启（D-dec4，承 AI-3.2-04 §10.3 第⑤步） | 各门控独立；底座段不受阻 |
flowchart TB
subgraph BASE["底座段（无门控，立即可开工）"]
D1["D1 实体+模块+migration+Workflow（1.5d）"]
D2["D2 对话引擎服务+webhook/REST 通道（3d）"]
D3["D3 TalkJS 会话维度+身份明示 UI（2d）"]
D4["D4 人工接管+通知（1d）"]
D5["D5 看板三区+聚合 API（2d）"]
D6["D6 降级路径+flag+单测（1d）"]
D7["D7 成交确认挂接点开发（feature 态关闭，1d）"]
D1 --> D2
D1 --> D3
D1 --> D5
D2 --> D4
D2 --> D6
D2 --> D7
end
G1{"C-c6-dialog 关闭：对话留存/告知/期限 + 话术场景生产启用"}
G2{"DEP-3.9-04 开启：把关框架 flag 后成交确认钩子挂接生效"}
G3{"D-dec4 关闭：定价/试用期定值后商业化检查点+分身自助"}
D2 --> G1
D7 --> G2
D2 --> G3
设计红线（AGENTS.md §0.1，逐条对照）
- Workflow 承载业务逻辑：digital_employee 全部状态变更走 Workflow step；
- 不修改上游源码：
@medusajs/*/@mercurjs/*/TalkJS SaaS 零触碰（TalkJS 仅经既有 App ID 开关与会话维度扩展消费）； - 后端是单一数据源：对话配置/实体/留痕以后端为准，TalkJS 仅承载消息传输 UI——对话审计与留痕以后端为准；
- 参数化 SQL：webhook 签名校验与查询全参数化。
对话引擎与 TalkJS 会话维度
会话链路为「入站 webhook → LLM 应答 → 出站 REST」三段：买家在 TalkJS ChatBox 发消息（现有 UI，发送侧零改动）→ 新增 backend/src/api/webhooks/talkjs/ 入站通道（签名校验强制），识别 conversationId 前缀族 digital-employee-* 后取 active 态实体并做 entitlement 预检 → 对话引擎服务（digital-employee 模块内 service，运行时请求-响应非 Workflow）完成上下文装配、话术注入与 LLM 调用 → 经 TalkJS REST API 以 digital_employee 参与者身份发送应答。
sequenceDiagram
autonumber
participant B as 买家（TalkJS ChatBox，发送侧零改动）
participant W as POST /api/webhooks/talkjs（新增，签名校验强制）
participant E as 对话引擎服务（digital-employee 模块）
participant L as translation client 通路（复用直调）
participant T as TalkJS REST API（后端出站，单向）
B->>W: 发送消息（conversationId 前缀族 digital-employee-*）
W->>E: 识别前缀族 → 取 digital_employee（active 校验）
E->>E: entitlement 预检（消费 AI-3.2-04 checkEntitlement 契约）
alt entitled=false
E->>T: 付费引导消息（承 AI-3.2-04 §4.5 前端呈现付费引导）
else 机制 flag 关闭（免费态直通）或 entitled=true
E->>E: 上下文装配（零留存当次上下文+商品/订单只读）+ 话术注入（scenario_code）+ 身份约束段
E->>L: LLM 调用（isAIConfigured 预检，60s 超时上限）
alt LLM 失败/超时/AI 未配置
E-->>B: 降级：不发送 AI 应答 → 会话由人类客服承接 + 接管通知
else 应答成功
E->>T: 以 digital_employee 参与者身份发送应答
T-->>B: AI 应答（参与者名带 AI 标记 + is_ai=true 字段）
end
end
| 触点 | 现状（复核行号） | 改造 |
|---|---|---|
ChatBox.tsx:47-49 | conversationId=product-…/order-… 前缀族（product_id 或 order_id 降级拼接） | 新增 digital-employee-${digital_employee_id}-${customer_id} 前缀族（商品讲解等场景可复合 digital-employee-{id}-{customer}-{product_id}）；参与者=买家 me + digital_employee 系统参与者 |
UserMessagesSection.tsx:8-14 | Inbox + syncConversation("my_conversations"+me.id) + useUnreads 未读范式 | 数字员工会话纳入同 Inbox（conversation participants 含 me 即自然聚合，TalkJS 语义内扩展；未读复用） |
Chat.tsx:11,:36-37 | NEXT_PUBLIC_TALKJS_APP_ID 开关（未配置返回 null） | 沿用：App ID 未配置=对话功能整体不可见（现状行为）；新增对话引擎独立 flag 叠加（关闭=纯人类客服） |
边界注记
b2b/h2b 前台 rg「TalkJS」0 命中——对话骨架仅 B2C storefront 在位；跨端扩展属 Phase 2 立项范围注记，本卡不越界。TalkJS SaaS 边界零改动：本卡仅经既有开关范式与会话维度扩展消费。
AI 身份明示（硬验收，三通道）与人工接管
- 会话开场明示：welcome_message 必含 AI 身份文案（三语内置默认；商家自定义文案经校验须保留 AI 声明语义——关键词校验+人工抽检）；
- 会话内持续标识：TalkJS 参与者显示名带 AI 标记（如
{name}（AI）/{name} (AI)，i18n 后缀）；自定义消息字段携is_ai: true供前端徽标渲染； - prompt 身份约束：system prompt 内嵌「以 AI 身份应答、不得否认 AI 身份、不得伪装自然人」指令段（与 UI 明示双通道——prompt 约束是软约束，UI 明示是硬验收）。
人工接管（「服务数据看板与人工接管可用」验收点）：人类员工（vendor-panel 触发）以自身 TalkJS 身份 setParticipant 加入同一 conversation（ChatBox.tsx:57-58 既有范式）；接管生效=digital_employee 静默（引擎对该会话停发应答，metadata.handoff 标记）；交还=解除 handoff 标记后 AI 恢复接待（显式动作，不自动恢复——防双应答冲突）。
LLM 通路三选一声明与降级路径
| 候选 | 评估 | 结论 |
|---|---|---|
| A. 复用直调（对话引擎 import 既有 client 纯函数调用能力） | 零新增通路审计面（SSRF 三层防护/60s 超时/加密配置全套继承）；client 为本地纯函数文件夹可跨模块调用 | ✅ 选定 |
| B. 并行新 client | 私搭第二套未经审计的 LLM 通路——任务卡明令禁止 | ❌ |
| C. 抽取公共 chat 基座 | 架构最干净但本卡时点改动面大；第三个非翻译消费方出现时按 rule-of-three 评估抽取 ai-client 公共基座（与 AI-3.3-04 §5.1 同一演进声明） | ⏳ 演进位 |
三选一结论一句话声明：本卡与 translation client 通路关系=复用（直调既有 OpenAI 兼容通路），非并行、非抽公共。配置源沿用 translation-config 加密存储与 DB 优先配置（isAIConfigured 预检范式，translation-config.ts:49-66）；对话与翻译共用 provider，若需对话独立模型，translation_config key 维度多行化与 AI-3.3-04/AI-3.5-03 为同一配置扩展协调项，三卡协调单点实施。对话 system prompt 独立组装（身份约束段+话术注入+只读业务上下文），不含 {source}/{target} 翻译占位语义。
| 故障场景 | 行为 |
|---|---|
| AI 未配置（isAIConfigured false） | 对话引擎整体静默：不发送 AI 应答，会话由人类客服承接（TalkJS 人类聊天现状形态）；触发接管通知 |
| LLM 调用失败/超时 | 同上（单次会话级降级；恢复后新消息重新走引擎）。超时即走降级路径（用户体验向超时预算数值基线立项定（DEC-5）） |
| TalkJS webhook/REST 异常 | 前端 Chat 组件为纯人类聊天现状（App ID 开关独立于引擎 flag），买卖家沟通零阻断 |
| entitlement 检查失败（DB 异常） | 承 AI-3.2-04 §5 显式声明：商业门控故障不放行（entitled=false+error 态）——与 AI 增强降级方向相反，两范式不得误套 |
| flag 关闭 | 引擎旁路=纯人类客服；已配置分身显示「暂停服务」态 |
范式句（逐字）
「未配置/故障即跳过不阻断主业务」——主业务=买卖沟通（人类通道恒可用），AI 接待为增强层。跳过路径测试点：①未配置→零 AI 应答+人类承接+通知；②LLM 5xx/超时→同①；③webhook 签名不符→401 且无副作用；④flag 关闭→引擎旁路；⑤entitlement 异常→不放行（付费引导态）。
成交确认钩子（references_only，消费 AI-3.9-04 框架）
引用声明（逐字对齐 AI-3.9-04 §4.3 消费方契约，禁止两套状态机）
数字员工接待中涉及成交确认的输出（报价承诺/订单关键条款确认等 AI 应答），按 NFR-3.9-04 枚举场景挂人工确认——消费 AI-3.9-04 三件：①draft→confirmed「未确认不生效」门禁（生效点只认 confirmed）；②ai_review_record 实体（artifact_type=digital_employee_reply，其首批三值之一）；③留痕范式 reviewed_by/reviewed_at/rejection_reason（reviewed_by=req.auth_context.actor_id 落库范式）。本卡零状态机设计——状态集/迁移表/工具全部引用其卡；本卡仅实现「生成侧挂 record + 生效侧查门禁」两侧挂接点（挂接实施随其框架 flag 开启，DEP-3.9-04 门控）。
服务数据看板（架构级；对话记录区受 C-c6-dialog 门控）
| 看板区 | 数据源（只读聚合） | 门控 |
|---|---|---|
| 服务状态 | digital_employee.status + 引擎运行态（AI 配置态 isAIConfigured 透出、降级态计数） | 无门控（无个人信息） |
| 对话记录 | 评估前置：C-c6-dialog 关闭前不落对话内容（该区仅显示会话计数/未读/接管次数，零内容留存）；关闭后按评估清单实施留存（dialog_log 表评估前不建，仅留 schema 扩展位） | C-c6-dialog 硬门控 |
| 客流 | distribution-lead 既有归因模型（distribution-lead.ts:21-31，QR 引流→会话转化漏斗口径）按 seller/时段聚合——本卡零改动只读消费 | 无门控（既有口径） |
| 成交转化 | 会话关联订单归因（conversationId↔order 关联元数据）聚合转化率；指标名 digital_employee_conversion_rate，数值基线立项定（DEC-5） | 无门控（聚合统计） |
逐端：vendor-panel 新增看板页（自家数字员工数据）；admin-panel 平台级聚合视图（Phase 1 智能客服数据）。Phase 1 看板=服务状态+客流+成交转化+会话计数；Phase 2 增分身维度筛选。
合规挂钩
| NFR / 评估项 | 影响判定 | 本卡动作 |
|---|---|---|
| AI 身份明示（合规挂钩①；《AI 事業者ガイドライン》参考） | 不得伪装自然人应答——硬验收 | 三通道（开场明示/持续标识/prompt 约束）；界面文案检查点（A1） |
| C6②（对话记录个人信息） | 须设计利用目的告知与保存期限（挂钩②原文）——评估清单未出（RK-07） | C-c6-dialog 硬门控：评估关闭前对话内容零留存；留存/告知/期限设计标注评估前置（接入段 A） |
| C6③（对话翻译越境对象升级） | 数字员工话术场景翻译属 AI-3.5-03 批次 2（同源门控） | 接入段 B 同闸声明——话术注入生产启用与其同闸 |
| NFR-3.9-04（成交确认人工把关） | 接待中涉及成交确认按枚举场景人工确认（挂钩③原文） | 消费 AI-3.9-04 框架（artifact_type=digital_employee_reply；未 confirmed 不生效）；DEP-3.9-04 门控挂接 |
| NFR-3.9-03（审计） | AI 应答调用纳入 ai_call_log 审计（承 AI-3.5-02 P-④ 载体，reference 扩展候选 digital_employee_dialog） | 引用+落位；接管/交还动作留痕（metadata.handoff 轨迹） |
| NFR-3.9-01（APPI 最小化） | 买家身份经 TalkJS 会话既有口径；对话引擎只读消费商品/订单上下文，无新增画像用途（画像归 AI-3.7-02，C6① 前置） | 只读边界声明 |
| 商业化合规 | 试用期转付费误导性缔约表示检查（特商法）随 AI-3.2-04 A5 检查用例 | 付费引导 UI 挂其检查点（承 AI-3.2-04 §6） |
外部决策点引用规范：D-dec4（产品边界/定价）、C-c6-dialog（评估）、DEC-5（响应时延/接待转化率数值）——仅引用编号，不内联臆造。
Workflow 设计（数据变更必须走 Workflow）
新 Workflow 目录 backend/src/workflows/digital-employee/：
upsert-digital-employee
steps: validate-digital-employee（owner_type/seller 必填校验；welcome_message AI 声明校验；
scenario_code 存在性校验——AI-3.5-03 枚举引用）
→ upsert-digital-employee-record
→ attach-digital-employee-link（seller/company link，复用 createRemoteLinkStep 范式
create-employees.ts:20-29；Phase 1 platform 态跳过）
→ emit "digital-employee.upserted"
补偿：事务回滚+link 拆除
transition-digital-employee
steps: load → assert-transition（draft→active→disabled 白名单，active↔disabled 可逆，守卫在 step）
→ update-status（metadata.handoff 清理于 disabled）
→ emit "digital-employee.transitioned"
补偿：快照回写对话引擎运行时（应答生成/发送）为无状态请求-响应服务，非 Workflow（无业务数据变更；对话内容留存属接入段 A，届时留痕写入以独立 Workflow/append-only 承载并随 C-c6-dialog 评估定稿）。
分期路线、迁移与回滚
Phase 1 智能客服（平台级，owner_type=platform）
引擎 + 实体平台态 + TalkJS 会话维度 + AI 身份明示
+ 看板三区 + 人工接管 + 降级 ← 底座段，无门控
Phase 2 数字员工（个人级分身，owner_type=seller）
分身配置自助化（vendor 入口）+ entitlement 商业化（D-dec4 后）
+ 话术场景注入生产（C-c6-dialog 后，AI-3.5-03 batch2 同闸）
+ 成交确认钩子生产（DEP-3.9-04 后）+ 对话数据留存（C-c6-dialog 后）
+ 跨端扩展注记（b2b/h2b——随 Phase 2 立项）| migration | 内容 | 兼容性 |
|---|---|---|
digital-employee 模块 migration | CREATE TABLE digital_employee（全列+2 索引）+ link 定义（seller/company/customer） | 新表，无存量 |
| 对话留痕表 | 评估前不建（C-c6-dialog 门控） | — |
pnpm db:reset / db:reset:demo 兼容 | 新表空表参与 reset；demo 种子不注入数字员工（引擎 flag 默认关=纯人类客服现状，种子链路零行为变化） | — |
| 变更 | 回滚路径 |
|---|---|
| 对话引擎整体 | 独立开关 featureFlags.digital_employee（medusa-config featureFlags 区，默认 false）：关闭=纯人类客服（TalkJS 人类聊天现状行为逐字节等价）；NEXT_PUBLIC_TALKJS_APP_ID 既有开关独立生效 |
| 成交确认钩子 | feature 态关闭=直通回退；框架侧总闸由 AI-3.9-04 ai_review_gate.enabled 承载（其卡 §10.2） |
| 商业化检查点 | 机制 flag tool_commercialization 关闭=免费态直通（承 AI-3.2-04 A8/§10.3） |
| 实体数据 | 状态 disabled 即业务下线；物理回滚仅限 migration down（新表无历史包袱）；已产生会话为 TalkJS SaaS 侧数据，平台侧零残留（评估前零留存声明的一致性收益） |
上线顺序建议：底座段（flag 关态交付=零行为变化）→ Phase 1 上线（flag 开启：先引擎+身份明示，观察看板与降级路径）→ 各闸关闭后按序解锁 Phase 2（C-c6-dialog→留存/话术；DEP-3.9-04→成交钩子；D-dec4→商业化+分身自助）。全卡不改动 TalkJS SaaS 边界与翻译管道语义。
数据模型与 API 契约
实体 digital_employee（首切片字段级，从零新建）
erDiagram
DIGITAL_EMPLOYEE {
text id PK "prefix digemp"
text owner_type "enum platform seller，default platform（两步走同构承载）"
text seller_id "nullable，owner_type=seller 时必填（service 层校验）"
text name "not null，渲染层强制附加 AI 标识"
text role_description "nullable，角色说明（接待范围话术）"
text script_scenario_code "default digital_employee_script（弱引用 AI-3.5-03 枚举）"
text welcome_message "nullable，必含 AI 身份明示（三语默认内置）"
jsonb language_policy "nullable，locale 白名单（复用 SUPPORTED_SOURCE_LOCALES）"
text status "enum draft active disabled，default draft"
text entitlement_state "nullable，商业化只读镜像（事实源在 tool_entitlement）"
jsonb metadata "nullable，TalkJS 绑定信息与 handoff 标记"
timestamptz created_at "标准三件套"
timestamptz updated_at "标准三件套"
timestamptz deleted_at "标准三件套"
}
SELLER |o--o{ DIGITAL_EMPLOYEE : "seller 归属（Phase 2 seller 态，link 挂载）"
COMPANY |o--o{ DIGITAL_EMPLOYEE : "B2B 组织 link（复用 createRemoteLinkStep 范式）"
| 字段 | 类型 | 约束 / 默认 | 说明 |
|---|---|---|---|
id | text | PK，prefix digemp | — |
owner_type | enum(platform, seller) | not null, default platform | 两步走同构承载：platform=Phase 1 智能客服（平台级，全店单一实体）；seller=Phase 2 个人级分身（DEC-4 边界定稿后启用 seller 态生产录入） |
seller_id | text | nullable | 商家归属（owner_type=seller 时必填，service 层校验）；link 挂载复用 create-employees.ts:20-29 范式（digital_employee_id↔seller/company/customer） |
name | text | not null | 分身显示名——渲染层强制附加 AI 标识，name 本身不得声称自然人身份（内容校验点 A1） |
role_description | text | nullable | 角色说明（接待范围话术） |
script_scenario_code | text | not null, default "digital_employee_script" | 话术场景引用——弱引用 AI-3.5-03 §4.1 scenario_code 枚举（service 层校验值存在；场景路由归其卡 owns，本卡不建场景实体） |
welcome_message | text | nullable | 会话开场文案——必须含 AI 身份明示（「本会话由 AI 助手应答」语义；i18n 三语默认文案内置） |
language_policy | jsonb | nullable | 多语应答 locale 白名单（值域复用 SUPPORTED_SOURCE_LOCALES，locale.ts:36-40；null=跟随用户 locale） |
status | enum(draft, active, disabled) | not null, default draft | 生命周期：draft（配置中）→active（接待中）→disabled（停用）；active↔disabled 可逆 |
entitlement_state | text | nullable | 商业化只读镜像（checkEntitlement 返回的 status 快照，承 AI-3.2-04 §4.5 契约；计费事实源在 tool_entitlement，本字段仅缓存展示态） |
metadata | jsonb | nullable | TalkJS 绑定信息（digital-employee 前缀族参数）、接管态标记等扩展 |
created_at / updated_at / deleted_at | timestamptz | 标准三件套 | — |
索引与约束：INDEX(owner_type, seller_id, status)（接待入口查询）；INDEX(status)。约束声明：persona 字段组（名称/角色/话术/locale）即 PRD「分身配置」首切片；话术内容本体（多语模板）归 AI-3.5-03 场景实体，本卡仅引用 scenario_code（references_only 边界）。
stateDiagram-v2
state "draft（配置中）" as D
state "active（接待中）" as A
state "disabled（停用）" as X
[*] --> D: upsert-digital-employee Workflow
D --> A: transition-digital-employee（白名单守卫在 step）
A --> X: 停用（清理 metadata.handoff）
X --> A: 重新启用（active↔disabled 可逆）
note right of A: 人工接管为会话级标记（metadata.handoff），非实体状态——接管时 AI 静默、显式交还后恢复
API 契约汇总
| 路由 | 方法 | 权限域 | 契约要点 | 错误码 |
|---|---|---|---|---|
/admin/digital-employees、/[id]、/[id]/transition | GET/POST/POST | admin | 实体 CRUD+状态流转（入 Workflow）；Phase 1 平台级实体管理 | 404 / 409（非法迁移） |
/vendor/digital-employees（或既有 vendor API 域内） | GET/POST/POST | vendor | Phase 2 商家分身自助配置（DEC-4 边界定稿后启用；Phase 1 无 vendor 入口） | 同上 |
/store/digital-employees | GET | store（customer auth） | 买家可见分身列表（active 态+AI 身份明示文案+entitlement 可用态） | — |
POST /api/webhooks/talkjs | POST | webhook 签名校验 | 对话入站通道；签名不符 401 拒绝 | 401 / 404（前缀族不匹配静默忽略+日志） |
| 看板聚合 | GET | vendor/admin | /vendor/digital-employee-dashboard、/admin/digital-employee-dashboard（四区） | — |
错误码统一
401（webhook 签名）/ 404 / 409（非法状态迁移）/ 400（validator）。
前端改动面与 i18n
前端触点（逐端）
| 端 | 改动 |
|---|---|
| storefront | ChatBox/Chat 扩展 digital-employee 会话维度；AI 身份明示徽标+开场文案渲染；UserMessagesSection Inbox 纳入（零结构改动，participants 聚合） |
| b2b / h2b storefront | 无改动（缺口⑤：无 TalkJS 骨架；跨端扩展属 Phase 2 立项范围注记） |
| vendor-panel | Phase 2：分身配置页+看板页（DEC-4 后启用） |
| admin-panel | Phase 1：平台级实体管理页+看板聚合页；成交确认复审条目经 AI-3.9-04 既有工作台消费（artifact_type=digital_employee_reply 筛选，其卡 owns 界面） |
i18n 三语言 key 规划（en / ja / zh-Hans）
| 文件 | 新增 key | 用途 |
|---|---|---|
storefront messages/{en,ja,zh-Hans}.json | digitalEmployee.badge.aiSuffix | 参与者 AI 标记后缀 |
digitalEmployee.disclosure.default | 三语开场明示默认文案 | |
digitalEmployee.untakeover.notice | 交还/暂停提示 | |
admin-panel i18n/translations/{en,zhCN,ja}.json | digitalEmployee.* | 管理命名空间（实体管理+看板页） |
三语值随实现提交；明示文案须经文案合规改写确认（日式商务表达惯例——PRD FR-3.6-03 注口径）。注（PRD 原文）：「不下班的 AI 分身」类营销表述仅限内部文档，对外口径须经文案合规改写。
验收与测试
验收标准（PRD 要点 + 技术口径）
| # | 验收标准 | 映射 |
|---|---|---|
| A1 | AI 身份明示：会话开场含 AI 声明文案（三语）；参与者名带 AI 标记；消息字段 is_ai=true 可断言；prompt 注入身份约束段；负面用例：应答文本否认 AI 身份的注入对抗抽检通过（身份明示不因对话内容被规避） | 身份三通道 / 合规挂钩 |
| A2 | 服务看板与人工接管可用：看板服务状态/客流/成交转化三区可查（对话区=计数态）；人工接管后 AI 静默、交还后恢复，全程无双应答 | 看板 / 人工接管 |
| A3 | 成交确认走人工确认流程：AI 应答中成交确认类输出生成 ai_review_record（draft 态）；未经 confirmed 的确认承诺不对外生效（负向测试——消费 AI-3.9-04 框架测试口径）；confirmed 后生效 | 成交确认钩子 |
| A4 | 对话数据处理方案经合规评估：C-c6-dialog 关闭前对话内容零留存（存储层负证据：dialog_log 表不存在+看板无内容）；评估关闭后按清单实施（后置验收） | 看板 / 合规挂钩 |
| A5 | 降级零阻断：AI 未配置/故障/超时三态下买卖沟通零阻断（人类客服承接+通知）；flag 关闭=纯人类客服 | 降级路径 / NFR-3.8-01 |
| A6 | 商业化检查点（D-dec4 后）：checkEntitlement 门控生效——trial/active 放行、expired/cancelled 付费引导、机制 flag 关闭免费态直通（承 AI-3.2-04 A8 语义） | 会话链路 / 承 AI-3.2-04 §4.5 |
| A7 | L0 门禁：本文档十要素齐备+关键锚点可 rg（Chat.tsx / ChatBox.tsx / UserMessagesSection.tsx / client.ts / create-employees.ts / company/types/common.ts / digital_employee / D-dec4 / C-c6-dialog / DEP-3.9-04 等）；translation 域 8 单测回归（client 复用无破坏） | 模板 |
测试策略（分层）
| 层 | 范围 | 明细 |
|---|---|---|
| 新增单测（实体+Workflow） | 实体/Workflow 设计 | owner_type/seller 校验；状态白名单（draft→active→disabled 矩阵）；welcome_message AI 声明校验；scenario_code 弱引用校验；link 挂载/拆除 |
| 新增单测（对话引擎） | 会话链路/降级 | webhook 签名校验（401 路径）；前缀族路由；entitlement 预检三态；LLM mock 成功/失败/超时→降级人类承接；接管静默/交还恢复；身份约束段注入断言 |
| 新增 integration（API） | API 契约 | admin CRUD+transition；store 列表（仅 active+明示文案）；webhook 端到端（mock TalkJS 出站）；看板聚合四区口径 |
| 负向测试（门禁） | A3/A4/A6 | 未 confirmed 不生效（三 artifact 口径对齐 AI-3.9-04 §8.2）；对话零留存存储层断言；entitlement 异常不放行 |
| 既有回归 | A7 | TalkJS 三组件现有行为（开关态/会话维度）不受破坏；translation 域 8 单测复跑 |
量化指标占位口径
数字员工接待转化率 digital_employee_conversion_rate（数据源：会话-订单归因聚合）、AI 应答时延 p95、人工接管响应时长、会话满意度（若后续引入评价）＝基线立项定（DEC-5）。
风险与开放问题
已识别风险
blocker
DEC-4 未决：产品边界（平台级 vs 个人级）与商业化定价未定稿
阻塞产品边界定稿（PRD 5.5 映射说明原文「划分方案随 P2 立项确认」）与商业化定价生产开启；不决策的后果为高风险 AI 场景缺统一商业口径。缓解：owner_type 双态同构承载——Phase 1 平台级智能客服先行落地，边界仅决定 Phase 2 时点；entitlement 检查点在机制 flag 关闭态=免费态直通，底座段全量可开工。
blocker
C-c6-dialog 评估清单未出：对话数据方案与话术场景生产被阻塞
阻塞对话数据方案定稿（留存/利用目的告知/保存期限——看板对话区与接入段 A）与话术场景生产启用（AI-3.5-03 batch2 同闸）。缓解：评估前零内容留存的底座段完整可交付；评估输入（对话数据流描述：webhook→LLM→REST，零留存）由本卡会话链路一节供给合规侧。
中
DEP-3.9-04 框架先行：成交确认钩子落地依赖把关框架 flag 开启
阻塞成交确认钩子落地（框架 flag 开启+artifact_type 枚举迁移后挂接生效）；不阻塞对话引擎本体架构（框架先行是消费前置非引擎前置——AI-3.9-04 §7.1 二分原文对偶）。缓解：挂接点两侧代码可先行开发（生成侧 record 调用+生效侧门禁查询，feature 态关闭=直通）；框架 flag 开启后零改造启用。
中
b2b/h2b 前台无 TalkJS 骨架：Phase 2 跨端扩展需复制会话组件
探索复核代码级新发现（rg 0 命中）——两步走的 Phase 2 若含 B2B 端数字员工，前端会话组件需跨端复制。缓解：架构级注记——Phase 1 收敛 B2C storefront；跨端扩展属 Phase 2 立项范围，本卡不越界。
低
对话应答时延体验：60s 技术上限与买家等待体感存在差距
对话应答复用 60s 上限（translation client 通路语义），用户体验向超时预算（买家等待时长）未定。缓解：数值基线立项定（DEC-5）；超时即走降级路径（人类承接+通知），零阻断兜底恒在。
前提与假设
假设
- 设计归属总口径（承任务卡 design_ownership，不得越界）：本卡 owns 对话引擎架构/digital_employee 实体/TalkJS 会话维度改造/服务数据看板架构/AI 身份明示触点；把关框架、entitlement 机制、翻译管道、话术场景、产品边界均为 references_only；
- 负证据（0 命中）为本执行 run rg 复核结论；锚点漂移双写共 1 处（Chat.tsx 卡内 :9-20 → 开关常量 :11 / 门禁 :36-37），其余复核精确成立；
- 本 TDD 为设计文档，不改任何源代码/迁移/配置（执行契约约束）。
开放问题
- DEC-4：数字员工的建设节奏与商业化定价（试用期时长、付费档位）方案——建议随 P2 立项一并决策（PRD §8.2 开放问题 4 原文）。
- C-c6-dialog：对话记录 APPI 影响评估清单的出具时点与保存期限结论（RK-07）。
- DEC-5：接待转化率基线、AI 应答时延 p95 预算、人工接管响应时长等数值定档。
- DEP-3.9-04：把关框架 flag 开启与 artifact_type 枚举迁移时点（P1 先行条目排期）。
前置决策点
Blocker 二分表（要素 7 强制完整——architectural 级硬要求）
| Blocker | 类型 | 阻塞什么 | 可并行做什么 |
|---|---|---|---|
| blocker D-dec4（P2 建设范围/试点工具选择/商业化定价，PRD 2.5/8.2-4） | management_decision | 阻塞产品边界定稿（平台级智能客服 vs 个人级分身的划分方案随 P2 立项确认）与商业化定价生产开启（承 AI-3.2-04 §10.3 第②⑤步）；不阻塞引擎架构+实体+会话维度+看板架构（findings D-dec4 does_not_block 原文：「AI-3.6-03 引擎架构层」） | 底座段全量可开工：Phase 1 平台级智能客服以 owner_type=platform 先行落地（两步走第一步不依赖边界定稿——边界仅决定 Phase 2 时点）；entitlement 检查点在机制 flag 关闭态=免费态直通 |
| blocker C-c6-dialog（对话记录/客服对话翻译 APPI 影响评估，清单未出——PRD 8.1 C6②③） | compliance_assessment | 阻塞对话数据方案定稿（对话内容留存/利用目的告知/保存期限——看板对话区与接入段 A）与话术场景生产启用（AI-3.5-03 batch2 同闸）；不阻塞引擎架构与会话维度设计（评估前零内容留存的底座段完整可交付） | 对话引擎/实体/会话/看板三区/AI 身份明示/人工接管全量并行；评估输入（对话数据流描述：webhook→LLM→REST，零留存）由本卡供给合规侧 |
| blocker DEP-3.9-04（审核把关框架延伸，AI-3.9-04 P1 先行——PRD 7.4） | internal_dependency | 阻塞成交确认钩子落地（框架 flag 开启+artifact_type 枚举迁移后挂接生效）；不阻塞对话引擎本体架构（其卡 §7.1 二分原文对偶：框架先行是消费前置非引擎前置） | 成交确认挂接点两侧代码可先行开发（生成侧 record 调用+生效侧门禁查询，feature 态关闭=直通）；框架 flag 开启后零改造启用 |
内部依赖与下游引用方
| 方向 | 条目 | 关系 |
|---|---|---|
| 上游 | AI-3.9-04-human-review-framework.md（p1） | 成交确认把关框架（references_only；禁止两套状态机） |
| 上游 | AI-3.2-04-tool-trial-and-paywall.md（p2-a） | entitlement 接口契约（references_only；首个绑定工具） |
| 上游 | AI-3.5-02-dynamic-content-translation.md（pilot） | LLM 通路底座（三选一声明对象） |
| 上游 | AI-3.5-03-vertical-scenario-translation.md（同波 p2-b） | 数字员工话术场景（scenario_code 弱引用；其 batch2 生产启用同 C-c6-dialog 闸） |
| 下游 | AI-3.6-04-offline-retail-plaza.md（C 波） | 扫码承接升级消费对话底座（DEP-3.6-03） |
| 下游 | AI-3.7-02-personal-digital-avatar.md（C 波） | 对话式购物/形象配置消费对话与多语应答底座（DEP-3.6-03 + PRD 7.5-④ 能力复用依赖） |
待决问题清单
- 前置决策 D-dec4：产品边界（平台级 vs 个人级）划分方案与试用期时长/付费档位——随 P2 立项一并决策。
- 前置决策 C-c6-dialog：对话数据留存评估关闭时点；关闭后留存/告知/期限方案按评估清单回填。
- 前置决策 DEP-3.9-04：把关框架 flag 开启时点与 digital_employee_reply 枚举迁移窗口。
- 前置决策 DEC-5：转化率基线/时延预算/接管响应时长等数值定档（立项时）。
附录：溯源对照
本文档由 docs/reports/ai-module-prd/tdd/AI-3.6-03-digital-employee.md（文档版本 v1.0，2026-10-26）转换生成。输出章节与源章节映射如下（Preserved = 保留原文内容；Summarized = 摘要化重组；Inferred = 转换侧推断标注）：
| 本文档章节 | 源章节 | 处理方式 |
|---|---|---|
| 摘要 | 元数据表 + §1.1 PRD 溯源 + §1.3 现状三态判定 + §4.0 两段式总览 | Summarized |
| 关键概念 | 文首口径声明（depth_baseline/复核约定/design_ownership）+ §1.2 关联映射 + §4.1/§4.2/§5.1/§5.3 术语 | Summarized |
| 方案设计 · 两段式总览与设计红线 | §4.0（含 AGENTS.md 红线逐条对照） | Preserved |
| 方案设计 · 对话引擎与 TalkJS 会话维度 | §4.2.1 会话链路 + §4.2.2 会话维度改造 + §2.1① 底座复核锚点 | Preserved（锚点行号、前缀族命名逐字保留） |
| 方案设计 · AI 身份明示与人工接管 | §4.2.3 + §4.2.4 | Preserved |
| 方案设计 · LLM 通路与降级路径 | §5.1 三选一声明 + §5.2 prompt 设计 + §5.3 降级与跳过路径 | Preserved（三选一结论、范式句逐字保留） |
| 方案设计 · 成交确认钩子 | §4.3（消费 AI-3.9-04 框架引用声明） | Preserved |
| 方案设计 · 服务数据看板 | §4.4（四区+门控） | Preserved |
| 方案设计 · 合规挂钩 | §6（七项挂钩表） | Preserved |
| 方案设计 · Workflow 设计 | §4.6（upsert/transition steps 链+补偿） | Preserved |
| 方案设计 · 分期路线与迁移回滚 | §9 两步走分期路线+子任务 DAG + §10 Migration/回滚/上线顺序 | Preserved（估时数值逐字保留） |
| 数据模型与 API 契约 | §4.1 字段表 + §4.5 API 契约汇总 + §4.6 Workflow 汇总 | Preserved（12 字段、5 组路由、错误码逐字保留） |
| 前端改动面与 i18n | §4.7（逐端触点+i18n key 规划） | Preserved |
| 验收与测试 | §8.1 验收标准 A1-A7 + §8.2 测试策略与量化占位 | Preserved |
| 风险与开放问题 | §3.2 缺口清单 + §7.1 blocker 表 + §7.2 依赖（风险分级为转换侧判定，与 blocker 标注对齐） | Inferred |
| 前置决策点 | §7.1 Blocker 二分表 + §7.2 内部依赖与下游引用方 | Preserved |
| 图1 / 图2 / 图3 / 图4 | §4.0 两段式+§9 子任务 DAG / §4.2.1 会话链路 / §4.1 字段表 / §4.1 status 枚举+§4.6 | Inferred（依源表格与文字绘制的可视化视图） |
溯源说明
源文档全部锚点在执行 run 以 rg/sed 逐条复核；漂移双写共 1 处（Chat.tsx 卡内 :9-20 → 开关常量 :11 / 门禁 :36-37），ChatBox.tsx:47-61、UserMessagesSection.tsx:8-14、create-employees.ts:15-40、company/types/common.ts:21（EmployeeDTO）、client.ts:1-28、distribution-lead.ts:21-31 复核精确无漂移；负证据（digital.?employee|数字员工|digital.?human 0 命中）经复核成立。内部流程标识（session/run 编号、findings 引用）属过程元数据，不影响契约性内容（实体字段表、API 契约、Workflow step 链、错误码、验收标准均完整保留）。