software-workspace/docs/create-project.md

# 新增项目详细指南

本指南说明如何在 SoftwareWorkspace 网站中新增一个完整的项目条目。

---

## 涉及文件总览

| 步骤 | 文件 | 是否必须 |
|------|------|---------|
| 1 | `src/data/projects/<项目id>.yaml` | **必须** |
| 2 | `src/utils/iconRegistry.ts` | 仅当使用新图标时 |
| 3 | `src/data/categories.yaml` | 仅当新增分类时 |
| 4 | `src/data/statuses.yaml` | 仅当新增状态时 |
| 5 | `public/logos/` | 仅当有项目 Logo 时 |
| 6 | `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'

# 项目 Logo 图片（可选，支持 SVG/PNG/JPG）
# 图片放在 public/logos/ 目录下，路径相对于 public 目录
# 若设置了 logo，卡片和详情页会优先展示 Logo 图片，否则回退到上面的 lucide 图标
# logo: '/logos/my-new-app.png'

# 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'
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'

# ========== 安装指南（可选） ==========
# 每个项目生产的安装包不同，按实际包格式填写即可
# 会以紧凑的单行提示展示在"下载安装"区域内
# 不填写则使用默认的通用安装说明

installGuide:
  zh:
    - platform: 'Windows'
      icon: '🪟'
      format: '.exe'
      tip: 'SmartScreen 拦截？点击"更多信息" → "仍要运行"'
    - platform: 'macOS'
      icon: '🍎'
      format: '.dmg'
      tip: '提示已损坏？终端运行: xattr -dr com.apple.quarantine /Applications/MyApp.app'
    - platform: 'Linux'
      icon: '🐧'
      format: '.AppImage'
      tip: 'chmod +x MyApp-*.AppImage && ./MyApp-*.AppImage'
  en:
    - platform: 'Windows'
      icon: '🪟'
      format: '.exe'
      tip: 'SmartScreen blocked? Click "More info" → "Run anyway"'
    - platform: 'macOS'
      icon: '🍎'
      format: '.dmg'
      tip: '"Damaged" error? Run: xattr -dr com.apple.quarantine /Applications/MyApp.app'
    - platform: 'Linux'
      icon: '🐧'
      format: '.AppImage'
      tip: 'chmod +x MyApp-*.AppImage && ./MyApp-*.AppImage'
```

---

## 步骤二（仅在需要新图标时）：注册图标

如果 `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 代码，项目即自动上线。**