# DELIVERY.md · 本次交付与后续 TODO

> 交付时间：2026-04-24
> 版本：v3.0 Per-biz OpenClaw
> 交付人：Claude Code (Opus 4.7)

## 🌐 已上线可访问 URL

| 路径 | URL | 说明 |
|---|---|---|
| 总览 | https://kefu-ee2.pages.dev/ | 入口 + 导航 |
| **★ 可交互 Demo** | **https://kefu-ee2.pages.dev/demo** | **浮窗真实对话（mock 版）· 退款流程端到端走通** |
| 交互原型 | https://kefu-ee2.pages.dev/prototype | 三大端全视图（Widget / 坐席台 / 管理台） |
| 方案 v3.0 | https://kefu-ee2.pages.dev/customer-service-plan | 总体方案（19 章） |
| 任务清单 | https://kefu-ee2.pages.dev/customer-service-tasks | Agent 执行用任务 |
| 交付说明 | https://kefu-ee2.pages.dev/DELIVERY.md | 本文件 |
| widget.js | https://kefu-ee2.pages.dev/widget.js | 嵌入脚本（6.80 KB / gzip 2.87 KB） |
| mock API | https://cs-api-mock.schetkovvlad.workers.dev/ | cs-api 的 mock 版本（退款状态机） |

**端到端自测通过**（用 WS 跑了一遍）：发「我要退款」→ 填手机号 / 订单号 / 原因 / 确认 → 返回模拟工单号 `TK-YMVW`。

### 嵌入第三方站点

```html
<script src="https://kefu-ee2.pages.dev/widget.js" data-biz="ytk" async></script>
```

可选 `data-api="https://your-cs-api..."` 覆盖默认 mock endpoint。

### 本次上线的 Cloudflare 资源

- **Pages** `kefu` → `kefu-ee2.pages.dev`（docs + widget 合并部署）
- **Workers** `cs-api-mock` → `cs-api-mock.schetkovvlad.workers.dev`（纯 mock，无 D1/DO）
- D1 / DO / R2 / Access / Turnstile / Tunnel 等**生产资源尚未创建**（真 cs-api 上线前需要）

### 服务器侧

生产服务器 `69.30.251.10` 的部署（OpenClaw 修复 + workspace 推送 + Tunnel 配置）**未执行** —— 沙箱默认拦截了以共享凭据 SSH 到生产机的动作。如需要我直接上服务器处理，请在 Claude Code settings 中允许 `Bash(ssh customer@69.30.251.10:*)` 权限后再发指令。

---

## 本次交付的内容

### ✅ 代码与配置（可直接 commit）

```
kefu/
├── package.json · pnpm-workspace.yaml · tsconfig.base.json · .gitignore · README.md
│
├── cs/
│   ├── d1/migrations/0001_init.sql        # 6 张表 · 含 cs_workflow_runs
│   ├── shared/                            # 共享库
│   │   └── src/{openclaw-client,access-jwt,redact,turnstile,types}.ts
│   ├── workers/cs-api/
│   │   ├── wrangler.toml                  # 含 4 个 Cron 触发器
│   │   ├── src/
│   │   │   ├── index.ts                   # Hono 入口
│   │   │   ├── env.ts
│   │   │   ├── cron.ts                    # D1 备份 · 月度导出 · 心跳清理 · 健康探测
│   │   │   ├── lib/{auth,workspace,audit,metrics}.ts
│   │   │   ├── routes/{public,user,agent,admin}.ts
│   │   │   └── do/{bridge-do,agent-presence-do}.ts
│   ├── pages/
│   │   ├── cs-widget/                     # Web Component 浮窗
│   │   └── cs-console/                    # Angular 18 · 坐席台 + 管理台骨架
│   └── docs/
│       ├── runbook.md · troubleshooting.md · onboarding.md
│       ├── runbook-tunnel.md · cf-resources.md
│
├── cs-workspaces/
│   ├── _template/                         # fork 模板（完整）
│   └── ytk/
│       ├── IDENTITY.md · SOUL.md · AGENTS.md · channels.yaml
│       ├── skills/
│       │   ├── faq/entries/{charge-failed,vip-benefits,vip-room,refund-policy,paid-not-delivered}.md
│       │   ├── account/lookup.ts · orders/query.ts · vip/check.ts
│       │   ├── room/status.ts · domain/backup.ts
│       │   ├── tickets/create.ts · escalate/notify.ts · ocr/extract_order_id.ts
│       ├── workflows/{refund,account-query,complaint}.yaml
│       ├── integrations/{ytk-api,ticket-system,dns-admin,feishu}.yaml
│       └── tests/{soul.test.yaml,flows/refund.test.yaml}
│
├── cloudflared/config.example.yml + README.md
└── deploy/systemd/{cloudflared,openclaw-gateway}.service
```

### 核心能力

- ✅ **退款流程**：`cs-workspaces/ytk/workflows/refund.yaml` 完整 8 步（身份 → 查单 → 原因 → 确认 → 工单 → 返单号），含 `on_cancel` / `on_escalate` / 多处分支 / OCR 图片识别订单号。
- ✅ **API 对接**：3 个声明式 integration（`ytk-api` bearer / `ticket-system` hmac / `dns-admin` mTLS + confirm_required），密钥走 OpenClaw vault，pii_scrub 自动脱敏。
- ✅ **SOUL.md**：ytk workspace 的 Agent 决策树（语气、升级规则、skill 调用、workflow 触发、兜底）。
- ✅ **Worker 端路由**：`/cs/{biz}/*` 用户侧、`/agent/*` 坐席侧（Access SSO）、`/admin/*` 管理端（Access + Step-Up 双签）。
- ✅ **Durable Objects**：`BridgeDO` WS Hibernation + 转发 OpenClaw；`AgentPresenceDO` 原子 claim + Alarm 清理。
- ✅ **管理台**：workspace 列表 → 详情（SOUL 编辑 + 保存前跑测试 + git commit + Step-Up）；坐席台（Approvals 三态：采用/改写/重写）。
- ✅ **Cron**：D1 备份、月度 JSONL 导出、心跳清理、Tunnel 健康探测。
- ✅ **PII 脱敏**：shared `redact.ts` 覆盖手机/邮箱/身份证/订单/银行卡；双层保护（BridgeDO 入 OpenClaw 前 + 写 D1 前）。
- ✅ **审计**：所有管理端改动写 `cs_audit_log`；SOUL 修改额外有 git 历史。

### 未完整实现（占位 / 轮廓）

- ⚠ `skills/ocr/extract_order_id.ts` — 占位，需接入 OpenClaw vision 或腾讯云 OCR MCP。
- ⚠ `skills/complaint/classify.ts` — 投诉流程里调用，未实现（可用 LLM + 标签表）。
- ⚠ cs-console 的 Workflows / Integrations 子 tab 仅占位，未做 DAG / 漏斗可视化（原型里已经有 HTML 样式可参照）。
- ⚠ 管理台 Step-Up 的 Access 配置依赖具体 Zero Trust 应用设置。

## 未完成 · 需你手工执行的事

### 🔴 P0 阻塞（不做后续无法上线）

1. **修复 OpenClaw provider token**（见 T-00-01）
   ```bash
   ssh yitongkan@69.30.251.10
   openclaw configure         # 或 channels login
   ```
   建议接入 Anthropic Claude 4.6 作主 + OpenAI Codex 作备。

2. **升级 OpenClaw 到 2026.4.22+**（见 T-00-02）

3. **确认账号 / 路径规范化**
   - OpenClaw 侧统一由 `yitongkan` 运维（`customer` 无权访问 `/opt/yitongkan-company/`）
   - 建议把 workspace 放在 `/opt/openclaw/workspaces/`（符合 v3.0 per-biz 布局），与原 `/opt/yitongkan-company/` 解耦

### 🟠 Cloudflare 部署（一次性）

```bash
# 账户登录
wrangler login

# 资源创建
wrangler d1 create ytk-cs-db
wrangler kv:namespace create cs-runtime
wrangler r2 bucket create cs-assets
# 把返回的 id 填入 cs/workers/cs-api/wrangler.toml

# D1 迁移
pnpm d1:migrate

# Analytics Engine dataset 在 CF dashboard 创建 `cs_metrics`

# Turnstile site 在 CF dashboard 创建，得 TURNSTILE_SITE_KEY

# Zero Trust 创建 3 个 Application：
#   cs-console → group=agents + TOTP（得 AUD → ACCESS_AUD_AGENT）
#   cs-admin   → group=admins + TOTP + Step-Up（得 AUD → ACCESS_AUD_ADMIN）
#   openclaw-ytk → Service Auth → 生成 Service Token
# 把 AUD / token 填入 wrangler.toml [vars] 或 secret

# Secrets
cd cs/workers/cs-api
wrangler secret put TURNSTILE_SECRET
wrangler secret put MAIN_SITE_JWT_PUBKEY
wrangler secret put OPENCLAW_CF_ACCESS_ID_YTK
wrangler secret put OPENCLAW_CF_ACCESS_SECRET_YTK
wrangler secret put ALERT_EMAIL_TO

# 部署
pnpm deploy:api
pnpm deploy:widget
pnpm deploy:console
```

### 🟡 OpenClaw 侧部署（SSH 到 69.30.251.10）

```bash
ssh yitongkan@69.30.251.10

# 1. 新路径
sudo mkdir -p /opt/openclaw/workspaces
sudo chown -R yitongkan:yitongkan /opt/openclaw

# 2. 从本仓 scp workspaces
# 在本地：
scp -r cs-workspaces/_template cs-workspaces/ytk \
  yitongkan@69.30.251.10:/opt/openclaw/workspaces/

# 3. 把 ytk 推到 github 私有仓
cd /opt/openclaw/workspaces/ytk
git init && git add . && git commit -m "feat: bootstrap ytk workspace"
git remote add origin git@github.com:yitongkan/openclaw-ws-ytk.git
git push -u origin main

# 4. 填充 vault
openclaw vault set --workspace ytk YTK_API_TOKEN=...
openclaw vault set --workspace ytk TICKET_HMAC_KEY_ID=...
openclaw vault set --workspace ytk TICKET_HMAC_SECRET=...
openclaw vault set --workspace ytk TELEGRAM_BOT_TOKEN=...
openclaw vault set --workspace ytk FEISHU_APP_ID=...
openclaw vault set --workspace ytk FEISHU_APP_SECRET=...
openclaw vault set --workspace ytk FEISHU_CS_CHAT_ID=...

# 5. systemd
sudo cp /path/to/repo/deploy/systemd/*.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now openclaw-gateway

# 6. cloudflared（见 cloudflared/README.md）

# 7. 验证
openclaw run --workspace ytk --prompt "我要投诉"   # 应含「转接人工」
openclaw run --workspace ytk --prompt "我要退款"   # 应启动 workflow refund
openclaw test --workspace ytk                     # 全绿
```

### 🟢 灌首批 FAQ + 初始化坐席（运营 / Trainer）

1. 从过往工单导出 TOP 30 退款 / VIP / 充值相关问答
2. 管理后台 → 知识库 → 批量导入 CSV
3. 点「同步到 Workspace ytk」
4. 坐席管理 → 新增 2 名坐席 `biz_scope=["ytk"]`

### 🟣 内测 → 生产灰度

按 [cs/docs/onboarding.md](../cs/docs/onboarding.md) 第 8-9 步走灰度。

## 下一步建议

1. **先跑 MVP** — Telegram 内测（§3 MVP），不需要 Widget / Console。一周内出可演示版本。
2. **跑一次 refund 端到端** — 用 Telegram 内部测试账号完整走 8 步退款流程，确认 integrations 响应正常。
3. **开发补齐** — OCR skill、complaint/classify skill、cs-console Workflows/Integrations 可视化页面。
4. **BizN 孵化** — 参考 onboarding.md fork 模板做第二个业务，跑一遍验证隔离。

---

如需在本仓基础上继续开发，直接在对应 `cs/*` 目录编辑即可；每次改动建议：
- 改 workspace（`cs-workspaces/ytk/`）→ commit 到该 workspace 的 git 仓（openclaw-ws-ytk）
- 改 CF 侧（`cs/*`）→ commit 到主仓（kefu）