Forum

受众：开发者摘要：spring-open-module-forum 论坛：板块 / 主题 / 回复 / 举报 / 处理记录 / 互动状态 / 主题访问策略 / 基础版规。

Forum 模块用于承载社区讨论场景。当前已提供板块、主题和回复三层模型，并补齐用户侧发帖、回帖、编辑、删除、点赞、收藏、举报和主题访问策略入口，满足 PC / App 移动端论坛基础闭环。

模块是可选依赖，应用不需要论坛能力时可以移除 spring-open-module-forum 引用，不影响 CMS、Blog、Mall 或其他模块。

配置

yaml

spring:
  open:
    forum:
      enabled: true
      rules:
        enabled: true
        topic:
          title-min-length: 2
          title-max-length: 120
          content-min-length: 0
          content-max-length: 20000
        reply:
          content-min-length: 1
          content-max-length: 10000
        forbidden-words: []
      notifications:
        enabled: true
        channels:
          - database
        notify-self: false
        reply-created-template: forum.reply.created
        topic-liked-template: forum.topic.liked
        topic-favorited-template: forum.topic.favorited
        reply-liked-template: forum.reply.liked
        report-status-changed-template: forum.report.status-changed
      reports:
        auto:
          enabled: true
          auto-startup: true
          timeout: 24h
          fixed-delay: 10m
          action: rejected
          task-name: forum.report.auto-handle
          instance-id: default
          limit: 100

spring.open.forum.enabled=false 时，Forum Controller、Service 和 Mapper 扫描都会关闭。

spring.open.forum.rules 用于发帖和回帖的基础版规校验。默认只做长度兜底和全局禁用词命中校验，复杂敏感词、AI 审核、人工审核队列和风控策略后续应通过独立审核 Provider 扩展，不直接写死在 Forum Service 中。

Forum 发布入口同时内置 forum-topic-rule-precheck / forum-reply-rule-precheck Pipeline Step 和 forum-topic-rule-check / forum-reply-rule-check Chain Rule，复用 spring.open.forum.rules 做标题、正文长度和禁用词校验。应用可通过 Pipeline / Chain starter 配置启停或调整排序，再叠加自定义 Handler。

Forum 举报治理入口也内置 forum-topic-report-rule-precheck / forum-reply-report-rule-precheck / forum-report-status-rule-precheck Pipeline Step，以及 forum-topic-report-rule-check / forum-reply-report-rule-check / forum-report-status-rule-check Chain Rule，用于校验举报目标、举报原因和处理状态等基础上下文。Service 仍负责可见性、落库、处理记录、Outbox 和事件，应用可继续叠加业务侧风控或处罚 Handler。

举报创建和举报状态处理会把本次 Pipeline / Chain 执行摘要追加到 extra_json.executionTrace，同时保留业务方传入的扩展 JSON。管理员可在后台“社区论坛举报”和“举报处理记录”详情中查看并复制 traceId、Pipeline 名称、Chain 名称、执行状态、中断来源和耗时，用于定位自定义 Handler 的阻断或失败原因。

spring.open.forum.notifications 用于 Forum 互动通知。Forum 模块只发布回复、点赞、收藏、举报待审核和举报状态变更事件，默认应用装配层再通过 Notification Facade 写入站内信。这样 Forum 不直接依赖 Notification，后续可在应用层改成 Queue、WebSocket 或其他通知策略。

可见回复创建后会发布 forum.reply.created 事件，主题点赞 / 收藏会发布 forum.topic.liked / forum.topic.favorited 事件，回复点赞会发布 forum.reply.liked 事件。普通互动通知默认通知内容作者；Notification 通知规则也可用同一编码配置运营接收人、通道、去重和静默窗口，用于关注高活跃主题、互动峰值、内容留存或潜在治理风险。未配置规则接收人时，Notification 规则链路会静默跳过。

用户创建主题或回复举报后，会发布 forum.report.pending-review 事件；应用装配层可通过 Notification 运行时通知规则把待审核提醒发送给审核运营。未配置运行时规则接收人时会静默跳过，不猜测默认管理员。

当应用同时启用 Outbox 时，举报状态真实变化还会由应用装配层写入 forum-report-status / forum.report.status-changed Outbox 事件，payload 包含举报 ID、举报人、目标类型、目标 ID、处理前后状态、操作者和发生时间。Forum 模块只依赖可选 producer contract，不直接依赖 Outbox 实现。forum.report.status-changed 也已接入 Notification 通知规则，运营可为 accepted / rejected / resolved 等处理结果配置接收人、通道、去重和静默窗口；pending 状态继续走 forum.report.pending-review，避免待审核提醒重复投递。

spring.open.forum.reports.auto 用于待处理举报超时自动处理。默认开启，超过 timeout 仍未人工处理时按 action 自动落为 accepted、rejected 或 resolved，并写入举报处理记录和触发举报状态变更通知。默认 rejected 表示驳回举报，让被举报内容继续放行，避免无人处理时自动处罚内容；强审核项目可以按业务改成 accepted 或关闭自动启动。

后台举报治理 SLA 也复用 reports.auto.timeout。GET /api/v1/admin/forum/statistics 会返回 SLA 时限、待处理举报、已超时待处理、临近超时待处理和最早待处理时间；Admin /forum/reports 页面会展示这些只读摘要，并支持一键筛选 slaOverdueOnly=true 的超时待处理举报。这样运营看板、人工处理和自动处理任务使用同一套超时口径，不需要额外维护第二份 SLA 配置。

上述 Forum 配置已通过模块 ServiceProvider 声明为配置中心元数据。启用配置中心后，后台可以发现并维护这些规则、通知和举报自动处理配置；未通过配置中心覆盖时继续使用 application.yml / 环境变量中的默认装配值。

配置	默认值	说明
`enabled`	`true`	是否启用 Forum 互动通知
`channels`	`database`	通知通道，支持 `database`、`websocket`、`mail`、`sms` 等已启用通道
`notify-self`	`false`	是否通知动作触发者本人
`reply-created-template`	`forum.reply.created`	主题收到回复模板
`topic-liked-template`	`forum.topic.liked`	主题被点赞模板
`topic-favorited-template`	`forum.topic.favorited`	主题被收藏模板
`reply-liked-template`	`forum.reply.liked`	回复被点赞模板
`report-status-changed-template`	`forum.report.status-changed`	举报处理进度模板

举报自动处理配置：

配置	默认值	说明
`reports.auto.enabled`	`true`	是否启用待处理举报超时自动处理
`reports.auto.auto-startup`	`true`	是否启动时自动注册调度任务
`reports.auto.timeout`	`24h`	待处理举报超过该时间仍未人工处理时自动处理
`reports.auto.fixed-delay`	`10m`	自动处理任务固定延迟执行间隔
`reports.auto.action`	`rejected`	超时后的默认动作：`accepted` / `rejected` / `resolved`
`reports.auto.limit`	`100`	单次处理数量，上限 1000

数据模型

当前包含以下表：

表	说明
`forum_board`	论坛板块，包含编码、名称、图标、排序、状态和统计快照
`forum_topic`	主题帖，包含所属板块、标题、摘要、正文、访问类型、解锁价格、会员权益项、预览内容、作者快照、状态、置顶、精华和统计快照
`forum_reply`	回复，包含所属主题、父回复、正文、作者快照、状态和点赞统计
`forum_topic_like`	主题点赞关系
`forum_reply_like`	回复点赞关系
`forum_topic_favorite`	主题收藏关系
`forum_topic_purchase_order`	付费主题购买订单，记录用户、主题快照、应付金额、支付状态和退款失效状态
`forum_report`	主题 / 回复举报记录
`forum_report_process_record`	举报处理记录，记录处理人、处理动作、处理前后状态和处理说明

状态字段统一使用：

值	说明
`0`	隐藏
`1`	可见

公开接口只返回可见、未删除且发布时间不晚于当前时间的内容。

主题访问类型使用 forum_topic.access_type：

值	说明
`free`	免费主题，公开详情返回完整正文
`paid`	付费主题，未解锁时只返回 `paidPreview`；默认使用 Entitlement item `forum-paid-topic` 判断内容解锁凭证
`vip`	会员主题，未解锁时只返回 `paidPreview`；默认使用 Entitlement item `forum-vip-topic` 判断内容解锁凭证
`member`	会员主题，语义与 `vip` 相同但文案更通用；未解锁时只返回 `paidPreview`，默认使用 Entitlement item `forum-vip-topic` 判断内容解锁凭证

访问判断通过模块内 ForumTopicAccessChecker 和 Forum 购买订单共同完成。作者本人始终可查看自己的主题。未解锁用户可以看到列表、标题、摘要和预览内容，但 GET /api/v1/forum/topics/{id}/replies 与 POST /api/v1/forum/topics/{id}/replies 会被后端阻断，避免回复区泄漏锁定主题上下文。

paid 主题支持公开购买接口创建收银台订单，支付成功后写入 paid 购买订单并解锁主题；退款回调或后台退款失效会把订单置为 refunded，用户再次访问时恢复为未解锁。付费主题还可以在扩展元数据中配置 memberDiscountItemCode 和 memberDiscountRate，读侧通过 spring-open-core-entitlement 的 ContentAccessPolicyService 复现会员折扣资格；命中折扣时主题仍保持未解锁，只把可享会员价提示返回给 PC / App，最终应付金额仍由购买链路确认。vip / member 主题继续通过 Entitlement 判断完整会员权益，不在 Forum 模块私造权益、余额或支付账本。

PC /forum/write 和 App /forum/publish 支持用户发布 free / paid / vip / member 四类主题。paid 主题需要填写非负解锁价格、币种、未解锁预览，可选填写会员折扣权益码和折扣率；vip / member 主题可填写会员权益码和未解锁预览。这些字段会直接进入 Forum 后端访问策略，不在前端私写支付或权益逻辑。

PC /forum/[id] 和 App /forum/detail 会根据 unlockRequired / contentLocked 展示付费或会员解锁卡片。paid 主题可直接创建购买订单并进入统一收银台；未解锁时只展示 paidPreview，回复输入会被禁用并提示先解锁。若 Entitlement 返回 memberDiscountEligible=true，详情页会额外展示可享会员折扣提示，方便用户进入购买确认。

Forum 板块会同时返回原始文案和展示文案：

字段	说明
`name` / `description`	后台维护的原始文案，适合后台编辑和运维管理
`displayName` / `displayDescription`	后端按当前语言解析后的展示文案，前端展示优先使用

多语言 key 约定：

properties

messages.forum.board.<code>.name=板块名称
messages.forum.board.<code>.description=板块描述

未配置翻译时会回退到原始文案。主题标题、正文和回复属于用户生成内容，默认不走业务元数据翻译。

内置演示数据

新环境会随 Forum 模块插入少量演示数据，包含「综合讨论」「建议反馈」两个板块，每个板块各 1 个主题和 1 条回复。它们用于让论坛首页、板块列表和主题详情在安装后不再空白。

这些数据使用稳定板块编码 general / feedback 和固定主题标题，种子主题与回复的 author_id 为空（真实用户发帖始终带 author_id）。受控清理入口已接入 Install 模块的演示数据清理（/api/v1/admin/install/quickstart-cleanups/forum，确认短语「清理 Forum 快速体验数据」）：只删除这批种子板块、主题和回复；种子板块或主题下存在真实用户主题、回复、点赞、收藏或举报时按阻塞项拒绝执行，不做级联误删。

举报处理状态使用：

值	说明
`0`	待处理
`1`	已采纳
`2`	已驳回
`3`	已处理

公共只读接口

所有接口的 JSON 响应体使用 Result<T>。

http

GET /api/v1/forum/home
GET /api/v1/forum/boards
GET /api/v1/forum/boards/{id}
GET /api/v1/forum/boards/code/{code}
GET /api/v1/forum/boards/{id}/topics
GET /api/v1/forum/boards/code/{code}/topics
GET /api/v1/forum/topics
GET /api/v1/forum/topics/popular
GET /api/v1/forum/sitemap
GET /api/v1/forum/search/summary
GET /api/v1/forum/authors/{id}/topics
GET /api/v1/forum/topics/{id}
GET /api/v1/forum/topics/path
GET /api/v1/forum/topics/{id}/replies
GET /api/v1/forum/authors/{id}/replies

GET /api/v1/forum/home 是 App / PC 论坛首页聚合入口，一次返回板块、置顶主题、精华主题和最新主题：

http

GET /api/v1/forum/home?boardSize=10&pinnedTopicSize=5&featuredTopicSize=5&latestTopicSize=10

返回字段：

字段	说明
`boards`	可见板块列表，包含 `displayName` / `displayDescription`
`pinnedTopics`	置顶主题列表
`featuredTopics`	精华主题列表
`latestTopics`	最新可见主题列表

主题列表支持：

http

page=1
size=10
keyword=spring
boardId=100
pinned=true
featured=true

主题列表、主题详情、首页聚合、热门主题和搜索摘要中的 ForumTopicVO 会携带板块展示快照，前端可以直接渲染板块入口：

字段	说明
`boardId`	板块 ID，用于接口交互
`boardCode`	稳定板块编码，适合用户侧路由
`boardName`	板块原始名称
`boardDisplayName`	后端按当前语言解析后的板块展示名称
`boardIconUrl`	板块图标
`accessType`	主题访问类型：`free` / `paid` / `vip` / `member`
`unlockPrice` / `unlockCurrency`	付费解锁价格和币种，供运营和前端展示
`vipItemCode`	会员权益项编码，未配置时按访问类型使用默认 item
`memberDiscountItemCode` / `memberDiscountRate`	付费主题可选会员折扣权益项和折扣率
`paidPreview`	未解锁时展示的预览内容
`unlockRequired`	当前主题是否需要解锁
`contentReadable`	当前访问者是否可读完整正文
`contentLocked`	当前响应是否已遮罩正文
`memberDiscountEligible` / `memberDiscountPackageCode`	当前访问者是否命中会员折扣资格，以及命中的会员套餐编码

公开主题查询会同时要求主题和所属板块都处于可见状态。隐藏板块下的主题不会出现在公开列表、作者主页、搜索摘要或回复作者页中。

热门主题用于论坛首页侧栏、移动端推荐流和内容发现卡片：

http

GET /api/v1/forum/topics/popular?size=10

popular 按浏览、回复、点赞、收藏、置顶和精华标记综合排序。size 范围为 1 到 50，默认 10。接口只返回公开可见主题，不增加阅读量，并会继续返回当前登录用户的点赞、收藏和举报状态。

站点地图条目用于前端 SSR、站点层 sitemap.xml 或 SEO 采集任务：

http

GET /api/v1/forum/sitemap?size=200

返回字段包括主题 ID、所属板块、path、标题、摘要、发布时间和更新时间。path 当前使用 /forum/topics/{id}，对应公开主题详情入口；接口只返回公开可见主题，不增加阅读量。

前端也可以直接按 sitemap path 查询主题详情：

http

GET /api/v1/forum/topics/path?path=/forum/topics/1001

该接口会去掉 path 中的 query / hash 后解析主题 ID，并返回和 GET /api/v1/forum/topics/{id} 一致的主题详情。

Forum 模块还通过 core UserActivitySource 向 IAM 用户动态聚合出口贡献公开可见主题。GET /api/v1/iam/users/{id}/activities 会把当前作者的可见主题合并进用户动态流，Forum 动态的稳定类型为 forum.topic，打开入口使用 PC 产品路由 /forum/{id}；Forum 模块不依赖 IAM 实现，仍保持可选业务模块边界。

搜索聚合摘要用于论坛搜索页和内容发现侧栏：

http

GET /api/v1/forum/search/summary?keyword=spring&topicSize=5&facetSize=10

返回字段：

字段	说明
`keyword`	归一化后的搜索词，未传时为 `null`
`total`	匹配到的公开可见主题总数
`topics`	匹配主题推荐列表，包含当前登录用户的点赞、收藏和举报状态
`boards`	匹配主题所在板块分面，包含 `displayName` 和主题数量
`authors`	匹配主题作者分面，包含作者显示名和主题数量

topicSize 范围为 1 到 20，默认 5；facetSize 范围为 1 到 50，默认 10。未传 keyword 时会基于全部公开可见主题做聚合；跨 CMS / Blog / Forum / Mall 的全站搜索仍由 Search 模块承载。

用户侧路由优先使用板块 code 作为公开地址，例如：

http

GET /api/v1/forum/boards/code/general
GET /api/v1/forum/boards/code/general/topics

这样 App / PC 可以使用稳定业务编码构建板块页，避免把数据库 ID 作为可见路由契约。后台管理仍保留按 ID 查询和维护入口。

回复列表支持：

http

page=1
size=20
topicId=100
keyword=spring

keyword 会匹配回复正文和回复作者快照；公开作者回复和我的回复也复用同一分页语义。公开侧回复 VO 会带所属主题快照，包含 topicTitle、topicStatus、topicPublishedAt 和 topicPath，方便 App / PC 在我的内容、作者主页或点赞回复列表中直接展示回复所属主题。

作者公开内容支持：

http

GET /api/v1/forum/authors/{id}/topics
GET /api/v1/forum/authors/{id}/replies

这两个接口用于用户资料卡、作者主页和个人内容流。接口只返回公开可见内容：作者主题必须可见、未删除且发布时间不晚于当前时间；作者回复还会额外要求所属主题仍然公开可见，避免隐藏主题下的回复从作者页泄漏出来。

主题详情会更新阅读量。

主题和回复 VO 会返回当前登录用户的互动状态。未登录访问时这些字段保持可安全渲染的默认值：

字段	主题	回复	说明
`liked`	是	是	当前用户是否已点赞
`favorited`	是	否	当前用户是否已收藏主题
`reported`	是	是	当前用户是否已举报
`reportStatus`	是	是	当前用户最近一条举报状态；未举报时为 `null`

用户互动接口

以下接口需要登录，JSON 响应体仍统一使用 Result<T>。

http

GET    /api/v1/forum/me/topics
GET    /api/v1/forum/me/topics/{id}
POST   /api/v1/forum/topics
PUT    /api/v1/forum/topics/{id}
DELETE /api/v1/forum/topics/{id}
POST   /api/v1/forum/topics/{id}/purchases

GET    /api/v1/forum/me/replies
GET    /api/v1/forum/me/replies/{id}
POST   /api/v1/forum/topics/{id}/replies
PUT    /api/v1/forum/replies/{id}
DELETE /api/v1/forum/replies/{id}

POST   /api/v1/forum/topics/{id}/likes
DELETE /api/v1/forum/topics/{id}/likes
POST   /api/v1/forum/replies/{id}/likes
DELETE /api/v1/forum/replies/{id}/likes
GET    /api/v1/forum/me/topic-likes
GET    /api/v1/forum/me/reply-likes

POST   /api/v1/forum/topics/{id}/favorites
DELETE /api/v1/forum/topics/{id}/favorites
GET    /api/v1/forum/me/favorites

GET    /api/v1/forum/me/reports
GET    /api/v1/forum/me/reports/{id}
POST   /api/v1/forum/topics/{id}/reports
POST   /api/v1/forum/replies/{id}/reports

设计约定：

用户只能编辑或删除自己的主题和回复。
/me/topics/{id} 和 /me/replies/{id} 会强制绑定当前登录用户，用于回看自己的隐藏、待处理或历史内容；公开详情接口仍只返回可见内容。
发帖、编辑主题、回帖和编辑回复的返回 VO 会和列表 / 详情保持一致，主题包含板块展示快照，回复包含所属主题快照，主题 / 回复都包含当前用户互动状态，前端提交成功后可直接刷新局部状态。
POST /api/v1/forum/topics/{id}/purchases 会为当前用户创建付费主题购买订单，返回订单号、金额、币种、支付 Provider、支付场景和支付状态；GET /api/v1/forum/topics/{id}/purchases/{orderNo} 仅允许当前用户查询自己在该主题下的购买单，PC / App 收银台回跳会携带 forumPurchaseOrderNo 并据此确认支付结果、刷新主题解锁状态；支付成功回调后完整正文自动解锁，退款回调或后台退款失效后自动撤销解锁。
发帖和回帖只保存 authorId 与 authorName 快照，不直接依赖 IAM 用户实体。
发帖和回帖会执行 spring.open.forum.rules 基础版规校验，违规时返回统一 Result<T> 错误消息。
点赞和收藏保持幂等，重复点赞 / 收藏不会重复增加统计。
/me/topic-likes 和 /me/reply-likes 分别返回当前用户点赞过且仍公开可见的主题和回复，VO 会继续带 liked、favorited、reported 和 reportStatus 等互动状态。
举报只写入举报记录，用户可通过 /me/reports 回看自己的举报处理状态；后台可在举报管理中更新处理状态或删除无效举报；创建 pending 举报时会触发 forum.report.pending-review 通知规则事件源，状态处理会自动写入举报处理记录，并在状态变化时通知举报人，同时在启用 Outbox 时入队举报状态变更事件。非 pending 处理结果还可通过 Notification 通知规则 forum.report.status-changed 另行通知运营接收人。
我的举报接口会强制绑定当前登录用户，即使请求参数里传入其他 userId 也不会查询到别人的举报。
待处理举报如果长时间没有人工处理，会由 forum.report.auto-handle 调度任务按 spring.open.forum.reports.auto.action 自动落为目标状态。自动处理同样会写举报处理记录，并触发举报状态变更通知。
主题收到回复、主题被点赞 / 收藏、回复被点赞时，默认通知内容作者；默认不通知动作触发者本人。主题收到新回复、主题点赞 / 收藏、回复点赞和举报处理结果还可通过 Notification 通知规则 forum.reply.created / forum.topic.liked / forum.topic.favorited / forum.reply.liked / forum.report.status-changed 另行通知运营接收人。

后台管理接口

后台提供板块、主题、回复和举报处理入口。

http

GET    /api/v1/admin/forum/statistics

GET    /api/v1/admin/forum/boards
GET    /api/v1/admin/forum/boards/{id}
POST   /api/v1/admin/forum/boards
PUT    /api/v1/admin/forum/boards/{id}
DELETE /api/v1/admin/forum/boards/{id}
DELETE /api/v1/admin/forum/boards

GET    /api/v1/admin/forum/topics
GET    /api/v1/admin/forum/topics/export
GET    /api/v1/admin/forum/topics/{id}
POST   /api/v1/admin/forum/topics
PUT    /api/v1/admin/forum/topics/{id}
DELETE /api/v1/admin/forum/topics/{id}
DELETE /api/v1/admin/forum/topics

GET    /api/v1/admin/forum/topic-purchases
GET    /api/v1/admin/forum/topic-purchases/revenue-summary
GET    /api/v1/admin/forum/topic-purchases/revenue-trend
POST   /api/v1/admin/forum/topic-purchases/{orderNo}/refund-invalidate

GET    /api/v1/admin/forum/replies
GET    /api/v1/admin/forum/replies/export
GET    /api/v1/admin/forum/replies/{id}
POST   /api/v1/admin/forum/replies
PUT    /api/v1/admin/forum/replies/{id}
DELETE /api/v1/admin/forum/replies/{id}
DELETE /api/v1/admin/forum/replies

GET    /api/v1/admin/forum/reports
GET    /api/v1/admin/forum/reports/export
GET    /api/v1/admin/forum/reports/{id}
PUT    /api/v1/admin/forum/reports/{id}
DELETE /api/v1/admin/forum/reports/{id}
DELETE /api/v1/admin/forum/reports

GET    /api/v1/admin/forum/report-process-records
GET    /api/v1/admin/forum/report-process-records/export
GET    /api/v1/admin/forum/report-process-records/{id}
DELETE /api/v1/admin/forum/report-process-records/{id}
DELETE /api/v1/admin/forum/report-process-records

后台菜单：

页面	菜单编码	路由	组件	权限
版块管理	`forum:board`	`/forum/boards`	`forum/board/index`	`forum:board:view`
主题管理	`forum:topic`	`/forum/topics`	`forum/topic/index`	`forum:topic:view`
付费主题订单	`forum:topic-purchase`	`/forum/topic-purchases`	`forum/topic-purchase/index`	`forum:topic:view`
回复管理	`forum:reply`	`/forum/replies`	`forum/reply/index`	`forum:reply:view`
举报处理	`forum:report`	`/forum/reports`	`forum/report/index`	`forum:report:view`
举报处理记录	`forum:report-process-record`	`/forum/report-process-records`	`forum/report-process-record/index`	`forum:report-process-record:view`

GET /api/v1/admin/forum/statistics 返回 Forum 后台运营快照，复用 forum:topic:view 读权限，包含板块、主题、回复、举报、待处理举报、今日新增、互动总量和举报治理 SLA 字段。Admin 前端 API 封装为 getForumOperationsStatistics()，举报处理页会消费其中的 reportSlaTimeoutSeconds、overduePendingReports、dueSoonPendingReports 和 oldestPendingReportAt，用于展示治理摘要和超时筛选入口。

GET /api/v1/admin/forum/topic-purchases 返回付费主题订单分页，支持按 orderNo、userId、topicId 和 status 筛选；GET /api/v1/admin/forum/topic-purchases/revenue-summary 返回付费订单数、退款订单数、付费用户数、付费主题数、总收入、退款金额和净收入；GET /api/v1/admin/forum/topic-purchases/revenue-trend 按当前筛选返回近 14 天支付、退款和净收入趋势，其中支付事件按 paidAt 归属，退款事件按 cancelledAt 归属；POST /api/v1/admin/forum/topic-purchases/{orderNo}/refund-invalidate 用于在退款或人工撤销后把订单标记为 refunded，后续该用户不再拥有对应主题解锁权限。Admin /forum/topic-purchases 已提供付费主题订单列表、收入汇总、收益趋势和退款失效操作，前端 API 封装为 getForumTopicPurchaseOrderList()、getForumTopicPurchaseRevenueSummary()、getForumTopicPurchaseRevenueTrend() 和 refundInvalidateForumTopicPurchaseOrder()；用户侧 PC /forum/[id] 和 App /forum/detail 通过 forumPurchaseOrderNo 回跳参数调用公开购买单详情接口确认结果，不需要用户手动刷新等待下一轮轮询。

GET /api/v1/admin/forum/topics/export 复用后台主题列表的 keyword、boardId、authorId、status、pinned 和 featured 筛选条件，返回 text/csv;charset=UTF-8 附件。CSV 只输出主题运营元数据、状态、置顶 / 精华标记和互动计数，不导出主题正文。

GET /api/v1/admin/forum/replies/export 复用后台回复列表的 topicId、authorId、keyword 和 status 筛选条件，返回 text/csv;charset=UTF-8 附件。CSV 只输出回复运营元数据、状态和互动计数，不导出回复正文或扩展 JSON。

GET /api/v1/admin/forum/reports 支持 slaOverdueOnly=true，用于只查询超过 Forum 举报治理 SLA 的待处理举报；开启后后端会强制限定 status=pending 并按 reports.auto.timeout 判定是否超时。GET /api/v1/admin/forum/reports/export 复用后台举报列表的 targetType、targetId、userId、status 和 slaOverdueOnly 筛选条件，返回 text/csv;charset=UTF-8 附件。CSV 只输出举报运营元数据和处理状态，不导出举报内容或扩展 JSON。

GET /api/v1/admin/forum/report-process-records/export 复用后台举报处理记录列表的 reportId、targetType、targetId、operatorId 和 action 筛选条件，返回 text/csv;charset=UTF-8 附件。CSV 只输出处理审计元数据和状态流转，不导出处理内容或扩展 JSON。

处理举报时请求体可以附带后台处理说明：

json

{
  "status": 1,
  "reason": "违规成立",
  "content": "已采纳举报并隐藏相关内容",
  "extraJson": "{\"source\":\"admin\"}"
}

forum_report_process_record 只作为治理审计记录，不作为举报当前状态的唯一来源。举报当前状态仍以 forum_report.status 为准。

权限标识：

txt

forum:board:view
forum:board:create
forum:board:update
forum:board:delete
forum:topic:view
forum:topic:create
forum:topic:update
forum:topic:delete
forum:reply:view
forum:reply:create
forum:reply:update
forum:reply:delete
forum:report:view
forum:report:update
forum:report:delete
forum:report-process-record:view
forum:report-process-record:delete

与前端视图联动

PC / App 视图可以接入：

http

GET /api/v1/forum/boards
GET /api/v1/forum/topics
GET /api/v1/forum/authors/{id}/topics
GET /api/v1/forum/topics/{id}
POST /api/v1/forum/topics/{id}/purchases
GET /api/v1/forum/topics/{id}/replies
GET /api/v1/forum/authors/{id}/replies
POST /api/v1/forum/topics
POST /api/v1/forum/topics/{id}/replies
POST /api/v1/forum/topics/{id}/likes
GET /api/v1/forum/me/topic-likes
GET /api/v1/forum/me/reply-likes
POST /api/v1/forum/topics/{id}/favorites
POST /api/v1/forum/topics/{id}/reports

论坛首页、板块页、主题详情页、作者主页、回复列表、发帖页、回帖、点赞、我的点赞、收藏和举报可以通过这些接口完成。

后续方向

内容审核、主题置顶和精华运营闭环。
板块级自定义版规、AI 审核、人工审核队列和通知联动。

Forum ​

配置 ​

数据模型 ​

内置演示数据 ​

公共只读接口 ​

用户互动接口 ​

后台管理接口 ​

与前端视图联动 ​

后续方向 ​

Forum

配置

数据模型

内置演示数据

公共只读接口

用户互动接口

后台管理接口

与前端视图联动

后续方向