docs+feat: 重构规格与 Gitea 式 SSR 骨架(首页)

在 rebuild/gitea-ssr 落地产品规格、Cursor 规则,以及 Go 模板 SSR 首页/板块列表;未迁移路径仍回落 SPA,便于对照 main。

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
2026-08-29 03:11:25 +08:00
parent 4dc3bbb13f
commit 1414c71dec
28 changed files with 2891 additions and 24 deletions

View File

@@ -0,0 +1,58 @@
# 08 · Gitea 式 SSR 架构(开发约定)
> **读者**:在本仓库 `rebuild/gitea-ssr` 分支上开发的 AI / 开发者
> **前置**[README.md](README.md)
> **对照上游**[go-gitea/gitea](https://github.com/go-gitea/gitea)
---
## 目标栈(已确认)
| 层 | 选择 |
|----|------|
| 公开页渲染 | Go `html/template` **真 SSR**(完整 HTML含帖文/列表 DOM |
| 渐进增强 | `web_src/` 少量 CSS/JS构建后嵌入 |
| 发布 | 单二进制 + `go:embed` |
| 业务语义 | 仍以本目录 `01``07` 为准 |
| 不做 | React/Next 公开页 SPA用户与爬虫双轨 HTML |
---
## 开发分支与对照
| 分支 | 用途 |
|------|------|
| `main` | 现网 **React SPA** 对照,勿在此做破坏性 SSR 替换 |
| `rebuild/gitea-ssr` | **唯一** Gitea 式重构开发分支 |
对照运行:
```bash
git checkout main # 旧 SPA
# 或
git worktree add ../jiang13-spa main
```
---
## 目录职责(演进中)
```text
routers/web/ # 返回 HTML 的页面路由
templates/ # Go 模板源文件(嵌入)
web_src/ # CSS/JS 源码
public/assets/ # web_src 构建产物嵌入URL 前缀 `/ssr-assets/`
modules/ # 横切(模板渲染等)
docs/rebuild-spec/ # 产品规格
.cursor/rules/ # AI 开发规则
```
现有 `model/``service/``handler/`JSON API可先复用公开页出口改为模板。
---
## 渲染原则
1. 用户访问已迁移路径时,「查看源代码」须可见内容 DOM而非空壳。
2. JSON `/api` 留给交互增强与后台;**不得**作为公开页首屏唯一数据来源。
3. 模板默认 HTML 转义;可信 HTML已消毒正文用明确的安全管道禁止随意 `| safe`