Files

freefire ae448e1ccc docs: 增加 SSR 进度路线图与 Admin 用户下一刀提纲

便于查阅当前完成度与默认继续刀序；lottery/§O 已在前序提交。

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-08-30 03:32:25 +08:00

6.4 KiB

Raw Blame History

姜十三论坛 · 重构规格文档包

读者：准备用新栈（建议真 SSR）重写站点的 AI / 开发者
事实来源：本仓库现有代码；规格描述「产品必须保留什么」，不是「必须继续用 Go + React SPA」
交叉引用：01-product · 02-features · 03-data-model · 04-api · 05-business-rules · 06-pages-ux · 07-config-ops · 08-gitea-ssr-architecture · 09-ssr-progress

实现栈（重构分支）：Gitea 式 Go 模板 SSR；开发分支 rebuild/gitea-ssr；main 保留 React SPA 对照。详见 08。

阅读顺序（请按序投喂）

顺序	文件	用途
1	本文 `README.md`	架构痛点、重构约束、术语
2	01-product.md	产品定位、角色、模块地图
3	02-features.md	验收级功能清单（可打勾）
4	03-data-model.md	表结构、枚举、设置键、等级徽章
5	04-api.md	HTTP 合约（路径 / 鉴权 / 请求响应）
6	05-business-rules.md	状态机与数值规则
7	06-pages-ux.md	路由、布局、编辑器、后台流程
8	07-config-ops.md	配置、数据目录、部署、SEO 字段
9	08-gitea-ssr-architecture.md	Gitea 式 SSR 分支与目录约定
10	09-ssr-progress.md	进度与刀序（「现在做到哪 / 下一刀」）

单次 context 不够时：先投喂 README + 01 + 02；跟进度看 09；实现某模块时再追加对应 03–06 章节。

当前产品是什么

姜十三论坛（Jiang13 Forum） 面向小圈子 / 团队 / 同好社群的轻量论坛。

当前实现技术栈（可抛弃，仅作对照）：

层	技术
后端	Go · Gin · GORM · SQLite
前端	React 18 SPA · TipTap · Tailwind · TanStack Virtual
发布	Vite 构建 → `go:embed` 打进单二进制
认证	bcrypt + DB opaque session Cookie（`jiang13_session`）

演示站：https://bbs.iioio.com/

为何要重构：架构痛点（必须打破）

flowchart LR
  browser[Browser]
  spa[ReactSPA]
  gin[GinAPI]
  sqlite[SQLite]
  bot[BotHTML]
  browser -->|"用户"| spa
  spa -->|"JSON /api"| gin
  gin --> sqlite
  browser -->|"爬虫 UA"| bot
  bot --> gin

痛点	现状	对用户的影响
非真 SSR	生产入口（`main` 的 `embed_static`）只注入 title / branding / Open Graph，不渲染帖文 DOM	刷新先出壳再灌数据，体验不如 SSR
爬虫双轨	`routers/api/seo_bot.go` 对爬虫返回独立 HTML	用户与爬虫看到的不是同一套渲染路径
无正式 migration	Schema 靠 GORM `AutoMigrate`（`models/db.go`）	升级靠「加字段」，难做破坏性迁移与审计
Cookie JWT（旧）	浏览器登录曾用 JWT Cookie	本分支已改为 DB `sessions` + opaque Cookie `jiang13_session`；`.jwt_secret` 仅 CSRF/HMAC

新站目标：用户首屏即可看到帖文 / 列表的服务端渲染（SSR）HTML；SEO meta 与正文同源。技术选型自定（Next.js / Nuxt / Remix / 其它均可）。

重构时必须保留 vs 可以改

必须保留（产品语义）

02-features.md 中列出的功能能力
03-data-model.md 中的实体关系与枚举含义（表名可改，语义对齐）
05-business-rules.md 中的数值与状态机（积分、审核、门控、悬赏分成等）
角色模型：游客 / 用户 / 认证用户（verified 免审）/ 管理员；管理员仅由 /install 创建（不再首注册变管理员）

建议兼容（降低迁移成本）

04-api.md 的 JSON 字段命名与路径形状（可做版本前缀，但旧字段名便于对照）
Cookie 名 jiang13_session（opaque session id；重建分支不做 jiang13_token 双读）
数据目录语义：jiang13.db、uploads/；敏感词在 forum_settings.filter_words（旧 filter_words.txt 可导入）

可以彻底改

语言与框架（不必再 Go + React SPA）
单二进制 / go:embed（可改为前后端分离部署）
SQLite（可换 PostgreSQL 等；规格不强制）
UI 视觉（布局信息密度见 06-pages-ux.md，视觉可重设）
爬虫专用 HTML 双轨（用真 SSR 取代）

术语表（首次出现）

术语	中文	说明
SSR	服务端渲染	首屏 HTML 含正文，非纯客户端壳
SPA	单页应用	当前前台实现形态
OIDC	开放身份连接	本站可作 Provider，供 Gitea 等 SSO
JWT	JSON Web Token	OIDC 对外 `id_token`/`access_token` 仍用；浏览器登录不用 JWT
Opaque session	不透明会话	Cookie 只存随机 id，服务端 `sessions` 表可吊销
Feed	信息流	首页 / 板块帖列表
门控	Content gate	登录可见 / 回复可见 / 积分可见区块
伪静态	Permalink	如 `/post/123.html` 的可选后缀

源码速查（核对规格时）

主题	路径
路由总装	`routers/setup.go`
GORM 模型	`models/models.go`
AutoMigrate	`models/db.go`
论坛设置键	`services/settings.go`
SSR 页面路由	`routers/web/`
JSON API	`routers/api/`
前端 API / 页面（对照）	仅 `main`：`frontend/src/api/`、`frontend/src/App.tsx`
产品介绍	`docs/introduction.md`、`README.md`

文档包完成标准

另一 AI 仅阅读本目录、不打开业务源码，应能：

列出全部用户可见功能与后台能力
画出核心表 ER 并理解枚举
实现或 mock 与现网兼容的 API 形状
复现审核 / 积分 / 门控 / 特殊帖规则
搭出等价的页面信息架构与关键交互

若规格与代码冲突：以代码为准，并应回写修正本目录文档。

6.4 KiB Raw Blame History Unescape Escape