feat: 全面重构网站工程化体系与 UI 架构

- 将单体 style.css 拆分为 tokens/reset/fonts/layout/responsive/组件级 CSS 模块 - 从 Google Fonts CDN 迁移至本地自托管字体（JetBrainsMono、NotoSansSC） - 引入 Vitest + Testing Library 测试体系，新增单元测试 - 添加 GitHub Actions CI 流水线（lint → build → test） - 新增 Prettier 格式化与 ESLint 规则强化 - 重构全部 YAML 数据文件，完善项目详情页（截图轮播、更新日志） - 新增项目文档编写指南（docs/create-project.md）
2026-05-22 13:34:41 +08:00
parent 5e79c96364
commit 6b58b55c32
83 changed files with 5890 additions and 3955 deletions
@@ -0,0 +1,316 @@
+# 新增项目详细指南
+
+本指南说明如何在 SoftwareWorkspace 网站中新增一个完整的项目条目。
+
+---
+
+## 涉及文件总览
+
+| 步骤 | 文件 | 是否必须 |
+|------|------|---------|
+| 1 | `src/data/projects/<项目id>.yaml` | **必须** |
+| 2 | `src/utils/iconRegistry.ts` | 仅当使用新图标时 |
+| 3 | `src/data/categories.yaml` | 仅当新增分类时 |
+| 4 | `src/data/statuses.yaml` | 仅当新增状态时 |
+| 5 | `public/screenshots/` | 仅当有截图时 |
+
+**核心原则：** 只需创建一个 YAML 文件，项目就会自动出现在网站上。`loader.ts` 使用 `import.meta.glob('./projects/*.yaml')` 自动扫描该目录，无需手动注册。
+
+---
+
+## 步骤一：创建项目 YAML 文件
+
+在 `src/data/projects/` 下新建文件，文件名即项目 ID（小写，用连字符分隔）。
+
+例如：`src/data/projects/my-new-app.yaml`
+
+### 完整字段模板
+
+```yaml
+# ========== 基础信息 ==========
+
+# 项目唯一标识（与文件名一致，用于 URL 路由 /projects/:id）
+id: 'my-new-app'
+
+# 项目内部名称（英文，小写）
+name: 'my-new-app'
+
+# 显示名称（双语，通常首字母大写）
+displayName:
+  zh: '我的新应用'
+  en: 'My New App'
+
+# 一句话简介（显示在卡片和详情页标题下方）
+slogan:
+  zh: '一句话中文描述'
+  en: 'A one-line English description'
+
+# 详细描述（显示在详情页"概览"区域）
+description:
+  zh: '详细的中文介绍，说明项目功能、技术特点和适用场景。'
+  en: 'Detailed English introduction explaining features, technical highlights and use cases.'
+
+# ========== 分类与状态 ==========
+
+# 项目分类，可选多个（对应 categories.yaml 中的 id）
+# 可用值：desktop / mobile / devtool / library / backend / selfhosted / ai
+type:
+  - 'desktop'
+
+# 开发状态（对应 statuses.yaml 中的 key）
+# 可用值：active / maintained / beta / experimental / archived
+status: 'active'
+
+# ========== 技术信息 ==========
+
+# 支持平台（对应 platforms.yaml 中的 key）
+# 可用值：windows / macos / linux / android / ios / web / docker / npm / cli
+platforms:
+  - 'windows'
+  - 'macos'
+  - 'linux'
+
+# 技术栈标签（自由填写，会出现在筛选下拉和项目卡片上）
+techStack:
+  - 'Rust'
+  - 'TypeScript'
+  - 'React'
+
+# 核心功能列表（双语，显示在详情页"核心功能"区域）
+features:
+  zh:
+    - '功能一'
+    - '功能二'
+    - '功能三'
+  en:
+    - 'Feature one'
+    - 'Feature two'
+    - 'Feature three'
+
+# 搜索标签（用于搜索框模糊匹配，界面上不直接展示）
+tags:
+  - 'Keyword1'
+  - 'Keyword2'
+  - 'Keyword3'
+
+# ========== 图标与链接 ==========
+
+# 项目图标（lucide-react 图标名称）
+# 已注册的图标：NotebookPen / Terminal / MapPin / SmartPhone / BookOpen /
+#               Monitor / Brain / KeyRound / Wrench / Package / Cloud / Server / FlaskConical
+# 如果需要新图标，见"步骤二"
+icon: 'Terminal'
+
+# GitHub 仓库地址（必须）
+repoUrl: 'https://github.com/shenjianZ/my-new-app'
+
+# 在线文档地址（可选，不填则不显示文档按钮）
+docsUrl: 'https://github.com/shenjianZ/my-new-app#readme'
+
+# npm 包地址（可选，仅 NPM 包类项目填写）
+# npmUrl: 'https://www.npmjs.com/package/my-new-app'
+
+# ========== 版本信息 ==========
+
+latestVersion: 'v1.0.0'
+releaseDate: '2026-05-22'
+license: 'MIT'
+stars: 10
+forks: 2
+language: 'TypeScript'
+lastUpdated: '2026-05-22'
+
+# ========== 首页展示控制 ==========
+
+# 是否在首页"重点项目"区域展示（true/false）
+recommended: false
+
+# 是否在首页"Featured"大卡片展示（true/false，通常只给 1-2 个项目）
+featured: false
+
+# 排序权重（数字越小越靠前）
+order: 9
+
+# 卡片主题色（十六进制色值）
+color: '#3B82F6'
+
+# ========== 下载信息（可选） ==========
+
+# 如果没有下载功能，设为空数组 []
+downloads:
+  - platform: 'Windows'
+    arch: 'x64'
+    url: 'https://github.com/shenjianZ/my-new-app/releases/download/v1.0.0/my-new-app-setup.exe'
+    size: '15 MB'
+    sha256: ''
+  - platform: 'macOS'
+    arch: 'universal'
+    url: 'https://github.com/shenjianZ/my-new-app/releases/download/v1.0.0/my-new-app.dmg'
+    size: '18 MB'
+    sha256: ''
+  - platform: 'Linux'
+    arch: 'x64'
+    url: 'https://github.com/shenjianZ/my-new-app/releases/download/v1.0.0/my-new-app.AppImage'
+    size: '14 MB'
+    sha256: ''
+
+# ========== 路线图（可选） ==========
+
+roadmap:
+  done:
+    - '已完成的功能'
+  doing:
+    - '正在开发的功能'
+  planned:
+    - '计划中的功能'
+
+# ========== 更新日志（可选） ==========
+
+changelog:
+  - version: 'v1.0.0'
+    date: '2026-05-22'
+    changes:
+      zh:
+        - '初始发布'
+        - '核心功能上线'
+      en:
+        - 'Initial release'
+        - 'Core features launched'
+
+# ========== 架构说明（可选） ==========
+
+architecture:
+  zh: '前端 (React) → API 层 → 后端 (Rust)'
+  en: 'Frontend (React) → API Layer → Backend (Rust)'
+
+# ========== 截图（可选） ==========
+
+# 截图文件放在 public/screenshots/<项目id>/ 目录下
+# screenshots:
+#   - '/screenshots/my-new-app/main.png'
+#   - '/screenshots/my-new-app/settings.png'
+```
+
+---
+
+## 步骤二（仅在需要新图标时）：注册图标
+
+如果 `icon` 字段需要使用一个尚未注册的 lucide-react 图标，编辑 `src/utils/iconRegistry.ts`：
+
+```ts
+// 1. 在 import 中添加新图标
+import {
+  // ... 已有图标
+  Zap,  // 新增
+} from 'lucide-react';
+
+// 2. 在 iconRegistry 对象中注册
+const iconRegistry: Record<string, ComponentType<{ size?: number }>> = {
+  // ... 已有图标
+  Zap,  // 新增
+};
+```
+
+然后在 YAML 中 `icon: 'Zap'` 即可。
+
+---
+
+## 步骤三（仅在需要新分类时）：添加分类
+
+编辑 `src/data/categories.yaml`，追加新分类：
+
+```yaml
+- id: 'new-category-id'
+  label:
+    zh: '新分类中文名'
+    en: 'New Category Name'
+  icon: 'IconName'  # 需要在 iconRegistry 中已注册
+```
+
+然后在项目的 `type` 字段中使用该 `id`。
+
+---
+
+## 步骤四（仅在需要新状态时）：添加状态
+
+编辑 `src/data/statuses.yaml`，追加新状态：
+
+```yaml
+new-status:
+  label:
+    zh: '中文状态名'
+    en: 'English Status Name'
+  color: '#HEXCOLOR'
+```
+
+---
+
+## 步骤五（仅在有截图时）：添加截图
+
+1. 在 `public/` 下创建目录：`public/screenshots/<项目id>/`
+2. 放入截图文件（推荐 PNG 格式）
+3. 在 YAML 中引用：
+
+```yaml
+screenshots:
+  - '/screenshots/my-new-app/main.png'
+  - '/screenshots/my-new-app/feature.png'
+```
+
+---
+
+## 步骤六：验证
+
+1. 启动开发服务器：`pnpm dev`
+2. 检查以下页面：
+   - **首页**：项目出现在"最新发布"区域；若 `featured: true` 则出现在 Featured 大卡片
+   - **项目列表页**：项目出现在列表中，技术栈/平台/状态筛选均生效
+   - **项目详情页**：访问 `/projects/<项目id>`，所有信息正确展示
+   - **搜索**：在搜索框输入 tags 中的关键词，能搜索到该项目
+3. 运行测试：`pnpm test`（siteData 测试会验证数据结构完整性）
+
+---
+
+## 可用值速查
+
+### type（分类）
+| id | 中文 | 英文 |
+|----|------|------|
+| desktop | 桌面软件 | Desktop Apps |
+| mobile | 移动应用 | Mobile Apps |
+| devtool | 开发者工具 | Dev Tools |
+| library | NPM / 组件库 | NPM / Libraries |
+| backend | 后端服务 | Backend |
+| selfhosted | 自托管 | Self-hosted |
+| ai | AI / 实验项目 | AI / Experiments |
+
+### status（状态）
+| key | 中文 | 英文 | 颜色 |
+|-----|------|------|------|
+| active | 活跃开发 | Active | #22C55E |
+| maintained | 维护中 | Maintained | #3B82F6 |
+| beta | 测试版 | Beta | #F59E0B |
+| experimental | 实验性 | Experimental | #A855F7 |
+| archived | 已归档 | Archived | #6B7280 |
+
+### platforms（平台）
+`windows` / `macos` / `linux` / `android` / `ios` / `web` / `docker` / `npm` / `cli`
+
+### 已注册图标
+`NotebookPen` / `Terminal` / `MapPin` / `SmartPhone` / `BookOpen` / `Monitor` / `Brain` / `KeyRound` / `Wrench` / `Package` / `Cloud` / `Server` / `FlaskConical`
+
+---
+
+## 数据流示意
+
+```
+src/data/projects/<id>.yaml
+  ↓ import.meta.glob 自动扫描
+src/data/loader.ts（解析为 Project 对象，按 order 排序）
+  ↓ 导出 siteData
+src/pages/HomePage.tsx     → 首页卡片、Featured、最新发布
+src/pages/ProjectsPage.tsx → 项目列表 + 筛选
+src/pages/ProjectDetailPage.tsx → 详情页（/projects/:id）
+```
+
+**只需创建 YAML 文件，无需修改任何 TypeScript 代码，项目即自动上线。**