# frontend-showcase

**Repository Path**: gitgreat/frontend-showcase

## Basic Information

- **Project Name**: frontend-showcase
- **Description**: 前端页面、组件、CSS 与 JavaScript 学习实验展示合集
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-21
- **Last Updated**: 2026-07-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Frontend Showcase

一个用于整理和展示前端页面、组件、CSS 与 JavaScript 学习实验的静态站点。项目使用 React、TypeScript、Vite、Tailwind CSS 和 Ant Design 构建，具体示例以独立 HTML 页面在 iframe 中预览。

## 当前状态

- 源码仓库：`https://gitee.com/gitgreat/frontend-showcase`
- 在线演示：`https://showcase.sofile.cn/`
- 发布状态：Public Preview；正式域名已完成核心交互冒烟和 167 个本地入口全量审计，当前 0 critical
- 开发阶段：本轮主动开发已结项，进入稳定维护；新功能以真实使用问题和可衡量收益为触发条件
- 内容规模：165 个作品、167 个本地演示入口，覆盖 CSS、JavaScript、组件、模块、页面和工具

## 快速开始

```bash
npm install
npm run dev
```

生产验证：

```bash
npm run check
npm run preview
```

如果本机其他项目已占用默认的生产测试端口 `4321`，可以为本次检查指定空闲端口：

```bash
PLAYWRIGHT_PREVIEW_PORT=4322 npm run check
```

项目要求 Node.js `20.19+` 或 `22.12+`，与当前 Vite 运行要求保持一致。

## 常用命令

| 命令 | 用途 |
| --- | --- |
| `npm run dev` | 启动本地开发服务器 |
| `npm run lint` | 检查 React/TypeScript 源码 |
| `npm run test` | 验证搜索、路由和分页等核心行为 |
| `npm run test:e2e` | 使用 Chromium 验证关键交互、动态导入失败、主题和移动端边界 |
| `npm run catalog:review-queue` | 输出当前最优先的 30 条历史来源审核队列 |
| `npm run catalog:preview-audit` | 只读审计全部本地演示的加载、脚本、空白、溢出和旋转信号 |
| `npm run check:catalog` | 校验目录结构、数量、来源字段和历史数据债务上限 |
| `npm run check:previews` | 校验预览策略对应的 WebP 并保持单图与总体积预算 |
| `npm run check:bundle` | 阻止 JS/CSS 重新合并成过大的单文件产物 |
| `npm run check:links` | 验证目录登记的本地演示文件 |
| `npm run check:publication` | 阻止已知第三方统计和真实电话链接重新进入发布产物 |
| `npm run check:production` | 验证正式域名、代表性案例、分享元数据、缓存与安全响应头 |
| `npm run build` | 构建静态站点到 `dist/` |
| `npm run check` | 执行完整发布前检查 |

仓库内的 [`.workflow/quality.yml`](.workflow/quality.yml) 使用同一条 `npm run check` 作为 Gitee Go 推送质量门禁；首次使用仍需由仓库所有者在 Gitee 中开通流水线服务。

## 项目文档

- [项目结项总结与开发方法](docs/project-closeout-and-development-guide-2026-07-23.md)：当前阶段的权威入口，归纳完整演进历史、开发经验、维护边界和重新启动条件。
- [目录重构、视觉升级与可靠性复盘](docs/catalog-redesign-and-reliability-retrospective.md)：记录目录数据模型、沉浸式实验墙、明暗主题、分页细节、演示空白页根因和后续维护规则。
- [交互状态矩阵](docs/interaction-state-matrix.md)：定义组件状态、盒模型检查、双主题/移动端验收和线上问题回收规则。
- [ADR-0003：用交互状态矩阵和浏览器回归约束视觉改动](docs/decisions/0003-interaction-states-and-regression-gates.md)：把已有线上问题转化为持续门禁。
- [ADR-0004：目录卡片使用证据驱动的预览策略与只读审计](docs/decisions/0004-preview-policy-and-audit.md)：记录 iframe、静态截图、全量审计和人工复核之间的边界。
- [精选模块首批来源复核记录](docs/catalog-curation-2026-07-23.md)：记录 10 个首页精选模块的来源、署名和本地证据。
- [历史来源复核第二批](docs/catalog-curation-2026-07-23-batch-2.md)：记录 29 条已有来源与描述记录的逐项复核、来源修正和证据限制。
- [历史来源复核第三批](docs/catalog-curation-2026-07-23-batch-3.md)：记录 61 条已有来源但缺少描述记录的本地行为复核、来源检查和债务收敛结果。
- [历史来源复核第四批](docs/catalog-curation-2026-07-23-batch-4.md)：为最后 60 条缺少来源记录补齐行为描述，完成 24 条有证据的归属复核，并隔离 36 条无法证明来源的历史债务。
- [交互、内容与性能治理阶段收尾](docs/quality-stage-closeout-2026-07-23.md)：汇总本轮实施结果、验证证据、五轴审查和功能扩展结论。
- [目录预览全量审计与首批治理记录](docs/catalog-preview-audit-2026-07-23.md)：记录 167 个入口的审计口径、首批静态预览、资源预算和剩余队列。
- [项目拆分与公开发布复盘](docs/extraction-and-publication-retrospective.md)：记录从父仓库独立、公开前治理、验证闭环和可复用经验。
- [展示内容扩展与交互复刻复盘](docs/content-expansion-and-interaction-retrospective.md)：记录番茄钟、品牌场景动效、HTML 光照实验和图片风格横幅的接入过程、反馈纠偏与后续开发方法。
- [图片风格引导横幅 Design QA](docs/image-style-banner-design-qa.md)：记录默认态、展开态、移动端和项目弹窗的视觉复测证据。
- [ADR-0001：源码托管与在线静态托管分离](docs/decisions/0001-source-and-hosting-boundary.md)：记录 Gitee 与静态托管平台的职责边界。
- [ADR-0002：公开预览采用默认隔离的案例运行边界](docs/decisions/0002-public-preview-browser-boundary.md)：记录 iframe sandbox、存储例外和响应头策略。

## 内容与授权边界

`src/`、构建配置和仓库维护脚本采用 MIT License。`public/` 中包含原创学习实验、界面临摹以及按各自许可证保留的第三方开源示例，不自动适用仓库根目录的 MIT License。

查看 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md) 了解第三方内容规则。目录里的“来源”链接表示设计或实现参考，不等于对方授权或背书。新增示例前应确认来源和再分发条件。

目录数据按模块、组件、页面、CSS、JavaScript 和工具拆分在 `src/catalog/items/`，每条记录使用稳定 `id` 和显式 `sortOrder`，不再依赖文件位置表达展示顺序。新增案例必须填写 `provenance`；开源收录必须同时填写许可证。尚未核实的历史案例统一标记为 `unreviewed-legacy`，其描述、来源和来源审核缺口由 `check:catalog` 设置只减不增的上限。

## 部署

Gitee Pages 已下线，因此 Gitee 仅作为源码仓库。静态构建产物由 EdgeOne Pages 发布到 `https://showcase.sofile.cn/`。Vite 使用相对基础路径，目录中的演示地址也会通过 `import.meta.env.BASE_URL` 解析，可兼容根域名与子路径托管。

EdgeOne 的缓存和安全响应头位于 `edgeone.json`。生产部署完成后运行：

```bash
npm run check:production
```

部署决策记录在 [ADR-0001](docs/decisions/0001-source-and-hosting-boundary.md)。