front/docs/小红书模块联调与验收.md

小红书模块 — 联调与验收

关联：小红书模块设计-063001.md · rbac系统设计-060801.md
代码：E:\oms0414 · C:\Users\wilso\Desktop\oms0414-back · C:\Users\wilso\Desktop\LIKE AI
版本：v0.1 · 2026-06-30

---

1　部署清单

1.1 数据库（两个库）

库	脚本	说明
OMS 业务库（如 fake_simple_admin）	sql/install_xhs_module.sql	建 8 张 t_xhs_* 表 + 技能/AI 提供商种子（推荐一键）
同上（仅表结构）	sql/migrate_t_xhs.sql	只建表
同上（可选拆分）	seed_xhs_skills.sql · seed_xhs_ai_providers.sql	单独补种子
RBAC 库	sql/fix_xhs_menu_bad_guids.sql	仅 menu 曾误写 CreateUserId=0 时执行
RBAC 库	sql/seed_xhs_rbac_menu.sql	菜单；@ADMIN_USER_ID 改为实际超级管理员 user.Id
RBAC 库	sql/seed_xhs_role_permissions.sql	给 Customer / Admin 追加 Xhs.* 权限（幂等）

推荐顺序

OMS 业务库：install_xhs_module.sql
RBAC 库：fix_xhs_menu_bad_guids.sql（若已报错）→ seed_xhs_rbac_menu.sql → seed_xhs_role_permissions.sql
重启 OMS API（会自动跑 XhsRolePermissionSeedContributor 合并权限，与 SQL 二选一即可）
重新登录 OMS（刷新 JWT 与菜单）

1.2 后端

cd C:\Users\wilso\Desktop\oms0414-back
dotnet build SimpleAdmin.sln
dotnet run --project src/SimpleAdmin.Api

默认监听以 launchSettings.json / 环境配置为准（常见 http://localhost:5281）。

1.3 前端

cd E:\oms0414
pnpm install   # 首次
pnpm dev

生产构建：pnpm build；前后端分域名后，/xhs/* 页面由前端 serve -s SPA 回退，/xhs/agent/* 等 API 走 api.* Admin，勿把 API 打到前端域名。

1.4 LIKE AI Agent

cd "C:\Users\wilso\Desktop\LIKE AI"
py -3 main.py activate <本地激活码>   # License 仍本地校验，与 OMS 无关
py -3 main.py agent --oms-url <API根> --token <JWT>

场景	--oms-url 示例
本机后端	http://localhost:5281/admin
远程 admin	https://api.nanafa.com/admin

注意：浏览器 dev 时前端走 Vite 代理 /xhs → admin，Python Agent 不能用 http://localhost:5173；必须指向真实 Admin API 根地址（含 /admin 后缀）。

---

2　环境自检

2.1 菜单与权限

检查项	预期
GET /rbac/menu/get-menu-tree	无 Guid: 0 报错
客户账号登录	左侧出现「小红书」6 个子菜单
系统菜单	「AI 助手」在「系统管理」下（/system/xhsAiAssistant）
权限	客户角色含 Xhs.Agent.Query 等（查 role_permission 或管理端角色页）

-- RBAC 库
SELECT Code, Name FROM role WHERE Code IN ('Customer', 'Admin');
SELECT PermissionCode FROM role_permission rp
JOIN role r ON r.Id = rp.RoleId
WHERE r.Code = 'Customer' AND PermissionCode LIKE 'Xhs.%';

2.2 业务表

-- OMS 业务库
SHOW TABLES LIKE 't_xhs_%';
SELECT COUNT(*) FROM t_xhs_skill;
SELECT COUNT(*) FROM t_xhs_ai_provider;

2.3 API 冒烟（Swagger 分组 OMS-Xhs 或 curl）

需 客户账号 JWT（loginType=1）：

POST /xhs/agent/list
Authorization: Bearer <token>
Content-Type: application/json

{"page":1,"pageSize":30}

返回 { items, total } 即通路正常。

---

3　端到端联调 Checklist

按顺序勾选；每步失败先查「5 常见问题」。

阶段 A — 连接与 Agent

• A1 客户账号登录 OMS Web
• A2 打开「小红书 → 启动服务」，复制 JWT 与启动命令
• A3 本机执行 py -3 main.py agent --oms-url ... --token ...，窗口保持运行
• A4 约 30s 内列表出现 Agent，状态 在线（心跳间隔 30s，在线阈值 90s）
• A5 点击「启动引擎」→ 任务创建成功；Agent 日志有 claim/report
• A6 点击「扫码登录」→ 本机 Chrome 弹出；登录后「检查登录」为已登录

阶段 B — 拟人设置

• B1 「拟人设置」页加载 JSON 配置
• B2 修改并保存 → 成功提示
• B3 Agent 下次心跳后拉取新配置（human-config/pull），本机行为生效

阶段 C — 内容分析

• C1 「新建采集」→ 选「关键词搜索」+ Agent → 提交
• C2 左侧会话列表出现新记录；详情任务状态由 pending → succeeded
• C3 「采集结果」Tab 出现笔记列表（或原始 JSON）
• C4 系统 → AI 助手：至少一个提供商已填 ApiSecret（Key） 与模型名
• C5 选提供商 →「AI 分析」→「AI 报告」Tab 有 Markdown
• C6 对某笔记 点赞 / 收藏 / 评论 → 提示任务号；Agent 执行后无报错

阶段 D — 爆款创作与发布

• D1 上传图片 → 返回 publicUrl
• D2 「AI 生成」文案（需提供商 Key）→ 标题/正文/标签填充
• D3 立即发布 → 发布记录状态 publishing → succeeded
• D4 定时发布（未来 5+ 分钟）→ 记录为 scheduled；到点后 Worker 触发（每分钟扫描）
• D5 定时任务 取消 / 失败任务 重试 可用

阶段 E — 技能卡片

• E1 列表可见 5 条系统技能（种子）
• E2 新建/编辑/删除自定义技能
• E3 analyze_only 一键执行 → 产生分析会话
• E4 create_and_publish + 图片 → 发布记录新增

阶段 F — AI 助手

• F1 系统 → AI 助手：提供商列表（DeepSeek / 豆包等模板）
• F2 编辑提供商：BaseUrl、Model、ApiSecret 保存成功
• F3 对话发送消息 → 流式/完整回复正常

阶段 G — 生产 / Traefik（上线前）

• G1 Ingress(tls) + cert-manager 证书就绪；前端 Service 健康
• G2 刷新站点域名下 /xhs/analysis 等返回 SPA，不 404
• G3 POST https://api.ideship.com/admin/xhs/agent/list（带 Token）正常
• G4 Agent 使用生产 --oms-url https://api.ideship.com/admin

---

4　验收标准（P0–P3）

模块	通过标准
Agent 连接	注册、心跳、列表、远程 control 四类动作可创建任务
内容分析	三种采集类型、轮询详情、AI 分析、笔记互动
爆款创作	上传、AI 生成、立即/定时发布
发布记录	筛选、取消定时、失败重试
技能卡片	CRUD + 三种 runMode
拟人设置	读写 + Agent 拉取
AI 助手	提供商 CRUD + 对话
权限隔离	客户 A 看不到客户 B 的 Agent/任务/发布记录
明确不做	物流查价、CLI 日志、License 不在 OMS 内

---

5　常见问题

5.1 get-menu-tree / 登录报错 Could not parse CHAR(36) value as Guid: 0

原因：RBAC 库某表 GUID 列被写成 "0"（常见于 menu.CreateUserId，也可能是 PId / role 审计字段等）。

⚠️ 本地 dev 易踩坑：pnpm dev 时 localhost:5173/rbac/* 经 Vite 代理到远程 http://api.nanafa.com/admin，在本机 MySQL 跑修复脚本不会影响登录。请确认 Navicat 连的是 API 实际使用的 RBAC 库（与 api.nanafa.com 同一实例）。

验证是否远程报错：

curl.exe -s "http://api.nanafa.com/admin/rbac/auth/login" -H "Content-Type: application/json" -d "{\"account\":\"admin\",\"password\":\"123456\",\"type\":0}"

本地 API 联调应直连：

curl.exe -s "http://localhost:5281/admin/rbac/auth/login" ...

处理（RBAC 库）：

1. sql/diagnose_rbac_bad_guids.sql — 查出脏行（勿只查 menu.Id，要看 CreateUserId / PId）
2. sql/fix_rbac_bad_guids.sql — 全表修复（或 fix_xhs_menu_bad_guids.sql 仅 menu）

勿用 WHERE CreateUserId = 0（整数），会触发 MySQL 1292。

5.2 登录后看不到「小红书」菜单

1. 确认 seed_xhs_rbac_menu.sql 已执行
2. 确认角色有 Xhs.*（SQL 或重启 API 种子）
3. 退出重新登录
4. 子客户需在主客户权限范围内单独分配

5.3 1146 Table 't_xhs_skill' doesn't exist

在 OMS 业务库 执行 migrate_t_xhs.sql 或 install_xhs_module.sql。

5.4 Agent 一直离线

可能	处理
Token 过期	重新复制 JWT 重启 Agent
--oms-url 错误	必须含 /admin，且 Agent 能访问该地址
非客户账号 Token	使用客户登录（loginType=1）
防火墙	本机 Agent 需出网访问 OMS API

5.5 前端 dev 正常、生产 404

• 站点域名下页面由 serve -s 回退 index.html
• API 请求应走 VITE_API_ADMIN_URL（如 https://api.ideship.com/admin），不要打到前端静态域名的 /xhs/agent/list

5.6 AI 生成 / 分析失败

1. 系统 → AI 助手：提供商 已启用、ApiSecret 已填、Model 名称 与厂商一致
2. BaseUrl 为 OpenAI 兼容 Chat Completions 地址
3. 看后端日志 / Swagger 返回 BusinessException 文案

5.7 定时发布未触发

• 确认 XhsScheduledPublishWorker 随 API 宿主运行（默认已注册）
• 服务器时间正确；记录状态为 scheduled 且 ScheduledTime <= now

---

6　关键路径速查

Agent  lifecycle : POST /xhs/agent/register | heartbeat | list | control
Task  pipeline   : POST /xhs/task/claim | report  （Agent 侧）
Analysis         : POST /xhs/analysis/start | list | detail | run-ai | interact
Creation         : POST /xhs/creation/generate | publish
Publish          : POST /xhs/publish/list | cancel | retry
Skills           : POST /xhs/skill/list | save | delete | run
Human config     : POST /xhs/human-config/get | save | pull
AI               : POST /xhs/ai/provider/list | save | chat
Media            : POST /xhs/media/upload  (multipart)

设计细节（表结构、字段、权限码全集）见 小红书模块设计-063001.md。

---

7　SQL 脚本索引

文件	库	用途
migrate_t_xhs.sql	OMS	8 张业务表
install_xhs_module.sql	OMS	建表 + 技能 + AI 提供商
seed_xhs_skills.sql	OMS	5 条系统技能
seed_xhs_ai_providers.sql	OMS	AI 提供商模板
seed_xhs_rbac_menu.sql	RBAC	菜单（含 AI 助手挂系统管理）
seed_xhs_role_permissions.sql	RBAC	Customer / Admin 权限
fix_xhs_menu_bad_guids.sql	RBAC	修复 menu GUID 脏数据

代码种子：SimpleAdmin.Api/Auth/XhsRolePermissionSeedContributor.cs — API 启动时幂等合并 Xhs.* 到 Customer / Admin 角色。