141 lines
7.2 KiB
Markdown
141 lines
7.2 KiB
Markdown
# 规划 · 未登录首页 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 备案号与语言切换正常
|