From e03af0c800bc789a671f5325a0f1190f48769cca Mon Sep 17 00:00:00 2001
From: SepComet <202308010230@stu.csust.edu.cn>
Date: Tue, 5 May 2026 10:45:53 +0800
Subject: [PATCH] docs: update roadmap to match current sync implementation

---
 TODO.md | 137 +++++++++++++++++++++++++++-----------------------------
 1 file changed, 66 insertions(+), 71 deletions(-)

diff --git a/TODO.md b/TODO.md
index 1381d13..054aa04 100644
--- a/TODO.md
+++ b/TODO.md
@@ -16,135 +16,130 @@
 - [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. 明确生成数据写入位置
-
-- [ ] 改为统一输出到：
+- [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 已改为读取真实生成数据
 
-### 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 环境中使用
+### Gitea
 
-### 4. 增加 package scripts
+- 当前不是直接读取“官方热力图原始数据”
+- 当前实现为：
+  - 按 `GITEA_USERNAME` 拉取 `/users/{username}/activities/feeds`
+  - 再按天聚合为 `gitea-activity.json` 中的 `days[]`
+  - `recent[]` 也来自用户 activity feeds
+- 项目仓库信息仍由 `src/content/projects/index.json` 中的 `gitea_repo` 决定
 
-- [ ] 在 `package.json` 中补充：
-  - `content:sync`
-  - `rebuild`
-- [ ] 推荐执行链：
-  - `npm run content:sync`
-  - `npm run build`
+### Seafile
 
-### 5. 明确失败策略
+- 当前不是“自动扫描整个目录树优先”
+- 当前实现为：
+  - 使用 `src/content/seafile/index.json` 作为资源映射层
+  - 每条资源支持两种方式：
+    - 直接填写 `url`
+    - 或填写 `repo_id + path` 供构建脚本请求 Seafile API
+- 项目资源挂到 `projects[].downloads[]`
+- 全站资源汇总进入 `shares.json`
 
-- [ ] 约定 Gitea / Seafile 拉取失败时如何处理：
-  - 默认保留上次成功数据继续构建
-  - 必要时可通过参数切换为严格失败
-- [ ] 在同步脚本里输出明确日志，便于 Astrbot 告警
+### 失败策略（当前实际行为）
+
+- 当前默认策略不是“保留上次成功 generated JSON 原样不动”
+- 当前实际策略是：
+  - Gitea / Seafile 某项失败时，回退到 seed / 映射数据继续生成
+  - 若 `STRICT_SYNC=true`，则同步失败直接中断
+- 后续可再评估是否增加“保留上一轮 generated 产物”的模式
+
+---
 
 ## P1：强烈建议尽快补上
 
-### 6. 给 JSON 数据加校验
+### 1. 给 JSON 数据加校验
 
 - [ ] 为 projects 数据建立 schema 校验
 - [ ] 为 shares 数据建立 schema 校验
 - [ ] 为 gitea activity 数据建立 schema 校验
 - [ ] 在构建前先校验数据格式，避免远程脏数据直接打爆页面
 
-### 7. 增加同步元数据
+### 2. 增加同步元数据展示
 
-- [ ] 生成 `updatedAt`
-- [ ] 生成 `source`
-- [ ] 生成 `itemCount`
-- [ ] 前端可显示“数据更新时间”
+- [x] 生成 `updatedAt`
+- [x] 生成 `source`
+- [x] 生成 `itemCount`（activity）
+- [ ] 前端更明确地显示“数据更新时间”
 
-### 8. 增加变更检测
+### 3. 增加变更检测
 
 - [ ] 数据无变化时跳过部署
 - [ ] 可通过 hash / diff / 序列化比较实现
 
-### 9. 增加日志与通知
+### 4. 增加日志与通知
 
-- [ ] Astrbot 每日 00:00 触发同步与重建
+- [ ] AstrBot 每日 00:00 触发同步与重建
 - [ ] 成功时发送通知
 - [ ] 失败时发送告警
 - [ ] 支持手动补跑一次
 
 ## P2：后续完善项
 
-### 10. 把 Gitea Activity 从静态占位改成真实数据
-
-- [ ] 当前 `src/components/GiteaActivity.astro` 仍是静态示例数据
-- [ ] 改为读取 `src/data/generated/gitea-activity.json`
-- [ ] 再决定是否需要客户端渲染热力图
-
-### 11. 仓库数据与页面映射收口
+### 5. 项目与资源映射收口
 
 - [ ] 明确“哪些仓库进入 projects”
 - [ ] 明确“哪些仓库只用于 activity 不进入 projects”
 - [ ] 决定项目封面图是继续本地维护，还是允许远程字段补充
+- [ ] 决定 `download_link` 是否最终完全被 `downloads[]` 取代
 
-### 12. Seafile 下载策略收口
+### 6. Seafile 下载策略收口
 
-- [ ] 首版默认只展示元数据 + 下载链接
+- [x] 首版支持只展示元数据 + 下载链接
 - [ ] 评估是否需要构建时同步特定打包文件到 `public/downloads/`
 - [ ] 如同步文件本体，补充大小限制、覆盖策略、清理策略
+- [ ] 评估是否需要“自动扫描目录”而不是完全依赖映射文件
 
-### 13. 补部署文件
+### 7. 首页与页面体验完善
+
+- [ ] 首页增加 shares preview / recent resources 模块
+- [ ] `/shares` 页增加更明确的类型 / 所属项目 / 链接状态展示优化
+- [ ] 项目卡片下载区样式优化
+- [ ] 前端更明确显示同步时间与数据来源
+
+### 8. 补部署文件
 
 - [ ] 增加 `Dockerfile`
 - [ ] 增加 `docker-compose.yml`
 - [ ] 明确静态产物部署方式
 
-### 14. 补文档
+### 9. 补文档
 
 - [ ] 在 README 或单独文档里写清：
   - AstrBot / cron 如何触发
   - 环境变量如何配置
+  - Gitea / Seafile 映射如何填写
   - 同步脚本职责
   - 构建失败如何排查
 
 ## 推荐最小闭环
 
 - [ ] AstrBot 每天 00:00 触发
-- [ ] 执行 `npm run content:sync`
-- [ ] 执行 `npm run build`
+- [x] 执行 `npm run content:sync`
+- [x] 执行 `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 定时任务
+1. 先补 projects / shares / activity schema 校验
+2. 再整理并提交 `src/config.ts` / `src/content/projects/index.json`
+3. 再补首页 shares preview
+4. 再补 AstrBot / cron 触发与通知
+5. 最后补 Docker / README / 部署说明