# 前端组件清单与核心交互流程

文档编号：pcbjia-FE-COMPONENTS-V1.0
范围：技术社区（聊天室 / 论坛 / 私信）、AI 能力、后台管理，配套风险清单。

---

## 一、公共基础组件

| 组件 | 职责 | 关键约束 |
| --- | --- | --- |
| Layout | 顶栏、侧栏、移动端抽屉 | 移动端折叠为汉堡菜单 |
| UserAvatar | 头像、昵称、身份标签、在线点 | 悬浮卡展示简介与关注按钮 |
| Tag | 技术标签与状态标签 | 点击进入全局搜索筛选 |
| AttachmentUploader | 拖拽、粘贴、批量上传 | 后缀白名单、进度与重试 |
| FilePreview | 图片、PDF、ZIP 预览 | ZIP 仅列清单不解压 |
| MarkdownEditor | 表格、代码块、公式、@用户 | 云端草稿 + 本地兜底 |
| MarkdownRender | 代码高亮、附件卡片 | 前端过滤 + 服务端二次校验 |
| NotifyBadge | 未读红点与计数 | 与消息中心同源 |
| Pagination | 统一分页 | 支持跳页与条数切换 |
| SearchInput | 全局搜索 | 范围切换：帖子/精华/附件 |
| ConfirmModal | 高风险二次确认 | 删除、解绑、撤销悬赏 |
| Toast | 全局提示 | 成功、警告、错误、加载 |
| SelectUser | @ 用户选择 | 优先在线与认证专家 |
| CreditDisplay | 积分与变动 | 增加绿色、扣减红色 |
| CollectFolderSelector | 收藏夹 | 支持新建与选择 |

## 二、论坛组件

| 组件 | 职责 |
| --- | --- |
| ForumPostCard | 列表卡片：标题、AI 摘要、标签、悬赏与状态标识 |
| PostTemplateSelector | 提问模板：阻抗、EDA 报错、失效分析、DFM、EMC |
| RewardSetting | 悬赏积分与冻结后余额预览 |
| PostAIAnswer | AI 预回答面板，含免责与来源 |
| ReplyItem | 楼层、编辑历史、设为最佳答案 |
| RelatedRecommend | 同标签与语义相似推荐 |
| ColumnChapter | 专栏目录与阅读进度 |
| PostTransferChatBtn | 一键开启聊天室讨论 |
| ExportBtn | 导出 Markdown / PDF |

## 三、聊天室组件

| 组件 | 职责 |
| --- | --- |
| RoomList | 房间列表、活跃线程、置顶 |
| RoomNotice | 置顶公告，支持链接 |
| ThreadCard | 线程卡片，含精华、归档、绑定标记 |
| MessageItem | 引用、编辑、单条精华、@高亮 |
| ThreadTransferForumBtn | 一键转论坛帖，可改标题与版块 |
| OnlineUserList | 在线成员与私聊入口 |
| ChatAIWidget | @AI 问答，带线程上下文 |
| ThreadExport | 线程导出 |
| ArchiveSwitch | 归档开关 |

## 四、私信组件

PMConversationList、PMMessageItem、PMSetting（隐私开关）。

## 五、AI 组件

AiTranslate、Ai8dGenerator、AiImpedanceCalc（结果标注为估算）、AiTagGenerator。

## 六、后台组件

DataDashboard、AuditTable、ConfigEditor、EssenceManager、LogTable。

后台受平台能力限制：仅按数据表增删改查，不做自建大盘与报表。

---

## 七、核心交互流程

### 流程 1：聊天室线程转论坛帖

```
线程内点击一键转帖
→ POST /chat/thread/:id/transfer-to-forum
→ 服务端读取消息与附件，整理正文与候选标签
→ 返回预览（标题、正文、标签、附件）
→ 用户修改标题、正文、版块、类型
→ 确认后创建 forum_post，写入 bind_chat_thread_id
→ chat_thread 写 bind_forum_post_id，双向绑定
→ 若标记精华，同步写入 essence_index
→ 返回帖子链接并跳转
```

### 流程 2：论坛帖绑定聊天室线程

```
帖子详情点击开启实时讨论
→ 选择房间
→ POST /forum/post/:id/bind-chat
→ 服务端创建 chat_thread 并带入标题与摘要
→ 双向绑定写入
→ 线程顶部固定回源卡片
→ 通知楼主与版主
```

### 流程 3：悬赏采纳

```
楼主点击设为最佳答案
→ POST /forum/reply/:id/best
→ 校验悬赏状态、操作者身份
→ credit_freeze 扣减并写入 user_credit 流水
→ 帖子状态改为已解决
→ 通知回答者
```

### 流程 4：精华标记

```
标记精华 → is_essence=1 → 写入 essence_index 并生成向量
取消精华 → is_essence=0 → essence_index 置 is_valid=0，AI 不再检索
```

### 流程 5：AI 问答

```
@AI 提问 + thread_id
→ POST /ai/chat/ask
→ 检索 essence_index + 读取线程上下文
→ 生成回答并追加免责
→ 写入 ai_usage_log 并扣减额度
```

### 流程 6：发帖预回答

```
发帖成功 → 异步生成预回答 → 写入 forum_post.ai_summary
→ 打开帖子自动展示，可重新生成
```

---

## 八、风险清单与规避

| 编号 | 风险 | 规避 |
| --- | --- | --- |
| R01 | 消息推送卡顿或丢失 | 先落库再推送；分页加载；心跳重连；只推当前线程 |
| R02 | 附件体积大、存储成本高 | md5 去重；大文件限流；孤立文件清理；ZIP 不解压 |
| R03 | AI 知识库混入闲聊 | 仅精华内容进入向量库，取消精华即时失效 |
| R04 | 双向绑定脏数据 | 一对一约束；变更前清空旧绑定；写操作日志 |
| R05 | 悬赏重复发放 | 冻结表 + 事务 + 幂等 + 状态机 |
| R06 | XSS 与外链钓鱼 | 双端过滤；图片走内部存储；外链加 nofollow |
| R07 | 闲聊被搜索引擎收录 | 未标记线程 noindex，仅精华与帖子开放 |
| R08 | 限流误杀专家 | 角色白名单；参数可配置 |
| R09 | 导出内容错乱 | 导出时生成临时资源链接，附来源与免责 |
| R10 | 注销导致内容丢失 | 内容保留，作者显示为已注销用户 |
| R11 | AI 接口雪崩 | 排队、配额、降级开关 |
| R12 | 水印开关冲突 | 水印跟随单条附件记录 |
| R13 | 移动端操作难点 | 按钮放大、弹窗全屏、核心互通保留 |
| R14 | 举报积压 | 超时升级，后台展示待处理数量 |
| R15 | 编辑不可溯源 | 独立历史表 + 软删除 + 回收站 |

---

## 九、前端状态约定

userStore（用户、权限、未读数）、settingStore（通知、AI、隐私）、chatStore（房间、线程、在线、连接状态）、forumStore（版块、筛选、标签缓存）、searchStore（搜索条件）、aiStore（额度、开关）。