# TODO

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

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

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

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

## 当前已具备

- [x] Astro 静态站骨架
- [x] 首页、项目页、分享页、日志列表页、日志详情页
- [x] `src/config.ts` 站点基础配置
- [x] `src/content/logs/*.md` 日志内容集合
- [x] 项目 / 分享静态种子数据入口（当前仍为手工 JSON）
- [x] `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 定时任务