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

5.2 KiB
Raw Permalink Blame History

TODO

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

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

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

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

当前已具备

  • Astro 静态站骨架
  • 首页、项目页、分享页、日志列表页、日志详情页
  • src/config.ts 站点基础配置
  • src/content/logs/*.md 日志内容集合
  • npm run build 静态构建命令
  • .env.example
  • scripts/fetch-gitea.ts
  • scripts/fetch-seafile.ts
  • scripts/sync-content.ts
  • package.json 中的 content:sync / rebuild
  • 生成数据输出到：
    • src/data/generated/projects.json
    • src/data/generated/shares.json
    • src/data/generated/gitea-activity.json
  • 页面层优先读取 generated data，缺失时回退到 seed data
  • src/content/seafile/index.json 资源映射文件
  • Gitea Activity 已改为读取真实生成数据

当前实现说明（与最初抽象规划相比的收敛结果）

Gitea

  • 当前不是直接读取“官方热力图原始数据”
  • 当前实现为：
    • 按 GITEA_USERNAME 拉取 /users/{username}/activities/feeds
    • 再按天聚合为 gitea-activity.json 中的 days[]
    • recent[] 也来自用户 activity feeds
  • 项目仓库信息仍由 src/content/projects/index.json 中的 gitea_repo 决定

Seafile

  • 当前不是“自动扫描整个目录树优先”
  • 当前实现为：
    • 使用 src/content/seafile/index.json 作为资源映射层
    • 每条资源支持两种方式：
      • 直接填写 url
      • 或填写 repo_id + path 供构建脚本请求 Seafile API
  • 项目资源挂到 projects[].downloads[]
  • 全站资源汇总进入 shares.json

失败策略（当前实际行为）

  • 当前默认策略不是“保留上次成功 generated JSON 原样不动”
  • 当前实际策略是：
    • Gitea / Seafile 某项失败时，回退到 seed / 映射数据继续生成
    • 若 STRICT_SYNC=true，则同步失败直接中断
  • 后续可再评估是否增加“保留上一轮 generated 产物”的模式

P1：强烈建议尽快补上

1. 给 JSON 数据加校验

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

2. 增加同步元数据展示

  • 生成 updatedAt
  • 生成 source
  • 生成 itemCount（activity）
  • 前端更明确地显示“数据更新时间”

3. 增加日志与通知

  • AstrBot 或 cron 每日 00:00 触发同步与重建
  • 封装统一重建指令供 AstrBot 调用（如 npm run rebuild 或独立 shell 入口）
  • 约定结构化执行结果与错误码，便于 AstrBot 判断成功/失败阶段
  • 成功时发送通知
  • 失败时发送告警
  • 支持手动补跑一次

4. 补部署文件与部署说明

  • 增加 Dockerfile
  • 增加 docker-compose.yml
  • 明确静态产物部署方式
  • 写清部署步骤与重建入口

5. 补运行文档

  • 在 README 或单独文档里写清：
    • AstrBot / cron 如何触发
    • AstrBot 调用的统一构建指令与返回约定
    • 错误码含义（sync/build/deploy/unknown）
    • 环境变量如何配置
    • Gitea / Seafile 映射如何填写
    • 同步脚本职责
    • 构建失败如何排查

P2：后续完善项

6. 项目与资源映射收口

  • 明确“哪些仓库进入 projects”
  • 明确“哪些仓库只用于 activity 不进入 projects”
  • 决定项目封面图是继续本地维护，还是允许远程字段补充
  • 决定 download_link 是否最终完全被 downloads[] 取代

7. Seafile 下载策略收口

  • 首版支持只展示元数据 + 下载链接
  • 评估是否需要构建时同步特定打包文件到 public/downloads/
  • 如同步文件本体，补充大小限制、覆盖策略、清理策略
  • 评估是否需要“自动扫描目录”而不是完全依赖映射文件

8. 首页与页面体验完善

  • 首页增加 shares preview / recent resources 模块
  • /shares 页增加更明确的类型 / 所属项目 / 链接状态展示优化
  • 项目卡片下载区样式优化
  • 前端更明确显示同步时间与数据来源

9. 变更检测（当前不是必须项）

  • 数据无变化时跳过部署
  • 可通过 hash / diff / 序列化比较实现
  • 当前数据量较小，可在部署资源或通知噪音变高时再做

推荐最小闭环

  • AstrBot 或 cron 每天 00:00 触发
  • 调用统一重建指令并读取错误码 / 执行结果
  • 执行 npm run content:sync
  • 执行 npm run build
  • 部署静态产物
  • 发送成功/失败通知

实施顺序建议

  1. 先补 AstrBot / cron 触发与通知
  2. 再补 Docker / docker-compose / 静态产物部署说明
  3. 再补 README / 运维文档，形成可维护闭环
  4. 然后回头做首页 shares preview 和列表体验优化
  5. 变更检测放到最后，需要时再做