商品评论 comment | API接口文档 | 文档中心 | DouPHP企业建站系统

商品评论 comment

模块说明

comment 提供内容评论能力：前台侧可公开读取任意模块内容（如商品）的评论列表；会员侧提供"我的评论、发表评论表单、提交评论、评论图片上传与删除"完整闭环（评论与订单项关联，需先完成购买）。

鉴权级别：评论列表公开；会员侧全部必须登录（comment/user/*）。

接口一览

方法	URL	鉴权	说明
GET	`/api/comment`	公开	模块入口（占位，返回空数据）
GET	`/api/comment/list`	公开	指定内容的评论列表
GET	`/api/comment/user`	必须	我的评论列表
GET	`/api/comment/user/add`	必须	发表评论表单数据
POST	`/api/comment/user`	必须	提交评论
POST	`/api/comment/user/filebox`	必须	上传评论图片（multipart）
POST	`/api/comment/user/filedel`	必须	删除评论图片

评论列表

请求参数

参数	必填	说明
`module`	是	模块英文名（如 `product`）
`item_id`	是	内容 ID（必须大于 0）
`page`	否	页码，默认 1

每页数量取站点配置 pagination.comment（默认 10）。

响应

{
  "code": "OK",
  "message": "",
  "data": {
    "comment_list": [
      { "id": 1, "content": "很好的商品", "add_time": "2026-01-01", "...": "以实际返回为准" }
    ],
    "total": 1
  },
  "errors": {},
  "request_id": "9f2a5c8e1b3d7f40"
}

场景	响应
`module` 为空或 `item_id <= 0`	`400 INVALID_PARAMS`

我的评论

GET /api/comment/user?page=1

{
  "code": "OK",
  "message": "",
  "data": {
    "title": "我的评论",
    "comment_list": [ { "...": "评论记录（含关联订单项与内容信息）" } ],
    "total": 3
  },
  "errors": {},
  "request_id": "9f2a5c8e1b3d7f40"
}

发表评论表单

GET /api/comment/user/add?order_item_id=123

参数	必填	说明
`order_item_id`	是	订单项 ID（评论以订单项为单位）

{
  "code": "OK",
  "message": "",
  "data": {
    "title": "发表评论",
    "item": { "...": "订单项对应的内容信息" },
    "order_item_id": 123,
    "html_file_list": [ "...已上传的评论图 HTML 片段..." ]
  },
  "errors": {},
  "request_id": "9f2a5c8e1b3d7f40"
}

场景	响应
订单项不存在	`400 INVALID_PARAMS`
无权限评论（未购买 / 已评论等，由评论服务判定）	`403 FORBIDDEN`（`message` 为具体原因）
表单数据缺失	`404 NOT_FOUND`

提交评论

POST /api/comment/user

参数	必填	说明
`order_item_id`	是	订单项 ID
评论内容及评分字段	是	由评论服务按站点配置校验（如 `content`、`rank` 等）
图片	否	先经 `filebox` 上传，提交时随表单字段关联

{
  "code": "OK",
  "message": "评论发表成功",
  "data": { "success": "评论发表成功" },
  "errors": {},
  "request_id": "9f2a5c8e1b3d7f40"
}

场景	响应
业务规则拒绝（未购买、重复评论、水贴等）	`422 BUSINESS_RULE_VIOLATION`（`message` 为具体原因）
其它校验失败	`400 INVALID_PARAMS`

评论图片上传 / 删除

上传 `POST /api/comment/user/filebox`（multipart/form-data）

参数	必填	说明
`item_id`	是	订单项 ID 对应的内容 ID（与提交评论同一上下文）
`gallery`	是	图片文件字段（multipart）

单个内容最多保留 3 张评论图；超出后上传被静默忽略（仍返回当前图集）。无权限时返回空图集。

响应（上传与删除结构一致）：

{
  "code": "OK",
  "message": "",
  "data": {
    "html_file_list": [ "...图集 HTML 片段（用于小程序富文本渲染）..." ]
  },
  "errors": {},
  "request_id": "9f2a5c8e1b3d7f40"
}

删除 `POST /api/comment/user/filedel`

参数	必填	说明
`number`	是	文件编号（仅允许字母、数字、点号，如 `123_abc123_20260101.jpg`）

注意事项

comment/user/add 与 comment/user/filebox 中传入的 item_id 语义不同：前者是订单项 ID，后者是内容 ID；两者均由评论服务的权限校验兜底；
html_file_list 返回的是可直接渲染的 HTML 片段（小程序侧约定），通用客户端建议自行从片段中提取图片地址，或改为按业务需要二次开发返回结构化文件列表；
评论列表为公开接口，评论的展示与否（审核）由后台站点配置控制。

添加日期：2026-10-06