ModReleaser/docs/index.md

# Mod Releaser

一个基于 Web 界面的本地工具，用于通过 API 向 Modrinth 和 CurseForge 一键发布 mod 新版本。

## 技术栈

- **框架**：Next.js（前后端不分离，WebUI 作为本地界面）
- **UI 库**：Ant Design
- **图标库**：@ant-design/icons
- **通信层**：tRPC（避免手写 API Route，除了 `[trpc]/route.ts` 一个入口文件）
- **工具库**：use-debounce（防抖）
- **Markdown 编辑器**：@uiw/react-md-editor（风格需调整为与 Ant Design 统一）
- **校验库**：Zod（运行时校验 config 文件 + API 响应）
- **测试框架**：Vitest
- **平台 API**：Modrinth API、CurseForge API

## 项目结构

```
/
├── secrets.json              # API 密钥（curseforge / modrinth）
├── configs/
│   └── {config_name}.json   # 各 mod 的配置
├── public/                    # 静态资源（图标、图片等）
├── src/
│   ├── app/                   # Next.js App Router（页面、布局）
│   ├── components/            # 可复用 UI 组件
│   ├── lib/                   # 后端逻辑（与前端直接调用，不创建 API Route）
│   └── types/                 # TypeScript 类型定义
├── docs/                      # 本文档
├── package.json
└── ...
```

## 开发规范

### 前后端通信

日常功能使用 Next.js Server Actions 或直接在 Server Component 中调用后端函数，**不创建 API Route**。前端通过 `"use server"` 指令的函数或 Server Component 的 `async` 逻辑直接调用 `src/lib/` 中的后端代码，避免前后端分离的冗余 API 层。

仅发布功能使用 tRPC（需 subscription 推送实时进度），在 `src/app/api/publish/[trpc]/route.ts` 中定义唯一的 HTTP 入口，前端通过 tRPC Client 调用：

- 变更：`trpc.release.publish.useMutation()`
- 订阅：`trpc.release.progress.useSubscription(...)`

### `src/` 目录说明

| 目录 | 职责 |
|------|------|
| `app/` | Next.js App Router 页面与布局 |
| `components/` | 可复用的 Ant Design 组件 |
| `lib/` | 纯后端逻辑（读取配置、调用 API、模板解析等），可供前端直接引用 |
| `types/` | TypeScript 类型/接口定义，使用 Zod schema 统一校验并导出类型 |

### 代码质量

- 每个文件行数不宜过多，单一职责，低耦合高内聚
- 尽可能减少技术债，写出可维护性高的代码
- 组件拆分粒度合理，逻辑与 UI 分离

### 类型定义（`src/types/`）

```
src/types/
├── config.ts            # config.json + secrets.json 的 Zod schema 与类型
├── modrinth/            # Modrinth API 请求/响应的 Zod schema 与类型
│   └── ...
├── curseforge/          # CurseForge API 请求/响应的 Zod schema 与类型
│   └── ...
└── index.ts             # 统一导出
```

所有外部数据（配置文件、API 请求体、API 响应体）统一用 Zod schema 校验，同时导出 TypeScript 类型。

## 文档目录

- [frontend.md](./frontend.md) — 前端页面与组件（WebUI）
- [modrinth/](./modrinth/) — Modrinth API 参考
- [curseforge/](./curseforge/) — CurseForge API 参考
- [workflow.md](./workflow.md) — 整体发布流程、状态管理、错误处理

## 参考文档

编写代码时，如需查阅框架或组件库文档，通过 fetch 工具按以下体系获取：

### Modrinth API

参考 `docs/modrinth/` 目录（忽略 `openapi.yml`）：

| 文件 | 说明 |
|------|------|
| `upload.md` | 新建版本 API（`POST /version`） |
| `get.md` | 获取版本信息 API（列出项目版本、获取单个版本等） |
| `get-meta.md` | 元数据查询 API（加载器列表、游戏版本列表等） |

### CurseForge API

参考 `docs/curseforge/` 目录：

| 文件 | 说明 |
|------|------|
| `upload.md` | 上传文件 API（含 Game Version Types / Game Versions 查询） |
| `get.md` | 获取文件列表 API（`GET /mods/{modId}/files`） |

### 前端框架与组件库

#### Next.js

- `nextjs.org/docs/llms.txt` — 目录索引（带描述）
- 每页 `.md` — 逐页获取正文

#### Ant Design

- `ant.design/llms.txt` — 目录索引（纯链接）
- `ant.design/design.md` — 设计语言上下文
- 每页 `.md` — 逐页获取正文
- 每组件 `semantic.md` — 单个组件语义结构

#### use-debounce

- `https://www.npmjs.com/package/use-debounce` — npm 页面
- `https://raw.githubusercontent.com/xnimorz/use-debounce/refs/heads/master/README.md` — README 原文

#### tRPC

- `https://trpc.io/llms.txt` — 目录索引（带描述）
- 每页逐页获取正文

#### Zod

- `https://zod.dev/llms.txt` — 目录索引（纯链接）
- `https://raw.githubusercontent.com/colinhacks/zod/refs/heads/main/packages/zod/README.md` — README 原文

#### Vitest

- `https://vitest.dev/llms.txt` — 目录索引

#### @uiw/react-md-editor

- `https://github.com/uiwjs/react-md-editor/blob/master/core/README.md` — README 原文