# 技术支持与论坛 — 规划设计及实施方案

## 一、概述

### 1.1 目标

基于 [ICT 服务平台](ICT服务平台概要.md) 统一认证底座（OpenLDAP + Keycloak）和互联网应用服务器基础设施，构建**面向客户、经销商与合作伙伴的互动社区论坛平台**，覆盖技术支持、产品反馈、用户建议、营销互动的完整场景。论坛与 [文档生产及输出管理](文档生产及输出管理.md) 系统深度协同，共同构成企业对外知识服务与客户运营体系。

### 1.2 核心设计原则

- **全栈开源**：论坛引擎（Discourse）、LLM 推理（Ollama + Qwen2.5）、RAG 编排（LangChain）、向量检索（pgvector）、文本嵌入（bge-large-zh）全部采用开源方案，零 API 费用
- **认证复用**：登录用户接入 Keycloak SSO 免密码秘钥登录；游客免登录可浏览公开栏目
- **AI 驱动**：基于开源大模型本地部署，帖子自动分类、智能回复草稿生成、内容合规检测，人工审核后发布，数据全程不出企业服务器
- **主题订阅**：用户自主选择关注的主题，信息流仅展示已关注内容，类似微信群的「入群 / 退群」机制
- **积分激励**：通过积分奖励体系拉动社区活跃度与用户留存
- **管控有序**：分级审核机制，管理员可对不雅或不相关主题实施警告、冻结、关停

### 1.3 用户角色

论坛在 ICT 平台已有角色（游客 / 访客 / 读者 / 管理员）基础上定义论坛专属角色：

| 角色 | 说明 | 典型场景 |
|------|------|---------|
| 游客 (Guest) | 免登录浏览公开栏目，不可发帖 | 搜索引擎入口、链接分享打开阅读 |
| 普通用户 (Member) | 注册并登录后参与论坛互动 | 发帖、跟帖、点赞、关注主题、积累积分 |
| 经销商 (Dealer) | 经过企业认证的经销商账号 | 创建专属主题、发布产品服务信息、管理自有主题 |
| 版主 (Moderator) | 被管理员任命管理特定栏目或主题 | 置顶、移帖、警告、关闭话题 |
| 客服 (Support) | 企业客服团队成员 | 审核 AI 回复草稿、人工解答、处理投诉 |
| 管理员 (Admin) | 论坛系统管理员 | 栏目管理、主题审批、用户封禁、积分规则配置 |

### 1.4 论坛层级结构

论坛内容采用四级层级组织，对应企业网站上的导航结构：

```
栏目 (Category) ─── 网站顶部导航，如"技术支持""吐槽""建议"
  └─ 主题 (Theme) ─── 类似微信群的持续讨论空间，如"智能笔连接问题"
       └─ 话题帖 (Topic) ─── 某个具体问题或讨论，如"BLE 连接超时怎么办"
            └─ 跟帖 (Reply) ─── 对话题帖的回复，支持多级引用
```

- **栏目**是企业预设的固定分类，对应网站的一级导航栏目
- **主题**是栏目下的持续讨论空间，用户可关注或取消关注，类似加入或退出微信群
- **话题帖**是主题内的具体讨论，每个话题帖有独立 URL 可链接分享
- **跟帖**是话题帖内的交互回复，支持引用、@提及、Markdown 格式

---

## 二、系统架构

### 2.1 整体架构图

```plantuml
@startuml
skinparam componentStyle rectangle
title 技术支持与论坛 - 系统架构

actor "游客" as Guest
actor "用户/经销商" as User
actor "客服/管理员" as Admin

node "互联网应用服务器\n(腾讯云/阿里云)" as AppServer {
  component "Discourse\n论坛引擎" as Forum
  component "ForumAI\nAI 回复服务" as AI
  component "Keycloak\nSSO 认证" as KC
  component "MsgHub\n消息中心" as MsgHub
  component "Umami\n统计分析" as Analytics
  component "Nginx + SSL" as Nginx
  database "Redis\n缓存/会话" as Redis
}

node "私有云 [数据后端]" as PCloud {
  database "PostgreSQL\nAI草稿/积分/审核" as DB
  database "OpenLDAP\n用户目录" as LDAP
}

node "LLM 推理节点\n(Ollama + Qwen2.5)" as LLM

Guest -down-> Nginx : HTTPS 浏览
User -down-> Nginx : HTTPS 互动
Admin -down-> Nginx : 管理后台

Nginx -down-> Forum : 论坛请求
Nginx -down-> KC : 认证
Forum -right-> AI : Webhook\n新帖事件
AI -right-> LLM : 生成回复草稿
AI -down-> DB : 草稿/审核队列
AI -left-> Forum : API 发布回复
Forum -down-> MsgHub : 论坛通知
Forum -down-> Analytics : 访问埋点
Forum -down-> Redis : 会话/缓存
KC -down-> LDAP : 用户认证
MsgHub -down-> DB : 消息存储
@enduml
```

### 2.2 核心组件清单

| 组件 | 开源方案 | 用途 | 许可证 |
|------|---------|------|--------|
| 论坛引擎 | **Discourse** | 帖子发布、主题管理、搜索、信任等级 | GPL v2 |
| AI 回复服务 | **ForumAI**（Node.js + LangChain） | 帖子分析、回复草稿生成、FAQ 匹配、RAG 检索 | MIT (LangChain) |
| LLM 本地推理 | **Ollama** + **Qwen2.5** | 中文理解、回复生成、情感分析，全部本地部署 | MIT / Apache 2.0 |
| 文本嵌入 | **bge-large-zh-v1.5**（BAAI） | 中文 Embedding，FAQ 语义匹配 | MIT |
| 向量存储 | **pgvector**（PostgreSQL 扩展） | FAQ 向量索引与余弦相似度检索 | PostgreSQL |
| 认证中心 | **Keycloak**（已有） | OIDC SSO 统一登录 | Apache 2.0 |
| 消息推送 | **MsgHub**（已有） | 论坛事件实时通知 | — |
| 统计分析 | **Umami**（已有） | 论坛页面访问与互动数据 | MIT |
| 缓存 | **Redis**（已有） | 会话管理、积分缓存、限流 | BSD |
| 数据存储 | **PostgreSQL**（已有） | ForumAI 草稿、积分记录、审核日志 | PostgreSQL |
| 反向代理 | **Nginx**（已有） | SSL 终止、路由分发 | BSD |

> **全栈开源**：上述所有组件均为开源方案，LLM 推理通过 Ollama 本地部署 Qwen2.5 模型，无需依赖任何付费 API，数据全程不出企业服务器。Discourse Docker 镜像内含独立的 PostgreSQL 和 Redis，ForumAI 使用平台共享的 PostgreSQL + pgvector 存储 AI 草稿、积分和向量数据。

---

## 三、论坛栏目与主题体系

### 3.1 预设栏目

企业网站上的论坛以栏目形式呈现，每个栏目是一个独立的一级导航入口：

| 栏目 | URL 标识 | 访问级别 | 说明 |
|------|---------|---------|------|
| **技术支持** | `technical-support` | public | 产品使用问题、故障排查、技术咨询，AI 优先回复 |
| **产品反馈** | `product-feedback` | public | 用户吐槽、使用体验、Bug 报告 |
| **建议与需求** | `suggestions` | public | 功能建议、需求提案，支持投票表决 |
| **公告** | `announcements` | public | 企业官方公告、版本发布、活动通知（仅管理员可发帖） |
| **经销商专区** | `dealer-zone` | login | 经销商专属讨论，需认证后可见 |
| **自由讨论** | `general` | login | 注册用户自由交流 |

### 3.2 主题定义与管理

每个栏目下包含多个**主题（Theme）**，主题是围绕特定产品、功能或客户群体的持续讨论空间：

| 属性 | 说明 | 示例 |
|------|------|------|
| 名称 | 主题的显示名称 | "Qink 智能笔使用交流" |
| 标识 | URL 友好的英文标识 | `qink-smart-pen` |
| 所属栏目 | 挂载在哪个栏目下 | 技术支持 |
| 创建者 | 企业预设 / 用户申请 / 经销商自建 | admin / dealer-001 |
| 描述 | 主题简介，显示在主题列表 | "关于 Qink 智能笔的连接、使用、固件问题" |
| 图标 | 主题头像或 Logo | 产品图片 |
| 状态 | 正常 / 警告中 / 已停止 / 已归档 | 正常 |
| 关注人数 | 当前关注该主题的用户数 | 1,234 |

**预设主题示例**：

| 栏目 | 主题 | 说明 |
|------|------|------|
| 技术支持 | 智能笔连接问题 | BLE 配对、固件升级、连接不稳定 |
| 技术支持 | 大屏显示与同步 | 笔迹同步延迟、画面适配、多设备场景 |
| 技术支持 | 手写识别与 OCR | 识别准确率、语言支持、特殊字符 |
| 产品反馈 | Qink 使用体验 | Qink 系列产品的综合体验反馈 |
| 产品反馈 | iTone 音质讨论 | iTone 系列音频产品体验 |
| 建议与需求 | 功能投票箱 | 用户对新功能的提案与投票 |

### 3.3 用户与经销商自建主题

普通用户和经销商可申请创建自己的主题，系统提供完整支撑：

#### 创建流程

```
用户/经销商提交"创建主题"申请
  │
  ├─ 填写：主题名称、所属栏目、描述、创建理由
  │
  ├─ 系统自动检查：
  │    ├─ 名称是否与已有主题重复
  │    ├─ 内容是否包含违禁词
  │    └─ 用户信任等级是否满足要求
  │
  ├─ 经销商账号 → 自动通过（免审核）
  │
  └─ 普通用户 → 进入管理员审核队列
       ├─ 审核通过 → 主题创建，申请者自动成为该主题版主
       └─ 审核拒绝 → 通知申请者并说明原因
```

#### 自建主题权限

| 角色 | 创建主题 | 免审核 | 管理自有主题 | 删除自有主题 |
|------|---------|--------|------------|------------|
| 普通用户（等级 3+） | 可申请 | 否 | 可（版主权限） | 需管理员确认 |
| 经销商 | 可直接创建 | 是 | 可（版主权限） | 可 |
| 管理员 | 可直接创建 | 是 | 全部主题 | 可 |

### 3.4 主题关注与信息流

用户通过**关注（Follow）机制**管理自己可见的内容，类似微信群的加入与退出：

| 操作 | 效果 |
|------|------|
| 关注主题 | 该主题下的新话题帖出现在用户信息流中；新帖通知推送到消息中心 |
| 取消关注 | 该主题内容从信息流消失；停止该主题的消息推送 |
| 未关注 | 用户不会看到该主题下的任何内容（栏目页仍可看到主题列表） |

**信息流规则**：

- 论坛首页（个人信息流）仅展示**已关注主题**下的话题帖，按最新回复时间倒序排列
- 栏目页展示该栏目下**所有主题列表**（含未关注的），用户可浏览并决定是否关注
- 新注册用户自动关注企业预设的「推荐主题」（如技术支持 / 公告），后续可自行调整
- 每个主题卡片显示：主题名称、描述、关注人数、最新活跃时间、「关注 / 已关注」按钮

---

## 四、帖子交互与链接分享

### 4.1 帖子发布与跟帖

#### 发布话题帖

登录用户在已关注的主题内可发布话题帖：

| 字段 | 说明 |
|------|------|
| 标题 | 话题帖标题，简洁描述问题或主题 |
| 正文 | 支持 Markdown 格式，可嵌入图片、代码块、表格 |
| 标签 | 可选，便于检索分类（如 `BLE` `固件` `Android`） |
| 附件 | 支持上传图片、日志文件（大小 / 类型受限） |

#### 跟帖（回复）

- 对话题帖的回复支持 Markdown 格式
- 支持**引用回复**（引用某条跟帖后回复）
- 支持 **@提及** 其他用户，触发专属通知
- 支持**点赞**，高赞回复自动置顶或标记为「有帮助」
- 帖子作者可将某条回复标记为**最佳回答**（技术支持栏目尤为重要）

### 4.2 链接分享体系

每个论坛页面均有独立的、可分享的 URL：

| 页面 | URL 格式 | 示例 |
|------|---------|------|
| 论坛首页 | `https://forum.writech.cn/` | — |
| 栏目页 | `https://forum.writech.cn/c/{栏目标识}` | `forum.writech.cn/c/technical-support` |
| 主题页 | `https://forum.writech.cn/c/{栏目}/{主题}` | `forum.writech.cn/c/technical-support/qink-smart-pen` |
| 话题帖 | `https://forum.writech.cn/t/{标题slug}/{帖子ID}` | `forum.writech.cn/t/ble-timeout/456` |
| 特定跟帖 | `https://forum.writech.cn/t/{slug}/{ID}/{跟帖序号}` | `forum.writech.cn/t/ble-timeout/456/3` |

**分享能力**：

- 每个话题帖页面提供**分享按钮**，支持复制链接、生成二维码
- 分享链接携带渠道追踪参数（复用 PromoAPI 的 `ch` / `cmp` 参数体系）
- 链接在微信、浏览器等平台打开时展示完整的帖子内容
- 游客通过分享链接可直接阅读公开栏目下的帖子，无需登录

### 4.3 SEO 与社交分享优化

- Discourse 原生支持 SSR（服务端渲染），搜索引擎可抓取论坛内容
- 每个话题帖生成 Open Graph 元标签，分享到微信 / 微博时展示标题 + 摘要 + 缩略图
- 技术支持类帖子沉淀为**搜索引擎可索引的知识库**，持续引流

---

## 五、AI 辅助回复系统（ForumAI）

### 5.1 设计理念

ForumAI 是论坛的 AI 后端服务，核心目标是**降低客服团队工作量**，同时保证回复质量：

- **AI 先行**：每条新帖自动生成回复草稿，客服只需审核确认或微调
- **人工兜底**：AI 无法处理的复杂问题自动转交人工，确保每条帖子都有回应
- **知识积累**：FAQ 库随帖子积累不断丰富，AI 回复准确率持续提升
- **透明标记**：AI 回复标记「AI 助手」标签，用户知晓回复来源

### 5.2 工作流程

```plantuml
@startuml
skinparam componentStyle rectangle
title ForumAI 工作流程

start
:用户发布话题帖或跟帖;
:Discourse Webhook 推送到 ForumAI;

:ForumAI 分析帖子内容;
note right
  意图识别: 提问 / 反馈 / 建议 / 投诉
  情感分析: 正面 / 中性 / 负面
  关键词提取: 产品 / 功能 / 问题
end note

if (匹配 FAQ 知识库 ?) then (是)
  :生成标准回复草稿;
  note right: 附上 FAQ 文档链接
else (否)
  :调用 LLM 生成回复草稿;
  note right
    Ollama + Qwen2.5 (本地部署)
    LangChain RAG: 产品知识 + 帖子上下文
  end note
endif

:草稿存入审核队列;

if (AI 置信度高且为常见问题 ?) then (是)
  :自动发布回复;
  note right: 标注 "AI 助手" 标签
else (否)
  :推送到客服审核队列;
  :客服查看/编辑草稿;
  :客服确认发布;
endif

:回复发布到论坛;
:MsgHub 通知帖子作者;
stop
@enduml
```

### 5.3 AI 能力矩阵

| 能力 | 说明 | 实现方式 |
|------|------|---------|
| 意图识别 | 判断帖子是提问、反馈、建议还是投诉 | LLM 分类 + 规则引擎 |
| 情感分析 | 检测用户情绪（正面 / 中性 / 负面 / 愤怒） | LLM 情感评分 |
| FAQ 匹配 | 将帖子与已有 FAQ 知识库进行语义匹配 | bge-large-zh Embedding + pgvector 余弦相似度检索 |
| 回复生成 | 基于产品知识库和帖子上下文生成回复草稿 | LangChain RAG（Ollama + Qwen2.5 + pgvector） |
| 内容审核 | 检测帖子是否含不良内容、广告、违禁词 | Qwen2.5 审核 + 关键词过滤 |
| 智能分类 | 自动为帖子打标签、分配到合适的主题 | LLM 分类 |
| 优先级评估 | 根据情感和紧急程度评估帖子优先级 | 规则引擎 + LLM |

### 5.4 人工辅佐审核机制

客服团队通过**审核后台**管理 AI 生成的回复草稿：

```
┌──────────────────────────────────────────────────┐
│  ForumAI 审核后台                          客服  │
├──────────────────────────────────────────────────┤
│  待审核 (12)  │  已发布 (89)  │  已驳回 (3)     │
├──────────────────────────────────────────────────┤
│  🔴 [紧急] BLE 连接频繁断开              3分钟前  │
│     AI 草稿：建议重新配对，详见固件升级指南...     │
│     置信度：87%  │  意图：提问  │  情感：负面     │
│     [✅ 发布] [✏️ 编辑后发布] [❌ 驳回] [👤 转人工] │
├──────────────────────────────────────────────────┤
│  🟡 [一般] Qink 能否支持 Windows 手写输入   1小时前 │
│     AI 草稿：目前 Qink 主要支持 Android/iOS...   │
│     置信度：72%  │  意图：提问  │  情感：中性     │
│     [✅ 发布] [✏️ 编辑后发布] [❌ 驳回] [👤 转人工] │
└──────────────────────────────────────────────────┘
```

**审核流程规则**：

| 场景 | 处理方式 |
|------|---------|
| AI 置信度 > 90% 且为 FAQ 匹配 | 自动发布，标记「AI 助手」 |
| AI 置信度 70-90% | 进入客服审核队列，客服确认或修改后发布 |
| AI 置信度 < 70% | 标记「需人工回复」，客服从头撰写 |
| 情感为「愤怒」或「投诉」 | 无论置信度均进入人工处理，标记高优先级 |

### 5.5 技术实现

```
ForumAI (Node.js 服务，端口 3005)
  ├─ Express.js            — HTTP 接收 Discourse Webhook (MIT)
  ├─ @discourseconnect     — Discourse REST API 客户端
  ├─ LangChain.js          — RAG 编排：串联 LLM + 向量检索 + Prompt (MIT)
  ├─ Ollama Client         — 调用本地 Ollama 推理 Qwen2.5（HTTP localhost:11434）
  ├─ pg + pgvector         — 草稿/审核写入 PostgreSQL，FAQ Embedding 向量检索
  ├─ ioredis               — 限流、FAQ 缓存 (MIT)
  └─ MsgHub Client         — 审核通知推送
```

**FAQ 知识库管理**：

- FAQ 条目以 Markdown 存储于 Git 仓库，通过 DocForge 同步更新
- 每条 FAQ 通过 **bge-large-zh-v1.5**（BAAI 开源，MIT）生成 1024 维 Embedding 向量，存入 PostgreSQL（**pgvector** 扩展）
- 新帖到达时，ForumAI 通过 **LangChain RAG** 流程计算帖子 Embedding 并与 FAQ 库做余弦相似度检索
- 匹配度 > 0.85 视为 FAQ 命中，直接引用对应回复模板
- LLM 推理全部通过 **Ollama**（MIT）本地运行 **Qwen2.5**（Apache 2.0）模型，无需外部 API 依赖

---

## 六、积分奖励体系

### 6.1 积分获取规则

通过积分奖励拉动论坛活跃度，积分规则涵盖日常互动和内容贡献：

| 行为 | 积分 | 频次限制 | 说明 |
|------|------|---------|------|
| 每日首次登录 | +5 | 每日 1 次 | 连续签到额外奖励 |
| 发布话题帖 | +10 | 每日 5 帖 | 鼓励提问和分享 |
| 发表跟帖 | +3 | 每日 20 条 | 鼓励参与讨论 |
| 被点赞（每个赞） | +2 | 无限制 | 鼓励高质量回复 |
| 回复被标记为「最佳回答」 | +50 | 无限制 | 重奖有价值的回答 |
| 关注新主题 | +1 | 每日 3 次 | 鼓励探索更多主题 |
| 邀请新用户注册 | +30 | 每月 10 次 | 拉新奖励 |
| 连续签到 7 天 | +20 | 每周 1 次 | 额外奖励 |
| 连续签到 30 天 | +100 | 每月 1 次 | 月度奖励 |
| 举报违规内容（查实后） | +10 | 无限制 | 鼓励社区自治 |

### 6.2 用户等级体系

积分累计决定用户等级，不同等级解锁不同特权：

| 等级 | 名称 | 累计积分 | 特权 |
|------|------|---------|------|
| Lv.0 | 新手 | 0 | 浏览、跟帖（需审核） |
| Lv.1 | 活跃用户 | 50+ | 跟帖免审核、点赞 |
| Lv.2 | 贡献者 | 200+ | 发帖免审核、上传附件 |
| Lv.3 | 达人 | 500+ | 申请创建主题、编辑自己的帖子标签 |
| Lv.4 | 专家 | 2000+ | 编辑他人帖子标签、参与社区管理投票 |
| Lv.5 | 社区大使 | 5000+ | 自建主题免审核、推荐至首页热门 |

### 6.3 积分兑换

积分可用于兑换企业提供的奖励：

| 兑换项目 | 所需积分 | 说明 |
|---------|---------|------|
| 品牌周边（贴纸、明信片） | 100 | 邮寄至用户地址 |
| 产品优惠券（满减 / 折扣） | 300 | 在官网或经销商处使用 |
| 新品试用资格 | 500 | 优先体验未发布产品 |
| 专属客服通道 | 1000 | 一对一技术支持 |
| 年度社区贡献者荣誉 | — | 年底评选，非积分兑换 |

### 6.4 营销活动积分

管理员可配置**限时积分活动**以拉动特定时段的社区活跃度：

| 活动类型 | 示例 | 积分规则 |
|---------|------|---------|
| 签到翻倍周 | 每年特定周 | 所有签到积分 x2 |
| 话题悬赏 | "分享你的智能笔使用场景" | 参与发帖 +30，最佳帖 +200 |
| 邀新冲刺 | 月度邀新活动 | 邀请积分 x3，邀新排行额外奖励 |
| 节日专题 | 教师节、开学季 | 特定话题帖积分加成 |

积分核心逻辑基于 Discourse 开源插件 **discourse-gamification**（MIT）实现用户等级和徽章展示，ForumAI 负责自定义积分规则计算和营销活动积分加成。活动规则通过管理后台配置，ForumAI 自动识别活动期间的帖子并按活动规则计算积分。

---

## 七、内容审核与管控

### 7.1 三级审核机制

论坛内容审核采用 AI 自动审核 + 版主审核 + 管理员终审的三级机制：

| 审核级别 | 执行者 | 处理内容 | 响应时间 |
|---------|--------|---------|---------|
| **一级：AI 自动审核** | ForumAI | 新帖/跟帖自动扫描：违禁词、广告、不良内容、灌水 | 即时（< 3 秒） |
| **二级：版主审核** | 版主 | AI 标记为可疑的内容、用户举报的内容 | < 30 分钟 |
| **三级：管理员终审** | 管理员 | 主题创建审批、用户封禁、重大争议裁决 | < 24 小时 |

### 7.2 管理员操作工具

管理员和版主可对帖子和主题执行以下操作：

| 操作 | 适用对象 | 说明 |
|------|---------|------|
| **置顶** | 话题帖 | 在主题内或栏目内置顶显示 |
| **锁定** | 话题帖 | 禁止新跟帖，保留可阅读 |
| **移动** | 话题帖 | 将帖子移至更合适的主题或栏目 |
| **合并** | 话题帖 | 将重复的帖子合并为一个 |
| **隐藏** | 帖子/跟帖 | 从公开视图隐藏，仅管理员可见 |
| **删除** | 帖子/跟帖 | 永久删除内容（需三级管理员确认） |
| **警告** | 用户 | 向用户发送违规警告通知，记录在案 |
| **禁言** | 用户 | 暂时禁止用户发帖和跟帖（可设期限） |
| **封禁** | 用户 | 永久禁止用户访问论坛 |

### 7.3 AI 自动审核

ForumAI 对每条新发布的帖子和跟帖执行自动审核：

| 检测项 | 检测方式 | 处理动作 |
|--------|---------|---------|
| 违禁词 | 关键词词典匹配 | 拦截，进入版主审核队列 |
| 广告推销 | LLM 分类 + URL 检测 | 拦截，标记为疑似广告 |
| 人身攻击 / 不雅内容 | LLM 毒性检测 | 拦截，自动隐藏 + 通知版主 |
| 灌水 / 重复发帖 | 频率检测 + 内容相似度 | 限流，超过阈值自动拦截 |
| 敏感信息 | 正则匹配（手机号、身份证等） | 自动打码，提醒用户修改 |

### 7.4 主题状态管理

主题具有完整的生命周期，管理员可根据主题表现进行状态管控：

```plantuml
@startuml
skinparam componentStyle rectangle
title 主题状态管理

state "申请中" as Pending
state "正常" as Active
state "警告中" as Warning
state "已停止" as Stopped
state "已归档" as Archived
state "已拒绝" as Rejected

[*] --> Pending : 用户/经销商提交申请
[*] --> Active : 管理员直接创建

Pending --> Active : 管理员审核通过
Pending --> Rejected : 管理员拒绝

Active --> Warning : 管理员发出警告\n(内容不当/偏离主题)
Warning --> Active : 整改通过
Warning --> Stopped : 未整改或再次违规

Active --> Stopped : 严重违规直接停止
Stopped --> Active : 管理员解除停止

Active --> Archived : 长期不活跃\n或管理员手动归档
Archived --> Active : 管理员重新激活
@enduml
```

**各状态说明**：

| 状态 | 对用户的表现 | 可执行操作 |
|------|------------|----------|
| 申请中 | 仅申请者可见，显示"审核中" | 等待管理员审批 |
| 正常 | 正常显示和互动 | 发帖、跟帖、关注 |
| 警告中 | 主题顶部显示黄色警告条，提示整改内容 | 可继续互动，但新帖需审核 |
| 已停止 | 主题页显示"该主题已被管理员停止"，禁止新帖 | 仅可阅读历史内容 |
| 已归档 | 主题页显示"已归档"，禁止新帖 | 仅可阅读历史内容 |
| 已拒绝 | 仅申请者收到拒绝通知 | 可修改后重新申请 |

---

## 八、权限与访问控制

### 8.1 论坛访问级别

论坛栏目的访问控制复用文档系统的权限模型：

| 级别 | 标识 | 说明 |
|------|------|------|
| **公开** | `public` | 游客可浏览帖子内容，登录后方可发帖和跟帖 |
| **需登录** | `login` | 仅登录用户可浏览和互动（如经销商专区） |
| **受限** | `restricted` | 仅特定用户组可访问（如内部测试反馈栏目） |

### 8.2 论坛权限矩阵

| 操作 | 游客 | 普通用户 | 经销商 | 版主 | 客服 | 管理员 |
|------|------|---------|--------|------|------|--------|
| 浏览公开栏目 | 可 | 可 | 可 | 可 | 可 | 可 |
| 浏览 login 栏目 | 否 | 可 | 可 | 可 | 可 | 可 |
| 发布话题帖 | 否 | 可 | 可 | 可 | 可 | 可 |
| 发表跟帖 | 否 | 可 | 可 | 可 | 可 | 可 |
| 点赞 | 否 | 可 | 可 | 可 | 可 | 可 |
| 关注主题 | 否 | 可 | 可 | 可 | 可 | 可 |
| 创建主题 | 否 | Lv.3+ 申请 | 直接创建 | 否 | 否 | 直接创建 |
| 标记最佳回答 | 否 | 仅自己帖子 | 仅自己帖子 | 可 | 可 | 可 |
| 审核帖子 | 否 | 否 | 否 | 所辖主题 | 所有 | 所有 |
| 管理主题状态 | 否 | 否 | 自有主题 | 所辖主题 | 否 | 所有 |
| 封禁用户 | 否 | 否 | 否 | 否 | 否 | 可 |
| AI 审核后台 | 否 | 否 | 否 | 否 | 可 | 可 |

### 8.3 与认证底座的关系

| 层次 | 组件 | 职责 |
|------|------|------|
| 身份源 | OpenLDAP（私有云） | 用户账户、组织架构、角色 |
| 认证中心 | Keycloak（互联网服务器） | SSO 登录，签发 OIDC Token |
| 论坛认证 | Discourse SSO 对接 | 通过 Keycloak OIDC 实现单点登录 |
| 角色映射 | ForumAI 配置 | Keycloak 角色组映射到论坛角色（Member / Dealer / Support / Admin） |
| 匿名访问 | Discourse 公开分类 | 游客无需登录即可浏览 public 级别栏目 |

---

## 九、消息通知与 MsgHub 集成

### 9.1 论坛事件接入 MsgHub

论坛产生的事件通过 Discourse Webhook 接入 MsgHub 消息中心，与文档系统的消息统一展示：

```
Discourse 论坛事件
  │
  ├─ Webhook → ForumAI → MsgHub
  │
  └─ MsgHub 统一推送到用户消息中心
       ├─ WebSocket 实时推送（在线用户）
       └─ 未读消息存储（离线用户）
```

### 9.2 论坛消息类型

| 消息类型 | 触发条件 | 消息内容 |
|---------|---------|---------|
| 新回复 | 关注的话题帖收到新跟帖 | "{用户}回复了你关注的《{帖子标题}》" |
| @提及 | 帖子或跟帖中 @了你 | "{用户}在《{帖子标题}》中提到了你" |
| 最佳回答 | 你的回复被标记为最佳回答 | "你在《{帖子标题}》中的回复被选为最佳回答 (+50积分)" |
| AI 回复已发布 | 客服确认发布了 AI 回复 | "你的帖子《{标题}》已收到官方回复" |
| 主题动态 | 关注的主题有新话题帖 | "【{主题名}】有新话题：{帖子标题}" |
| 主题审批 | 你申请的主题被审批 | "你申请的主题「{名称}」已通过审核" |
| 警告通知 | 管理员对你发出警告 | "你的帖子《{标题}》收到管理员警告" |
| 积分变动 | 积分增加或兑换 | "恭喜获得 50 积分（最佳回答奖励）" |
| 等级提升 | 用户等级提升 | "恭喜升级为 Lv.3 达人！解锁「创建主题」特权" |

### 9.3 通知策略

| 策略 | 说明 |
|------|------|
| 即时推送 | @提及、最佳回答、警告通知、等级提升 |
| 聚合推送 | 新回复、主题动态（同一主题 5 分钟内聚合为一条） |
| 静默 | 用户可设置单个主题为「免打扰」，仅 @提及 时通知 |
| 摘要邮件 | 每日 / 每周发送论坛摘要邮件到用户邮箱（可选开启） |

---

## 十、部署方案

### 10.1 服务部署清单

论坛相关服务在已有 ICT 平台基础上新增以下组件：

| 服务 | 部署方式 | 运行位置 | 端口 | 说明 |
|------|---------|---------|------|------|
| **Discourse 论坛引擎** | Docker (官方镜像) | 互联网应用服务器 | 4000 | 含内置 PostgreSQL + Redis + Sidekiq |
| **Ollama LLM 推理** | Docker (GPU 可选) | 互联网应用服务器 | 11434 | 本地运行 Qwen2.5 开源大模型 |
| **ForumAI 服务** | Docker (Node.js) | 互联网应用服务器 | 3005 | LangChain RAG + 积分 + 审核 |
| PostgreSQL（已有） | 原生安装 | 私有云 | 5432 | ForumAI 草稿/积分/审核日志 |
| Redis（已有） | Docker | 互联网应用服务器 | 6379 | ForumAI 限流/缓存 |
| MsgHub（已有） | Docker | 互联网应用服务器 | 3003 | 论坛消息通知 |
| Keycloak（已有） | Docker | 互联网应用服务器 | 8443 | SSO 认证 |
| Nginx（已有） | 原生 | 互联网应用服务器 | 443 | 反向代理 |

### 10.2 Nginx 路由规则

在现有 Nginx 配置中新增论坛相关路由：

```nginx
# Discourse 论坛（独立子域名）
server {
    listen 443 ssl http2;
    server_name forum.writech.cn;

    ssl_certificate     /etc/ssl/certs/writech_cn.pem;
    ssl_certificate_key /etc/ssl/private/writech_cn.key;

    # 论坛所有请求代理到 Discourse
    location / {
        proxy_pass http://127.0.0.1:4000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }

    # WebSocket 支持（Discourse MessageBus）
    location /message-bus/ {
        proxy_pass http://127.0.0.1:4000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

# ForumAI 服务（内部调用 + Discourse Webhook）
# 在主站 server 块中添加：
location /api/forum-ai/ {
    proxy_pass http://127.0.0.1:3005;
}
```

### 10.3 DNS 配置

在腾讯云 DNSPod 中新增 `forum.writech.cn` 子域名记录：

| 记录 | 类型 | 指向 | DNS 平台 | 用途 |
|------|------|------|---------|------|
| forum.writech.cn | A | 腾讯云广州服务器 | 腾讯云 DNSPod | 论坛子域名 |

> 通配符 SSL 证书（`*.writech.cn`）已覆盖 `forum.writech.cn`，无需额外证书。

---

## 十一、实施路线图

| 阶段 | 任务 | 预计周期 |
|------|------|--------|
| **第一阶段：基础** | Discourse Docker 部署、Keycloak SSO 对接 | 第 1-2 周 |
| **第一阶段** | 预设栏目和主题创建、Nginx 路由配置 | 第 2 周 |
| **第一阶段** | 基础 UI 定制（品牌配色、Logo、导航栏集成） | 第 2-3 周 |
| **第二阶段：互动** | 主题关注与信息流功能开发 | 第 4 周 |
| **第二阶段** | 用户/经销商自建主题审批流程开发 | 第 4-5 周 |
| **第二阶段** | MsgHub 集成（论坛事件 Webhook → 消息中心） | 第 5 周 |
| **第三阶段：智能** | Ollama + Qwen2.5 本地部署、bge-large-zh 嵌入模型部署 | 第 6 周 |
| **第三阶段** | ForumAI 服务开发（Webhook + LangChain RAG 编排 + pgvector） | 第 6-7 周 |
| **第三阶段** | FAQ 知识库构建与向量检索集成 | 第 7-8 周 |
| **第三阶段** | AI 审核后台开发（客服审核队列 + 草稿管理） | 第 8-9 周 |
| **第四阶段：运营** | 积分奖励体系开发（积分规则 + 等级 + 兑换） | 第 10-11 周 |
| **第四阶段** | 内容审核与管控工具（AI 审核 + 管理员操作） | 第 11 周 |
| **第四阶段** | 营销活动积分模块 + 运营看板 | 第 12 周 |
| **第五阶段：优化** | SEO 优化、Open Graph 社交分享、链接分享体系完善 | 第 13 周 |
| **第五阶段** | 全链路测试、性能调优、上线 | 第 13-14 周 |