小红书投放数据接入
清海通过客户端后端 API 接入小红书聚光投放数据，用户在飞书/TG 等平台自然语言查询、分析自己公司的投放数据。 角色维度的对话设计见 角色场景，能力定义见 Skill 清单。
背景与设计动机
| 维度 | 说明 |
|---|---|
| 数据源 | 团队开发的 xhs-jg-manager 客户端（Electron + React），直连小红书多端 API |
| 通信方式 | 清海通过 HTTP 调用客户端后端 API，获取实时投放数据 |
| 数据范围 | 账号管理、聚光订单、笔记互动、私信评论、充值钱包、操作日志 |
| 核心价值 | 用户不需要打开客户端软件，在飞书/TG 对话中直接获取投放数据和智能分析 |
与飞书表格方案的区别
| 对比维度 | 飞书表格方案（一个信念） | 客户端 API 方案（本方案） |
|---|---|---|
| 数据来源 | 人工录入飞书表格（9 张表） | 客户端直连小红书 API，实时拉取 |
| 数据实时性 | 依赖人工更新频率 | 实时或准实时 |
| 数据维度 | 表格中预设的字段 | 小红书全量原始数据（167 个 IPC 频道） |
| 适用客户 | 已有飞书表格体系的团队 | 使用 xhs-jg-manager 客户端的团队 |
| 扩展性 | 受限于表格结构 | 可随客户端迭代扩展 |
客户端能力概览
客户端提供以下模块的数据查询能力（第一期仅接入只读查询）：
| 模块 | 可提供数据 | 接入价值 |
|---|---|---|
| 账号管理 | 账号列表、余额（现金/赠款/薯币）、在线状态、分组 | 资产总览、账号健康监控 |
| 订单管理 | 聚光推广订单、消耗汇总、效果指标（曝光/阅读/互动/转化） | 投放效果分析、ROI 追踪 |
| 笔记管理 | 笔记列表、互动数据（浏览/点赞/收藏/评论/分享）、发布状态 | 内容表现分析 |
| 私信评论 | 会话列表、消息历史、评论数据 | 用户互动监控、线索追踪 |
| 充值钱包 | 余额明细、充值记录 | 财务监控 |
| 操作日志 | 上下线、IP 变更、设备变更 | 安全审计 |
客户端数据模型
客户端提供完整的 TypeScript 数据模型，核心实体：
| 实体 | 关键字段 | 业务含义 |
|---|---|---|
Account | id, nickname, balance, cashBalance, grantBalance, chipsBalance, isOnline, feishuUserId | 小红书账号，通过 feishuUserId 关联飞书用户 |
Order | orderId, noteTitle, budget, consume, impression, read, likes, collect, comments, follow, messageCount, status | 聚光推广订单，含完整效果指标 |
Note | noteId, title, type, viewCount, likes, collects, comments, shares, status | 笔记，含互动数据 |
Conversation | sessionId, targetNickname, lastMessage, unreadCount, firstUnreplyTime | 私信会话 |
Comment | commentId, noteId, content, authorNickname, likes | 笔记评论 |
数据隔离与权限体系
公司级数据隔离
每个客户公司独立部署客户端实例，清海通过公司标识路由到对应的客户端后端 API，数据天然隔离。
公司内部角色权限（基于飞书组织架构）
| 角色 | 数据可见范围 | 不可见数据 |
|---|---|---|
| 老板 | 全部账号、全部订单、全部笔记、财务数据、全员互动数据 | — |
| 部门负责人 | 本部门管理的账号及其订单/笔记/互动数据 | 其他部门数据、公司级财务汇总 |
| 员工 | 仅自己负责的账号及其订单/笔记/互动数据 | 他人账号数据、团队汇总、财务数据 |
权限识别链路：
账号-人员映射：客户端 Account 数据模型中的 feishuUserId 字段将小红书账号与飞书用户关联，accountGroupId 用于部门级权限路由。
越权查询处理
| 角色 | 越权查询 | 清海回应 |
|---|---|---|
| 员工 | "公司总消耗多少" | "公司整体消耗数据需要找管理层了解" |
| 员工 | "XX 的账号余额多少" | "同事的账号数据可以找部门负责人了解" |
| 部门负责人 | "其他部门的投放数据" | "其他部门的数据可以找老板了解" |
四大业务场景
场景总览
场景 → 能力映射表
| 场景 | 典型触发方式 | 核心能力 | 数据来源 |
|---|---|---|---|
| 数据查询问答 | 用户主动提问 | 客户端 API 查询 + 权限过滤 | 账号/订单/笔记/私信/评论 |
| 主动巡检告警 | 定时触发（Cron） | 异常检测 + 主动通知 | 订单消耗 + 账号状态 |
| AI 智能分析 | 用户主动提问 | 多维度数据聚合分析 | 跨模块数据关联 |
| 报表导出 | 用户主动要求 | CSV 导出 + 报表生成 | 订单统计数据 |
场景一：数据查询问答
核心价值：用户用自然语言查投放数据，AI 自动按权限过滤，实时返回。
账号查询
| 用户问法 | 清海应答 | 数据接口 |
|---|---|---|
| "我的账号余额还剩多少" | 列出该用户绑定账号的余额明细（现金/赠款/薯币） | list_accounts + get_account_balance |
| "哪些账号离线了" | 列出离线账号及原因（cookie 过期/错误） | list_accounts |
| "XX 分组下有哪些账号" | 列出该分组的账号列表及状态 | list_accounts |
订单查询
| 用户问法 | 清海应答 | 数据接口 |
|---|---|---|
| "今天消耗了多少" | 当日各账号消耗汇总 + 总消耗 | get_cost_summary |
| "这周的推广订单" | 近 7 天订单列表（消耗/曝光/阅读/互动） | list_orders |
| "推广中的订单有哪些" | 按状态筛选进行中的订单 | list_orders |
笔记查询
| 用户问法 | 清海应答 | 数据接口 |
|---|---|---|
| "哪篇笔记表现最好" | 按互动量排序的笔记列表 | list_notes + get_note_stats |
| "最近发布的笔记状态" | 笔记列表含审核状态 | list_notes |
互动查询
| 用户问法 | 清海应答 | 数据接口 |
|---|---|---|
| "有多少未回复私信" | 未回复会话数 + 最早未回复时间 | list_conversations |
| "最近的评论" | 笔记下的最新评论列表 | list_comments |
数据流转
场景二：主动巡检告警
核心价值：AI 定时检查投放数据，发现异常主动通知相关人，无需人工盯盘。
巡检指标
| 指标 | 异常判定 | 告警级别 |
|---|---|---|
| 账号离线 | cookie 过期或状态异常 | 高 |
| 余额不足 | 账号余额低于阈值 | 高 |
| 消耗异常 | 消耗显著偏离近 7 天均值 | 中 |
| 零产出 | 有消耗但无互动（曝光/阅读/点赞均为 0） | 中 |
| 订单状态异常 | 审核不通过、推广终止 | 中 |
巡检流程
告警示例
账号离线：
你负责的账号「XX美妆」已离线，原因：cookie 过期。请及时在客户端重新登录。
余额预警：
账号「XX健康」余额仅剩 ¥52.30（现金 ¥12.30 + 赠款 ¥40.00），建议及时充值。
消耗异常：
账号「XX瘦身」今日消耗 ¥2,850（近 7 天日均 ¥800），是在加大投放还是需要检查？
零产出：
订单「春季焕新计划」今日消耗 ¥456 但曝光仅 23 次，可能素材被限流，建议检查。
巡检防骚扰规则
| 规则 | 说明 |
|---|---|
| 冷却期 | 同一账号同一异常类型 24 小时内不重复告警 |
| 时段限制 | 仅在 9:00-21:00 发送告警 |
| 每日上限 | 单人每日最多收到 5 条告警 |
| 合并发送 | 多个异常合并为一条消息 |
场景三：AI 智能分析
核心价值：跨模块数据关联分析，提供投放优化建议。
典型分析场景
| 用户问法 | 清海分析逻辑 | 涉及数据 |
|---|---|---|
| "这周投放效果怎么样" | 消耗趋势 + 效果指标（曝光/阅读/互动）环比 + 转化成本分析 | 订单 |
| "哪个账号 ROI 最高" | 各账号消耗 vs 互动数据对比，计算单次互动成本 | 订单 + 账号 |
| "笔记和投放效果的关系" | 关联笔记互动数据和对应推广订单效果 | 笔记 + 订单 |
| "私信进线质量怎么样" | 私信进线量 vs 开口量 vs 转化率分析 | 订单（messageCount/messageOpen） |
| "各账号消耗分布" | 各账号消耗占比 + 效率排名 | 订单汇总 |
| "最近有没有异常趋势" | 多指标综合分析，发现异常模式 | 跨模块 |
分析数据流
场景四：报表导出
核心价值：一句话导出投放报表，免去手动统计。
| 用户问法 | 清海动作 | 数据接口 |
|---|---|---|
| "导出这周的投放数据" | 生成近 7 天订单统计 CSV | export_stats_csv |
| "导出本月消耗报表" | 按日期汇总本月消耗明细 | get_stats_by_date + 格式化 |
| "各账号本月消耗汇总" | 按账号维度汇总月度数据 | get_cost_summary |
导出格式：CSV 文件，包含日期、账号、消耗、曝光、阅读、互动、转化成本等字段。
Skill 触发机制
用户消息 → 命中触发词（投放|消耗|余额|账号|订单|笔记|私信|评论|小红书|聚光|曝光|ROI|导出|报表...）
→ 渐进式加载对应 Skill 定义
→ AI 根据意图选择工具组合
→ 调用客户端 API → 权限过滤 → 格式化返回
主动巡检 → daemon 定时触发（每日 20:00）
→ 拉取数据 → 异常判定 → 通知相关人安全约束
| 约束 | 说明 |
|---|---|
| Cookie/签名不暴露 | 小红书认证信息仅存在于客户端，不经过清海 |
| API 通信加密 | 清海与客户端后端 API 通信使用 HTTPS |
| 金额单位统一 | 客户端返回的金额以分为单位，清海展示时转换为元 |
| 时间戳统一 | 客户端使用毫秒时间戳，清海转换为可读日期 |
| 敏感数据脱敏 | 私信内容在展示时遵守数据隐私规范 |
| 批量操作禁止 | 第一期不接入任何写入/批量操作 |
与清海现有能力的对接
| 需求 | 可复用能力 | 需新建能力 |
|---|---|---|
| 用户身份识别 | PersonCard + 飞书组织架构 | 飞书用户 → 小红书账号映射 |
| 权限过滤 | 角色权限路由（已有框架） | 按 feishuUserId/accountGroupId 过滤 |
| 定时巡检 | Concern 引擎 + daemon.py | 客户端数据巡检策略 |
| 主动通知 | NotificationEngine + 飞书/TG Bot | 投放告警消息模板 |
| 防骚扰 | NotificationEngine 冷却/时段/上限 | 告警频率配置 |
| 数据分析 | LLM 链路（分析/总结） | 投放数据分析 prompt 模板 |