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

7.2 KiB
Raw Blame History

规划 · 未登录首页 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)、主按钮「免费注册」/ 次按钮「登录」/ 文字链「浏览全部仓库 →」
右 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 备案号与语言切换正常