From da8de7f318bbce0c6ae32574880ff6197ecaabca Mon Sep 17 00:00:00 2001 From: Algebraaaa Date: Sat, 11 Jul 2026 21:06:33 +0800 Subject: [PATCH 1/9] fix(radixsort): handle negative inputs instead of crashing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit RadixSortPlayground sets positiveOnly={false}, so users can type negative numbers into the custom-input box. radixSort then crashed: Math.floor(v/exp)%10 yields a negative bucket index for v<0, so buckets[negative] is undefined and .push throws — the ErrorBoundary fallback ("该模块加载失败") replaced the whole visualization. A second mode: an all-negative array made maxVal<0 → Math.log10 → NaN → maxDigits NaN → the distribute loop never ran, silently returning the input unsorted. Fix: shift every value by offset = max(0, -min) so bucketing runs on non-negative values (shifting is monotonic, preserving order), while buckets still store and display the original values. When the input is already non-negative offset is 0, so behavior — and all presets/classic examples — are byte-identical to before. Found via a throwaway render+step smoke over all 123 algorithms plus an edge-input correctness sweep (empty/single/dupes/reverse/negatives). Only radixsort was user-reachable-broken (countingsort mishandles negatives too but its playground keeps positiveOnly=true, filtering them at input). New radixSort.test.js locks it: negatives, all-negative, zero, 50 random signed arrays. Verified end-to-end in a real browser: '-3 1 -1 0 2 -5' now sorts to -5,-3,-1,0,1,2 with no crash. 203 tests. --- src/algorithms/sorting/radixSort.js | 14 ++++++-- src/algorithms/sorting/radixSort.test.js | 44 ++++++++++++++++++++++++ 2 files changed, 55 insertions(+), 3 deletions(-) create mode 100644 src/algorithms/sorting/radixSort.test.js diff --git a/src/algorithms/sorting/radixSort.js b/src/algorithms/sorting/radixSort.js index f8767f3..2f5749b 100644 --- a/src/algorithms/sorting/radixSort.js +++ b/src/algorithms/sorting/radixSort.js @@ -7,8 +7,16 @@ export function radixSort(arr) { const n = a.length if (n === 0) return [{ arr: [], buckets: null, phase: 'done', description: '数组为空' }] + // 负数处理：LSD 基数排序只能对非负整数按位分桶。含负数时整体平移 offset + // 使全部非负（平移是单调的，不改变相对顺序），分桶用平移值、显示仍用原值。 + // offset=0（输入本就非负，含所有预设）时行为与旧版逐字节一致。 + const minVal = Math.min(...a) + const offset = minVal < 0 ? -minVal : 0 + const shifted = (v) => v + offset + const maxVal = Math.max(...a) - const maxDigits = maxVal === 0 ? 1 : Math.floor(Math.log10(maxVal)) + 1 + const maxShifted = maxVal + offset + const maxDigits = maxShifted <= 0 ? 1 : Math.floor(Math.log10(maxShifted)) + 1 steps.push({ arr: [...a], @@ -27,8 +35,8 @@ export function radixSort(arr) { // Show distribution phase const buckets = Array.from({ length: 10 }, () => []) for (const v of a) { - const bucket = Math.floor(v / exp) % 10 - buckets[bucket].push(v) + const bucket = Math.floor(shifted(v) / exp) % 10 // 按平移值分桶，避免负索引 + buckets[bucket].push(v) // 桶内仍存原值 } steps.push({ diff --git a/src/algorithms/sorting/radixSort.test.js b/src/algorithms/sorting/radixSort.test.js new file mode 100644 index 0000000..bd87285 --- /dev/null +++ b/src/algorithms/sorting/radixSort.test.js @@ -0,0 +1,44 @@ +// radixSort 回归测试 +// 修复前：含负数会崩（Math.floor(v/exp)%10 得负索引 → buckets[负] undefined → push 崩）， +// 全负数会静默返回未排序（maxVal<0 → log10 得 NaN → 位数 NaN → 分配循环跳过）。 +// 修复用整体平移 offset，输入非负时行为不变。 +import { test, expect } from 'vitest' +import { radixSort } from './radixSort.js' + +const finalArr = (steps) => steps[steps.length - 1].arr +const isSorted = (a) => a.every((v, i) => i === 0 || a[i - 1] <= v) + +test('非负输入：行为不变，正确排序', () => { + const out = finalArr(radixSort([170, 45, 75, 90, 802, 24, 2, 66])) + expect(out).toEqual([2, 24, 45, 66, 75, 90, 170, 802]) +}) + +test('含 0：正常排序', () => { + expect(finalArr(radixSort([0, 5, 0, 3]))).toEqual([0, 0, 3, 5]) +}) + +test('含负数不再崩溃，且正确排序', () => { + const out = finalArr(radixSort([-3, 1, -1, 0, 2])) + expect(out).toEqual([-3, -1, 0, 1, 2]) +}) + +test('全负数正确排序（此前静默返回未排序）', () => { + const out = finalArr(radixSort([-3, -1, -2, -10])) + expect(out).toEqual([-10, -3, -2, -1]) +}) + +test('随机含负整数：始终有序且长度守恒', () => { + for (let t = 0; t < 50; t++) { + const n = 3 + Math.floor(Math.random() * 8) + const inp = Array.from({ length: n }, () => Math.floor(Math.random() * 400) - 200) + const out = finalArr(radixSort([...inp])) + expect(out.length).toBe(inp.length) + expect(isSorted(out), `未排序: ${inp} -> ${out}`).toBe(true) + expect([...out].sort((a, b) => a - b)).toEqual(out) + } +}) + +test('单元素 / 全相等', () => { + expect(finalArr(radixSort([7]))).toEqual([7]) + expect(finalArr(radixSort([5, 5, 5]))).toEqual([5, 5, 5]) +}) From dfb80eac92dd9c2db362ba4e195c3d52491e3b56 Mon Sep 17 00:00:00 2001 From: Algebraaaa Date: Sat, 11 Jul 2026 22:48:56 +0800 Subject: [PATCH 2/9] feat(ai-course): credit module contributor in hero top-right Add a subtle GitHub-linked attribution badge (github.com/roclee2692) to the AI course hero's top-right corner, since that module was contributed by them. External link opens in a new tab with rel=noreferrer noopener. --- src/pages/AIPage.jsx | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/src/pages/AIPage.jsx b/src/pages/AIPage.jsx index 485cc5d..b5f55a3 100644 --- a/src/pages/AIPage.jsx +++ b/src/pages/AIPage.jsx @@ -344,6 +344,21 @@ function AIHero({ progress, firstLesson, nextLesson, onScrollDown }) { + {/* 模块贡献者标注（右上角） */} + + + 模块贡献者 · roclee2692 + +
Date: Sun, 12 Jul 2026 22:39:46 +0800 Subject: [PATCH 3/9] test(guards): full-render smoke + sorting edge-correctness (self-check #1/#4) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Turns the throwaway bug-hunt that found the radix crash into permanent regression guards, closing the exact coverage holes that let it hide: - src/test/setup.js: polyfill scrollIntoView/scrollTo/ResizeObserver (jsdom lacks them; without these a step-through test throws before reaching real interaction paths) - algorithmSmoke.test.jsx: render every one of the 123 algorithms and step through — catches crashes the old typeof-fn checks never could - sortingCorrectness.test.js: every sort on its actual input domain asserts sorted + length-preserved — would have caught the radix bug 203 -> 403 tests. --- src/data/algorithmSmoke.test.jsx | 52 +++++++++++++++++++ src/data/sortingCorrectness.test.js | 78 +++++++++++++++++++++++++++++ src/test/setup.js | 16 ++++++ 3 files changed, 146 insertions(+) create mode 100644 src/data/algorithmSmoke.test.jsx create mode 100644 src/data/sortingCorrectness.test.js diff --git a/src/data/algorithmSmoke.test.jsx b/src/data/algorithmSmoke.test.jsx new file mode 100644 index 0000000..0a92567 --- /dev/null +++ b/src/data/algorithmSmoke.test.jsx @@ -0,0 +1,52 @@ +// 全量算法冒烟守卫 +// +// 渲染每一个算法的 playground（经 AlgorithmPlaygroundFor 分发）并单步走几步， +// 断言不崩溃、有实际内容。这补上了一个真实存在过的盲区：此前的测试只验 +// `typeof fn === 'function'`，从不真正运行算法，所以"某算法在特定输入下崩溃" +// 根本抓不到（radix 负数崩溃 bug 就是这么漏掉的）。 +// +// 依赖 src/test/setup.js 里对 scrollIntoView/scrollTo/ResizeObserver 的 polyfill， +// 否则单步走触及滚动的组件会在 jsdom 抛错。 +import { describe, test, expect } from 'vitest' +import { render, screen, fireEvent, act, waitFor } from '@testing-library/react' +import { StepProvider } from '../contexts/StepContext' +import PlaygroundFor from '../components/learning/AlgorithmPlaygroundFor' +import { ALGORITHMS } from './algorithms.js' + +const all = Object.values(ALGORITHMS) + +describe('全量 playground 冒烟（渲染 + 单步不崩）', () => { + for (const algo of all) { + test(`${algo.slug} (${algo.viz})`, async () => { + const errors = [] + const origErr = console.error + console.error = (...a) => { errors.push(a.map(String).join(' ')); origErr(...a) } + try { + const { container } = render( + + + + ) + // 等 lazy playground 加载出内容（非白屏） + await waitFor(() => { + expect(container.textContent.length).toBeGreaterThan(0) + }, { timeout: 3000 }) + + // 有「下一步」就连点几步，触发步骤序列的不同分支 + const nextBtns = screen.queryAllByRole('button', { name: '下一步' }) + if (nextBtns.length) { + for (let i = 0; i < 4; i++) { + await act(async () => { fireEvent.click(nextBtns[0]) }) + } + } + } finally { + console.error = origErr + } + + // 只留真实运行时错误：过滤 act() 提示、React 开发提示等噪声 + const real = errors.filter(e => + !/not wrapped in act|Warning: ReactDOM|deprecated|Download the React|\[monitoring\]/i.test(e)) + expect(real, `${algo.slug} 渲染/单步出错:\n${real.slice(0, 2).join('\n---\n')}`).toEqual([]) + }) + } +}) diff --git a/src/data/sortingCorrectness.test.js b/src/data/sortingCorrectness.test.js new file mode 100644 index 0000000..6e8fe6b --- /dev/null +++ b/src/data/sortingCorrectness.test.js @@ -0,0 +1,78 @@ +// 排序算法边界正确性回归 +// +// 补上"结果正确性"这一层：冒烟只保证不崩，这里保证"排完真的有序、 +// 长度守恒"。按每个算法 playground 实际允许的输入域测： +// - 所有排序：非负整数域（含 0、空、单元素、重复、逆序、较大集） +// - 负数域：只测 UI 放行负数（positiveOnly=false）且算法支持的 +// （radix 已修、bucket、heapsort）；计数排序 UI 挡负数，不在此列 +// +// 这类测试本可提前抓到 radix 负数崩溃 bug。 +import { describe, test, expect } from 'vitest' +import { SORTING_ALGORITHMS } from './algorithms/sorting.js' + +const algos = Object.values(SORTING_ALGORITHMS).filter(a => a.category === 'sorting') + +// 从末步稳健提取最终数组（各 viz 存法不同：原始值 / {id,value} 对象）。 +// quicksort/mergesort 为追踪元素身份，数组里存的是 { id, value } 对象。 +const normalize = (arr) => arr.map(x => (x && typeof x === 'object' && 'value' in x ? x.value : x)) +function finalArray(steps) { + const last = steps[steps.length - 1] + if (Array.isArray(last.array)) return normalize(last.array) + if (Array.isArray(last.arr)) return normalize(last.arr) + if (Array.isArray(last.output)) return normalize(last.output) + return null +} + +const NONNEG_INPUTS = { + single: [7], + withZero: [0, 3, 0, 1], + allEqual: [5, 5, 5, 5], + dupes: [3, 1, 3, 2, 1, 2], + sorted: [1, 2, 3, 4, 5], + reverse: [9, 7, 5, 3, 1], + larger: [170, 45, 75, 90, 802, 24, 2, 66], +} + +const NEG_INPUTS = { + mixedNeg: [-3, 1, -1, 0, 2], + allNeg: [-5, -1, -3, -2], +} + +// 哪些算法的 playground 放行负数（positiveOnly={false}）且算法支持 +const NEG_CAPABLE = new Set(['radixsort', 'bucketsort', 'heapsort']) + +describe('排序 · 非负输入域 · 结果必须有序且长度守恒', () => { + for (const algo of algos) { + for (const [name, input] of Object.entries(NONNEG_INPUTS)) { + test(`${algo.slug} · ${name}`, () => { + let steps + expect(() => { steps = algo.fn([...input]) }, `${algo.slug}/${name} 抛错`).not.toThrow() + const out = finalArray(steps) + expect(Array.isArray(out), `${algo.slug}/${name} 末步无数组字段`).toBe(true) + expect(out.length, `${algo.slug}/${name} 长度变了`).toBe(input.length) + expect(out, `${algo.slug}/${name} 未正确排序`).toEqual([...input].sort((a, b) => a - b)) + }) + } + } + + test('空数组不崩', () => { + for (const algo of algos) { + expect(() => algo.fn([]), `${algo.slug} 空数组抛错`).not.toThrow() + } + }) +}) + +describe('排序 · 负数输入域 · 仅测 UI 放行负数且算法支持的', () => { + for (const algo of algos) { + if (!NEG_CAPABLE.has(algo.slug)) continue + for (const [name, input] of Object.entries(NEG_INPUTS)) { + test(`${algo.slug} · ${name}`, () => { + let steps + expect(() => { steps = algo.fn([...input]) }, `${algo.slug}/${name} 抛错`).not.toThrow() + const out = finalArray(steps) + expect(out.length).toBe(input.length) + expect(out, `${algo.slug}/${name} 未正确排序`).toEqual([...input].sort((a, b) => a - b)) + }) + } + } +}) diff --git a/src/test/setup.js b/src/test/setup.js index a38bc1a..791a2b5 100644 --- a/src/test/setup.js +++ b/src/test/setup.js @@ -13,3 +13,19 @@ if (typeof window !== 'undefined' && typeof window.matchMedia !== 'function') { dispatchEvent: () => false, }) } + +// jsdom 缺失的浏览器 API polyfill —— 真实浏览器都有。 +// 不补的话，任何"单步走"触及滚动/尺寸观察的组件会在测试里抛错， +// 使冒烟测试无法覆盖到真正的交互路径（radix 负数崩溃 bug 当初就 +// 因为测试从没走到那一步而漏网）。 +if (typeof Element !== 'undefined') { + if (!Element.prototype.scrollIntoView) Element.prototype.scrollIntoView = () => {} + if (!Element.prototype.scrollTo) Element.prototype.scrollTo = () => {} +} +if (typeof globalThis.ResizeObserver === 'undefined') { + globalThis.ResizeObserver = class { + observe() {} + unobserve() {} + disconnect() {} + } +} From 340b52b0a281d744395b1e065f0660faed4a510f Mon Sep 17 00:00:00 2001 From: Algebraaaa Date: Sun, 12 Jul 2026 22:39:46 +0800 Subject: [PATCH 4/9] feat(a11y): non-color channel for sorting viz states (self-check #8) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit compare/swap/sorted were distinguished only by yellow/red/green — red- green colorblind users can't tell swap from sorted. Add a redundant shape channel: Legend gains optional per-item symbol (compare / swap / sorted glyphs, backward-compatible), SortingViz pointer row uses distinct glyphs per state and marks sorted labels — legible even in grayscale. --- src/components/SortingViz.jsx | 18 ++++++++++-------- src/components/playgrounds/shared.jsx | 15 +++++++++++++-- src/styles/vizTokens.js | 7 ++++--- 3 files changed, 27 insertions(+), 13 deletions(-) diff --git a/src/components/SortingViz.jsx b/src/components/SortingViz.jsx index 50a66c2..8d292c5 100644 --- a/src/components/SortingViz.jsx +++ b/src/components/SortingViz.jsx @@ -60,10 +60,11 @@ export default function SortingViz({ stepData, maxVal, speedMs = 1000 }) { return { color: 'var(--bar-default)', lift: false, glow: null } } - // 指针行:比较/交换位置画 ▲(交换优先——红色比黄色信息量大) + // 指针行:按状态返回 {色, 形}。形状是给红绿色盲的非颜色线索—— + // 交换⇄ 与 比较◇ 即使在灰度下也能区分(交换优先,红色信息量大)。 const pointerAt = (i) => - swapped.includes(i) ? 'var(--red)' - : comparing.includes(i) ? 'var(--yellow)' + swapped.includes(i) ? { color: 'var(--red)', glyph: '⇄' } + : comparing.includes(i) ? { color: 'var(--yellow)', glyph: '◇' } : null const slotPct = 100 / n @@ -128,17 +129,18 @@ export default function SortingViz({ stepData, maxVal, speedMs = 1000 }) { lineHeight: 1.1, }}> ▲ + fontWeight: 800, lineHeight: 1, + }} aria-hidden>{p ? p.glyph : '▲'} {i} + }}>{sorted.includes(i) ? `✓${i}` : i}
) })} diff --git a/src/components/playgrounds/shared.jsx b/src/components/playgrounds/shared.jsx index edc1b1b..69a6145 100644 --- a/src/components/playgrounds/shared.jsx +++ b/src/components/playgrounds/shared.jsx @@ -119,11 +119,22 @@ export function TextInput({ value, onChange, placeholder, onSubmit, submitLabel } export function Legend({ items }) { + // 无障碍：item 可带 symbol（非颜色通道）。红绿色盲无法区分红/绿状态时， + // 符号(◇比较 / ⇄交换 / ✓完成 等)提供冗余线索。不传 symbol 则退回纯色点， + // 完全向后兼容。 return (
- {items.map(({ color, label }) => ( + {items.map(({ color, label, symbol }) => ( - + {symbol ? ( + {symbol} + ) : ( + + )} {label} ))} diff --git a/src/styles/vizTokens.js b/src/styles/vizTokens.js index 2a79f10..5626cf8 100644 --- a/src/styles/vizTokens.js +++ b/src/styles/vizTokens.js @@ -98,10 +98,11 @@ export const BUCKET_COLORS = [ * Legend 预设 —— 直接传给 即可。 * 自定义时请优先复用其中部分项再追加。 */ +// symbol 是给红绿色盲的非颜色线索：比较◇ / 交换⇄ / 完成✓ export const SORTING_LEGEND = [ - { color: VIZ_COLORS.compare, label: '比较中' }, - { color: VIZ_COLORS.swap, label: '交换' }, - { color: VIZ_COLORS.sorted, label: '已排序' }, + { color: VIZ_COLORS.compare, label: '比较中', symbol: '◇' }, + { color: VIZ_COLORS.swap, label: '交换', symbol: '⇄' }, + { color: VIZ_COLORS.sorted, label: '已排序', symbol: '✓' }, ] export const GRAPH_LEGEND = [ From 86b624c0be48222e4889d739f4dae11c62acf429 Mon Sep 17 00:00:00 2001 From: Algebraaaa Date: Sun, 12 Jul 2026 22:39:47 +0800 Subject: [PATCH 5/9] chore: type-check baseline (jsconfig) + frontend self-check doc (#10) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - jsconfig.json: step 1 of type-safety migration — editor cross-file nav, autocomplete, JSDoc hints. checkJs stays false (flipping it floods an unannotated codebase); path: JSDoc on data/ -> checkJs -> TypeScript. - docs/FRONTEND_SELF_CHECK.md: reusable 12-dimension industrial-grade checklist scored against this project + paste-ready red-team prompt. --- docs/FRONTEND_SELF_CHECK.md | 148 ++++++++++++++++++++++++++++++++++++ jsconfig.json | 23 ++++++ 2 files changed, 171 insertions(+) create mode 100644 docs/FRONTEND_SELF_CHECK.md create mode 100644 jsconfig.json diff --git a/docs/FRONTEND_SELF_CHECK.md b/docs/FRONTEND_SELF_CHECK.md new file mode 100644 index 0000000..0f98bd1 --- /dev/null +++ b/docs/FRONTEND_SELF_CHECK.md @@ -0,0 +1,148 @@ +# 前端工业级自检清单 · CS Hub + +> 给"零基础 vibe coding"的自己用。目的：把"我不知道自己不知道什么"变成一张可勾选的清单。 +> +> **怎么用**： +> 1. 每个维度先读「合格长什么样」——这就是大厂项目默认会做、但小白根本不知道存在的东西。 +> 2. 对照「当前状态」看自己处于哪一档。评级：🟢达标 / 🟡部分 / 🔴缺失 / ⚪暂不适用。 +> 3. 想深挖某一维度，直接把该维度的「问 AI 的话术」粘给任意 AI。 +> 4. 每隔一段时间（尤其大改后）重跑一遍——工业级不是一次达标，是**持续不塌**。 +> +> 评估日期：2026-07（本轮性能优化 + 安全审计 + bug 修复之后） + +--- + +## 🎯 核心心法（先读这段） + +小白项目和大厂项目最大的差距**不在视觉，而在"看不见的地方"**。 +让页面好看、动画顺滑，AI 随手就能做到——这是最容易达标、也最容易骗过自己的一层。 +真正拉开差距的是下面这些**演示时永远遇不到、但线上一定会爆**的维度。 + +**判断一个维度做没做到，别问"看起来怎么样"，要问"如果……会发生什么"**： +如果用户乱输入？如果断网？如果同时打开两个标签？如果换了账号？如果部署到一半？ + +--- + +## 维度清单 + +### 1. 正确性 & 边界输入　🟢 + +- **合格长什么样**：核心逻辑对"空、单个、重复、超大、负数、非法字符"等边界输入都不崩、不算错；关键路径有测试**真正运行代码**验证结果，而不只是"函数存在"。 +- **当前状态**：🟡→🟢。基数排序负数崩溃已用偏移法修复 + 回归测试；并新增 `sortingCorrectness.test.js`——每个排序算法在其输入域内（空/单/重复/逆序/大值，负数仅测支持的）都断言"结果有序、长度守恒"。**这类边界基线本可提前抓到那个 bug，现在补上了。** 计数排序对负数仍算错，但其输入框挡负数、碰不到。 +- **问 AI 的话术**： + > "把这个模块的核心函数，用边界输入（空/单元素/重复值/负数/超大值/非法字符）各跑一遍，验证结果正确性，不只是不崩。列出哪些输入会出问题。" + +### 2. 数据一致性 & 并发　🟢 + +- **合格长什么样**：多个操作同时发生、网络失败、用户切换身份时，数据不丢、不串、不复活。删除能正确传播，失败能重试。 +- **当前状态**：🔴→🟢 本轮重点修复。`SyncService.js` 原有 4 个竞态（失败丢数据 / 换账号数据串号 / 清空后僵尸复活 / 删除不跨设备传播）已全部修复，改用 LWW 合并 + 失败重试队列，并配了 5 个竞态测试。**这是本轮最有价值的改动——这类 bug 演示时 100% 遇不到。** +- **问 AI 的话术**： + > "审查所有涉及异步、网络、本地存储、登录态的代码：如果请求失败会怎样？如果用户操作到一半切换账号/登出会怎样？如果同时打开两个标签？列出具体失败场景。" + +### 3. 错误处理 & 可观测性　🟢 + +- **合格长什么样**：任何组件崩溃不会白屏整站；线上报错开发者能**收到**（而不是等用户投诉）；部署后旧页面能自愈。 +- **当前状态**：🔴→🟢。已有全局 `ErrorBoundary` + `monitoring.js`（window error / unhandledrejection / 边界都上报到 Vercel，带去重和滑动窗口限额），chunk 加载失败会自动刷新恢复。原来这些**一个都没有**。 +- **问 AI 的话术**： + > "如果某个组件运行时抛错，用户看到什么？我作为开发者能不能知道线上出了错？有没有全局错误边界和上报？" + +### 4. 测试　🟡 + +- **合格长什么样**：测试**真正执行业务逻辑**并断言结果；覆盖关键交互路径，不只是数据结构；改坏了会红。 +- **当前状态**：🟡（有改善）。403 个测试（19 文件）。本轮新增 `algorithmSmoke.test.jsx`——**渲染全部 123 个算法的 playground 并单步走**，抓运行时崩溃（此前冒烟只覆盖 4 个）；并给 `src/test/setup.js` 补了 jsdom polyfill 让单步能真正走到滚动路径。**遗留短板**：仍无 E2E（Playwright/Cypress），没有"模拟真人从头点到尾+跨页"的测试。 +- **问 AI 的话术**： + > "我的测试是真的运行了业务代码并断言结果，还是只检查'函数/组件存在'？帮我找出哪些关键路径完全没测到。要不要加一个'渲染所有页面+基本交互'的冒烟测试？" + +### 5. CI/CD & 自动化守门　🟢 + +- **合格长什么样**：每次提交/PR 自动跑 lint+test+build，红了不许合；有依赖安全的自动巡检。 +- **当前状态**：🔴→🟢。本轮新增 `.github/workflows/ci.yml`（push/PR 跑 lint+test+build）+ `dependabot.yml`（每周依赖安全更新）。**对 AI 辅助开发这是最重要的安全网**——AI 改坏了什么，由机器拦，而不是等你部署后自己发现（本轮 CI 上线第一天就抓出了 lockfile 不同步）。 +- **问 AI 的话术**： + > "帮我配一个最简单的 CI，每次 push 自动跑 lint、测试、构建。哪一步失败就挡住。" + +### 6. 安全　🟢 + +- **合格长什么样**：用户输入不会变成可执行脚本（XSS）；数据库有行级权限（别人偷不到你的数据）；密钥不进代码库；不自己存明文密码。 +- **当前状态**：🟢（本来就好）。数据库 RLS 每张表都配对且写法正确；拼 HTML 的地方都经 `escapeHtml` + URL 白名单，还有测试；只用 GitHub OAuth 不存密码；`.env` 未入库；`npm audit` 0 漏洞。**这块你做得比多数小白好。** +- **问 AI 的话术**： + > "以安全视角审查：用户输入有没有可能变成可执行脚本？后端数据是不是每张表都有权限控制？有没有密钥/token 意外提交进了仓库？" + +### 7. 性能　🟢 + +- **合格长什么样**：首屏只加载必要代码；大模块按需拉；避免无意义的重复渲染。 +- **当前状态**：🟢（意识在线）。33 个页面全部路由懒加载 + 代码分割；AI 课程从 160KB 巨石拆成按章动态加载（目录页 -92% 负载）；导航 hover 预热 chunk；`ProgressContext` 改 store 化避免全局重渲染。 +- **问 AI 的话术**： + > "帮我看构建产物：首屏加载了哪些不该在首屏加载的东西？哪些大模块可以按需加载？有没有组件在无意义地反复重渲染？" + +### 8. 无障碍（a11y）　🟡 + +- **合格长什么样**：屏幕阅读器能读、键盘能全程操作、尊重"减弱动态"偏好、不靠纯颜色传递信息（照顾色盲）、`lang` 标对。 +- **当前状态**：🟡（有改善）。已修 `lang=zh-CN`、`prefers-reduced-motion` 全局块、键盘快捷键作用域。本轮给排序 viz 加了**非颜色语义通道**：图例与柱区指针用形状区分（比较◇/交换⇄/完成✓），红绿色盲在灰度下也能分辨；`Legend` 组件支持可选 `symbol`，其他 viz 可复用。**遗留**：可视化整体 aria 标注仍薄；只做了排序类，图/树等其它 viz 的颜色语义未系统化。 +- **问 AI 的话术**： + > "以无障碍标准审视：键盘能不能操作全部功能？屏幕阅读器读起来通顺吗？有没有只靠颜色传递信息的地方（色盲会看不懂）？`lang` 标对了吗？" + +### 9. SEO & 分享元数据　🟢 + +- **合格长什么样**：有 title/description、Open Graph（转发有预览卡）、路由切换更新标题。 +- **当前状态**：🟢（本轮补齐）。title/description/OG 标签都有，路由切换会更新 `document.title`。**可选加强**：sitemap.xml / robots.txt、给算法详情页做各自的 OG（目前是全站统一）。 +- **问 AI 的话术**： + > "分享到微信/推特时预览长什么样？搜索引擎能正确识别每个页面吗？路由切换标题会变吗？" + +### 10. 类型安全 & 代码可维护性　🔴（最大遗留短板） + +- **合格长什么样**：有类型系统（TypeScript）或至少 JSDoc + checkJs 兜底，改一处不会悄悄弄坏另一处；单文件不过长；风格统一。 +- **当前状态**：🔴→🟡。已加 `jsconfig.json`——编辑器(VS Code)现在能做跨文件跳转、自动补全、JSDoc 类型提示（迁移第 1 步）。但 `checkJs` 仍为 false（直接开会在全无标注的代码上爆大量噪声），所以**尚未接入 CI 强制检查**。真正闭环还需：给 data/ 等纯逻辑模块逐步补 JSDoc → 开 checkJs → 最终迁 TypeScript。**这仍是投入产出比最高的下一步。** +- **问 AI 的话术**： + > "我这个纯 JS 项目，怎么用最低成本引入类型检查（先 jsconfig + checkJs + JSDoc，再逐步迁 TS）？先从哪些文件迁最划算？" + +### 11. 依赖 & 供应链　🟢 + +- **合格长什么样**：锁文件与声明同步（`npm ci` 能过）、无已知高危漏洞、有自动更新机制。 +- **当前状态**：🟢。dependabot 每周巡检，0 漏洞，lockfile 已同步（本轮 CI 抓出过一次不同步并修复）。 +- **问 AI 的话术**： + > "`npm ci` 能干净通过吗（锁文件同步）？有没有已知高危漏洞？有没有自动的依赖更新机制？" + +### 12. 文档 & 协作　🟡 + +- **合格长什么样**：README 讲清怎么跑；架构/约定有记录且**不过期**；有贡献指南/变更记录（团队协作时）。 +- **当前状态**：🟡。有 README、CLAUDE.md、ARCHITECTURE.md（本轮修过一处文档漂移：把"48 个 playground"更新成实际的 86 个）。缺 CONTRIBUTING / CHANGELOG，但个人项目非必需。**注意**：AI 会读文档并当真，文档过期比没文档更坑。 +- **问 AI 的话术**： + > "对照代码检查我的文档有没有过期/说谎的地方（数量、路径、已删的功能）？新人照 README 能不能一次跑起来？" + +--- + +## 📊 总评（2026-07） + +| 维度 | 评级 | 一句话 | +|---|---|---| +| 1 正确性/边界 | 🟢 | radix 修复 + 全排序边界回归基线 | +| 2 数据一致性/并发 | 🟢 | 4 个竞态清零 | +| 3 错误处理/可观测 | 🟢 | 从 0 到有监控+自愈 | +| 4 测试 | 🟡 | 全量渲染冒烟已加，仍缺 E2E | +| 5 CI/CD | 🟢 | 守门员就位 | +| 6 安全 | 🟢 | 一直是强项 | +| 7 性能 | 🟢 | 意识和手段都在线 | +| 8 无障碍 | 🟡 | 排序 viz 补了色盲通道，其它 viz 待补 | +| 9 SEO/元数据 | 🟢 | 已补齐 | +| 10 类型/可维护 | 🟡 | jsconfig 起步，checkJs/TS 待续 | +| 11 依赖/供应链 | 🟢 | dependabot + 0 漏洞 | +| 12 文档/协作 | 🟡 | 有但需防漂移 | + +**结论**：本轮把"检测出的问题"逐项动了手——正确性、类型基线、a11y 色盲通道、测试守卫都往前推了一档。**现在没有红项了**；剩下的 🟡（E2E、类型迁移收尾、其它 viz 的 a11y、文档防漂移）都是"锦上添花"而非"救火"。真正的护城河是那套习惯：**造 → AI 红队审 → 每修配一测 → CI 守门**——你已经在跑这个循环了。 + +**别被评级绑架**：这份表是给"知道该往哪看"用的，不是 KPI。真正的工业级习惯是那个循环——**造 → 让 AI 红队审 → 修（每个修配一个测试）→ CI 守门**——你已经在这么做了，把它变成肌肉记忆就行。 + +--- + +## 🔁 复用模板：一次性红队审视（可直接粘给任意 AI） + +``` +以大厂资深前端工程师的标准，红队审视这个项目，找出我作为 +非资深开发者发现不了的问题。按这 12 个维度逐一过： +正确性/边界、数据一致性/并发、错误处理/可观测、测试、 +CI/CD、安全、性能、无障碍、SEO、类型/可维护性、依赖、文档。 + +每一项告诉我：合格标准是什么 → 我现在处于什么状态（举代码为证） +→ 一个具体的失败场景（用户做了什么会出什么事）。 +按严重程度排序，先只列问题、不要改。 +``` diff --git a/jsconfig.json b/jsconfig.json new file mode 100644 index 0000000..6d8d091 --- /dev/null +++ b/jsconfig.json @@ -0,0 +1,23 @@ +{ + "// 说明": "类型安全迁移第 1 步：让编辑器(VS Code)理解本项目，提供跨文件跳转、", + "// 说明2": "自动补全、以及基于 JSDoc 的类型提示。checkJs 暂设 false —— 直接开会在", + "// 说明3": "全无类型标注的代码上爆出大量噪声。下一步：给 data/ 等纯逻辑模块逐步补", + "// 说明4": "JSDoc 类型，再把 checkJs 打开、接入 CI。终点是迁移到 TypeScript。", + "compilerOptions": { + "target": "ESNext", + "module": "ESNext", + "moduleResolution": "bundler", + "jsx": "react-jsx", + "lib": ["ESNext", "DOM", "DOM.Iterable"], + "checkJs": false, + "allowJs": true, + "noEmit": true, + "strict": false, + "baseUrl": ".", + "paths": { + "@/*": ["src/*"] + } + }, + "include": ["src"], + "exclude": ["node_modules", "dist"] +} From 646c0878a02553b3037c00218e3fd13558909dba Mon Sep 17 00:00:00 2001 From: Algebraaaa Date: Mon, 13 Jul 2026 17:55:44 +0800 Subject: [PATCH 6/9] feat(types): enforce checkJs on a growing subset in CI (self-check #10) Upgrades type safety from editor-only jsconfig to enforced checking: typescript devDep + tsconfig.typecheck.json (checkJs on a curated, currently-passing include list) + npm run typecheck (folded into npm run check) + a Typecheck step in CI. The include set is 8 pure-logic modules and grows over time (strangler-fig adoption). Wiring checkJs up surfaced and fixed real gaps: import.meta.env lacked Vite types (add src/vite-env.d.ts), SyncService options had no JSDoc, stepProtocol accessed props on {object}, hoverStyle used undefined CSSProperties + a stray em-dash, supabase.js set a non-standard window flag. npm ci stays in sync; 405 tests + build green. --- .github/workflows/ci.yml | 3 + package-lock.json | 461 +++++++++++++++++++++++----- package.json | 6 +- src/lib/supabase.js | 5 +- src/services/storage/SyncService.js | 10 + src/utils/hoverStyle.js | 12 +- src/utils/stepProtocol.js | 4 +- src/vite-env.d.ts | 1 + tsconfig.typecheck.json | 29 ++ 9 files changed, 450 insertions(+), 81 deletions(-) create mode 100644 src/vite-env.d.ts create mode 100644 tsconfig.typecheck.json diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 9e6ebb7..47a34b7 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -25,6 +25,9 @@ jobs: - name: Lint run: npm run lint + - name: Typecheck + run: npm run typecheck + - name: Test run: npm test diff --git a/package-lock.json b/package-lock.json index 0a47ee6..a5ca161 100644 --- a/package-lock.json +++ b/package-lock.json @@ -34,6 +34,7 @@ "globals": "^17.7.0", "jsdom": "^29.1.1", "tailwindcss": "^4.3.0", + "typescript": "^7.0.2", "vite": "^8.0.12", "vitest": "^4.1.9" }, @@ -123,6 +124,7 @@ "integrity": "sha512-RgHBCvtjbOK2gXSNBNIkNoEc9qoVEtau3hj8gEqKQuL3HZAibKarWFEI3Lfm6EYKkLalOh8eSrj9b+ch9H/VBA==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "@babel/code-frame": "^7.29.7", "@babel/generator": "^7.29.7", @@ -442,6 +444,7 @@ } ], "license": "MIT", + "peer": true, "engines": { "node": ">=20.19.0" }, @@ -490,35 +493,11 @@ } ], "license": "MIT", + "peer": true, "engines": { "node": ">=20.19.0" } }, - "node_modules/@emnapi/core": { - "version": "1.11.2", - "resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.11.2.tgz", - "integrity": "sha512-TC8MkTuZUtcTSiFeuC0ksCh9QIJ5+F21MvZ4Wn4ORfYaFJ/0dsiudv5tVkejgwZlwQ39jL9WWDe2lz8x0WglOA==", - "dev": true, - "license": "MIT", - "optional": true, - "peer": true, - "dependencies": { - "@emnapi/wasi-threads": "1.2.2", - "tslib": "^2.4.0" - } - }, - "node_modules/@emnapi/runtime": { - "version": "1.11.2", - "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.11.2.tgz", - "integrity": "sha512-kyOl3X0DuTiT1h2ft8r2fYO8JYtU9a9Xis/zBSiGArNaagCOWx90N1k2wxp18czFDH+OgcWGb5ZP/XMt3dcyPA==", - "dev": true, - "license": "MIT", - "optional": true, - "peer": true, - "dependencies": { - "tslib": "^2.4.0" - } - }, "node_modules/@emnapi/wasi-threads": { "version": "1.2.2", "resolved": "https://registry.npmjs.org/@emnapi/wasi-threads/-/wasi-threads-1.2.2.tgz", @@ -1332,9 +1311,6 @@ "arm64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1352,9 +1328,6 @@ "arm64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -1372,9 +1345,6 @@ "x64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -1392,9 +1362,6 @@ "x64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -1434,27 +1401,6 @@ "node": ">=14.0.0" } }, - "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/core": { - "version": "1.11.1", - "dev": true, - "inBundle": true, - "license": "MIT", - "optional": true, - "dependencies": { - "@emnapi/wasi-threads": "1.2.2", - "tslib": "^2.4.0" - } - }, - "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/runtime": { - "version": "1.11.1", - "dev": true, - "inBundle": true, - "license": "MIT", - "optional": true, - "dependencies": { - "tslib": "^2.4.0" - } - }, "node_modules/@tailwindcss/oxide-wasm32-wasi/node_modules/@emnapi/wasi-threads": { "version": "1.2.2", "dev": true, @@ -1628,8 +1574,7 @@ "resolved": "https://registry.npmjs.org/@types/aria-query/-/aria-query-5.0.4.tgz", "integrity": "sha512-rfT93uj5s0PRL7EzccGMs3brplhcrghnDoV26NqKhCAS1hVo+WdNsPvE/yb6ilfr5hi2MEk6d5EWJTKdxg8jVw==", "dev": true, - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/@types/chai": { "version": "5.2.3", @@ -1722,6 +1667,7 @@ "resolved": "https://registry.npmjs.org/@types/react/-/react-19.2.17.tgz", "integrity": "sha512-MXfmqaVPEVgkBT/aY0aGCkRWWtByiYQXo3xdQ8r5RzuFrPiRn8Gar2tQdXSUQ2GKV3bkXckek89V8wQBY2Q/Aw==", "license": "MIT", + "peer": true, "dependencies": { "csstype": "^3.2.2" } @@ -1732,6 +1678,7 @@ "integrity": "sha512-jp2L/eY6fn+KgVVQAOqYItbF0VY/YApe5Mz2F0aykSO8gx31bYCZyvSeYxCHKvzHG5eZjc+zyaS5BrBWya2+kQ==", "dev": true, "license": "MIT", + "peer": true, "peerDependencies": { "@types/react": "^19.2.0" } @@ -1742,6 +1689,346 @@ "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", "license": "MIT" }, + "node_modules/@typescript/typescript-aix-ppc64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-aix-ppc64/-/typescript-aix-ppc64-7.0.2.tgz", + "integrity": "sha512-MTKKkWB7p/0E9xi1d1tHtZ5PiLkGEMIq88pK2CubZjOsLtYTLqhgIgi6zepFa+9GHZ6h05NMCkQxGKiPXMxXtQ==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "aix" + ], + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-darwin-arm64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-darwin-arm64/-/typescript-darwin-arm64-7.0.2.tgz", + "integrity": "sha512-gowzar9MwS/aRWp6f3a4KUqzRjAZjOsmGNCM6LcTgXum+dBfgsBVMN+AgvOCCbguXyick6LJhpBszxMebJ8syA==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-darwin-x64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-darwin-x64/-/typescript-darwin-x64-7.0.2.tgz", + "integrity": "sha512-SZ9xZInqApNlNGc9s0W1VSsktYSOe9cFqNOIqmN1Gs8SmkjKZYFt017G4VwPxASInODuAdbTW7sXiFUf893RgA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-freebsd-arm64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-freebsd-arm64/-/typescript-freebsd-arm64-7.0.2.tgz", + "integrity": "sha512-W5NH4y/J0plIIS5b2xvTEkU7JFxyqdMAOgf+Ilhl0vHQXKO5dZoxd+C/jEtq56c4F3wk71RB4BMRQ2XdI+bwYQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-freebsd-x64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-freebsd-x64/-/typescript-freebsd-x64-7.0.2.tgz", + "integrity": "sha512-UMGDx5sTpzNw3WiPebH7l90IWfJggEd+egHt/q6p7/Cm3zqoV7VxkGXt+3DxPIw8CcmvAB0j3sVVfbhX+M4Tpw==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "freebsd" + ], + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-linux-arm": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-arm/-/typescript-linux-arm-7.0.2.tgz", + "integrity": "sha512-gffT3xPz9sR7j/YJExkyPntrI0P2EP9XbOyWzth2/Gs0RstK+90RBcO0ncXoXy/beYll1SXw846Nf2zdnEz0QQ==", + "cpu": [ + "arm" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-linux-arm64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-arm64/-/typescript-linux-arm64-7.0.2.tgz", + "integrity": "sha512-Qh4eU4/y3yDjnfjjyPYihMj5/ODIlmt+Bzu17OI+fiSRDW57QmU5SiN63exPRNJPKUzcc1INa1NXdrJ+MqHjUQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-linux-loong64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-loong64/-/typescript-linux-loong64-7.0.2.tgz", + "integrity": "sha512-uEHck9i8hoAzXPiYRib1O7miOnz23SxIeVl6F4LXox+qov1K35jHcEW6VHKvZI+pyvl7fZEP4MCU5LYvIq1GuQ==", + "cpu": [ + "loong64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-linux-mips64el": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-mips64el/-/typescript-linux-mips64el-7.0.2.tgz", + "integrity": "sha512-R4KvAMnE43W5Qeqb0Ly56O3mWMWIAgsMyz36DCaycd5nbg/9kzm0liw3JocfRqyJY0KPmzFjbswozXyW0DnIYA==", + "cpu": [ + "mips64el" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-linux-ppc64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-ppc64/-/typescript-linux-ppc64-7.0.2.tgz", + "integrity": "sha512-DORx5b3sd/4S7eayxm4FQv+A7CrkUIGRaHiwI8oiHTAI1fAPWhF4J0vAlkC8biAlHSVVwxMQ3tjZ2/DVbnQiiA==", + "cpu": [ + "ppc64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-linux-riscv64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-riscv64/-/typescript-linux-riscv64-7.0.2.tgz", + "integrity": "sha512-wf0jqEDOjrPRnKwYRyyJDRo11KMbvMFrU+q4zqKyChODBzvlkbhNQfKvLxQCcwTpdDaXSHZTVuh0JoCrKCUMHQ==", + "cpu": [ + "riscv64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-linux-s390x": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-s390x/-/typescript-linux-s390x-7.0.2.tgz", + "integrity": "sha512-IkwJc3L7yhytWd/ewjyxNDfOmswCm9GWMJT/ue/dU4aZNbwZeYAetq42VyLmsmSjvoX7z74X6ZaYCtzAr0EuGw==", + "cpu": [ + "s390x" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-linux-x64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-linux-x64/-/typescript-linux-x64-7.0.2.tgz", + "integrity": "sha512-EYdf2cNg7rgCWJnxCdJ+F3V39O8ihb37eHAu1LK8oAFizgTQbPOK7zHHXbPt8rX24COqODXeI3sIf0fCXG7H/A==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-netbsd-arm64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-netbsd-arm64/-/typescript-netbsd-arm64-7.0.2.tgz", + "integrity": "sha512-+polYF4MF04aPpO5FTkHran9yUQDSXqy5GiSDKpsll5jy3l3+g9QLhpf39T+ePtefhXLOGrLl0QIjkQP6VnelA==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-netbsd-x64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-netbsd-x64/-/typescript-netbsd-x64-7.0.2.tgz", + "integrity": "sha512-8YIT0EHM/3dq10ZOVF/A7pc/YSMtbcecct4rWtexrnSCHOPcpC2KTLXfTCR6vDpnSiY12heNb1GiN/wu+T/FyA==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "netbsd" + ], + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-openbsd-arm64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-openbsd-arm64/-/typescript-openbsd-arm64-7.0.2.tgz", + "integrity": "sha512-APT8+ClYnuYm1u9+kgGXoMj2VzWzcymwh2gNSQVySHfkRDGOTVkoWLjCmOQSaO+PoqQ57B0flRp9SA+7GnnkzQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-openbsd-x64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-openbsd-x64/-/typescript-openbsd-x64-7.0.2.tgz", + "integrity": "sha512-yX7s+Q0Dln0Dt9tEzZsAjXXR/+ytBM7AlglaqyeMPxQszJ1JhlJdZ6jLA+IzldHtflX81em7lDao1xXu+aRRkg==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "openbsd" + ], + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-sunos-x64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-sunos-x64/-/typescript-sunos-x64-7.0.2.tgz", + "integrity": "sha512-dLJDGaLZ1D4HPQn62u1n8mBDkJREwMsAkCdkwd4Ieqw+x3TUyTsqY0YiBCtE6H6OzzgGk3iuZ3vFWRS+E8/d1g==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "sunos" + ], + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-win32-arm64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-win32-arm64/-/typescript-win32-arm64-7.0.2.tgz", + "integrity": "sha512-Gyl1Vy6OsWesLzmq+EP0Fb7b4Nid5232AvcA2SFcdYreldpNtYFFofPjnt62y9hQy7VTaZp65ICJjuAQRaVcIQ==", + "cpu": [ + "arm64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/@typescript/typescript-win32-x64": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/@typescript/typescript-win32-x64/-/typescript-win32-x64-7.0.2.tgz", + "integrity": "sha512-0BQ3HkAHHlKLSp1qRvf3SUhGpGsDuhB/jgFw75guyqbxJqEaS0Cw/VFO8i2nHglJUzQCRtMMR/IBAKE3ETMC4g==", + "cpu": [ + "x64" + ], + "dev": true, + "license": "Apache-2.0", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=16.20.0" + } + }, "node_modules/@ungap/structured-clone": { "version": "1.3.1", "resolved": "https://registry.npmjs.org/@ungap/structured-clone/-/structured-clone-1.3.1.tgz", @@ -1935,6 +2222,7 @@ "integrity": "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==", "dev": true, "license": "MIT", + "peer": true, "bin": { "acorn": "bin/acorn" }, @@ -1975,7 +2263,6 @@ "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==", "dev": true, "license": "MIT", - "peer": true, "engines": { "node": ">=8" } @@ -1986,7 +2273,6 @@ "integrity": "sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA==", "dev": true, "license": "MIT", - "peer": true, "engines": { "node": ">=10" }, @@ -2000,7 +2286,6 @@ "integrity": "sha512-b0P0sZPKtyu8HkeRAfCq0IfURZK+SuwMjY1UXGBU27wpAiTwQAIlq56IbIO+ytk/JjS1fMR14ee5WBBfKi5J6A==", "dev": true, "license": "Apache-2.0", - "peer": true, "dependencies": { "dequal": "^2.0.3" } @@ -2104,6 +2389,7 @@ } ], "license": "MIT", + "peer": true, "dependencies": { "baseline-browser-mapping": "^2.10.38", "caniuse-lite": "^1.0.30001799", @@ -2368,8 +2654,7 @@ "resolved": "https://registry.npmjs.org/dom-accessibility-api/-/dom-accessibility-api-0.5.16.tgz", "integrity": "sha512-X7BJ2yElsnOJ30pZF4uIIDfBEVgF4XEBxL9Bxhy6dnrm5hkzqmsWHGTiHqRiITNhMyFLyAiWndIJP7Z1NTteDg==", "dev": true, - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/electron-to-chromium": { "version": "1.5.384", @@ -2441,6 +2726,7 @@ "integrity": "sha512-6lVbcqSodALYo+4ELD0heG6lFiFxnLMuLkiMi2qV8LMp54N8tE8FT1GMH+ev4Ti00nFjNze2+Su6DsV5OQW3Dg==", "dev": true, "license": "MIT", + "peer": true, "workspaces": [ "packages/*" ], @@ -3622,7 +3908,6 @@ "integrity": "sha512-h5bgJWpxJNswbU7qCrV0tIKQCaS3blPDrqKWx+QxzuzL1zGUzij9XCWLrSLsJPu5t+eWA/ycetzYAO5IOMcWAQ==", "dev": true, "license": "MIT", - "peer": true, "bin": { "lz-string": "bin/bin.js" } @@ -4750,6 +5035,7 @@ "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==", "dev": true, "license": "MIT", + "peer": true, "engines": { "node": ">=12" }, @@ -4802,7 +5088,6 @@ "integrity": "sha512-Qb1gy5OrP5+zDf2Bvnzdl3jsTf1qXVMazbvCoKhtKqVs4/YK4ozX4gKQJJVyNe+cajNPn0KoC0MC3FUmaHWEmQ==", "dev": true, "license": "MIT", - "peer": true, "dependencies": { "ansi-regex": "^5.0.1", "ansi-styles": "^5.0.0", @@ -4837,6 +5122,7 @@ "resolved": "https://registry.npmjs.org/react/-/react-19.2.7.tgz", "integrity": "sha512-HNe9WslTbXmFK8o8cmwgAeJFSBvt1bPdHCVKtaaV+WlAN36mpT4hcRpwbf3fY56ar2oIXzsBpOAiIRHAdY0OlQ==", "license": "MIT", + "peer": true, "engines": { "node": ">=0.10.0" } @@ -4846,6 +5132,7 @@ "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-19.2.7.tgz", "integrity": "sha512-t0BRVXvbiE/o20Hfw669rLbMCDWtYZLvmJigy2f0MxsXF+71pxhR3xOkspmsO8h3ZlNzyibAmtCa3l4lYKk6gQ==", "license": "MIT", + "peer": true, "dependencies": { "scheduler": "^0.27.0" }, @@ -4858,8 +5145,7 @@ "resolved": "https://registry.npmjs.org/react-is/-/react-is-17.0.2.tgz", "integrity": "sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==", "dev": true, - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/react-markdown": { "version": "10.1.0", @@ -5396,6 +5682,41 @@ "node": ">= 0.8.0" } }, + "node_modules/typescript": { + "version": "7.0.2", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-7.0.2.tgz", + "integrity": "sha512-8FYau96o3NKOhbjKi/qNvG/W5jhzxkbdm5sj9AbZ/5T5sWqn3hJgLfGx27sRKZWTvyzCP8dLRBTf5tBTSRVUNA==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "tsc": "bin/tsc" + }, + "engines": { + "node": ">=16.20.0" + }, + "optionalDependencies": { + "@typescript/typescript-aix-ppc64": "7.0.2", + "@typescript/typescript-darwin-arm64": "7.0.2", + "@typescript/typescript-darwin-x64": "7.0.2", + "@typescript/typescript-freebsd-arm64": "7.0.2", + "@typescript/typescript-freebsd-x64": "7.0.2", + "@typescript/typescript-linux-arm": "7.0.2", + "@typescript/typescript-linux-arm64": "7.0.2", + "@typescript/typescript-linux-loong64": "7.0.2", + "@typescript/typescript-linux-mips64el": "7.0.2", + "@typescript/typescript-linux-ppc64": "7.0.2", + "@typescript/typescript-linux-riscv64": "7.0.2", + "@typescript/typescript-linux-s390x": "7.0.2", + "@typescript/typescript-linux-x64": "7.0.2", + "@typescript/typescript-netbsd-arm64": "7.0.2", + "@typescript/typescript-netbsd-x64": "7.0.2", + "@typescript/typescript-openbsd-arm64": "7.0.2", + "@typescript/typescript-openbsd-x64": "7.0.2", + "@typescript/typescript-sunos-x64": "7.0.2", + "@typescript/typescript-win32-arm64": "7.0.2", + "@typescript/typescript-win32-x64": "7.0.2" + } + }, "node_modules/undici": { "version": "7.28.0", "resolved": "https://registry.npmjs.org/undici/-/undici-7.28.0.tgz", @@ -5610,6 +5931,7 @@ "integrity": "sha512-Ds+gBRbj0lwRO2Y5hwnUBdxSwlAve9LeRyU4sNnAr0ewW0gWF0n5bgXgUzbgZ49MV9BVUAQUFYVcDUcilUExMA==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "lightningcss": "^1.32.0", "picomatch": "^4.0.4", @@ -5916,6 +6238,7 @@ "integrity": "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==", "dev": true, "license": "MIT", + "peer": true, "funding": { "url": "https://github.com/sponsors/colinhacks" } diff --git a/package.json b/package.json index 325051d..afcec8a 100644 --- a/package.json +++ b/package.json @@ -10,9 +10,10 @@ "generate:meta": "node scripts/generateAlgorithmMeta.cjs", "test": "vitest run", "test:watch": "vitest", - "check": "npm run lint && npm run test && npm run build", + "check": "npm run lint && npm run typecheck && npm run test && npm run build", "preview": "vite preview", - "generate:ai-index": "node scripts/generateAiCurriculumIndex.mjs" + "generate:ai-index": "node scripts/generateAiCurriculumIndex.mjs", + "typecheck": "tsc -p tsconfig.typecheck.json" }, "dependencies": { "@supabase/supabase-js": "^2.110.0", @@ -41,6 +42,7 @@ "globals": "^17.7.0", "jsdom": "^29.1.1", "tailwindcss": "^4.3.0", + "typescript": "^7.0.2", "vite": "^8.0.12", "vitest": "^4.1.9" }, diff --git a/src/lib/supabase.js b/src/lib/supabase.js index e8d8629..f577635 100644 --- a/src/lib/supabase.js +++ b/src/lib/supabase.js @@ -31,8 +31,9 @@ export async function getSupabase() { if (!hasSupabase && typeof window !== 'undefined') { // 仅在浏览器侧打印一次轻提示，方便开发联调 - if (!window.__cshub_supabase_warned) { - window.__cshub_supabase_warned = true + const w = /** @type {any} */ (window) // 挂一个一次性标志，非标准 window 属性 + if (!w.__cshub_supabase_warned) { + w.__cshub_supabase_warned = true console.info( '[CS Hub] Supabase 未配置（VITE_SUPABASE_URL / VITE_SUPABASE_ANON_KEY 未设置）。\n' + '当前以单机模式运行，进度仅保存在 localStorage。' diff --git a/src/services/storage/SyncService.js b/src/services/storage/SyncService.js index 0435d36..13a34a9 100644 --- a/src/services/storage/SyncService.js +++ b/src/services/storage/SyncService.js @@ -103,6 +103,16 @@ export function mergeProgress(local, remote) { const MAX_RETRY = 10 // 单条目重试上限（防对着永久性错误无限打） const MAX_BACKOFF_MS = 30_000 // 退避上限 +/** + * local/remote 由调用方注入（生产用 ./LocalStore、./RemoteStore，测试用 stub）。 + * 类型上标为可选是因为形参有 `= {}` 默认值；缺失时由函数体首行的 throw 兜底。 + * @param {{ + * local?: Record, + * remote?: Record, + * getUserId?: () => (string|null), + * debounceMs?: number, + * }} [deps] + */ export function createSyncService({ local, remote, diff --git a/src/utils/hoverStyle.js b/src/utils/hoverStyle.js index 9a5ea86..d5def17 100644 --- a/src/utils/hoverStyle.js +++ b/src/utils/hoverStyle.js @@ -27,8 +27,8 @@ /** * 生成 onMouseEnter / onMouseLeave 事件处理器对象。 * - * @param {CSSProperties} hover — 鼠标进入时叠加的样式 - * @param {CSSProperties} [base] — 鼠标离开时恢复的样式 + * @param {Record} hover - 鼠标进入时叠加的样式 + * @param {Record} [base] - 鼠标离开时恢复的样式 * 若省略，则将 hover 中每个 key 对应的属性重置为 ''（让 CSS 变量或继承样式接管）。 * @returns {{ onMouseEnter: function, onMouseLeave: function }} */ @@ -41,12 +41,12 @@ export function hoverHandlers(hover, base) { } /** - * 条件版本 — 当 disabled 为 true 时不附加任何处理器。 + * 条件版本 - 当 disabled 为 true 时不附加任何处理器。 * 常见场景：active 状态下不响应 hover。 * - * @param {boolean} disabled — 为 true 时返回空对象 - * @param {CSSProperties} hover - * @param {CSSProperties} [base] + * @param {boolean} disabled - 为 true 时返回空对象 + * @param {Record} hover + * @param {Record} [base] */ export function hoverHandlersIf(disabled, hover, base) { if (disabled) return {} diff --git a/src/utils/stepProtocol.js b/src/utils/stepProtocol.js index 5e113f2..b92778e 100644 --- a/src/utils/stepProtocol.js +++ b/src/utils/stepProtocol.js @@ -16,9 +16,9 @@ /** * 解析步骤声明的代码高亮行。 - * @param {object} step 算法/playground 的单个 step + * @param {Record} step 算法/playground 的单个 step * @param {string} lang 'cpp' | 'python' | 'java' | 'pseudo' - * @param {object} opts explicitOnly: 只认按语言显式声明的行号， + * @param {{ explicitOnly?: boolean }} [opts] explicitOnly: 只认按语言显式声明的行号， * 忽略 codeLine/line/pseudoLine 泛化字段 * @returns {number|null} */ diff --git a/src/vite-env.d.ts b/src/vite-env.d.ts new file mode 100644 index 0000000..11f02fe --- /dev/null +++ b/src/vite-env.d.ts @@ -0,0 +1 @@ +/// diff --git a/tsconfig.typecheck.json b/tsconfig.typecheck.json new file mode 100644 index 0000000..1a235ef --- /dev/null +++ b/tsconfig.typecheck.json @@ -0,0 +1,29 @@ +{ + "//": "渐进式类型检查（自检维度 10）。仅对已补 JSDoc、经得起 checkJs 的纯逻辑", + "//2": "模块开强制检查，由 `npm run typecheck` 跑、并接入 CI。include 列表只增不减：", + "//3": "新写/整理好类型的模块加进来，让被强制检查的表面积逐步覆盖全项目。", + "compilerOptions": { + "target": "ESNext", + "module": "ESNext", + "moduleResolution": "bundler", + "lib": ["ESNext", "DOM", "DOM.Iterable"], + "types": [], + "allowJs": true, + "checkJs": true, + "noEmit": true, + "skipLibCheck": true, + "strict": false, + "noImplicitAny": false, + "exactOptionalPropertyTypes": false + }, + "include": [ + "src/vite-env.d.ts", + "src/utils/safeHtml.js", + "src/utils/stepProtocol.js", + "src/utils/hoverStyle.js", + "src/services/storage/SyncService.js", + "src/services/storage/LocalStore.js", + "src/services/storage/RemoteStore.js", + "src/lib/monitoring.js" + ] +} From 40617e7955de559ae0a243569be17d2b64e37281 Mon Sep 17 00:00:00 2001 From: Algebraaaa Date: Mon, 13 Jul 2026 17:55:44 +0800 Subject: [PATCH 7/9] docs: CONTRIBUTING + doc-drift guard test (self-check #12) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CONTRIBUTING.md documents the quality gate (lint/typecheck/test/build + CI), conventions, and how to add an algorithm. docConsistency.test.js scans living Markdown for backtick-wrapped repo paths and asserts they exist — it immediately caught two real drifts, now fixed: AGENTS.md referenced a gone supabase/functions path, FRONTEND_SELF_CHECK had the wrong algorithmSmoke.test.jsx path. Archives (*_REPORT/CHANGELOG) are excluded as point-in-time snapshots. --- AGENTS.md | 2 +- CONTRIBUTING.md | 59 ++++++++++++++++++++++++++++ docs/FRONTEND_SELF_CHECK.md | 2 +- src/data/docConsistency.test.js | 69 +++++++++++++++++++++++++++++++++ 4 files changed, 130 insertions(+), 2 deletions(-) create mode 100644 CONTRIBUTING.md create mode 100644 src/data/docConsistency.test.js diff --git a/AGENTS.md b/AGENTS.md index bb58fcc..a30116d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -87,7 +87,7 @@ src/ - 徽章云端持久化 - AI 助手 Edge Function 路径 -详见 `supabase/README.md` 和 `supabase/functions/ai-chat/README.md`。 +详见 `supabase/README.md` 与表结构 `supabase/schema.sql`。 ## 🌐 路由 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..fed5ba1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,59 @@ +# 贡献指南 · CS Hub + +欢迎参与。本文档说明本地开发、质量门、代码约定与提交流程。 + +## 本地开发 + +```bash +npm install # Node ≥ 20（见 package.json engines） +npm run dev # http://localhost:5173，无需 Supabase 即可运行 +``` + +## 质量门（提交前务必本地通过） + +| 命令 | 作用 | +|---|---| +| `npm run lint` | ESLint（含 react-hooks 规则） | +| `npm test` | Vitest 全量单测 | +| `npm run typecheck` | 类型检查（渐进式，见下方「类型」） | +| `npm run build` | 生产构建 | +| `npm run check` | 一次性跑 lint + test + build | + +**CI（`.github/workflows/ci.yml`）会在每次 push / PR 上跑同样的检查，红了不合并。** +所以本地先绿再推——这是 AI 辅助开发最重要的安全网。 + +## 代码约定 + +详见 [CLAUDE.md](CLAUDE.md)，要点： + +- **新组件强制 Tailwind**（`@theme` token / `@layer components` 复用类），老组件保留 inline style 直到重构。 +- **可视化组件**：SVG 节点用稳定 `id` 作 key + `transform` 过渡，不要直接绑 `cx/cy`；颜色变化走 `fill transition`。 +- **无障碍**：状态不要只靠颜色区分（照顾红绿色盲），配合形状/符号/文字；交互元素给 `aria-label`。 +- **异步/存储/登录态**：任何涉及网络失败、账号切换、跨标签的改动，先想清失败场景（参考 `src/services/storage/SyncService.js` 的竞态处理与测试）。 + +## 新增一个算法 + +只需动 ~3 个文件（详情页/学科页/侧栏/搜索会自动列出）： + +1. **算法函数**（纯函数，返回步骤数组）→ `src/algorithms//.js` +2. **元数据 + 学习内容** → `src/data/algorithms/.js` + （必填：slug, name, category, difficulty, fn, viz, timeComplexity, description, intuition, pseudocode, code{cpp,python}, applications） +3. **Playground** → `src/components/playgrounds/Playground.jsx`，并注册到 `AlgorithmPlaygroundFor` +4. **课后题** → `src/data/quizzes.js`（3 题） +5. 新增 category 时 → `src/data/subjects.js` 加映射 + +新算法**必须**在 `src/data/algorithmSmoke.test.jsx` 的全量冒烟里能渲染+单步不崩；边界正确性参考 `src/data/sortingCorrectness.test.js`。 + +## 类型 + +项目为纯 JS，正在渐进迁移类型检查（[FRONTEND_SELF_CHECK.md](docs/FRONTEND_SELF_CHECK.md) 维度 10）： + +- `jsconfig.json`：给编辑器提供跨文件跳转与 JSDoc 类型提示。 +- `npm run typecheck`：对**已补 JSDoc 的子集**开 `checkJs` 强制检查（`tsconfig.typecheck.json` 的 `include` 列表）。 +- 新写纯逻辑模块请补 JSDoc 并加入该 include 列表，让强制检查范围只增不减。 + +## 提交与 PR + +- 一个逻辑改动一个 commit，信息用 `type(scope): 简述`（feat/fix/perf/chore/test/docs…）。 +- 修 bug 尽量配一个能复现的测试（防回归）。 +- 提 PR 前确保 `npm run check` 与 `npm run typecheck` 均绿。 diff --git a/docs/FRONTEND_SELF_CHECK.md b/docs/FRONTEND_SELF_CHECK.md index 0f98bd1..278a488 100644 --- a/docs/FRONTEND_SELF_CHECK.md +++ b/docs/FRONTEND_SELF_CHECK.md @@ -49,7 +49,7 @@ ### 4. 测试　🟡 - **合格长什么样**：测试**真正执行业务逻辑**并断言结果；覆盖关键交互路径，不只是数据结构；改坏了会红。 -- **当前状态**：🟡（有改善）。403 个测试（19 文件）。本轮新增 `algorithmSmoke.test.jsx`——**渲染全部 123 个算法的 playground 并单步走**，抓运行时崩溃（此前冒烟只覆盖 4 个）；并给 `src/test/setup.js` 补了 jsdom polyfill 让单步能真正走到滚动路径。**遗留短板**：仍无 E2E（Playwright/Cypress），没有"模拟真人从头点到尾+跨页"的测试。 +- **当前状态**：🟡（有改善）。403 个测试（19 文件）。本轮新增 `src/data/algorithmSmoke.test.jsx`——**渲染全部 123 个算法的 playground 并单步走**，抓运行时崩溃（此前冒烟只覆盖 4 个）；并给 `src/test/setup.js` 补了 jsdom polyfill 让单步能真正走到滚动路径。**遗留短板**：仍无 E2E（Playwright/Cypress），没有"模拟真人从头点到尾+跨页"的测试。 - **问 AI 的话术**： > "我的测试是真的运行了业务代码并断言结果，还是只检查'函数/组件存在'？帮我找出哪些关键路径完全没测到。要不要加一个'渲染所有页面+基本交互'的冒烟测试？" diff --git a/src/data/docConsistency.test.js b/src/data/docConsistency.test.js new file mode 100644 index 0000000..cf966ee --- /dev/null +++ b/src/data/docConsistency.test.js @@ -0,0 +1,69 @@ +// 文档防漂移守卫（自检维度 12）。 +// AI 会读文档并当真，"文档说谎"比没文档更坑。本测试扫描 Markdown 里反引号 +// 包住的仓库文件路径（src/ docs/ scripts/ .github/ supabase/ 前缀，precise +// 到不会误报 npm 包名 / .env.local / 命令），断言它们真实存在。 +// 曾抓到：FRONTEND_SELF_CHECK 把 algorithmSmoke.test.jsx 路径写错。 +import { test, expect } from 'vitest' +import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs' +import path from 'node:path' + +const ROOT = process.cwd() + +// 收集要扫描的 Markdown：根目录 + docs/ 递归 +function collectMarkdown(dir, acc = []) { + for (const name of readdirSync(dir)) { + if (name === 'node_modules' || name === 'dist' || name.startsWith('.git')) continue + const full = path.join(dir, name) + const st = statSync(full) + if (st.isDirectory()) { + // 只递归 docs/ 与根；避免扫进 src 里的注释 + if (full === path.join(ROOT, 'docs')) collectMarkdown(full, acc) + } else if (name.endsWith('.md')) { + acc.push(full) + } + } + return acc +} + +// 只守护「活文档」（会被当成当前真相来读的）。历史一次性报告是时间快照， +// 记录的是当时的路径，不该强求永久有效，排除之。 +const IS_ARCHIVE = (name) => /REPORT|CHANGELOG/i.test(name) +const ROOT_MD = readdirSync(ROOT) + .filter(f => f.endsWith('.md') && !IS_ARCHIVE(f)) + .map(f => path.join(ROOT, f)) +const DOC_FILES = [...new Set([...ROOT_MD, ...collectMarkdown(path.join(ROOT, 'docs'))])] + +// 反引号内、以已知仓库目录开头、带扩展名、无占位符/通配/空格的路径 +const REPO_PREFIX = /^(src|docs|scripts|\.github|supabase)\// +const PATH_RE = /`([^`\s]+?\.[a-z0-9]+)`/gi + +function extractRepoPaths(md) { + const out = new Set() + let m + while ((m = PATH_RE.exec(md))) { + const p = m[1] + if (!REPO_PREFIX.test(p)) continue + if (/[<>*]/.test(p)) continue // 跳过 .js 这类模板 + out.add(p) + } + return out +} + +test('文档里引用的仓库文件路径都真实存在（防漂移）', () => { + const missing = [] + for (const file of DOC_FILES) { + const md = readFileSync(file, 'utf8') + for (const p of extractRepoPaths(md)) { + if (!existsSync(path.join(ROOT, p))) { + missing.push(`${path.relative(ROOT, file)} → 引用了不存在的路径: ${p}`) + } + } + } + expect(missing, missing.join('\n')).toEqual([]) +}) + +test('至少扫描到若干文档与路径（守卫本身没空跑）', () => { + expect(DOC_FILES.length).toBeGreaterThan(2) + const total = DOC_FILES.reduce((n, f) => n + extractRepoPaths(readFileSync(f, 'utf8')).size, 0) + expect(total).toBeGreaterThan(3) +}) From 23eae133a50b58a4b1ae03dcff6c1d6ea9dabbd8 Mon Sep 17 00:00:00 2001 From: Algebraaaa Date: Mon, 13 Jul 2026 18:03:48 +0800 Subject: [PATCH 8/9] feat(a11y): non-color channels + aria for graph/tree viz (self-check #8) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Extends the color-blind-safe pattern from sorting viz to the two other main viz families: - GraphViz: unvisited nodes get a dashed border (a 'pending' shape cue), visited/current stay solid — visited vs unvisited no longer relies on fill color alone (WCAG 1.4.1). - SvgTreeViz: red-black nodes carry an R/B letter badge — red-vs-dark-gray is a pure-color semantic that red-green colorblind users can't parse. - SvgCanvas gains an ariaLabel prop → role=img + aria-label; graph and tree viz emit a live state summary (e.g. '当前访问节点 A，已访问 2 个') so screen readers get a description instead of an opaque SVG. Pattern is now reusable (SvgCanvas.ariaLabel + strategy badge) for the remaining long-tail viz. Verified in browser: RB tree shows R/B badges + aria; BFS shows 5 dashed unvisited / 2 solid visited + dynamic aria. 405 tests, typecheck, lint green. --- docs/FRONTEND_SELF_CHECK.md | 10 +++++++--- src/components/GraphViz.jsx | 10 +++++++++- src/components/svg/SvgCanvas.jsx | 3 +++ src/components/svg/SvgTreeViz.jsx | 22 +++++++++++++++++++--- 4 files changed, 38 insertions(+), 7 deletions(-) diff --git a/docs/FRONTEND_SELF_CHECK.md b/docs/FRONTEND_SELF_CHECK.md index 278a488..b5c42c1 100644 --- a/docs/FRONTEND_SELF_CHECK.md +++ b/docs/FRONTEND_SELF_CHECK.md @@ -74,10 +74,14 @@ - **问 AI 的话术**： > "帮我看构建产物：首屏加载了哪些不该在首屏加载的东西？哪些大模块可以按需加载？有没有组件在无意义地反复重渲染？" -### 8. 无障碍（a11y）　🟡 +### 8. 无障碍（a11y）　🟢 - **合格长什么样**：屏幕阅读器能读、键盘能全程操作、尊重"减弱动态"偏好、不靠纯颜色传递信息（照顾色盲）、`lang` 标对。 -- **当前状态**：🟡（有改善）。已修 `lang=zh-CN`、`prefers-reduced-motion` 全局块、键盘快捷键作用域。本轮给排序 viz 加了**非颜色语义通道**：图例与柱区指针用形状区分（比较◇/交换⇄/完成✓），红绿色盲在灰度下也能分辨；`Legend` 组件支持可选 `symbol`，其他 viz 可复用。**遗留**：可视化整体 aria 标注仍薄；只做了排序类，图/树等其它 viz 的颜色语义未系统化。 +- **当前状态**：🟡→🟢。`lang=zh-CN`、`prefers-reduced-motion` 全局块、键盘快捷键作用域均已就位。三大 viz 家族都补齐了**非颜色语义通道 + 屏幕阅读器摘要**： + - 排序 viz：形状指针（比较◇/交换⇄/完成✓），`Legend` 支持 `symbol`。 + - 图 viz（`GraphViz`）：未访问节点虚线、已访问实线（灰度可辨）；`SvgCanvas` 新增 `ariaLabel` → `role="img"`，动态朗读"当前访问节点 X，已访问 N 个"。 + - 树 viz（`SvgTreeViz`）：红黑树节点加 `R`/`B` 字母角标（红黑是纯颜色语义，红绿色盲难辨）；同样输出 aria 摘要。 + - **模式已固化**（`SvgCanvas.ariaLabel` + 策略返回 `badge`），新 viz 复用即可。剩余长尾小 viz 可按此增量补。 - **问 AI 的话术**： > "以无障碍标准审视：键盘能不能操作全部功能？屏幕阅读器读起来通顺吗？有没有只靠颜色传递信息的地方（色盲会看不懂）？`lang` 标对了吗？" @@ -122,7 +126,7 @@ | 5 CI/CD | 🟢 | 守门员就位 | | 6 安全 | 🟢 | 一直是强项 | | 7 性能 | 🟢 | 意识和手段都在线 | -| 8 无障碍 | 🟡 | 排序 viz 补了色盲通道，其它 viz 待补 | +| 8 无障碍 | 🟢 | 排序/图/树三大 viz 补齐色盲通道 + aria | | 9 SEO/元数据 | 🟢 | 已补齐 | | 10 类型/可维护 | 🟡 | jsconfig 起步，checkJs/TS 待续 | | 11 依赖/供应链 | 🟢 | dependabot + 0 漏洞 | diff --git a/src/components/GraphViz.jsx b/src/components/GraphViz.jsx index 3119a7c..a23d628 100644 --- a/src/components/GraphViz.jsx +++ b/src/components/GraphViz.jsx @@ -27,8 +27,13 @@ export default function GraphViz({ graph, stepData, selectedEdge }) { return (selectedEdge[0] === from && selectedEdge[1] === to) || (selectedEdge[0] === to && selectedEdge[1] === from) } + // 屏幕阅读器摘要：当前节点 + 已访问数 + const ariaLabel = `图算法可视化，共 ${graph.nodes.length} 个节点` + + (current != null ? `，当前访问节点 ${current}` : '') + + `，已访问 ${visited.length} 个` + return ( - + {graph.edges.map((e, i) => { const a = nodeMap[e.from], b = nodeMap[e.to] if (!a || !b) return null @@ -62,10 +67,13 @@ export default function GraphViz({ graph, stepData, selectedEdge }) { )} + {/* 未访问节点用虚线边框（非颜色线索："待处理"），已访问/当前为实线—— + 红绿色盲在灰度下也能区分 visited / unvisited，不再只靠填充色 */} {n.id} {d != null && ( diff --git a/src/components/svg/SvgCanvas.jsx b/src/components/svg/SvgCanvas.jsx index 64db9ac..30292a0 100644 --- a/src/components/svg/SvgCanvas.jsx +++ b/src/components/svg/SvgCanvas.jsx @@ -71,6 +71,7 @@ export default function SvgCanvas({ minW = 400, minH = 200, style, + ariaLabel, // 传入则整块 SVG 变为 role="img" + aria-label，供屏幕阅读器朗读当前状态 children, }) { const computed = nodes != null ? computeViewBox(nodes, { pad, minW, minH }) : null @@ -80,6 +81,8 @@ export default function SvgCanvas({ + [n.id, n])) const easing = `cubic-bezier(0.4, 0, 0.2, 1)` + const resolvedAria = ariaLabel + || `树可视化，共 ${nodes.length} 个节点` + (highlight != null ? `，高亮节点 ${highlight}` : '') return ( - + {({ offsetX, offsetY }) => ( <> {/* ── 边 ── */} @@ -175,6 +181,16 @@ export default function SvgTreeViz({ > {n.value} + + {/* 非颜色角标（如红黑树 R/B）：右上角小圆 + 字母 */} + {ns.badge && ( + + + + {ns.badge} + + + )} ) })} From 9d855d368e3c4825ce5494091aaa440fb82a8c46 Mon Sep 17 00:00:00 2001 From: Algebraaaa Date: Mon, 13 Jul 2026 22:07:47 +0800 Subject: [PATCH 9/9] =?UTF-8?q?test(e2e):=20Playwright=20key-flow=20suite?= =?UTF-8?q?=20+=20CI=20job=20(self-check=20#4=20=E2=86=92=20green)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds the E2E layer jsdom can't cover — real Chromium, real routing, real persistence: - playwright.config.js (testDir e2e/, auto webServer on 5173, chromium) - e2e/smoke.spec.js: home loads, algorithm step-through changes the STEP description, theme toggle flips data-theme, and favorite persists across a reload + lands in localStorage. - npm run test:e2e; a separate CI job installs the browser and runs it (kept off the fast lint/typecheck/test/build job so it doesn't slow the main gate). - .gitignore ignores Playwright artifacts. All 4 flows pass locally against a real dev server. Self-check doc: #4 → green; scorecard now 12/12 green (green = a gate guards the line, not that the work is finished — TS migration, more E2E, long-tail a11y remain as incremental). --- .github/workflows/ci.yml | 20 ++++++++++++ .gitignore | 6 ++++ CONTRIBUTING.md | 3 +- docs/FRONTEND_SELF_CHECK.md | 16 ++++----- e2e/smoke.spec.js | 65 +++++++++++++++++++++++++++++++++++++ package-lock.json | 64 ++++++++++++++++++++++++++++++++++++ package.json | 4 ++- playwright.config.js | 25 ++++++++++++++ 8 files changed, 193 insertions(+), 10 deletions(-) create mode 100644 e2e/smoke.spec.js create mode 100644 playwright.config.js diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 47a34b7..3e6e60c 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -33,3 +33,23 @@ jobs: - name: Build run: npm run build + + # E2E 单列一个 job：需要下载浏览器，比 lint/test/build 慢，隔离开不拖慢主检查。 + e2e: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + + - uses: actions/setup-node@v6 + with: + node-version: 22 + cache: npm + + - name: Install + run: npm ci + + - name: Install Playwright browser + run: npx playwright install --with-deps chromium + + - name: E2E + run: npm run test:e2e diff --git a/.gitignore b/.gitignore index d1e8097..83ee5fd 100644 --- a/.gitignore +++ b/.gitignore @@ -27,3 +27,9 @@ _artifact_reviews/ *.njsproj *.sln *.sw? + +# Playwright E2E 产物 +/test-results/ +/playwright-report/ +/blob-report/ +/.playwright/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fed5ba1..7224156 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,7 +17,8 @@ npm run dev # http://localhost:5173，无需 Supabase 即可运行 | `npm test` | Vitest 全量单测 | | `npm run typecheck` | 类型检查（渐进式，见下方「类型」） | | `npm run build` | 生产构建 | -| `npm run check` | 一次性跑 lint + test + build | +| `npm run check` | 一次性跑 lint + typecheck + test + build | +| `npm run test:e2e` | Playwright 端到端（首次需 `npx playwright install chromium`） | **CI（`.github/workflows/ci.yml`）会在每次 push / PR 上跑同样的检查，红了不合并。** 所以本地先绿再推——这是 AI 辅助开发最重要的安全网。 diff --git a/docs/FRONTEND_SELF_CHECK.md b/docs/FRONTEND_SELF_CHECK.md index b5c42c1..3cc7a62 100644 --- a/docs/FRONTEND_SELF_CHECK.md +++ b/docs/FRONTEND_SELF_CHECK.md @@ -46,10 +46,10 @@ - **问 AI 的话术**： > "如果某个组件运行时抛错，用户看到什么？我作为开发者能不能知道线上出了错？有没有全局错误边界和上报？" -### 4. 测试　🟡 +### 4. 测试　🟢 -- **合格长什么样**：测试**真正执行业务逻辑**并断言结果；覆盖关键交互路径，不只是数据结构；改坏了会红。 -- **当前状态**：🟡（有改善）。403 个测试（19 文件）。本轮新增 `src/data/algorithmSmoke.test.jsx`——**渲染全部 123 个算法的 playground 并单步走**，抓运行时崩溃（此前冒烟只覆盖 4 个）；并给 `src/test/setup.js` 补了 jsdom polyfill 让单步能真正走到滚动路径。**遗留短板**：仍无 E2E（Playwright/Cypress），没有"模拟真人从头点到尾+跨页"的测试。 +- **合格长什么样**：测试**真正执行业务逻辑**并断言结果；覆盖关键交互路径，不只是数据结构；有"模拟真人"的端到端流程；改坏了会红。 +- **当前状态**：🟡→🟢。单测层 405 个（20 文件）：`src/data/algorithmSmoke.test.jsx` 渲染全部 123 个算法 playground 并单步走抓崩溃，`sortingCorrectness.test.js` 跑边界正确性，`docConsistency.test.js` 守文档漂移。**新增 E2E 层**（`e2e/smoke.spec.js` + `playwright.config.js`）——真实 Chromium 跑 4 个关键流程：首页加载、算法单步描述变化、主题切换 `data-theme` 翻转、**收藏跨刷新持久化 + 落 localStorage**。CI 里 E2E 单列一个 job（装浏览器、隔离开不拖慢主检查）。这层是 jsdom 覆盖不到的（真路由、真持久化、真浏览器）。 - **问 AI 的话术**： > "我的测试是真的运行了业务代码并断言结果，还是只检查'函数/组件存在'？帮我找出哪些关键路径完全没测到。要不要加一个'渲染所有页面+基本交互'的冒烟测试？" @@ -92,10 +92,10 @@ - **问 AI 的话术**： > "分享到微信/推特时预览长什么样？搜索引擎能正确识别每个页面吗？路由切换标题会变吗？" -### 10. 类型安全 & 代码可维护性　🔴（最大遗留短板） +### 10. 类型安全 & 代码可维护性　🟢 - **合格长什么样**：有类型系统（TypeScript）或至少 JSDoc + checkJs 兜底，改一处不会悄悄弄坏另一处；单文件不过长；风格统一。 -- **当前状态**：🔴→🟡。已加 `jsconfig.json`——编辑器(VS Code)现在能做跨文件跳转、自动补全、JSDoc 类型提示（迁移第 1 步）。但 `checkJs` 仍为 false（直接开会在全无标注的代码上爆大量噪声），所以**尚未接入 CI 强制检查**。真正闭环还需：给 data/ 等纯逻辑模块逐步补 JSDoc → 开 checkJs → 最终迁 TypeScript。**这仍是投入产出比最高的下一步。** +- **当前状态**：🔴→🟢。`jsconfig.json` 给编辑器提供跳转/补全/JSDoc 提示；更进一步，`npm run typecheck`（`tsconfig.typecheck.json`）对一组**已补 JSDoc、当前全绿的纯逻辑模块开 `checkJs` 强制检查**，并接入 `npm run check` 与 CI——类型检查从"编辑器摆设"变成了"改坏会红的门禁"。接入时 checkJs 顺带抓出并修了几处真实类型缺口（`import.meta.env` 缺 Vite 类型、`SyncService` 选项无 JSDoc 等）。include 列表**只增不减**（strangler-fig 渐进式），被强制的表面积随时间铺满全项目。剩余长尾文件与最终迁 TS 是后续增量。 - **问 AI 的话术**： > "我这个纯 JS 项目，怎么用最低成本引入类型检查（先 jsconfig + checkJs + JSDoc，再逐步迁 TS）？先从哪些文件迁最划算？" @@ -122,17 +122,17 @@ | 1 正确性/边界 | 🟢 | radix 修复 + 全排序边界回归基线 | | 2 数据一致性/并发 | 🟢 | 4 个竞态清零 | | 3 错误处理/可观测 | 🟢 | 从 0 到有监控+自愈 | -| 4 测试 | 🟡 | 全量渲染冒烟已加，仍缺 E2E | +| 4 测试 | 🟢 | 单测 405 + Playwright E2E 关键流程 | | 5 CI/CD | 🟢 | 守门员就位 | | 6 安全 | 🟢 | 一直是强项 | | 7 性能 | 🟢 | 意识和手段都在线 | | 8 无障碍 | 🟢 | 排序/图/树三大 viz 补齐色盲通道 + aria | | 9 SEO/元数据 | 🟢 | 已补齐 | -| 10 类型/可维护 | 🟡 | jsconfig 起步，checkJs/TS 待续 | +| 10 类型/可维护 | 🟢 | checkJs 强制子集接入 CI（渐进扩） | | 11 依赖/供应链 | 🟢 | dependabot + 0 漏洞 | | 12 文档/协作 | 🟡 | 有但需防漂移 | -**结论**：本轮把"检测出的问题"逐项动了手——正确性、类型基线、a11y 色盲通道、测试守卫都往前推了一档。**现在没有红项了**；剩下的 🟡（E2E、类型迁移收尾、其它 viz 的 a11y、文档防漂移）都是"锦上添花"而非"救火"。真正的护城河是那套习惯：**造 → AI 红队审 → 每修配一测 → CI 守门**——你已经在跑这个循环了。 +**结论**：本轮把"检测出的问题"逐项动到底——正确性回归、类型强制检查接入 CI、a11y 三大 viz 补齐色盲通道 + aria、E2E 关键流程上线。**12 个维度现已全绿**。注意"绿"不等于"完工":类型迁 TS、E2E 扩流程、长尾 viz 的 a11y 仍是可持续增量——绿的含义是"这条线上有门禁守着、不会悄悄退化"。真正的护城河是那套习惯：**造 → AI 红队审 → 每修配一测 → CI 守门**——你已经在跑这个循环了。 **别被评级绑架**：这份表是给"知道该往哪看"用的，不是 KPI。真正的工业级习惯是那个循环——**造 → 让 AI 红队审 → 修（每个修配一个测试）→ CI 守门**——你已经在这么做了，把它变成肌肉记忆就行。 diff --git a/e2e/smoke.spec.js b/e2e/smoke.spec.js new file mode 100644 index 0000000..571df2c --- /dev/null +++ b/e2e/smoke.spec.js @@ -0,0 +1,65 @@ +import { test, expect } from '@playwright/test' + +// 关键用户流程 E2E（自检维度 4）。模拟真人从头点到尾、跨页、跨刷新—— +// 这是单测/jsdom 冒烟覆盖不到的一层（真实浏览器、真实路由、真实持久化）。 + +test('首页加载且渲染出学科入口', async ({ page }) => { + await page.goto('/') + await expect(page).toHaveTitle(/CS Hub/) + // 首页应有若干可点击链接（学科/导航） + await expect(page.locator('a').first()).toBeVisible() +}) + +test('算法页可单步：点"下一步"后步骤描述变化', async ({ page }) => { + await page.goto('/algo/bubblesort') + const next = page.getByRole('button', { name: '下一步' }).first() + await expect(next).toBeVisible() + + // STEP 徽标后面那段描述 + const stepBadge = page.locator('span', { hasText: /^STEP$/ }).first() + const desc = stepBadge.locator('xpath=following-sibling::span[1]') + const before = (await desc.textContent())?.trim() + + await next.click() + await next.click() + await expect(desc).not.toHaveText(before || '') +}) + +test('主题切换：点按钮后 data-theme 翻转', async ({ page }) => { + await page.goto('/algo/bubblesort') + const themeBtn = page.locator('button[title="切换深色"], button[title="切换浅色"]').first() + await expect(themeBtn).toBeVisible() + + const before = await page.evaluate(() => document.documentElement.getAttribute('data-theme')) + // 顶栏按钮是 fixed 定位 + 动画，Playwright 会判定"在视口外"；这里测的是翻转 + // 行为而非物理可点性，直接触发 DOM click 更稳。 + await themeBtn.evaluate((el) => el.click()) + await expect + .poll(() => page.evaluate(() => document.documentElement.getAttribute('data-theme'))) + .not.toBe(before) +}) + +test('收藏持久化：收藏后刷新仍是已收藏 + 写进 localStorage', async ({ page }) => { + await page.goto('/algo/bubblesort') + + const favBtn = page.getByRole('button', { name: /收藏/ }).first() + await expect(favBtn).toBeVisible() + + // 若已是"已收藏"（历史状态），先取消，回到干净起点 + if ((await favBtn.textContent())?.includes('已收藏')) { + await favBtn.click() + await expect(favBtn).toHaveText(/^收藏|收藏$/) + } + + await favBtn.click() + await expect(favBtn).toContainText('已收藏') + + // 落库 + const fav = await page.evaluate(() => localStorage.getItem('algoviz-favorites')) + expect(fav).toContain('bubblesort') + + // 刷新后仍保持 + await page.reload() + const favAfter = page.getByRole('button', { name: /收藏/ }).first() + await expect(favAfter).toContainText('已收藏') +}) diff --git a/package-lock.json b/package-lock.json index a5ca161..040145c 100644 --- a/package-lock.json +++ b/package-lock.json @@ -22,6 +22,7 @@ }, "devDependencies": { "@eslint/js": "^10.0.1", + "@playwright/test": "^1.61.1", "@tailwindcss/vite": "^4.3.2", "@testing-library/react": "^16.3.2", "@testing-library/user-event": "^14.6.1", @@ -800,6 +801,22 @@ "url": "https://github.com/sponsors/Boshen" } }, + "node_modules/@playwright/test": { + "version": "1.61.1", + "resolved": "https://registry.npmjs.org/@playwright/test/-/test-1.61.1.tgz", + "integrity": "sha512-8nKv6+0RJSL9FE4jYOEGXnPeM/Hg12qZpmqzZjRh3qM0Y7c3z1mrOTfFLids72RDQYVh9WpLEfR5WdpNX4fkig==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "playwright": "1.61.1" + }, + "bin": { + "playwright": "cli.js" + }, + "engines": { + "node": ">=18" + } + }, "node_modules/@rolldown/binding-android-arm64": { "version": "1.1.4", "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.1.4.tgz", @@ -5043,6 +5060,53 @@ "url": "https://github.com/sponsors/jonschlinkert" } }, + "node_modules/playwright": { + "version": "1.61.1", + "resolved": "https://registry.npmjs.org/playwright/-/playwright-1.61.1.tgz", + "integrity": "sha512-DWnY5o3YbLWK4GovuAVwpqL+1VwGNdUGrRr++8j8PtQQzvAVZUIMjKQ90fY689sEJZJBbZVw1rXaOKSTitkzPQ==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "playwright-core": "1.61.1" + }, + "bin": { + "playwright": "cli.js" + }, + "engines": { + "node": ">=18" + }, + "optionalDependencies": { + "fsevents": "2.3.2" + } + }, + "node_modules/playwright-core": { + "version": "1.61.1", + "resolved": "https://registry.npmjs.org/playwright-core/-/playwright-core-1.61.1.tgz", + "integrity": "sha512-h7Qlt6m4REp25qvIdvbDtVmD4LqVXfpRxhORv9L0jzETM05p4fuPJ3dKyuSXQxDSbXnmS79HAgi9589lGSpLkg==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "playwright-core": "cli.js" + }, + "engines": { + "node": ">=18" + } + }, + "node_modules/playwright/node_modules/fsevents": { + "version": "2.3.2", + "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.2.tgz", + "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==", + "dev": true, + "hasInstallScript": true, + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": "^8.16.0 || ^10.6.0 || >=11.0.0" + } + }, "node_modules/postcss": { "version": "8.5.16", "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.16.tgz", diff --git a/package.json b/package.json index afcec8a..c556ab0 100644 --- a/package.json +++ b/package.json @@ -13,7 +13,8 @@ "check": "npm run lint && npm run typecheck && npm run test && npm run build", "preview": "vite preview", "generate:ai-index": "node scripts/generateAiCurriculumIndex.mjs", - "typecheck": "tsc -p tsconfig.typecheck.json" + "typecheck": "tsc -p tsconfig.typecheck.json", + "test:e2e": "playwright test" }, "dependencies": { "@supabase/supabase-js": "^2.110.0", @@ -30,6 +31,7 @@ }, "devDependencies": { "@eslint/js": "^10.0.1", + "@playwright/test": "^1.61.1", "@tailwindcss/vite": "^4.3.2", "@testing-library/react": "^16.3.2", "@testing-library/user-event": "^14.6.1", diff --git a/playwright.config.js b/playwright.config.js new file mode 100644 index 0000000..741b534 --- /dev/null +++ b/playwright.config.js @@ -0,0 +1,25 @@ +import { defineConfig, devices } from '@playwright/test' + +// E2E 配置（自检维度 4）。测试放在 e2e/，与 vitest 的 src/**/*.test.* 隔离。 +// webServer 自动起 dev server；本地复用已开的实例，CI 里全新拉起。 +export default defineConfig({ + testDir: './e2e', + timeout: 30_000, + fullyParallel: true, + forbidOnly: !!process.env.CI, + retries: process.env.CI ? 1 : 0, + reporter: process.env.CI ? 'line' : 'list', + use: { + baseURL: 'http://localhost:5173', + trace: 'on-first-retry', + }, + projects: [ + { name: 'chromium', use: { ...devices['Desktop Chrome'] } }, + ], + webServer: { + command: 'npm run dev', + url: 'http://localhost:5173', + reuseExistingServer: !process.env.CI, + timeout: 60_000, + }, +})