basil
/
personal-homepage
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
personal-homepage/TODO.md

4.3 KiB
Raw Blame History

TODO

基于当前仓库现状整理的最小落地清单。当前项目定位已经明确为：

静态站点 + 构建时数据同步层

目标不是加长期在线后端，而是补齐：

  • 构建时从 Gitea / Seafile 主动拉数据
  • 生成站点内部统一消费的只读数据
  • 提供稳定的重建入口与失败兜底

当前已具备

  • Astro 静态站骨架
  • 首页、项目页、分享页、日志列表页、日志详情页
  • src/config.ts 站点基础配置
  • src/content/logs/*.md 日志内容集合
  • 项目 / 分享静态种子数据入口（当前仍为手工 JSON）
  • npm run build 静态构建命令

P0：先补齐可运行的数据同步链

1. 增加内容同步脚本

  • 新建 scripts/fetch-gitea.ts
  • 新建 scripts/fetch-seafile.ts
  • 新建 scripts/sync-content.ts
  • 约定职责：
    • fetch-gitea.ts：拉取贡献热力图、最近活动、选定仓库摘要
    • fetch-seafile.ts：拉取特定目录 / 特定文件元数据与分享链接
    • sync-content.ts：统一清洗、转换、校验、写入站点数据文件

2. 明确生成数据写入位置

  • 改为统一输出到：
    • src/data/generated/projects.json
    • src/data/generated/shares.json
    • src/data/generated/gitea-activity.json
  • 页面层统一只读最终生成数据，不直接处理上游原始响应

3. 增加环境变量约定

  • 新建 .env.example
  • 至少定义：
    • GITEA_BASE_URL=
    • GITEA_TOKEN=
    • GITEA_USERNAME=
    • SEAFILE_BASE_URL=
    • SEAFILE_TOKEN=
    • SYNC_OUTPUT_DIR=
  • 如需镜像下载文件，再补：
    • SEAFILE_MIRROR_DOWNLOADS=
    • DOWNLOADS_OUTPUT_DIR=
  • 确保 token 只在服务端构建环境 / AstrBot 环境中使用

4. 增加 package scripts

  • 在 package.json 中补充：
    • content:sync
    • rebuild
  • 推荐执行链：
    • npm run content:sync
    • npm run build

5. 明确失败策略

  • 约定 Gitea / Seafile 拉取失败时如何处理：
    • 默认保留上次成功数据继续构建
    • 必要时可通过参数切换为严格失败
  • 在同步脚本里输出明确日志，便于 Astrbot 告警

P1：强烈建议尽快补上

6. 给 JSON 数据加校验

  • 为 projects 数据建立 schema 校验
  • 为 shares 数据建立 schema 校验
  • 为 gitea activity 数据建立 schema 校验
  • 在构建前先校验数据格式，避免远程脏数据直接打爆页面

7. 增加同步元数据

  • 生成 updatedAt
  • 生成 source
  • 生成 itemCount
  • 前端可显示“数据更新时间”

8. 增加变更检测

  • 数据无变化时跳过部署
  • 可通过 hash / diff / 序列化比较实现

9. 增加日志与通知

  • Astrbot 每日 00:00 触发同步与重建
  • 成功时发送通知
  • 失败时发送告警
  • 支持手动补跑一次

P2：后续完善项

10. 把 Gitea Activity 从静态占位改成真实数据

  • 当前 src/components/GiteaActivity.astro 仍是静态示例数据
  • 改为读取 src/data/generated/gitea-activity.json
  • 再决定是否需要客户端渲染热力图

11. 仓库数据与页面映射收口

  • 明确“哪些仓库进入 projects”
  • 明确“哪些仓库只用于 activity 不进入 projects”
  • 决定项目封面图是继续本地维护，还是允许远程字段补充

12. Seafile 下载策略收口

  • 首版默认只展示元数据 + 下载链接
  • 评估是否需要构建时同步特定打包文件到 public/downloads/
  • 如同步文件本体，补充大小限制、覆盖策略、清理策略

13. 补部署文件

  • 增加 Dockerfile
  • 增加 docker-compose.yml
  • 明确静态产物部署方式

14. 补文档

  • 在 README 或单独文档里写清：
    • AstrBot / cron 如何触发
    • 环境变量如何配置
    • 同步脚本职责
    • 构建失败如何排查

推荐最小闭环

  • AstrBot 每天 00:00 触发
  • 执行 npm run content:sync
  • 执行 npm run build
  • 部署静态产物
  • 发送成功/失败通知

实施顺序建议

  1. 先补 .env.example
  2. 再补 scripts/sync-content.ts
  3. 再补 fetch-gitea.ts / fetch-seafile.ts
  4. 再补 package.json scripts
  5. 再补 projects / shares / activity schema 校验
  6. 最后接 AstrBot 定时任务