墨台 MUOTAI

Appearance

云集市字典 & 标签管理接口 ​

网关前缀：/ai
鉴权：Bearer Token
统一响应：{ "code": 0, "msg": null, "data": ... }

一、业务字典（只读） ​

1.1 按分组查启用项 ​

GET /v1/dict/groups/{groupCode}/items

参数位置说明
groupCodepath分组编码

常用 groupCode：

groupCode说明
MARKET_NAV云集市左侧导航
EXPERT_SCENE / EXPERT_ROLE / EXPERT_PRICE专家筛选项
LIGHT_APP_SCENE / LIGHT_APP_SOURCE / LIGHT_APP_PRICE轻应用筛选项

data 项字段：id、label、itemValue、sortOrder、status

二、字典管理（管理端） ​

Base：/v1/admin/dict

用途方法路径
分组列表GET/groups?keyword=
新增分组POST/groups
编辑分组PUT/groups/{groupId}
删除分组DELETE/groups/{groupId}
分组下键值（含禁用）GET/groups/{groupCode}/items
新增键值POST/groups/{groupCode}/items
编辑键值PUT/groups/{groupCode}/items/{itemId}
启停键值PATCH/items/status
删除键值DELETE/groups/{groupCode}/items/{itemId}

新增/编辑分组 Body ​

json
{
  "groupName": "场景",
  "groupCode": "EXPERT_SCENE",
  "description": "专家顾问-场景筛选",
  "parentCode": "expert",
  "sortOrder": 20
}
  • groupCode：仅新增必填
  • parentCode：可选；筛选项分组填导航 itemValue（如 expert / light_app）；通用字典不传

新增/编辑键值 Body ​

json
{
  "label": "法务合规",
  "itemValue": "legal_compliance",
  "sortOrder": 1,
  "status": "ENABLED"
}

启停键值 Body ​

json
{
  "groupCode": "EXPERT_SCENE",
  "itemId": 202202,
  "status": "DISABLED"
}

status：ENABLED / DISABLED

三、标签管理 ​

Base：/v1/biz-tag

用途方法路径
标签分类（推荐）GET/categories?groupCode=MARKET_NAV&includeOptions=true
导航+筛选（同上，固定 MARKET_NAV）GET/nav-filters?includeOptions=true
某业务筛选项行GET/groups?bizType=expert
某行选项GET/groups/{tagGroupCode}/options?bizType=expert
业务已绑标签GET/list?bizType=light_app&bizId=12
覆盖绑定单组PUT/bind
批量绑定PUT/bind-batch
清空标签DELETE/clear?bizType=&bizId=&tagGroupCode=
按标签查业务 IDPOST/query-biz-ids

bizType 与 MARKET_NAV.itemValue 一致：expert / light_app / feed / doc_template

3.1 标签分类 ​

GET /v1/biz-tag/categories?groupCode=MARKET_NAV&includeOptions=true

关联规则：筛选项分组 parent_code = 导航项 itemValue

data 示例：

json
[
  {
    "id": 202802,
    "bizType": "expert",
    "label": "专家顾问",
    "sortOrder": 1,
    "hasFilters": true,
    "filterGroups": [
      {
        "id": 200013,
        "groupCode": "EXPERT_SCENE",
        "groupName": "场景",
        "description": "专家顾问-场景筛选",
        "options": [
          { "id": 202202, "itemValue": "legal_compliance", "label": "法务合规" }
        ]
      }
    ]
  }
]

已绑标签 GET /list 返回示例：

json
[
  {
    "id": 200013,
    "tagGroupCode": "EXPERT_SCENE",
    "tagGroupName": "场景",
    "items": [
      {
        "id": 10001,
        "bindId": 10001,
        "dictItemId": 202201,
        "tagValue": "official_doc",
        "tagLabel": "公文写作",
        "sortOrder": 1
      }
    ]
  }
]

字段说明：分组 id=字典分组主键；items[].id/bindId=绑定表主键；items[].dictItemId=字典项主键（自定义值可能为空）。

3.2 覆盖绑定单组 ​

PUT /v1/biz-tag/bind

json
{
  "bizType": "expert",
  "bizId": 1001,
  "tagGroupCode": "EXPERT_SCENE",
  "tagValues": ["legal_compliance", "official_doc"]
}

3.3 批量绑定 ​

PUT /v1/biz-tag/bind-batch

json
{
  "bizType": "light_app",
  "bizId": 12,
  "groups": [
    { "tagGroupCode": "LIGHT_APP_SCENE", "tagValues": ["legal_compliance"] },
    { "tagGroupCode": "LIGHT_APP_SOURCE", "tagValues": ["official"] },
    { "tagGroupCode": "LIGHT_APP_PRICE", "tagValues": ["paid"] }
  ]
}

某组 tagValues: [] 表示清空该组。
tagGroupCode / tagValues 允许自定义（不强制落在预置字典）；预置分组仍建议用字典值。绑定只做规范化：groupCode 转大写、tagValue 转小写。

手动扩展字段：

字段说明
costPoints消耗墨点（数字）
recommended是否推荐资源
imagePath图片路径（封面/展示图）
unlockCondition是否解锁条件
json
{
  "bizType": "expert",
  "bizId": 1001,
  "recommended": true,
  "unlockCondition": true,
  "imagePath": "/files/market/cover.png",
  "groups": [
    { "tagGroupCode": "EXPERT_PRICE", "tagValues": ["paid"], "costPoints": 7 },
    { "tagGroupCode": "EXPERT_SCENE", "tagValues": ["official_doc"] }
  ]
}

或按项：

json
{
  "tagGroupCode": "EXPERT_PRICE",
  "tagItems": [{ "tagValue": "paid", "costPoints": 7, "recommended": true, "unlockCondition": true, "imagePath": "/files/market/cover.png" }]
}

查询 /list 返回 items[].costPoints / recommended / imagePath / unlockCondition；云集市卡片会组装 priceText、recommended、unlockCondition；有 imagePath 时覆盖卡片 coverUrl。

3.4 按标签反查业务 ID ​

POST /v1/biz-tag/query-biz-ids

json
{
  "bizType": "expert",
  "unlockCondition": true,
  "filters": [
    { "tagGroupCode": "EXPERT_SCENE", "tagValues": ["legal_compliance"] },
    { "tagGroupCode": "EXPERT_ROLE", "tagValues": ["ai_expert"] }
  ]
}

规则：组间 AND，组内 OR。
unlockCondition：可选；true=资源至少有一条解锁条件标签；false=没有任何解锁条件标签；不传不按此筛。
data：[1001, 1002]（已去重）

无筛选时不要调本接口，直接拉业务列表。

3.5 清空 ​

DELETE /v1/biz-tag/clear?bizType=expert&bizId=1001
可选：&tagGroupCode=EXPERT_SCENE（不传则清空该业务全部标签）

四、云集市列表查询（后端编排） ​

前端不要自行调业务列表拼卡片；统一走本接口。

POST /v1/marketplace/query

请求 ​

json
{
  "bizType": "expert",
  "keyword": "",
  "unlockCondition": true,
  "filters": [
    { "tagGroupCode": "EXPERT_SCENE", "tagValues": ["legal_compliance"] },
    { "tagGroupCode": "EXPERT_PRICE", "tagValues": ["paid"] }
  ],
  "current": 1,
  "size": 20,
  "pageable": true
}
字段说明
bizTypeexpert / light_app / doc_template / all（分组返回）
keyword标题/简介模糊搜
unlockCondition可选；true/false 按是否含解锁条件标签筛选；不传不筛
filters可选；在「已打标资源」上再按标签收窄。不传 = 该 bizType 下全部已打标资源
current/size单类目分页；all 时 size=每组最多条数
pageable默认 true；false 不分页返回全部

不分页 ​

POST /v1/marketplace/query-all

Body 与 /query 相同（可省略 current/size），强制返回全部匹配结果。

带业务数据 ​

用途路径
分页 + 业务明细POST /v1/marketplace/query-biz
不分页 + 业务明细POST /v1/marketplace/query-biz-all

入参/筛选与 /query 完全一致；每条 items[] 多一个 bizData：

  • bizType=expert → ai_agent（id/uid/name/description/photo/agentType/publish）
  • bizType=light_app → 轻应用商店模板
  • bizType=doc_template → marketplace_doc_template

流程 ​

  1. 以 marketplace_biz_tag 为主：先取该 bizType 下已打标的 biz_id
  2. 有 filters → 再按标签条件收窄 ID
  3. 回源卡片：expert → Feign 查 AI ai_agent；light_app → Feign 商店模板；doc_template → 本库 marketplace_doc_template；并挂上已绑标签
  4. expert / light_app 未打标的资源不会出现在云集市列表；doc_template 无筛选时直接出模板表（可不打标）

响应 ​

json
{
  "grouped": false,
  "total": 10,
  "current": 1,
  "size": 20,
  "sections": [
    {
      "bizType": "expert",
      "title": "专家顾问",
      "total": 10,
      "items": [
        {
          "bizType": "expert",
          "bizId": 1001,
          "title": "法务审核专家",
          "subtitle": "专家顾问 · 智能专家",
          "description": "...",
          "coverUrl": "...",
          "priceText": "付费",
          "badges": ["付费"],
          "actionLabel": "立即对话",
          "tags": []
        }
      ]
    }
  ]
}

bizType=all 时 grouped=true，sections 含多组（供需 feed 暂为空占位）。

五、数据关系简图 ​

MARKET_NAV.itemValue = expert
        ↑ parent_code
EXPERT_SCENE / EXPERT_ROLE / EXPERT_PRICE
        ↑ group_code
字典项（公文写作、智能专家…）

业务资源 ← marketplace_biz_tag → 上述字典项