feat(sync): auto-discover fixed gist for cloud sync

Author: linull24

app/src/lib/apps/SyncPanel.svelte

@@ -212,11 +212,7 @@
 	async function handleGistImportConfirm() {
 		const token = requireGithubToken();
 		if (!token) return;
-		const gistId = get(githubGistId);
-		if (!gistId) {
-			gistStatus = t('panels.sync.statuses.gistIdRequired');
-			return;
-		}
+		const gistId = get(githubGistId) ?? undefined;
 
 		try {
 			confirmBusy = true;
@@ -225,7 +221,7 @@
 			const { result, effectsDone } = dispatchTermActionWithEffects({
 				type: 'SYNC_GIST_IMPORT_REPLACE',
 				token,
-				gistId
+				gistId: gistId ?? undefined
 			});
 			const dispatchResult = await result;
 			if (!dispatchResult.ok) {
@@ -242,6 +238,7 @@
 			const details = last?.details as Record<string, unknown> | undefined;
 			if (last?.id.startsWith('sync:import-ok:')) {
 				gistStatus = t('panels.sync.statuses.gistImportSuccess');
+				if (details && typeof details.gistId === 'string') setGithubGistId(details.gistId);
 				confirmOpen = false;
 				return;
 			}

app/src/lib/data/github/gistSync.ts

@@ -13,6 +13,63 @@ export interface GistFileContent {
 	content: string;
 }
 
+type GistListItem = {
+	id: string;
+	html_url?: string;
+	description?: string | null;
+	updated_at?: string;
+	files?: Record<string, { filename?: string } | undefined>;
+};
+
+async function fetchJson<T>(url: string, token: string): Promise<T> {
+	const response = await fetch(url, {
+		headers: {
+			Authorization: `token ${token}`,
+			Accept: 'application/vnd.github+json'
+		}
+	});
+	if (!response.ok) {
+		const error = await response.text().catch(() => '');
+		throw new Error(`GitHub API 请求失败: ${response.status} ${response.statusText} - ${error}`);
+	}
+	return (await response.json()) as T;
+}
+
+export async function findLatestGistId(config: {
+	token: string;
+	filename: string;
+	descriptionIncludes?: string;
+	maxPages?: number;
+}): Promise<string | null> {
+	const maxPages = Math.max(1, Math.min(10, config.maxPages ?? 5));
+	const needle = String(config.descriptionIncludes || '').trim();
+
+	let best: { id: string; updatedAt: number } | null = null;
+	for (let page = 1; page <= maxPages; page++) {
+		const list = await fetchJson<GistListItem[]>(`${API_ROOT}/gists?per_page=100&page=${page}`, config.token);
+		if (!Array.isArray(list) || list.length === 0) break;
+
+		for (const gist of list) {
+			const id = String(gist?.id || '').trim();
+			if (!id) continue;
+			const files = gist?.files ?? {};
+			if (!files || typeof files !== 'object') continue;
+			if (!Object.prototype.hasOwnProperty.call(files, config.filename)) continue;
+
+			if (needle) {
+				const desc = String(gist?.description || '');
+				if (!desc.includes(needle)) continue;
+			}
+
+			const updatedAt = gist?.updated_at ? Date.parse(gist.updated_at) : 0;
+			const score = Number.isFinite(updatedAt) ? updatedAt : 0;
+			if (!best || score > best.updatedAt) best = { id, updatedAt: score };
+		}
+	}
+
+	return best?.id ?? null;
+}
+
 export async function syncGist(config: GistSyncConfig) {
 	const body = {
 		description: config.description ?? 'SHU Course Scheduler data',

app/src/lib/data/termState/reducer.ts

@@ -1909,14 +1909,15 @@ export async function reduceTermState(state: TermState, action: TermAction): Pro
 			};
 		}
 		case 'SYNC_GIST_IMPORT_REPLACE': {
+			const gistId = action.gistId;
 			const next = appendHistory(state, {
 				id: `sync:import:${state.history.entries.length}`,
 				at: nowEpochMs(),
 				type: 'sync',
 				label: '从 Gist 导入覆盖',
-				details: { gistId: action.gistId }
+				details: gistId ? { gistId } : undefined
 			});
-			return { state: next, effects: [{ type: 'EFF_GIST_GET', token: action.token, gistId: action.gistId }] };
+			return { state: next, effects: [{ type: 'EFF_GIST_GET', token: action.token, gistId: gistId ?? undefined }] };
 		}
 		case 'SYNC_GIST_EXPORT_OK': {
 			const next = appendHistory(state, {

app/src/lib/data/termState/types.ts

@@ -272,7 +272,7 @@ export type TermAction =
 	| { type: 'SOLVER_RUN_ERR'; error: string }
 	| { type: 'SOLVER_APPLY_RESULT'; resultId: string; mode: 'merge' | 'replace-all' }
 	| { type: 'SOLVER_UNDO_LAST_APPLY' }
-	| { type: 'SYNC_GIST_IMPORT_REPLACE'; token: string; gistId: string }
+	| { type: 'SYNC_GIST_IMPORT_REPLACE'; token: string; gistId?: string }
 	| { type: 'SYNC_GIST_EXPORT'; token: string; gistId?: string; note?: string; public?: boolean }
 	| { type: 'SYNC_GIST_EXPORT_OK'; gistId: string; url: string }
 	| { type: 'SYNC_GIST_EXPORT_ERR'; error: string }
@@ -289,7 +289,7 @@ export type TermEffect =
 	| { type: 'EFF_AUTO_SOLVE_RUN'; mode: 'merge' | 'replace-all'; runId: string }
 	| { type: 'EFF_AUTO_SOLVE_EXIT_EXPORT'; mode: 'merge' | 'replace-all'; runId: string }
 	| { type: 'EFF_DATASET_REFRESH' }
-	| { type: 'EFF_GIST_GET'; token: string; gistId: string }
+	| { type: 'EFF_GIST_GET'; token: string; gistId?: string }
 	| { type: 'EFF_GIST_PUT'; token: string; gistId?: string; note?: string; public?: boolean; payloadBase64: string };
 
 export function assertNever(value: never, message = 'Unexpected value'): never {

app/src/lib/stores/termStateStore.ts

@@ -22,7 +22,7 @@ import {
 } from '../data/jwxt/jwxtApi';
 import { digestToMd5LikeHex } from '../data/termState/digest';
 import { courseCatalogMap, courseDataset } from '../data/catalog/courseCatalog';
-import { getGistFileContent, syncGist } from '../data/github/gistSync';
+import { findLatestGistId, getGistFileContent, syncGist } from '../data/github/gistSync';
 import { assertNever } from '../data/termState/types';
 import { deriveGroupKey } from '../data/termState/groupKey';
 	import { collapseCoursesByName } from './courseDisplaySettings';
@@ -190,6 +190,7 @@ export function clearTermStateAlert() {
 }
 
 const GIST_BUNDLE_FILENAME = 'term-state.json';
+const GIST_BUNDLE_DESCRIPTION = 'NeoSHUSchedulingHelper TermState Bundle';
 const GistBundleSchema = z.object({
 	updatedAt: z.number(),
 	payloadBase64: z.string().min(1)
@@ -1241,11 +1242,21 @@ async function runEffect(effect: TermEffect) {
 			try {
 				const updatedAt = Date.now();
 				const payload = JSON.stringify({ updatedAt, payloadBase64: effect.payloadBase64 } satisfies z.infer<typeof GistBundleSchema>);
+
+				// Auto-discover the existing cloud backup gist (prevents creating many same-name gists).
+				let gistId: string | undefined = effect.gistId ?? undefined;
+				if (!gistId) {
+					gistId = (await findLatestGistId({
+						token: effect.token,
+						filename: GIST_BUNDLE_FILENAME,
+						descriptionIncludes: GIST_BUNDLE_DESCRIPTION
+					})) ?? undefined;
+				}
 				const result = await syncGist({
 					token: effect.token,
-					gistId: effect.gistId,
+					gistId: gistId ?? undefined,
 					public: false,
-					description: 'SHU Course Scheduler TermState Bundle',
+					description: GIST_BUNDLE_DESCRIPTION,
 					files: {
 						[GIST_BUNDLE_FILENAME]: payload
 					}
@@ -1261,9 +1272,19 @@ async function runEffect(effect: TermEffect) {
 		}
 		case 'EFF_GIST_GET': {
 			try {
+				// Auto-discover cloud backup gist if not pinned locally yet.
+				let gistId: string | undefined = effect.gistId ?? undefined;
+				if (!gistId) {
+					gistId = (await findLatestGistId({
+						token: effect.token,
+						filename: GIST_BUNDLE_FILENAME,
+						descriptionIncludes: GIST_BUNDLE_DESCRIPTION
+					})) ?? undefined;
+				}
+				if (!gistId) throw new Error('No cloud backup yet');
 				const file = await getGistFileContent({
 					token: effect.token,
-					gistId: effect.gistId,
+					gistId,
 					filename: GIST_BUNDLE_FILENAME
 				});
 				const raw = JSON.parse(file.content.trim()) as unknown;
@@ -1278,14 +1299,15 @@ async function runEffect(effect: TermEffect) {
 
 				await dispatchTermAction({
 					type: 'SYNC_GIST_IMPORT_OK',
-					gistId: effect.gistId,
+					gistId,
 					state: bundle.termState,
 					generatedAt: bundle.generatedAt
 				});
 			} catch (error) {
+				const fallbackGistId = effect.gistId ?? 'auto';
 				await dispatchTermAction({
 					type: 'SYNC_GIST_IMPORT_ERR',
-					gistId: effect.gistId,
+					gistId: fallbackGistId,
 					error: error instanceof Error ? error.message : String(error)
 				});
 			}