花枫咖啡馆内部扩展 API — 社区与动态模块 (Extra)

基础信息

• 前缀URL: /v1/internal
• 主要功能: 社区帖子 CRUD、个人动态 CRUD、评论与点赞系统、社区圈子与子版块管理。

---

接口列表

1. 帖子管理 (Posts)

1.1 创建社区帖子

POST /v1/internal/post.create

在论坛/社区中发表新帖子或讨论。需 Header 携带 Token。

请求参数

参数名	类型	必填	描述
community_id	number	否	社区 ID，默认 1
subsection_id	number	否	子版块 ID
category_id	number	否	分类 ID
title	string	是	帖子标题
content	string	否	帖子内容
tags	any	否	标签
attachment_urls	any	否	附件 URL 列表
type	string	否	帖子类型，默认 discussion

请求示例

{
  "community_id": 1,
  "title": "关于Satori协议拓展的讨论",
  "content": "大家觉得这个设计如何？",
  "type": "discussion"
}

成功响应示例

{
  "id": 50,
  "user_id": 1,
  "title": "关于Satori协议拓展的讨论",
  "content": "大家觉得这个设计如何？",
  "created_at": "2026-02-01 12:00:00"
}

1.2 获取帖子详情

POST /v1/internal/post.get

查询单个社区帖子的详细信息。

请求参数

参数名	类型	必填	描述
post_id	number	是	帖子 ID

请求示例

{
  "post_id": 50
}

成功响应示例

{
  "id": 50,
  "community_id": 1,
  "user_id": 1,
  "title": "关于Satori协议拓展的讨论",
  "content": "大家觉得这个设计如何？"
}

1.3 获取帖子列表

POST /v1/internal/post.list

按社区或全站公开查询帖子列表。

请求参数

参数名	类型	必填	描述
community_id	number	否	筛选社区 ID（未传则查询全站公开帖子）
limit	number	否	限制条数，默认 50
offset	number	否	偏移量，默认 0

请求示例

{
  "community_id": 1,
  "limit": 20,
  "offset": 0
}

成功响应示例

{
  "data": [
    {
      "id": 50,
      "title": "关于Satori协议拓展的讨论"
    }
  ],
  "next": null
}

1.4 删除帖子

POST /v1/internal/post.delete

删除本人发表的社区帖子。需 Header 携带 Token。

请求参数

参数名	类型	必填	描述
post_id	number	是	帖子 ID

请求示例

{
  "post_id": 50
}

成功响应示例

{}

---

2. 动态管理 (Moments)

2.1 发布个人动态

POST /v1/internal/moment.create

发布朋友圈/个人动态。需 Header 携带 Token。

请求参数

参数名	类型	必填	描述
content	string	否	动态正文文本
media_urls	string[]	否	图片/媒体文件 URL 数组
video_url	string	否	视频文件 URL

请求示例

{
  "content": "今天天气真好！",
  "media_urls": ["/static/uploads/chat/pic1.jpg"]
}

成功响应示例

{
  "id": 12,
  "user_id": 1,
  "content": "今天天气真好！",
  "created_at": "2026-02-01 12:00:00"
}

2.2 获取动态列表

POST /v1/internal/moment.list

查询个人或全站公开动态列表。

请求参数

参数名	类型	必填	描述
user_id	number	否	指定用户 ID
limit	number	否	条数限制，默认 50
offset	number	否	偏移量，默认 0

请求示例

{
  "limit": 10,
  "offset": 0
}

成功响应示例

{
  "data": [
    {
      "id": 12,
      "content": "今天天气真好！"
    }
  ],
  "next": null
}

2.3 删除动态

POST /v1/internal/moment.delete

删除本人发布的个人动态。需 Header 携带 Token。

请求参数

参数名	类型	必填	描述
moment_id	number	是	动态 ID

请求示例

{
  "moment_id": 12
}

成功响应示例

{}

---

3. 评论与点赞 (Comments & Likes)

3.1 发表评论

POST /v1/internal/comment.create

为指定的动态或社区帖子发表评论。需 Header 携带 Token。

请求参数

参数名	类型	必填	描述
target_type	string	是	目标类型 (moment 或 post)
target_id	number	是	目标 ID (动态 ID 或 帖子 ID)
content	string	是	评论正文
parent_id	number	否	父级评论 ID (用于回复特定评论)

请求示例

{
  "target_type": "post",
  "target_id": 50,
  "content": "赞同你的看法！"
}

成功响应示例

{
  "id": "88"
}

3.2 获取评论列表

POST /v1/internal/comment.list

获取动态或帖子的评论列表。

请求参数

参数名	类型	必填	描述
target_type	string	是	目标类型 (moment 或 post)
target_id	number	是	目标 ID
page	number	否	页码，默认 1
limit	number	否	每页限制，默认 20

请求示例

{
  "target_type": "post",
  "target_id": 50,
  "page": 1,
  "limit": 10
}

成功响应示例

{
  "data": [
    {
      "id": 88,
      "user_id": 1,
      "content": "赞同你的看法！",
      "created_at": "2026-02-01 12:05:00"
    }
  ]
}

3.3 点赞

POST /v1/internal/like.create

对动态或帖子进行点赞。需 Header 携带 Token。

请求参数

参数名	类型	必填	描述
target_type	string	是	目标类型 (moment 或 post)
target_id	number	是	目标 ID

请求示例

{
  "target_type": "moment",
  "target_id": 12
}

成功响应示例

{}

3.4 取消点赞

POST /v1/internal/like.delete

取消对动态或帖子的点赞。需 Header 携带 Token。

请求参数

参数名	类型	必填	描述
target_type	string	是	目标类型 (moment 或 post)
target_id	number	是	目标 ID

请求示例

{
  "target_type": "moment",
  "target_id": 12
}

成功响应示例

{}

---

4. 社区与子版块 (Communities & Subsections)

4.1 创建社区

POST /v1/internal/community.create

创建一个新的社区/圈子。需 Header 携带 Token。创建者自动获得 owner 身份。

请求参数

参数名	类型	必填	描述
name	string	是	社区名称
description	string	否	社区描述
type	string	否	社区类型，默认 public
join_policy	string	否	加入策略 (open / invite / apply)，默认 open
avatar_url	string	否	社区图标 URL

请求示例

{
  "name": "咖啡爱好者交流圈",
  "description": "探讨咖啡豆与烘焙技巧",
  "type": "public",
  "join_policy": "open"
}

成功响应示例

{
  "id": 5,
  "name": "咖啡爱好者交流圈",
  "description": "探讨咖啡豆与烘焙技巧",
  "created_by": 1,
  "type": "public"
}

4.2 加入社区

POST /v1/internal/community.join

加入指定社区。需 Header 携带 Token。

请求参数

参数名	类型	必填	描述
community_id	number	是	社区 ID

请求示例

{
  "community_id": 5
}

成功响应示例

{
  "success": true
}

4.3 退出社区

POST /v1/internal/community.leave

退出指定社区。需 Header 携带 Token。

请求参数

参数名	类型	必填	描述
community_id	number	是	社区 ID

请求示例

{
  "community_id": 5
}

成功响应示例

{
  "success": true
}

4.4 创建子版块

POST /v1/internal/subsection.create

在指定社区下新建一个子版块。需 Header 携带 Token。

请求参数

参数名	类型	必填	描述
community_id	number	是	所属社区 ID
name	string	是	版块名称
description	string	否	版块描述
order_num	number	否	排序权重，默认 0

请求示例

{
  "community_id": 5,
  "name": "烘焙讨论",
  "description": "手冲与意式豆烘焙交流"
}

成功响应示例

{
  "id": 2,
  "name": "烘焙讨论"
}

4.5 获取子版块列表

POST /v1/internal/subsection.list

查询某个社区下的全部激活子版块。

请求参数

参数名	类型	必填	描述
community_id	number	是	社区 ID

请求示例

{
  "community_id": 5
}

成功响应示例

{
  "data": [
    {
      "id": 2,
      "community_id": 5,
      "name": "烘焙讨论",
      "description": "手冲与意式豆烘焙交流",
      "order_num": 0,
      "is_active": true
    }
  ]
}