freefire
4a21d362d0
顶栏循环切换，localStorage 记忆；head 内联脚本避免首屏闪烁。 Co-authored-by: Cursor <cursoragent@cursor.com>
姜十三论坛 · 重构规格文档包
读者：准备用新栈（建议真 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） |
为何要重构：架构痛点（必须打破）
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 形状
- 复现审核 / 积分 / 门控 / 特殊帖规则
- 搭出等价的页面信息架构与关键交互
若规格与代码冲突：以代码为准，并应回写修正本目录文档。