添加路线图与 Issue 模板，呈现待办事项

- ROADMAP.md 记录已知缺陷、计划功能与已完成项 - README 增加开发状态说明 - Gitea Issue 模板与预填议题文档 Co-authored-by: Cursor <cursoragent@cursor.com>
2026-06-15 23:01:18 +08:00
parent b27289bbea
commit 9230f7272d
6 changed files with 308 additions and 1 deletions
--- a/.gitea/ISSUE_TEMPLATE/bug_report.yaml
+++ b/.gitea/ISSUE_TEMPLATE/bug_report.yaml
@@ -0,0 +1,56 @@
+name: 缺陷报告
+about: 报告一个可复现的问题
+title: "[Bug] "
+labels:
+  - bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        感谢反馈！请尽量提供复现步骤，方便我们定位问题。
+  - type: textarea
+    id: description
+    attributes:
+      label: 问题描述
+      description: 简要说明发生了什么
+      placeholder: 评论回复换行后，页面上显示为一行…
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: 复现步骤
+      placeholder: |
+        1. 打开帖子详情页
+        2. 在评论框输入多行文字
+        3. 点击发送
+        4. 观察到换行丢失
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: 期望行为
+    validations:
+      required: true
+  - type: textarea
+    id: actual
+    attributes:
+      label: 实际行为
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: 版本 / 提交
+      placeholder: main @ abc1234 或 v1.0.0
+  - type: input
+    id: environment
+    attributes:
+      label: 环境
+      placeholder: Windows 11 / Chrome 125 / Go 1.26
+  - type: textarea
+    id: screenshots
+    attributes:
+      label: 截图或日志
+      description: 可粘贴图片或相关日志
--- a/.gitea/ISSUE_TEMPLATE/feature_request.yaml
+++ b/.gitea/ISSUE_TEMPLATE/feature_request.yaml
@@ -0,0 +1,44 @@
+name: 功能建议
+about: 提出新功能或改进现有体验
+title: "[Feature] "
+labels:
+  - enhancement
+body:
+  - type: markdown
+    attributes:
+      value: |
+        欢迎提出想法！请先搜索已有 Issue，避免重复。
+  - type: textarea
+    id: problem
+    attributes:
+      label: 要解决什么问题？
+      description: 从用户场景出发描述痛点
+      placeholder: 管理员在 React 前台无法置顶帖子，必须切到旧版后台…
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: 期望的方案
+      description: 你心目中的实现方式（可简略）
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: 备选方案
+      description: 如有其他思路可一并说明
+  - type: dropdown
+    id: area
+    attributes:
+      label: 涉及模块
+      options:
+        - 前台 UI/UX
+        - 管理后台
+        - 评论系统
+        - 帖子 / 板块
+        - 认证 / 权限
+        - 部署 / 构建
+        - 其他
+    validations:
+      required: true
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -34,13 +34,15 @@ make build           # Linux / macOS

 ## 报告问题

-在 [Issues](https://git.iioio.com/freefire/jiang13-forum/issues) 中描述：
+在 [Issues](https://git.iioio.com/freefire/jiang13-forum/issues) 中描述（也可使用仓库自带的 Issue 模板）：

 1. 复现步骤
 2. 期望行为 vs 实际行为
 3. 环境信息（系统、浏览器、Go/Node 版本）
 4. 截图或日志（如有）

+已知问题与计划功能见 [ROADMAP.md](../ROADMAP.md)。
+
 ## 行为准则

 请保持友善、尊重他人。骚扰、歧视或恶意行为不被容忍。
--- a/README.md
+++ b/README.md
@@ -16,6 +16,7 @@
 [快速开始](#-快速开始) ·
 [界面预览](#-界面预览) ·
 [功能亮点](#-功能亮点) ·
+[路线图](ROADMAP.md) ·
 [参与贡献](CONTRIBUTING.md)

 <br>
@@ -24,6 +25,11 @@

 <sub>浅色主题 · V2EX/NGA 风格三栏布局 · 虚拟滚动帖列表</sub>

+<br>
+
+> **开发状态：** 项目积极开发中，部分功能尚未完善（如评论换行显示、React 前台置顶等）。  
+> 查看 [路线图 ROADMAP.md](ROADMAP.md) · [Issues 反馈](https://git.iioio.com/freefire/jiang13-forum/issues)
+
 </div>

 ---
@@ -202,6 +208,8 @@ jiang13-forum/
 ├── embed_static/          # go:embed 内嵌的 SPA 与模板
 ├── frontend/              # React 源码（Vite 构建）
 ├── docs/screenshots/      # README 界面截图
+├── docs/issue-templates.md # Issue 预填模板
+├── ROADMAP.md             # 路线图与已知问题
 └── scripts/               # 开发辅助脚本
 ```

@@ -221,6 +229,20 @@ data/

 ---

+## 开发状态
+
+项目**积极开发中**，作为论坛产品功能尚未完善，欢迎参与共建。
+
+| 类型 | 示例 |
+|------|------|
+| 🐛 已知缺陷 | 评论回复换行不显示 |
+| 📋 计划中 | React 前台帖子置顶（API 已有，缺 UI） |
+| ✅ 已可用 | 三栏布局、暗色主题、虚拟滚动、楼层评论 |
+
+完整列表见 **[路线图 ROADMAP.md](ROADMAP.md)**。发现问题请提交 [Issues](https://git.iioio.com/freefire/jiang13-forum/issues)，认领任务请参考 [CONTRIBUTING.md](CONTRIBUTING.md)。
+
+---
+
 ## 参与贡献

 欢迎提交 Issue 和 Pull Request！详见 [CONTRIBUTING.md](CONTRIBUTING.md)。
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -0,0 +1,86 @@
+# 路线图 ROADMAP
+
+> 姜十三论坛仍在积极开发中，功能尚未完善。  
+> 欢迎通过 [Issues](https://git.iioio.com/freefire/jiang13-forum/issues) 反馈问题或认领任务。
+
+**图例：** ✅ 已完成 · 🚧 进行中 · 📋 计划中 · 🐛 已知缺陷
+
+---
+
+## 开发状态概览
+
+| 模块 | 状态 | 说明 |
+|------|------|------|
+| 前台 SPA（React） | 🚧 | 核心浏览/发帖/回复可用，部分管理能力仍依赖旧版后台 |
+| 管理后台 | 🚧 | 旧版 HTML 后台功能较全；React 侧尚未统一 |
+| 评论系统 | 🐛 | 换行显示等问题待修复 |
+| 帖子管理 | 🐛 | 置顶 API 已有，React 前台缺操作入口 |
+
+---
+
+## 🐛 已知缺陷（Bug）
+
+| 优先级 | 问题 | 说明 | Issue |
+|--------|------|------|-------|
+| 高 | 评论回复换行不显示 | 输入多行回复后，展示时合并为一行 | [创建 Issue](https://git.iioio.com/freefire/jiang13-forum/issues/new/choose) |
+| 中 | — | （欢迎补充） | — |
+
+### 评论换行不显示 · 详情
+
+- **现象**：在评论框输入带换行的内容，提交后页面上不保留换行
+- **相关代码**：`frontend/src/components/CommentContent.tsx`、`frontend/src/utils/content.ts`
+- **可能原因**：`\r\n` 未处理、`innerHTML` 与 `white-space: pre-wrap` 叠加异常
+
+---
+
+## 📋 计划中（Planned）
+
+| 优先级 | 功能 | 说明 | Issue |
+|--------|------|------|-------|
+| 高 | React 前台支持帖子置顶 | 后端 `pinned` 字段与 API 已存在，需在 SPA 管理入口暴露操作 | [创建 Issue](https://git.iioio.com/freefire/jiang13-forum/issues/new/choose) |
+| 中 | 管理后台 React 化 | 统一旧版 `/admin/*` 与新版 SPA 体验 | — |
+| 中 | 通知已读状态优化 | 右栏通知点击后的已读同步 | — |
+| 低 | 帖子搜索增强 | 标题/正文/作者组合筛选 | — |
+| 低 | 邮件通知 | 回复提醒（需 SMTP 配置） | — |
+
+### 帖子置顶 · 详情
+
+- **现状**：
+  - ✅ 数据模型有 `pinned` 字段
+  - ✅ 列表按 `pinned desc` 排序
+  - ✅ 旧版管理后台 `/admin/posts` 可置顶
+  - ✅ React 列表/详情可显示「置顶」徽章
+  - ❌ React SPA 中管理员无法一键置顶/取消
+- **相关代码**：`service/post.go`、`handler/admin.go`、`frontend/src/pages/PostDetailPage.tsx`
+
+---
+
+## 🚧 进行中（In Progress）
+
+_当前无公开认领任务。若你正在开发某项，请在对应 Issue 留言认领。_
+
+---
+
+## ✅ 已完成（Done）
+
+- [x] 三栏布局 + 虚拟滚动帖列表
+- [x] 浅色 / 暗色主题切换
+- [x] 移动端响应式适配
+- [x] 用户注册登录、JWT 鉴权
+- [x] 板块管理、发帖、Markdown 编辑
+- [x] 楼层式评论、引用回复、@ 高亮
+- [x] 点赞、收藏、热门帖
+- [x] 敏感词过滤、发帖限流
+- [x] SQLite 备份、单二进制部署
+
+---
+
+## 如何参与
+
+1. 在 [Issues](https://git.iioio.com/freefire/jiang13-forum/issues) 挑选任务（预填内容见 [docs/issue-templates.md](docs/issue-templates.md)）
+2. Fork → 分支 → PR，详见 [CONTRIBUTING.md](CONTRIBUTING.md)
+3. 有新想法先开 Issue 讨论，避免重复劳动
+
+---
+
+_最后更新：2026-06-15_
--- a/docs/issue-templates.md
+++ b/docs/issue-templates.md
@@ -0,0 +1,97 @@
+# Issue 预填模板
+
+以下两条可直接复制到 [Gitea Issues](https://git.iioio.com/freefire/jiang13-forum/issues/new) 创建，或使用仓库自带的 Issue 模板。
+
+---
+
+## Issue #1 · 评论回复换行不显示
+
+**标题：** `[Bug] 评论回复换行不显示`
+
+**标签：** `bug` `ui/ux`
+
+**正文：**
+
+### 问题描述
+
+在帖子详情页的评论框中输入多行文字（按 Enter 换行），提交后评论展示区域不保留换行，所有文字合并为一行。
+
+### 复现步骤
+
+1. 打开任意帖子详情页（如 `/post/2`）
+2. 在底部评论框输入：
+   ```
+   第一行
+   第二行
+   第三行
+   ```
+3. 点击发送
+4. 查看刚发布的评论
+
+### 期望行为
+
+评论正文按输入时的换行分段显示，行与行之间有明显间隔。
+
+### 实际行为
+
+多行内容被渲染成单行连续文字。
+
+### 相关代码
+
+- `frontend/src/components/CommentContent.tsx`
+- `frontend/src/utils/content.ts`（`highlightMentions` 中的 `\n` → `<br>` 转换）
+- `frontend/src/styles/global.css`（`.floor-body` 的 `white-space: pre-wrap`）
+
+### 可能原因
+
+- 仅处理了 `\n`，未处理 Windows 的 `\r\n`
+- `dangerouslySetInnerHTML` 与 `pre-wrap` 样式叠加导致表现异常
+- 服务端 `strings.TrimSpace` 或其他处理误删换行（待排查）
+
+### 环境
+
+- 前台：React SPA（`:3000` 嵌入版或 `:5173` 开发版）
+- 浏览器：Chrome / Edge 最新版
+
+---
+
+## Issue #2 · React 前台支持帖子置顶
+
+**标题：** `[Feature] React 前台增加帖子置顶操作`
+
+**标签：** `enhancement` `ui/ux` `good first issue`
+
+**正文：**
+
+### 要解决的问题
+
+管理员无法在 React SPA 前台对帖子执行置顶/取消置顶，必须跳转到旧版 HTML 管理后台（`/admin/posts`），体验割裂。
+
+### 现状
+
+| 能力 | 状态 |
+|------|------|
+| 数据模型 `pinned` 字段 | ✅ 已有 |
+| 列表按置顶排序 | ✅ 已有 |
+| API `POST /admin/api/posts/:id/pin` | ✅ 已有 |
+| 旧版后台置顶按钮 | ✅ 已有 |
+| React 列表/详情显示置顶徽章 | ✅ 已有 |
+| **React 前台置顶操作入口** | ❌ 缺失 |
+
+### 期望方案
+
+在 React SPA 中为管理员提供置顶操作，例如：
+
+1. **帖子详情页**：标题旁增加「置顶 / 取消置顶」按钮（仅 `role === 'admin'` 可见）
+2. **帖列表项**：管理员 hover 时显示置顶快捷操作（可选）
+3. 调用已有 API，成功后刷新列表/详情，无需跳转旧后台
+
+### 相关代码
+
+- 后端：`service/post.go` → `SetPinned`，`handler/admin.go` → `AdminAPIPinPost`
+- 前端：`frontend/src/pages/PostDetailPage.tsx`、`frontend/src/components/PostListItem.tsx`
+- 参考旧版：`embed_static/templates/admin/posts.html` 中的 `togglePin`
+
+### 备注
+
+适合作为 `good first issue`，改动范围小、API 已就绪。