153 lines
5.2 KiB
Markdown
153 lines
5.2 KiB
Markdown
# TODO
|
||
|
||
基于当前仓库现状整理的最小落地清单。当前项目定位已经明确为：
|
||
|
||
> **静态站点 + 构建时数据同步层**
|
||
|
||
目标不是加长期在线后端，而是补齐：
|
||
|
||
- 构建时从 Gitea / Seafile 主动拉数据
|
||
- 生成站点内部统一消费的只读数据
|
||
- 提供稳定的重建入口与失败兜底
|
||
|
||
## 当前已具备
|
||
|
||
- [x] Astro 静态站骨架
|
||
- [x] 首页、项目页、分享页、日志列表页、日志详情页
|
||
- [x] `src/config.ts` 站点基础配置
|
||
- [x] `src/content/logs/*.md` 日志内容集合
|
||
- [x] `npm run build` 静态构建命令
|
||
- [x] `.env.example`
|
||
- [x] `scripts/fetch-gitea.ts`
|
||
- [x] `scripts/fetch-seafile.ts`
|
||
- [x] `scripts/sync-content.ts`
|
||
- [x] `package.json` 中的 `content:sync` / `rebuild`
|
||
- [x] 生成数据输出到：
|
||
- `src/data/generated/projects.json`
|
||
- `src/data/generated/shares.json`
|
||
- `src/data/generated/gitea-activity.json`
|
||
- [x] 页面层优先读取 generated data，缺失时回退到 seed data
|
||
- [x] `src/content/seafile/index.json` 资源映射文件
|
||
- [x] 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 数据加校验
|
||
|
||
- [x] 为 projects 数据建立 schema 校验
|
||
- [x] 为 shares 数据建立 schema 校验
|
||
- [x] 为 gitea activity 数据建立 schema 校验
|
||
- [x] 在构建前先校验数据格式，避免远程脏数据直接打爆页面
|
||
|
||
### 2. 增加同步元数据展示
|
||
|
||
- [x] 生成 `updatedAt`
|
||
- [x] 生成 `source`
|
||
- [x] 生成 `itemCount`（activity）
|
||
- [x] 前端更明确地显示“数据更新时间”
|
||
|
||
### 3. 增加日志与通知
|
||
|
||
- [ ] AstrBot 或 cron 每日 00:00 触发同步与重建
|
||
- [x] 封装统一重建指令供 AstrBot 调用（如 `npm run rebuild` 或独立 shell 入口）
|
||
- [x] 约定结构化执行结果与错误码，便于 AstrBot 判断成功/失败阶段
|
||
- [ ] 成功时发送通知
|
||
- [ ] 失败时发送告警
|
||
- [x] 支持手动补跑一次
|
||
|
||
### 4. 补部署文件与部署说明
|
||
|
||
- [x] 增加 `Dockerfile`
|
||
- [x] 增加 `docker-compose.yml`
|
||
- [x] 明确静态产物部署方式
|
||
- [x] 写清部署步骤与重建入口
|
||
|
||
### 5. 补运行文档
|
||
|
||
- [x] 在 README 或单独文档里写清：
|
||
- [x] AstrBot / cron 如何触发
|
||
- [x] AstrBot 调用的统一构建指令与返回约定
|
||
- [x] 错误码含义（sync/build/deploy/unknown）
|
||
- [x] 环境变量如何配置
|
||
- [x] Gitea / Seafile 映射如何填写
|
||
- [x] 同步脚本职责
|
||
- [x] 构建失败如何排查
|
||
|
||
## P2：后续完善项
|
||
|
||
### 6. 项目与资源映射收口
|
||
|
||
- [ ] 明确“哪些仓库进入 projects”
|
||
- [ ] 明确“哪些仓库只用于 activity 不进入 projects”
|
||
- [ ] 决定项目封面图是继续本地维护，还是允许远程字段补充
|
||
- [ ] 决定 `download_link` 是否最终完全被 `downloads[]` 取代
|
||
|
||
### 7. Seafile 下载策略收口
|
||
|
||
- [x] 首版支持只展示元数据 + 下载链接
|
||
- [ ] 评估是否需要构建时同步特定打包文件到 `public/downloads/`
|
||
- [ ] 如同步文件本体，补充大小限制、覆盖策略、清理策略
|
||
- [ ] 评估是否需要“自动扫描目录”而不是完全依赖映射文件
|
||
|
||
### 8. 首页与页面体验完善
|
||
|
||
- [ ] 首页增加 shares preview / recent resources 模块
|
||
- [ ] `/shares` 页增加更明确的类型 / 所属项目 / 链接状态展示优化
|
||
- [ ] 项目卡片下载区样式优化
|
||
- [ ] 前端更明确显示同步时间与数据来源
|
||
|
||
### 9. 变更检测（当前不是必须项）
|
||
|
||
- [ ] 数据无变化时跳过部署
|
||
- [ ] 可通过 hash / diff / 序列化比较实现
|
||
- [ ] 当前数据量较小，可在部署资源或通知噪音变高时再做
|
||
|
||
## 推荐最小闭环
|
||
|
||
- [ ] AstrBot 或 cron 每天 00:00 触发
|
||
- [ ] 调用统一重建指令并读取错误码 / 执行结果
|
||
- [x] 执行 `npm run content:sync`
|
||
- [x] 执行 `npm run build`
|
||
- [ ] 部署静态产物
|
||
- [ ] 发送成功/失败通知
|
||
|
||
## 实施顺序建议
|
||
|
||
1. 先补 AstrBot / cron 触发与通知
|
||
2. 再补 Docker / docker-compose / 静态产物部署说明
|
||
3. 再补 README / 运维文档，形成可维护闭环
|
||
4. 然后回头做首页 shares preview 和列表体验优化
|
||
5. 变更检测放到最后，需要时再做
|