# 小红书模块 — 联调与验收

> **关联**：[小红书模块设计-063001.md](./小红书模块设计-063001.md) · [rbac系统设计-060801.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 后端

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

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

### 1.3 前端

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

生产构建：`pnpm build`，Nginx 配置见 `nginx-default.conf`（**仅** SPA 页面路径走 `index.html`，`/xhs/agent/list` 等 API 走 admin 后端，勿整段 `/xhs` 当 SPA）。

### 1.4 LIKE AI Agent

```bash
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` 或管理端角色页） |

```sql
-- 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 业务表

```sql
-- 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`）：

```http
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 — 生产/nginx（上线前）

- [ ] **G1** `nginx -t && nginx -s reload` 已执行
- [ ] **G2** 刷新 `/xhs/analysis` 等页面返回 SPA，**不** 404
- [ ] **G3** `POST https://api.nanafa.com/admin/xhs/agent/list`（带 Token）正常
- [ ] **G4** Agent 使用生产 `--oms-url https://api.nanafa.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` 同一实例）。

验证是否远程报错：

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

本地 API 联调应直连：

```bash
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

- Nginx 仅对 **页面路径** 回退 `index.html`（见 `nginx-default.conf` 第 63–66 行）  
- API 请求应走 `VITE_API_ADMIN_URL`（如 `https://api.nanafa.com/admin`），不要打到 oms 静态站点的 `/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](./小红书模块设计-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 角色。