zzh
c6723ab476
Some checks failed
Build and Deploy Front / deploy (push) Failing after 32m20s
生产不再内置 nginx/`__cos__`；镜像用 serve -s，HTTPS 由 Traefik+cert-manager；面单预览走 stream。 Co-authored-by: Cursor <cursoragent@cursor.com>
282 lines
11 KiB
Markdown
282 lines
11 KiB
Markdown
# 小红书模块 — 联调与验收
|
||
|
||
> **关联**：[小红书模块设计-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`；前后端分域名后，`/xhs/*` 页面由前端 `serve -s` SPA 回退，`/xhs/agent/*` 等 API 走 **api.*** Admin，勿把 API 打到前端域名。
|
||
|
||
### 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 — 生产 / 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` 同一实例）。
|
||
|
||
验证是否远程报错：
|
||
|
||
```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
|
||
|
||
- 站点域名下页面由 `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](./小红书模块设计-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 角色。
|