MLS 作品接口文档

路径前缀：POST /mls/tool/{Tag}。需登录接口在 Body 传 token（网关注入 uin）。

0. 作品统计字段说明

列表/详情中的互动与观看数据均来自 apaas.mls_works 累计字段（由点赞、评论、分享、reportMlsWorksStat 等接口实时维护），不再对流水表做 COUNT。

我的作品累计统计见 §6 getMyWorksStats（汇总当前用户全部 published 作品）。

1. POST 获取所有公开作品（首页作品流）

POST /mls/tool/getWorksFeed

说明：返回已发布且公开（status=published 且 isPrivate=0）的作品列表，按发布时间倒序。免登录可调用；传 token 且有效时返回 isLiked。

Body 请求参数

{
  "page": 1,
  "num": 10,
  "token": "{{token}}"
}

请求参数

返回字段说明（data[]）

返回示例

200 Response

{
  "flag": 100,
  "flagString": "success",
  "data": [
    {
      "worksId": 19,
      "episodeId": 612,
      "uin": 1037,
      "worksTitle": "1001-多语言版本",
      "languageCode": "multi",
      "videoUrl": [
        {
          "language": "中文",
          "url": "http://mls-long.huaguangyun.cn/u/1037/mp4/0x0/mls-1037-1037-9e981e62ae443c058f47b9e076b68319.mp4"
        },
        {
          "language": "英文",
          "url": "http://mls-long.huaguangyun.cn/u/1037/mp4/0x0/mls-1037-1037-6879a47844e6f5e13ed58ad6b20966f7.mp4"
        }
      ],
      "coverUrl": "http://cdn-dvr.jstest.aodianyun.cn/pic/g-dvr/u/1101/images/65fcb49cfc2243131c3ca608d148950e/0/0",
      "status": "published",
      "likeCount": 0,
      "commentCount": 0,
      "shareCount": 0,
      "pv": 120,
      "uv": 45,
      "vv": 80,
      "authorName": "120****5678",
      "authorAvatar": "",
      "isLiked": false
    }
  ],
  "total": 1
}

2. POST 发布作品

POST /mls/tool/publishWorks

说明：将 MLS 任务中已生成完成的语种发布为作品；从任务 results 按所选语种组装 videoUrl。不要求任务整体 resStatus=3，但前端提交的每个语种在 results 中须为成功（status=2）且含有效 url。发布后默认 status=under_review（待审核），管理后台审核通过后变为 published 方可在首页展示及开放互动。需登录。

Body 请求参数

{
  "token": "{{token}}",
  "episodeId": 612,
  "language": "chinese,english",
  "title": "1001-多语言版本",
  "coverUrl": "https://static-pro.guangdianyun.tv/common/img/eqx.jpg",
  "visibility": "public"
}

请求参数

业务说明

• 用户 status 须为 1，否则「账户受限，无法发布」。
• 任务须存在、属于当前用户；不要求任务整体 resStatus=3（部分语种完成即可发布对应语种）。
• 前端 language 为逗号分隔的 language_code 列表；每个提交的语种须在任务 results 中存在，且该条 status=2（已成功）并含有效 url；多语种全部校验通过后才允许发布。
• 视频 URL 写入前将 http:// 替换为 https://。
• 入库 status 为 under_review，非 published。
• 若任务 works_publish_blocked=1（该任务曾有作品被管理端下架），不可再次发布。

常见失败提示

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "productId": 21
  }
}

3. POST 获取我的作品列表

POST /mls/tool/getMyWorksList

说明：分页查询当前用户除已删除外的全部作品（含待审核、已发布、审核未通过、已下架等）。需登录。

Body 请求参数

{
  "token": "{{token}}",
  "page": 1,
  "num": 10,
  "language": "全部",
  "period": "30d"
}

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": [
    {
      "worksId": 20,
      "episodeId": 612,
      "uin": 1037,
      "worksTitle": "1001-希伯来语",
      "languageCode": "hebrew",
      "coverUrl": "/static/images/default-cover.png",
      "status": "under_review",
      "isPrivate": 1,
      "rejectReason": "",
      "reviewTime": 0,
      "likeCount": 0,
      "commentCount": 0,
      "shareCount": 0,
      "pv": 0,
      "uv": 0,
      "vv": 0
    }
  ],
  "total": 1
}

isPrivate：1 仅自己可见，0 公开可见。

作品 status 枚举

非 published 作品互动规则

点赞、分享、发表评论仅 status=published 时允许；查看评论列表规则略有不同（见 §10）。

作者在非 published 状态下操作点赞/分享/发表评论时的提示：

补充：

• 取消点赞（liked=false）：若用户此前已点赞且作品未删除，允许取消，不受上述状态限制。
• 浏览/播放上报（§13）：作者可预览本人非已发布作品，但不计入公开展示统计；规则见 §13。

4. POST 我的作品详情

POST /mls/tool/getMyWorksDetail

Body 请求参数

{
  "token": "{{token}}",
  "worksId": 11
}

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "id": 11,
    "episodeId": 612,
    "title": "1001-中文",
    "language": "多语言",
    "coverUrl": "https://static-pro.guangdianyun.tv/common/img/eqx.jpg",
    "videoUrl": [
      {
        "language": "中文",
        "url": "http://mls-long.huaguangyun.cn/u/1037/mp4/0x0/mls-1037-1037-9e981e62ae443c058f47b9e076b68319.mp4"
      },
      {
        "language": "英文",
        "url": "http://mls-long.huaguangyun.cn/u/1037/mp4/0x0/mls-1037-1037-6879a47844e6f5e13ed58ad6b20966f7.mp4"
      }
    ],
    "status": "published",
    "likeCount": 0,
    "commentCount": 0,
    "shareCount": 0,
    "pv": 0,
    "uv": 0,
    "vv": 0,
    "createdAt": 1776836462,
    "authorName": "120****5678",
    "authorAvatar": "",
    "isLiked": false
  }
}

5. POST 删除我的作品

POST /mls/tool/deleteMyWorks

说明：软删除本人作品（status=deleted），并清理点赞、分享及有效评论。需登录。

Body 请求参数

{
  "token": "{{token}}",
  "worksId": 20
}

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success"
}

5.1 POST 修改作品可见性

POST /mls/tool/updateMyWorksVisibility

说明：作者切换本人作品的公开范围（public / private）。仅可操作本人且非 deleted 的作品；under_review、rejected 不可修改。需登录。

Body 请求参数

{
  "token": "{{token}}",
  "worksId": 20,
  "visibility": "public"
}

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "worksId": 20,
    "visibility": "public",
    "isPrivate": 0
  }
}

5.2 POST 编辑审核未通过的作品

POST /mls/tool/editMyWorks

说明：仅 status=rejected（审核未通过） 的本人作品可编辑；可修改标题、封面图（至少传一项）。保存后状态变为 under_review（待审核），并清空 rejectReason。需登录。

Body 请求参数

{
  "token": "{{token}}",
  "worksId": 20,
  "title": "修改后的标题",
  "coverUrl": "https://example.com/cover.jpg"
}

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "worksId": 20,
    "title": "修改后的标题",
    "coverUrl": "https://example.com/cover.jpg",
    "status": "under_review"
  }
}

6. POST 获取我的作品统计

POST /mls/tool/getMyWorksStats

说明：汇总当前用户全部已发布（status=published）作品的累计互动/观看数据，数据来自 mls_works 表对应字段的 SUM。无 period、includeSeries 等其它入参。需登录。

Body 请求参数

{
  "token": "{{token}}"
}

请求参数

返回字段说明

说明：待审核、审核未通过、已下架、已删除的作品不计入本接口统计。

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "publishedCount": 3,
    "totalLikes": 10,
    "totalComments": 4,
    "totalShares": 6,
    "totalPv": 120,
    "totalUv": 45,
    "totalVv": 80
  }
}

7. POST 点赞/取消点赞

POST /mls/tool/likeWorks

说明：对 status=published 的作品点赞或取消点赞。非 published 时的权限与提示见 §3 非 published 作品互动规则。需登录。

Body 请求参数

{
  "token": "{{token}}",
  "worksId": 18,
  "liked": true
}

请求参数

业务说明

• 点赞（liked=true）：作品须为 published；否则非作者返回 作品不存在或不可操作，作者返回状态提示（如 作品已下架）。
• 取消点赞（liked=false）：若当前用户已有该作品点赞记录且作品未删除，允许取消。

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "liked": true
  }
}

8. POST 我点赞的作品列表

POST /mls/tool/getMyLikedWorksList

Body 请求参数

{
  "token": "{{token}}",
  "page": 1,
  "num": 10
}

请求参数

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": [
    {
      "worksId": 12,
      "episodeId": 612,
      "uin": 1037,
      "worksTitle": "1001-中文",
      "languageCode": "multi",
      "videoUrl": [
        {
          "language": "中文",
          "url": "http://mls-long.huaguangyun.cn/u/1037/mp4/0x0/mls-1037-1037-9e981e62ae443c058f47b9e076b68319.mp4"
        },
        {
          "language": "英文",
          "url": "http://mls-long.huaguangyun.cn/u/1037/mp4/0x0/mls-1037-1037-6879a47844e6f5e13ed58ad6b20966f7.mp4"
        }
      ],
      "coverUrl": "https://static-pro.guangdianyun.tv/common/img/eqx.jpg",
      "status": "published",
      "likeCount": 1,
      "commentCount": 0,
      "shareCount": 0,
      "pv": 10,
      "uv": 5,
      "vv": 8,
      "authorName": "120****5678",
      "authorAvatar": ""
    }
  ],
  "total": 1
}

9. POST 发表评论

POST /mls/tool/commentWorks

说明：对 status=published 的作品发表评论或回复。非 published 时不允许新增评论；作者本人会收到状态提示，非作者返回 作品不存在或不可操作。规则见 §3 非 published 作品互动规则。需登录。

Body 请求参数

{
  "worksId": 19,
  "content": "同意",
  "parentCommentId": 2, //主评论的id
  "replyToUserId": 1037, //回复评论的userId
  "token": "{{token}}"
}

请求参数

业务说明

• 作品须为 published 方可发表评论。
• 非 published：非作者 → 作品不存在或不可操作；作者 → 作品审核中 / 作品审核未通过 / 作品已下架 等。

返回示例

200 Response

{
    "flag": 100,
    "flagString": "success",
    "data": {
        "commentId": 3
    }
}

10. POST 评论列表

POST /mls/tool/getWorksCommentList

说明：分页查询作品评论。published 作品所有人可查看；非 published 时仅作者本人可查看评论列表，非作者返回 作品不存在或不可操作。规则见 §3 非 published 作品互动规则。

Body 请求参数

{
    "token": "{{token}}",
    "page": 1,
    "num": 10,
    "worksId": 19,
    "parentCommentId": 2 //不传为获取主评论，传的话则获取子评论
}

请求参数

主评论返回

200 Response

{
    "flag": 100,
    "flagString": "success",
    "data": [
        {
            "commentId": 2,
            "worksId": 19,
            "uin": 1037,
            "username": "120****5678",
            "avatar": "",
            "content": "这个视频太棒了",
            "createdAt": 1777012247,
            "replyCount": 1
        }
    ],
    "total": 1
}

子评论返回

200 Response

{
    "flag": 100,
    "flagString": "success",
    "data": [
        {
            "commentId": 3,
            "worksId": 19,
            "uin": 1037,
            "username": "120****5678",
            "avatar": "",
            "content": "同意",
            "createdAt": 1777012768,
            "replyToUin": 1037,
            "replyToUsername": "120****5678"
        }
    ],
    "total": 1
}

11. POST 删除评论

POST /mls/tool/deleteWorksComment

Body 请求参数

{
  "worksId": 19,
  "token": "{{token}}",
  "commentId": 2
}

请求参数

返回示例

200 Response

{
    "flag": 100,
    "flagString": "success"
}

12. POST 作品分享上报

POST /mls/tool/shareMlsWorks

说明：记录作品分享次数。仅 status=published 的作品允许分享；非 published 时的权限与提示见 §3 非 published 作品互动规则。

Body 请求参数

{
  "worksId": 19
}

请求参数

说明

• 前端每次触发分享动作后调用一次，后端写入 mls_works_share 分享流水。
• 作品须为 published；否则非作者返回 作品不存在或不可操作（flag=40401），作者返回状态提示（如 作品已下架）。
• 接口支持游客调用：未登录时会以 userId=0 记录分享流水。
• 接口限流：同一客户端 1 秒内仅允许写入 1 条分享记录（超限时静默成功，但不会新增流水）。
  • 已登录：按用户 uin 限流
  • 游客：按 IP + User-Agent 指纹限流

返回示例

{
  "flag": 100,
  "flagString": "success"
}

13. POST 作品浏览/播放上报

POST /mls/tool/reportMlsWorksStat

Body 请求参数

{
  "worksId": 19,
  "eventType": "pv"
}

请求参数

说明

• 免登录可调用（首页游客）；带 token 时网关会解析登录用户并注入 uin（与 shareMlsWorks 一致），便于作者在「我的作品」预览本人待审核/未通过/下架作品。
• 仅 status=published 的作品对访客累计 pv/vv/uv；作者预览本人非已发布作品时接口返回成功，不计入展示统计，避免污染公开展示数据。
• 非已发布作品且访问者非作者：返回「作品不存在或不可操作」。
• 同一访客对同一作品 1 秒内 重复上报静默成功但不累加。
• 数据写入 mls_works_stat_daily（按日）并同步 mls_works 累计字段。
• UV：Redis 键 mls:works:uv:{worksId}:{statDate}:{visitorHash}，当日首次 pv 计 1 次 UV。

返回示例

{
  "flag": 100,
  "flagString": "success"
}

14. POST 获取上传图片凭证（封面上传）

POST /mls/tool/getOssInfo

Body 请求参数

{
    "token": "{{token}}"
}

请求参数

返回示例
200 Response

{
    "flag": 100,
    "flagString": "success",
    "data": {
        "accessid": "Td3t2RJXQVwZtI0wghwRTIe1",
        "callback": "eyJjYWxsYmFja1VybCI6Imh0dHA6Ly9nZHlvc3MuanN0ZXN0LmFvZGlhbnl1bi5jbi92MS9maWxlL3NldE1zZyIsImNhbGxiYWNrQm9keSI6ImZpbGVuYW1lPSR7b2JqZWN0fVx1MDAyNnNpemU9JHtzaXplfVx1MDAyNm1pbWVUeXBlPSR7bWltZVR5cGV9XHUwMDI2aGVpZ2h0PSR7aW1hZ2VJbmZvLmhlaWdodH1cdTAwMjZ3aWR0aD0ke2ltYWdlSW5mby53aWR0aH0iLCJjYWxsYmFja0JvZHlUeXBlIjoiYXBwbGljYXRpb24veC13d3ctZm9ybS11cmxlbmNvZGVkIn0=",
        "dir": "1037/mls/",
        "expire": 1777433365,
        "host": "gdyoss.jstest.aodianyun.cn/v1/file/frontUpload?authKey=e22488067969afd2c63f722d5727321&bucket=g-dvr",
        "policy": "eyJleHBpcmF0aW9uIjoiMjAyNi0wNC0yOVQxMToyODoyNVoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsMCwxMDQ4NTc2MDAwXSxbInN0YXJ0cy13aXRoIiwiJGtleSIsIjEwMzcvbWxzLyJdXX0=",
        "signature": "gYLrnvLRu/C0DS8GSJZPqgvDkcU="
    }
}

15. POST 查询当前有效的积分奖励规则

POST /mls/tool/getMlsWorksRewardRuleList

说明：返回后台已启用且在有效期内配置的积分规则及阶梯，供作品侧展示激励说明。需登录（网关校验 token，未在 NO_TOKEN_CMDS 白名单）；业务实现不依赖 uin，可按类型/维度筛选。

Body 请求参数

{
  "token": "{{token}}",
  "ruleType": 1,
  "dimension": 1
}

返回字段说明（data.list[]）

业务说明

• 仅 enable = 1 且当前时间在有效期内的规则（长期有效或固定时段窗口内）。
• 阶梯按 threshold 升序；发奖逻辑与后台 mls_points_rule / mls_points_rule_tier 一致。

16. POST 查询作品积分奖励未读列表

POST /mls/tool/getMlsWorksRewardNoticeList

说明：查询当前登录用户（创作者）近 3 天内、未读的作品积分激励达标记录，用于任务中心/达标弹窗。需登录（token）；uin 由网关根据 token 注入，无需前端传。

Body 请求参数

{
  "token": "{{token}}"
}

请求参数

返回字段说明（data.list[]）

业务说明

• 仅返回 is_read = 0 且 achieve_time 在 最近 3 天 内的记录，最多 200 条，按达成时间倒序。
• 播放量维度按作品 UV 统计；达标后写入 mls_works_reward_record，并由后台定时任务消费 Redis 队列发放积分。

返回示例

{
  "flag": 100,
  "flagString": "success",
  "data": {
    "list": [
      {
        "id": 2,
        "uin": 1074,
        "worksId": 27,
        "episodeId": 612,
        "videoId": 612,
        "ruleId": 1,
        "ruleName": "测试转发",
        "ruleType": 1,
        "dimension": 3,
        "dimensionName": "转发量",
        "threshold": 10,
        "metricValue": 12,
        "rewardPoints": 500,
        "conditionDesc": "转发量>=10",
        "achieveTime": 1779783600,
        "isRead": 0,
        "grantStatus": 1,
        "grantTime": 1779783716
      }
    ]
  }
}

17. POST 标记作品积分奖励已读

POST /mls/tool/markMlsWorksRewardRead

说明：将指定奖励记录标记为已读；仅可更新当前用户本人的记录。需登录（token）。

Body 请求参数（单条）

{
  "token": "{{token}}",
  "id": 2
}

Body 请求参数（批量）

{
  "token": "{{token}}",
  "ids": [2, 3, 5]
}

请求参数

业务说明

• id 与 ids 至少传一种；仅更新 is_read = 0 的记录。
• 已读不影响积分发放状态（grantStatus 由后台发奖任务维护）。

返回示例

{
  "flag": 100,
  "flagString": "success"
}

附录 A：作品接口一览

* getWorksCommentList 未强制 token；非 published 作品时作者须传有效 token 方可查看。

文档同步说明：§2 发布校验已改为按语种 results.status=2 校验（不再要求任务 resStatus=3）；§3 补充非 published 互动规则；§7/§9/§10/§12 与线上一致。