锐达赢·智营 CRM API 操作
本技能让 WorkBuddy 以调用者自身的 CRM 账号直连锐达赢·智营 CRM 的 REST API，完成查询、统计、业务操作与审批闭环。后端生产域名 https://crm.ruiday.com（本机调试可用 http://127.0.0.1:8080）。
> 本技能对"多用户 / 多租户"安全的前提：每个使用者用自己的 CRM 账号，后端租户拦截器会自动按该账号所属租户与角色隔离——他只能看自己租户、自己权限内的数据。共用 wb_bot（租户1管理员）仅能看到租户1数据，其他租户用户请勿用它。
前置条件
凭据文件（技能目录外，不随技能分发，每台机器各一份）：%USERPROFILE%\.workbuddy\crm-credentials.json
{ "base_url": "https://crm.ruiday.com", "username": "你自己的CRM账号", "password": "你的CRM密码" }
- 远程/其他机器必须把
base_url设为https://crm.ruiday.com（本机调试才用http://127.0.0.1:8080）。 username填使用者本人的 CRM 登录名（非 wb_bot），以保证租户与权限隔离正确。- 凭据文件缺失或字段不全时，请求脚本会明确报错——此时提示用户补建，禁止把凭据写进技能目录或任何会提交/分享的文件。
请求方式
一律通过 bundled 脚本发起。脚本路径以技能加载时系统给出的 SKILL.md 实际位置为准（同级 scripts/crm-api.mjs），市场安装与手动安装的落盘目录可能不同，勿写死路径。Node 用 WorkBuddy 托管版本或 PATH 上的 node（需 18+）：
# 读操作：直接执行
node "<技能目录>\scripts\crm-api.mjs" api GET "/api/v1/customer/list"
# 写操作：先向用户确认端点/参数/影响范围，用户同意后追加 --confirm 执行
# （脚本硬约束：非 GET 不带 --confirm 会被拒绝，绝不发起请求）
node "<技能目录>\scripts\crm-api.mjs" api POST "/api/v1/lead/create" \
"{\"leadName\":\"XX项目线索\",\"source\":\"转介绍\"}" --confirm
> 若 WorkBuddy 托管 Node 未在 PATH，用绝对路径：
> "%USERPROFILE%\.workbuddy\binaries\node\versions\22.22.2-2\node.exe"（版本目录以本机为准）。
脚本行为契约：
- 每次调用自动登录（form: username/password/device=web → data.accessToken），无需管理 token 过期；token 不落盘。
- 安全护栏：① 非 GET 请求未带 --confirm 直接拒绝、不发起任何网络请求；② base_url 为非本机 http:// 时拒绝执行（防明文传密码）。
- 输出第一行 HTTP <status>，其后为响应体原文；退出码 0 = 成功。
- 响应为 ApiResp{code,msg,data} 全局包裹——取业务数据读 .data；HTTP 200 但 code!=200 视为失败并退出码 1。
- 登录响应 LoginResult{accessToken,refreshToken,mfaRequired,userId,username}；账号未配 MFA 时 mfaRequired=false 直接拿到 token。
操作边界（硬规则）
- 读操作（GET）直接执行：查询、列表、统计、看板、报表、AI 问数、审批待办/历史。
- 写操作（POST/PUT/DELETE）必须先确认：向用户说明将调用哪个端点、关键参数、影响哪条数据，明确同意后再执行。删除（delete/void）类必须二次确认。
- 身份边界：技能以凭据文件中的
username（使用者本人 CRM 账号）运行。后端租户拦截器按该账号所属租户/角色自动隔离——每个用户只能看自己租户、自己权限范围内的数据，这是设计而非故障。若用户要求跨租户查看/操作不属于自己账号的数据，说明隔离限制并拒绝。 - 数据安全：不直接操作数据库（SQL 仅在用户明确要求排障时经既有流程使用）；不碰
Z_DEMO_/Z_TEST_/E2E_/smoke_标记的测试数据除非用户点名；批量操作（transfer-batch、recycle/run、run-engine 等）视为写操作且需展示影响面。 - 勿扰他产：仅访问 8080 后端；不触碰 8018 及其它产品端口/服务。
- AI 问数类端点（/ai/agent/chat、/report/ask、/funnel/ask）回答中若声明"数据缺失"不得编造补齐，与系统诚实红线一致。
高频场景配方
端点全集见 references/api-map.md（68 个控制器按业务域分组）。常用入口：
| 场景 | 端点 |
|---|---|
| 我的工作台 | GET /api/v1/dashboard/overview |
| 客户列表/公海/详情 | GET /api/v1/customer/list · /pool · /{id} |
| 线索列表/评分/转换 | GET /api/v1/lead/list · POST /{id}/convert/{cid} |
| 商机推进 | GET /api/v1/opportunity/list · POST /stage |
| 合同/报价/订单全生命周期 | POST /api/v1/contract → /{id}/submit → /{id}/archive |
| 审批待办/完成 | GET /api/v1/flow/tasks/todo · POST /{taskId}/complete（body: action/comment） |
| AI 问数/智能体 | POST /api/v1/ai/agent/chat（body: {"message":"问题","sessionId":"续聊可传"}）· 会话回看 GET /sessions/{id} |
| 经营报表/BI 9 维 | GET /api/v1/report/business · GET /api/v1/bi/company 等 9 维 |
| 漏斗/预测/分析 | GET /api/v1/funnel · /trend · /sales-forecast |
| 业绩目标 | GET /api/v1/performance/target · /summary · /gap |
| 工单 | GET /api/v1/ticket/list · POST /assign · /resolve |
| 发票/回款 | GET /api/v1/invoice · GET /api/v1/receipt |
| 交付管理 | GET /api/v1/delivery/board/overview |
| 知识库 | GET /api/v1/knowledge/articles · GET /search |
| 通知 | GET /api/v1/notify/messages |
分页参数通常为 page/size 或 pageNum/pageSize（以响应体 total 字段为准翻页）。
排障
- 401：凭据失效或账号被停用——先跑
login命令验证，再检查账号 status。 - 403 "需要管理员权限"：管理端点要求 admin——确认该 CRM 账号在系统里具 admin 角色，否则只调得通普通权限内的端点。
- 连接拒绝：先核对
base_url（远程应为https://crm.ruiday.com）；本机场景检查 8080 端口与看门狗。勿自行重启生产服务，报告用户。
共享给其他 CRM 用户（分发）
技能文件只存在于使用者本机 ~/.workbuddy/skills/，不会自动同步。要让团队其他人也在 WorkBuddy 里用上，任选其一：
- 手动拷贝（最稳）：把本技能目录
zhiying-crm-workbuddy/整体打成 zip 发给同事，他解压到自己的%USERPROFILE%\.workbuddy\skills\即可。凭据文件crm-credentials.json不要打进 zip——每人自己建。 - 项目级（团队共仓库）：把技能目录放到项目仓的
.workbuddy/skills/zhiying-crm-workbuddy/并提交，克隆/拉取该仓的人自动获得。注意.workbuddy默认不进.gitignore，确认仓库不含凭据。 - 市场/BuiltinMarket（一键安装）：若 WorkBuddy 提供技能市场发布入口，将技能目录发布后，同事在市场中一键安装即可。
无论哪种方式，凭据都留在各自机器，且推荐每人填自己的 CRM 账号——这样租户与权限由后端自然隔离，互不串数据。
