JustRight AI · 完整 API 文档

1. 基础地址

线上：https://cj.zhengl.vip

2. 鉴权方式

① 对外 API Key 鉴权（/api/v1/*）：在「API」菜单创建授权，请求头携带

Authorization: Bearer ZK-xxxxxxxx

② 后台管理接口：需先调用 POST /api/login 登录（使用管理员/用户账号），浏览器自动携带会话 Cookie。

③ 公开接口：无需鉴权（健康检查、系统信息、H5 预览、访问记录、登录等）。

3. 权限说明

权限叠加规则：用户有效权限 = 用户自身权限 ∪ 所属各用户组权限（多组叠加）；admin 角色自动拥有全部权限。用户组与用户的权限勾选均以中文展示，底层存储 key。

4. 统一返回结构

{"code": 0, "msg": "ok", "data": {...}}   # 对外接口
{"ok": true, ...}                            # 管理接口

POST /api/v1/tasks — 发起采集任务

权限：task_create

创建采集任务，系统排队执行采集 → AI 生成图文 → 打标全流程。支持「精准采集」（关键字+标签）与「智能采集」（一句话描述）。

{
  "name": "高血压慢病断药采集",
  "scene": "慢病断药",
  "disease": "高血压",
  "keyword": "高血压 用药",
  "target_count": 5,
  "source_ids": [1,2,3],         // 可选，留空=全部商用来源
  "mode": "precise",             // precise=精准 / smart=智能（默认precise）
  "description": "采集高血压患者断药相关的健康科普",  // smart模式必填
  "icd_tags": ["高血压病"], "sic_tags": ["高血压"],
  "sic_med_tags": [], "crowd_tags": [], "lifestyle_tags": [],
  "space_tags": [], "time_tags": ["全年通用"],   // 时间标签必选
  "func_tags": ["用药规范","疾病科普"]
}

返回：{"code":0,"data":{"taskNo":"TASK-...","status":"queued"}}

字段说明：name=任务名称；mode=采集方式（precise 精准：按 keyword+tags 严格采集；smart 智能：按 description 一句话描述自动采集并打标）；target_count=目标数量；source_ids=来源ID数组；*_tags=标签组合。

POST /api/v1/content — 新增内容

权限：content_write

{
  "title": "高血压患者如何规律服药",
  "disease": "高血压",
  "content": "<p>正文HTML...</p>",
  "digest": "摘要...",
  "cover_image": "https://cdn.sinoxk.com/...",
  "recommend_speech": "推荐话术...",
  "source_name": "广东省疾病预防控制中心",
  "tags": {"icd":["高血压病"],"sic":["高血压"],"time":["全年通用"],"func":["疾病科普"]}
}

POST /api/v1/content/feed — 获取内容

权限：content_read

按标签组合查询内容，返回多条（含标题/摘要/封面/正文/来源/标签）。

{
  "icd": ["高血压病"], "sic": ["高血压"], "sic_med": [],
  "crowd": [], "func": ["用药规范"], "limit": 10
}

也支持 GET：/api/v1/content/feed?sic=高血压&func=用药规范&limit=10

GET /api/v1/content/export · /api/v1/content/export.xlsx — 导出内容

权限：content_read

按条件导出内容数据，支持 JSON 与 Excel 两种格式。

GET /api/v1/content/export?icd=高血压病&func=用药规范&limit=500
GET /api/v1/content/export.xlsx?sic=高血压

GET /api/v1/push-logs — 推送/访问记录

权限：content_read

查询内容的推送次数、访问次数、访问时长、访问设备等记录，用于统计内容触达与阅读效果。

GET /api/v1/push-logs?content_id=AUTO-ZK-...&limit=50

访问记录参数：action=push|open；duration=浏览时长(秒)；channel=渠道；open_uuid=打开来源；device=设备类型。预览页已内置自动上报脚本，分享链接后系统自动记录访问设备、浏览时长与打开次数。

标签组接口（v17 新增）

API 授权管理接口（/api/api-keys，v18 补充）

接口：GET /api/api-keys 列表；POST /api/api-keys 创建（body：{"name":string, "scopes":array, "remark":string}，返回一次性完整 key）；PUT /api/api-keys/{kid} 更新；DELETE /api/api-keys/{kid} 删除。

后台「创建 API 授权」弹窗按 API 类型（发起采集任务/获取内容/新增内容/数据上报/推送记录查询）分组勾选，勾选后自动映射到上表权限 scope。

GET /api/report/tokens-detail — tokens 调用明细（v18 新增）

返回 {"total":int,"page":int,"size":int,"items":[{time,task_no,task_name,stage,step,model,prompt_tokens,completion_tokens,total_tokens,cost}]}；cost 为 number|null——按「AI 模型配置」中该模型的价格（元/千 tokens）估算的费用，未配置价格时为 null。GET /api/report/tokens-detail/export 相同筛选参数导出 CSV（含费用估算列）。

GET /api/report — 数据报表（v17 增加筛选与采集数据）

返回新增 collect_report（采集数据块）：任务总数/完成/失败、目标与完成数量、达成率、内容完整度（标题/摘要/正文/封面图/内容链接/标签/来源 各字段填充率与完整率）、按日期采集趋势。

GET /api/scopes — 全部权限点

返回系统全部权限点（key + 中文名称），供用户/用户组权限勾选使用。

GET /api/scopes
→ {"items":[{"key":"dashboard","name":"首页概览"},{"key":"task_manage","name":"任务管理"},...]}

GET /api/users — 用户列表（管理员）

返回 {"total":总数,"items":[用户对象]}，用户对象字段：

POST /api/users — 新建用户（管理员）

{"username":"zhangsan","password":"Abc@123456","nickname":"张三","role":"editor",
 "email":"zhangsan@example.com","scopes":["task_manage","content_manage"],
 "group_ids":[1,3],"tokens_quota":1000000}
→ {"ok":true,"id":12}

PUT /api/users/{uid} — 编辑用户（管理员）

请求体与新建相同（UserIn），全部字段均可选；额外说明：

返回 {"ok":true}；用户不存在返回 404，用户名冲突返回 400。

POST /api/users/{uid}/reset-password — 重置密码（管理员）

POST /api/users/12/reset-password   {"password":"New@123456"}
→ {"ok":true,"password":"New@123456"}

POST /api/users/{uid}/toggle — 启用/停用用户（管理员）

无请求体，切换启停状态；不能停用当前登录账号（返回 400）。返回 {"ok":true,"status":1或0}

DELETE /api/users/{uid} — 删除用户（管理员）

删除用户及其用户组关联；不能删除当前登录账号。返回 {"ok":true}

GET /api/users/me — 当前登录用户

返回当前会话用户对象（字段同用户列表，不含 groups/eff_scopes），未登录返回 401。

GET /api/groups — 用户组列表（登录即可）

返回 {"items":[用户组对象]}，字段：

POST /api/groups — 新建用户组（管理员）

{"name":"运营组","code":"ops","scopes":["task_manage","content_manage","report_view"],
 "remark":"内容运营","member_ids":[3,5]}
→ {"ok":true,"id":2}

PUT /api/groups/{gid} — 编辑用户组（管理员）

请求体同新建；member_ids 传入则整体替换成员。返回 {"ok":true}

DELETE /api/groups/{gid} — 删除用户组（管理员）

删除组及其成员关联（用户本身不受影响）。返回 {"ok":true}

GET /api/media-configs — 配置列表

返回配置对象数组，字段：

POST /api/media-configs — 新增配置 / PUT /api/media-configs/{mid} — 编辑配置

请求体字段与上表一致，其中：

{"name":"千问-对话","cfg_type":"chat","api_type":"dashscope","base_url":"https://dashscope.aliyuncs.com/compatible-mode/v1",
 "api_key":"sk-xxx","model":"qwen-plus","provider":"qwen","auth_mode":"key","enabled":1}
→ {"ok":true,"id":3}

DELETE /api/media-configs/{mid} 删除配置。流程步骤级模型绑定：在「AI 模型配置」页为每个流程步骤选择接口配置（cfg）+ 模型 ID，保存至 flow_models 设置项，格式 {"标题生成":{"cfg":3,"model":"qwen-plus"}}。

任务管理接口（/api/tasks）

GET /api/tasks — 任务列表

返回 {"total":int,"items":[任务对象]}，任务对象字段：

POST /api/tasks — 创建任务（请求体 TaskIn）

其他任务接口：GET /api/tasks/{tid} 任务详情（返回任务对象）；GET /api/tasks/{tid}/exec 执行过程（35 子步骤逐条状态）；POST /api/tasks/{tid}/cancel 取消运行中任务；DELETE /api/tasks/{tid} 删除任务；POST /api/tasks/auto-config AI 自动配置（body：{"requirement":string}，返回建议的场景/标签/数量）。

内容管理接口（/api/content）

GET /api/content — 内容列表

返回 {"total":int,"items":[内容对象],"page":int,"size":int}，内容对象字段：

POST /api/content — 新增内容（请求体 ContentIn，字段同上表可写字段）：title 必填；body_html 正文 HTML；status 默认 active。返回 {"ok":true,"content_id":"AUTO-ZK-..."}。

PUT /api/content/{cid} 编辑（请求体同 ContentIn）；DELETE /api/content/{cid} 删除；POST /api/content/{cid}/stop|resume 停用/恢复；GET /api/content/{cid}/stats 访问统计（push_count、open_count 等）；POST /api/content/{cid}/generate-image 生成科普图（body 可选：{"size":string}）；POST /api/content/{cid}/generate-video 生成视频；POST /api/content/{cid}/video-generate 创建视频生成任务（body VideoGenIn：prompt string、first_frame_url/last_frame_url string、ratio string、resolution string、duration int、storyboard array、model string、config_id int、audio bool）。

标签管理接口（/api/tags）

GET /api/tags 返回标签数组，字段：id int、tag_type string（icd/sic/sic_med/crowd/lifestyle/space/time/func）、group_name string（分组名）、tag_value string（标签值）、map_sic / map_icd string（SIC/ICD 映射）、enabled int、is_custom int。GET /api/tags/options 返回标签选项（按类别分组的下拉数据）。

POST /api/tags — 新增标签（请求体 TagIn）：

PUT /api/tags/{tid} 编辑（请求体同 TagIn）；DELETE /api/tags/{tid} 删除（已被内容使用的标签返回 400）。标签组接口见第三章「标签组接口」。

来源与黑名单接口（/api/sources · /api/source-groups · /api/blacklist）

GET /api/sources 参数：group_id int（分组筛选）、keyword string（名称/域名搜索）、enabled int（0=全部，默认）、page/size int（默认 1/200）。返回 {"total":int,"items":[{id:int,name:string,domain:string,category:string,url:string,group_id:int,enabled:int}]}。

POST /api/sources — 新增来源（SourceIn）：

PUT /api/sources/{sid} 编辑（请求体同 SourceIn）；DELETE /api/sources/{sid} 删除。

GET /api/source-groups 返回来源分组数组（含组内来源）。POST /api/source-groups（SourceGroupIn：name string 必填、remark string、source_ids array<int> 组内来源）。PUT /api/source-groups/{gid}、DELETE /api/source-groups/{gid}。

GET /api/blacklist 返回黑名单数组（domain、reason、enabled）。POST /api/blacklist（BlackIn：domain string 必填、reason string、enabled int 默认 1）。DELETE /api/blacklist/{bid}。

模板管理接口（/api/templates）

GET /api/templates 返回模板数组：id int、name string、version string、is_default int（1 默认模板）、content string（模板 HTML，支持变量占位符）。

POST /api/templates — 新增模板（TemplateIn）：

PUT /api/templates/{tid} 编辑（请求体同 TemplateIn）；POST /api/templates/{tid}/copy 复制模板；DELETE /api/templates/{tid} 删除。

设置接口（/api/settings）

GET /api/settings 返回 {"settings":{key:value,...}}，常用键：

PUT /api/settings 请求体为键值对字典（仅需传要修改的键），返回 {"ok":true}。

日志接口（/api/logs）

GET /api/logs 参数：module string（模块筛选）、level string（info/warn/error）、keyword string（详情搜索）、page/size int（默认 1/50）。返回 {"total":int,"items":[{id:int,level:string,module:string,action:string,detail:string,operator:string,created_at:datetime}]}。GET /api/logs/export 导出 CSV。

营销接口（/api/products · /api/marketing）（v22 新增）

GET /api/products 参数：keyword string（按名称模糊）、enabled int（-1 全部/1 启用/0 停用）。返回 {"items":[商品]}，商品字段：id int、goods_no string（货号）、name string、generic_name string（通用名）、spec string（规格）、manufacturer string（生产单位）、price float（零售价，元）、brand string、category string（品类，六选一：药品-OTC/药品-Rx/保健食品/医疗器械/普通食品/其他，缺省「其他」）、selling_point string、instruction string（商品说明书）、image_url string、remark string、enabled int、content_count int（露出文章数）、last_at string（最近露出时间）。

POST /api/products — 新增商品（ProductIn）：

GET /api/products/{pid} 返回 {"item":商品}（字段同列表，v23 新增）。PUT /api/products/{pid} 编辑（请求体同 ProductIn，全量提交）；DELETE /api/products/{pid} 删除（连带删除露出关联）。

POST /api/products/ai-fill：AI 批量加工商品资料（v24 新增）。请求体 {"limit": 20}（每批最多 40 条），对通用名/品类/品牌/卖点存在空缺的商品自动补全（已有值不覆盖，品类仅修正「其他」）。返回 {"filled":int,"pending":int,"items":[{id,name,generic_name,category,brand,selling_point,changed:[更新字段]}]}，前端循环调用直至 pending 为 0。

POST /api/products/import：multipart 上传 Excel，按表头名自动识别列（v23 起支持商品清单模板列：序号/货号/商品名(必填)/通用名/规格/生产单位/零售价/品类/品牌/商品说明书/品牌卖点；也兼容旧列：商品名称/品牌/品类/卖点/图片链接/备注）。同名或同货号更新、否则新增；品类为空或非法自动归「其他」。返回 {"created":int,"updated":int,"skipped":int,"cat_fixed":int}。

GET /api/products/{pid}/contents 返回该商品露出的文章列表（content_id、title、digest、cover_image、status、created_at）。

GET /api/marketing/stats 返回 {"items":[商品露出统计（含 count 排名）],"total_products":int,"enabled_products":int,"total_exposures":int,"categories":[{category,count}]}。

营销机制：AI 生成文章初稿时，自动将「启用」状态的商品注入提示词，AI 选择与主题相关的 1-3 个商品以健康建议口吻自然融入；文章入库后按商品名匹配正文自动记录露出关联。

场景管理接口（/api/scenes）

GET /api/scenes 返回 {"items":[{id:int,name:string,remark:string}]}。POST /api/scenes（SceneIn：name string 必填、remark string）。PUT /api/scenes/{sid} 编辑；DELETE /api/scenes/{sid} 删除。

上传接口（/api/upload/image）

POST /api/upload/image：multipart/form-data，字段 file（image/*）。返回 {"url":string}（对象存储/本机存储公网地址）。

公众号接口（/api/mp）

POST /api/mp/test：无请求体，测试公众号连通性，返回测试结果。POST /api/mp/publish — 发布文章（MpPublishIn）：

GET /api/mp/publish/{publish_id} 查询发布任务状态与结果。

AI 生成接口（/api/ai）

POST /api/ai/generate — AI 通用生成（AiGenIn）：

POST /api/ai/cover — AI 生成封面图（请求体同 AiGenIn），返回封面图 URL。

媒体任务接口（/api/media-tasks）

GET /api/media-tasks 参数：content_id string（按内容筛选）、status string（0 待处理 / 1 处理中 / 2 完成 / 3 失败）。返回媒体任务数组：id int、task_no string、content_id string、type string（image/video）、model string、prompt string、status int、url string（生成结果）、extra JSON（含配置与模型信息）。

PUT /api/media-tasks/{mtid} 编辑提示词并重跑（MediaTaskIn：prompt string），返回 {"ok":true}。

用户与用户组同步接口（v19 补充文档）

供外部系统（如企微、HR）批量同步用户与用户组，API Key 鉴权（Authorization: Bearer ZK-xxx，任意启用的 Key 均可调用，无需额外 scope）。

POST /api/users/sync — 批量同步用户，请求体：

返回 {"ok":true,"created":int,"updated":int,"skipped":int}（username 为空跳过计入 skipped）。

POST /api/groups/sync — 批量同步用户组，请求体：

返回 {"ok":true,"created":int,"updated":int}。