personal-homepage/TODO.md

TODO

基于当前仓库现状整理的最小落地清单。目标不是加复杂后端，而是补齐“安全的数据同步层 + 定时重建入口”。

当前已具备

• Astro 静态站骨架
• 首页、项目页、分享页、日志列表页、日志详情页
• src/config.ts 站点基础配置
• src/content/logs/*.md 日志内容集合
• src/content/projects/index.json 项目数据入口
• src/content/shares/index.json 分享数据入口
• npm run build 静态构建命令

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

1. 增加内容同步脚本

• 新建 scripts/fetch-gitea.ts
• 新建 scripts/fetch-seafile.ts
• 新建 scripts/sync-content.ts
• 约定职责：
  • fetch-gitea.ts：拉取 Gitea 数据
  • fetch-seafile.ts：拉取 Seafile 数据
  • sync-content.ts：统一清洗、转换、写入站点数据文件

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

• 决定是否继续覆盖：
  • src/content/projects/index.json
  • src/content/shares/index.json
• 或改为单独输出到：
  • data/generated/projects.json
  • data/generated/shares.json
• 页面层统一只读最终生成数据，不直接处理上游原始响应

3. 增加环境变量约定

• 新建 .env.example
• 至少定义：
  • GITEA_BASE_URL=
  • GITEA_TOKEN=
  • SEAFILE_BASE_URL=
  • SEAFILE_TOKEN=
• 确保 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 校验
• 在构建前先校验数据格式，避免远程脏数据直接打爆页面

7. 增加同步元数据

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

8. 增加变更检测

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

9. 增加日志与通知

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

P2：后续完善项

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

• 当前 src/components/GiteaActivity.astro 仍是静态示例数据
• 后续改为读取同步后生成的数据
• 再决定是否需要客户端渲染热力图

11. 补部署文件

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

12. 补文档

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

推荐最小闭环

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

实施顺序建议

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