QQgit/docs/PLAN-landing-v1.4.md

141 lines
7.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 规划 · 未登录首页 v1.4(方案 A 首屏 + 热门公开仓库)
> 状态:**仅规划,未动任何代码**(2026-11-05)
> 目标实例:`https://git.qyhhh.top`(Gitea 1.21.11)
> 铁律不变:只走 `custom/` 覆盖、先 `preview/` 后线上、蓝白配色、**禁止绿色**、大量留白。
---
## 1. 已确认的决策
| # | 问题 | 决定 |
| --- | --- | --- |
| 1 | 热门仓库放几个 | **单行 3 个**(宽屏 3 列 × 1 行) |
| 2 | 排序 | **星标优先**(同星数再按最近更新) |
| 3 | Fork / 镜像仓库 | **排除** |
| 4 | 数字条 | **待定**,默认建议:删除(见 §6) |
| 5 | 终端 `git clone` 示例 | **占位地址** `https://git.qyhhh.top/qq/repo.git` |
参考效果图:`dsh-image-gen/image-5f71a3ab.png`(方案 A)、`dsh-image-gen/image-c8208180.png`(方案 B 的仓库区)。
---
## 2. 页面结构(自上而下)
| 区块 | 内容 | 备注 |
| --- | --- | --- |
| 顶栏 | Gitea 原生顶栏 | 不动,沿用 `qq-ui.css` 毛玻璃 |
| ① 首屏 Hero(左右分栏) | **左 7/12**:渐变大标题 `{{AppName}}`、口号「自己的代码,自己的地方。」、搜索框(提交到 `/explore/repos`)、主按钮「免费注册」/ 次按钮「登录」/ 文字链「浏览全部仓库 →」<br>**右 5/12**:毛玻璃卡片,内含 SVG 提交分支图(蓝色节点 + 分叉线),右下叠终端小窗 `$ git clone https://git.qyhhh.top/qq/repo.git` + 复制按钮 | 方案 A |
| ② 热门公开仓库 | 标题「热门公开仓库」+ 右侧「查看全部 →」(`/explore/repos?sort=moststars`);**3 张卡片单行** | 方案 B 的仓库区 |
| ③ 功能卡 | 沿用现有三卡(版本控制 / 议题与看板 / 数据自持),视觉降一级作为收尾 | 文案不变 |
| ④ 数字条 | 待定(§6) | — |
| 页脚 | 左站点信息 / 中语言切换 / 右 ICP 备案号 | 不动 |
整体限宽 **1280px 居中**,与登录后控制台一致。
---
## 3. 仓库卡片规格
```
┌────────────────────────────────────┐
│ (头像20px) owner/仓库名 │
│ 描述文字,最多两行,超出省略…… │
│ ● 语言 ★ 12 ⑂ 3 3 天前更新 │
└────────────────────────────────────┘
```
- 语言圆点:**只用品牌蓝色阶**(`#1D4ED8` / `#3B82F6` / `#60A5FA` / `#93C5FD` 按语言名哈希取色),不用 Gitea 原生语言色(含绿色)。
- hover:上浮 2px,描边变主色 `#3B82F6`(深色 `#38BDF8`)。
- 深色模式:卡片底 `#161B22`,沿用 `qq-dark` 变量。
- 圆角 8px,字体 JetBrains Mono(数字/仓库名)。
---
## 4. 数据来源(关键技术点)
Gitea 1.21 的首页 handler **不给模板传仓库列表**,因此改为前端调用官方公开 API:
```
GET /api/v1/repos/search?sort=stars&order=desc&limit=10&mode=source
```
- 匿名调用只返回公开仓库,不会泄露私有仓库。
- 取多一些(10 个)在前端二次过滤:去掉 `fork === true`、`mirror === true`、`private === true`、`archived === true`(归档是否排除可再议),按 `stars_count` 降序、同星按 `updated_at` 降序,截取前 **3** 个。
- 使用字段:`full_name`、`html_url`、`description`、`language`、`stars_count`、`forks_count`、`updated_at`、`owner.avatar_url`。
- 状态处理:
- 加载中:3 张骨架卡占位(无闪烁时遵守 `prefers-reduced-motion`);
- 结果为 0:整块隐藏,只留首屏「浏览全部仓库 →」;
- 接口失败 / 超时(5s):静默隐藏,不报错。
- **前置条件**:需实测匿名能访问该接口(`REQUIRE_SIGNIN_VIEW=false` 且 API 未禁用)。若不可用,退路是只放「查看全部仓库」入口,不做卡片。
---
## 5. 涉及文件
| 文件 | 改动 |
| --- | --- |
| `custom/templates/home.tmpl` | 重写 Hero 为左右分栏;新增仓库区空容器 `#qq-hot-repos` + 3 张骨架卡;`<script defer src="{{AssetUrlPrefix}}/js/qq-home.js?v=…">` 仅在首页引入 |
| `custom/public/assets/css/qq-pages.css` | 新增 `.qq-lp-split` / `.qq-lp-graph` / `.qq-lp-term` / `.qq-repo-card` / `.qq-skeleton` 等样式,沿用 `.qq-lp-*` 前缀 |
| `custom/public/assets/js/qq-home.js`(新增) | 拉 API → 过滤排序 → 渲染卡片;复制 clone 命令(`navigator.clipboard`,失败回退 `execCommand`);相对时间格式化 |
| `custom/public/assets/js/qq-fx.js` | 光斑 / 打字机挂载点随新 Hero 结构调整(选择器更新) |
| `custom/public/assets/css/qq-fx.css` | 如有 Hero 相关选择器同步调整 |
| `preview/index.html`(+ `preview/app.js`) | 落地页段换成新版式,仓库区用**本地假数据**,不打线上 |
| `docs/TODO.md` | 新增「阶段 8 · 首页 v1.4」条目与部署记录 |
不新增模板钩子以外的任何覆盖,不改 `app.ini`。
---
## 6. 关于「数字条」(待确认)
数字条指当前首页最底部那一排四格:
| 1.21.11 | MIT | MySQL | 1 台 |
| --- | --- | --- | --- |
| Gitea 版本 | 开源协议 | 独立数据库存储 | 服务器即可跑 |
对访客价值不高,且新版已有仓库区和功能卡,页面会偏长。三个选项:
- **A. 删除(默认建议)**
- B. 缩成首屏标题下一行小字:`Gitea 1.21.11 · MIT · 自托管`
- C. 保持原样放在功能卡下面
未回复则按 **A** 执行。
---
## 7. 响应式与无障碍
| 断点 | 行为 |
| --- | --- |
| > 1024px | Hero 左右分栏;仓库 3 列 |
| 641–1024px | Hero 上下堆叠(分支图卡片在文字下方);仓库 3 列压缩 → 不足时 2 列 + 第三张换行 |
| ≤ 640px | 仓库 1 列;终端小窗缩为单行可横向滚动;分支图隐藏 |
- `prefers-reduced-motion`:分支图静止、骨架不闪、关闭光斑。
- 仓库卡片整卡为 `<a>`,有可见焦点环;复制按钮有 `aria-label` 和「已复制」反馈。
---
## 8. 执行步骤(待批准后进行)
1. **接口验证**:匿名 `curl https://git.qyhhh.top/api/v1/repos/search?sort=stars&order=desc&limit=10&mode=source`,确认可用并记录当前公开仓库数量。
2. **离线预览**:在 `preview/` 做出新版,截图 日间 / 夜间 / 375px 移动端 交 QQ 确认。
3. **接入模板**:改 `home.tmpl` / `qq-pages.css` / 新增 `qq-home.js`;跑 `scripts/audit_colors.py` 确认无绿色;提交并打 `v1.4-rc1`。
4. **部署**:`./scripts/deploy.sh` 预演 → QQ 批准 → `./scripts/deploy.sh --yes`(自动备份到 `/var/backups/`)→ 线上实拍复核 → 打 `v1.4-live`。
5. **回滚预案**:`./scripts/rollback.sh /var/backups/gitea-custom-<时间戳>.tar.gz`。
---
## 9. 验收清单
- [ ] 未登录访问首页:首屏左右分栏,分支图 + 终端正常显示
- [ ] 复制按钮可复制 `git clone https://git.qyhhh.top/qq/repo.git`
- [ ] 热门仓库显示 ≤3 个,按星标降序,无 fork / 镜像 / 私有仓库
- [ ] 无公开仓库或接口失败时整块隐藏,页面无报错
- [ ] 日间 / 夜间 / 跟随系统 三主题无绿色、无白边
- [ ] 375px 移动端无横向溢出
- [ ] 登录后首页仍为控制台,不受影响
- [ ] 页脚 ICP 备案号与语言切换正常