freefire/jiang13-forum
2
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity

chore: 主题改媒体查询并清理未挂载 API

Browse Source 
去掉 head 防闪脚本；删除论坛 JSON CRUD 与 crawler，仅保留机器入口；用户向文档对齐 SSR。

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
姜十三
2026-08-30 05:10:23 +08:00
parent 4a21d362d0
commit 58b94df50c
27 changed files with 277 additions and 3182 deletions
Download Patch File Download Diff File Expand all files Collapse all files

38
docs/introduction.md
View File

@@ -11,7 +11,7 @@
它不做「大而全」的社区平台，而是聚焦一件事：让几个人到几百人的内部交流，有一个干净、顺手、自己能掌控的地方。
技术上，它是一个编译为 **单个 Go 二进制** 的 Web 应用：前端 SPA（单页应用）通过 `go:embed` 内嵌，数据库用内置 **SQLite**，拷贝到服务器就能跑——没有复杂的中间件矩阵，也没有「先装一堆依赖再祈祷能起来」的仪式感。
技术上，它是一个编译为 **单个 Go 二进制** 的 Web 应用：公开页用 **Go `html/template` 真 SSR**，`web_src` 做渐进增强 CSS/JS（`go:embed`），数据库默认 **SQLite**，拷贝到服务器就能跑。
---
@@ -60,24 +60,24 @@ Feed 可按 **最新发帖 / 最新回复 / 热门讨论** 切换。浅色与暗
整体气质更接近 V2EX / NGA 一类的信息密度——一屏能看更多内容，而不是大留白的营销站。
### 发帖：富文本，够用就好
### 发帖：Markdown，够用就好
发帖使用 **TipTap** 富文本编辑器：标题、排版、标签、板块选择、正文图片本地上传，日常写帖够用。帖子支持置顶；编辑后保留 **修订历史**，可做 diff（差异）对比。管理员还可配置普通用户的 **编辑时限**，避免无限制改稿。
发帖使用 **Markdown 工具栏**（标题、粗斜体、列表、代码块、图片上传、内容门控插入）与服务端预览；标签、板块选择日常写帖够用。帖子支持置顶；编辑后保留 **修订历史**。管理员还可配置普通用户的 **编辑时限**，避免无限制改稿。
### 讨论：楼层回复，聊得清楚
评论是楼层式的：可回复指定楼层、引用原文、@ 高亮。点赞、收藏、热门帖，把活跃内容自然推到前面。
评论是楼层式的：可回复指定楼层、引用原文；支持嵌套展示。点赞、收藏、热门帖，把活跃内容自然推到前面。
### 管理：后台也是 SPA
### 管理：SSR 后台
管理后台统一在 `/admin`，与前台同一套 React 体验：
管理后台统一在 `/admin`，与公开页同一套模板布局：
- 仪表盘、板块与帖子管理
- 用户禁言、删帖删评
- 论坛参数、限流、敏感词
- SQLite **一键备份**
权限模型很简单：**普通用户 / 管理员**；站点 **第一个注册用户自动成为管理员**，省去安装向导里的一堆步骤。
权限模型很简单：**普通用户 / 管理员**；首次通过 **安装向导** 创建管理员账号。
---
@@ -88,7 +88,7 @@ Feed 可按 **最新发帖 / 最新回复 / 热门讨论** 切换。浅色与暗
```text
编译 → 得到一个 jiang13（或 jiang13.exe）
放到目录里运行 → Env / CLI 引导（默认 SQLite）
打开浏览器注册 → 第一个账号就是管理员
打开浏览器完成安装向导 → 创建管理员
```
要点：
@@ -99,7 +99,7 @@ Feed 可按 **最新发帖 / 最新回复 / 热门讨论** 切换。浅色与暗
- **系统服务**：内置 Linux systemd / Windows Service 安装与启停；
- **跨平台**：Windows / Linux / macOS 均可编译与运行。
典型启动后访问 `http://localhost:3000`，注册即可开始。
典型启动后访问 `http://localhost:3000`，完成安装后即可开始。
---
@@ -107,26 +107,26 @@ Feed 可按 **最新发帖 / 最新回复 / 热门讨论** 切换。浅色与暗
| 层级 | 技术 |
|------|------|
| 后端 | Go · Gin · GORM · SQLite |
| 前端 | React 18 · TipTap · Radix UI · Tailwind CSS · TanStack Virtual |
| 构建 | Vite 构建 SPA，再由 `go:embed` 打进二进制 |
| 认证 | bcrypt + JWT Cookie；可选 OIDC Provider，对接 Gitea 等 SSO |
| 后端 / SSR | Go · Gin · GORM · SQLite · `html/template` |
| 渐进资源 | `web_src` → `public/assets`（`/ssr-assets/`） |
| 构建 | `web_src` + `go:embed` templates/assets，单二进制 |
| 认证 | bcrypt + 会话 Cookie；可选 OIDC Provider，对接 Gitea 等 SSO |
对运维者：数据目录结构清晰（数据库、日志、上传、敏感词、备份）。对开发者：前后端分离开发，`dev` 模式下 Vite HMR（热模块替换）可秒级预览前端改动。
对运维者：数据目录结构清晰（数据库、日志、上传、敏感词、备份）。对开发者：改模板/Go 后重启进程；改 `web_src` 后跑 `build.bat -Target web-src`。
---
## 现在走到哪一步
项目仍在积极开发中，核心体验已经可用：
项目仍在积极开发中，核心体验已经可用（分支 `rebuild/gitea-ssr`）：
- ✅ 三栏布局、主题切换、虚拟滚动、Feed 排序
- ✅ 发帖 / 评论 / 点赞收藏 / 修订历史
- ✅ React 管理后台与论坛参数配置
- ✅ 三栏布局、主题切换、Feed 排序、真 SSR 公开页
- ✅ 发帖 / 评论 / 点赞收藏 / 修订历史（Markdown 编辑器）
- ✅ SSR 管理后台与论坛参数配置
- ✅ OIDC Provider（可作 Gitea 等站点的登录源）
- ✅ 单二进制部署与系统服务
计划中的方向包括通知动态优化、搜索增强、邮件提醒等——完整列表见仓库 [ROADMAP.md](../ROADMAP.md)。
计划中的方向见仓库 [ROADMAP.md](../ROADMAP.md) 与 [09-ssr-progress.md](rebuild-spec/09-ssr-progress.md)。
---

73
docs/issue-templates.md
View File

@@ -1,12 +1,12 @@
# Issue 预填模板
以下两条可直接复制到本仓库 Issues 创建，或使用仓库自带的 Issue 模板。
以下可直接复制到本仓库 Issues 创建。本分支为 **SSR**（`rebuild/gitea-ssr`）；对照 SPA 请注明 `main`。
---
## Issue #1 · 评论回复换行不显示
## Issue · Bug 模板
**标题：** `[Bug] 评论回复换行不显示`
**标题：** `[Bug] 简短描述`
**标签：** `bug` `ui/ux`
@@ -14,79 +14,52 @@
### 问题描述
在帖子详情页的评论框中输入多行文字（按 Enter 换行），提交后评论展示区域不保留换行，所有文字合并为一行。
（一句话）
### 复现步骤
1. 打开任意帖子详情页（如 `/post/2`）
2. 在底部评论框输入：
```
第一行
第二行
第三行
```
3. 点击发送
4. 查看刚发布的评论
1. …
2. …
### 期望行为
### 期望行为 / 实际行为
评论正文按输入时的换行分段显示，行与行之间有明显间隔。
### 相关代码（若已知）
### 实际行为
多行内容被渲染成单行连续文字。
### 相关代码
- `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` 或其他处理误删换行（待排查）
- 模板：`templates/…`
- 路由：`routers/web/…`
- 样式/脚本：`web_src/…`
### 环境
- 前台：React SPA（`:3000` 嵌入版或 `:5173` 开发版）
- 浏览器：Chrome / Edge 最新版
- 分支：`rebuild/gitea-ssr`（或 `main` SPA）
- 浏览器 / OS
---
## Issue #2 · 示例：管理能力扩展（模板文案）
## Issue · 功能增强模板
**标题：** `[Feature] 管理后台增加某某能力`
**标题：** `[Feature] 简短描述`
**标签：** `enhancement` `ui/ux` `good first issue`
**标签：** `enhancement`
**正文：**
### 要解决的问题
描述管理员在 React SPA 管理后台 / 前台中缺少的操作入口或能力。
### 现状
| 能力 | 状态 |
| --- | --- |
| 数据模型与业务逻辑 | ✅ / ❌ |
| JSON API（如 `POST /api/admin/...`） | ✅ / ❌ |
| React 管理后台入口 | ✅ / ❌ |
| React 前台操作入口（如适用） | ✅ / ❌ |
| 规格（`docs/rebuild-spec`） | ✅ / ❌ |
| SSR 页面 / 表单 | ✅ / ❌ |
| 业务 `services/` | ✅ / ❌ |
### 期望方案
1. 在对应页面为管理员增加操作入口（仅 `role === 'admin'` 可见）
2. 调用已有或新增的 `/api/admin/*` JSON API
3. 成功后刷新列表/详情，无需离开当前页面
1. …
2. …
### 相关代码
- 后端：`service/`、`handler/api.go`、`router/router.go`
- 前端：`frontend/src/pages/admin/`、`frontend/src/api/client.ts`
### 备注
适合作为 `good first issue` 时，优先选择 API 已就绪、只需补 UI 的小改动。
- `routers/web/`、`templates/`、`services/`
- 规格：`docs/rebuild-spec/02-features.md` / `06-pages-ux.md`

2
docs/rebuild-spec/02-features.md
View File

@@ -12,7 +12,7 @@
## A. 浏览与布局
- [x] 三栏布局：左导航 / 中 Feed / 右栏小组件 — SSR（桌面；≤900px 隐藏右栏）
- [x] 浅色 / 暗色主题；跟随系统偏好并本地记忆 — `data-theme` + `localStorage`（`j13-theme`）；顶栏循环：跟随系统 / 浅色 / 暗色
- [x] 浅色 / 暗色主题；跟随系统偏好并本地记忆 — CSS `prefers-color-scheme` + `data-theme` 显式覆盖；顶栏循环：跟随系统 / 浅色 / 暗色（`j13-theme`）
- [ ] 响应式：平板/手机收起侧栏
- [ ] 长列表虚拟滚动或等价流畅方案
- [x] Feed 排序：`latest`（最新发帖）/ `reply`（最新回复）/ `hot`（热门）

2
docs/rebuild-spec/04-api.md
View File

@@ -5,7 +5,7 @@
> **源码**：[`routers/setup.go`](../../routers/setup.go)、[`modules/auth/auth.go`](../../modules/auth/auth.go)
本分支（`rebuild/gitea-ssr`）浏览器走 **`routers/web` 模板 + 表单**。
下列 JSON 合约保留作历史对照与未来机器 API；**当前进程仅注册** health / OIDC / robots / sitemap / media 等机器相关路由，论坛 CRUD 的 `/api/*` 已从路由表移除（handler 源码可删可留，不以 SPA 兼容为目的）。
**当前进程仅注册** health / OIDC / robots / sitemap / media thumb 等机器相关路由；论坛 CRUD 的 `/api/*` **handler 已从本分支删除**（对照实现见 `main`，合约形状见下文历史章节）。
`main` 分支 SPA 仍完整实现下表；对照请 checkout `main`。

7
docs/rebuild-spec/06-pages-ux.md
View File

@@ -105,10 +105,9 @@
### 2.5 主题
- 浅色 / 暗色；默认 **跟随系统**；`localStorage` 键 `j13-theme`（`system` | `light` | `dark`）
- `<html data-theme="light|dark" data-theme-pref="…">`；`<head>` 内联脚本防首屏闪烁
- 顶栏按钮循环切换；系统偏好变化时在 `system` 模式下即时更新
- 兼容旧 SPA 仅存 `light`/`dark` 的值
- 浅色 / 暗色；默认 **跟随系统**（CSS `@media (prefers-color-scheme)`）；`localStorage` 键 `j13-theme`（`system` | `light` | `dark`）
- 显式浅/深时设 `<html data-theme="light|dark">`；`system` 时去掉该属性，交给媒体查询
- 顶栏按钮循环切换；兼容旧 SPA 仅存 `light`/`dark` 的值
---

13
docs/rebuild-spec/09-ssr-progress.md
View File

@@ -10,15 +10,15 @@
| 项 | 值 |
|----|-----|
| **上一刀** | 浅色/暗色主题（跟随系统 + localStorage） |
| **下一刀** | 需点名（OIDC / S3 / Gitea / 表格表情…） |
| **上一刀** | 主题去防闪 + 删未挂载 JSON API / crawler + 文档对齐 |
| **下一刀** | 需点名（OIDC Admin / S3 / Gitea / 表格表情…） |
| **工作区** | 应干净 |
---
## 一句话状态
核心论坛、Admin、Limits/伪静态、嵌套评论、Markdown 编辑器、**主题**已齐。余量多为后置与体验打磨。
核心论坛、Admin、Limits/伪静态、嵌套评论、Markdown 编辑器、主题已齐；本分支 `routers/api` 仅保留机器入口。余量多为后置与体验打磨。
---
@@ -30,15 +30,16 @@
| Limits / 伪静态 / 品牌图 | 已迁 |
| 评论嵌套树 UI | 已迁 |
| Markdown 工具栏 + preview | 已迁 |
| 浅色 / 暗色 / 跟随系统 | 已迁 |
| 浅色 / 暗色 / 跟随系统 | 已迁（CSS 媒体查询，无 head 防闪脚本） |
| 未挂载论坛 JSON API | 已删（对照 `main`） |
---
## 未完成
- P3：TipTip、游客评论、修订 diff、响应式侧栏抽屉
- P3：游客评论、修订 diff、响应式侧栏抽屉
- 编辑器后置：TipTap、表格、图片组、表情贴纸
- 后置：OIDC、S3 热切换、Gitea `/projects`
- 后置：OIDC Admin UI、S3 热切换、Gitea `/projects`
---

12
docs/site-posts/about-jiang13.md
View File

@@ -98,12 +98,12 @@
### 浏览与发帖
- 三栏布局，桌面 / 移动自适应
- Feed 排序与虚拟滚动
- 浅色 / 暗色主题；板块图标与主题色可配
- TipTap 富文本、标签、正文图片
- 楼层评论：回复、引用、@
- Feed 排序
- 浅色 / 暗色主题（可跟随系统）；板块图标与主题色可配
- Markdown 编辑器、标签、正文图片、内容门控
- 楼层评论：回复、引用、嵌套树
- 点赞、收藏；置顶 / 精华
- 编辑修订历史（可对比差异）
- 编辑修订历史
- 可配置普通用户的编辑时限
### 社交与个人
@@ -114,7 +114,7 @@
### 管理后台
与前台同一套 React 体验，统一在 `/admin`：
SSR 后台统一在 `/admin`：
| 模块 | 能力 |
| --- | --- |