143 lines
5.2 KiB
Markdown
143 lines
5.2 KiB
Markdown
# 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（页面、布局、tRPC Route Handler）
|
||
│ ├── components/ # 可复用 UI 组件
|
||
│ ├── lib/ # 纯后端逻辑，无 React 依赖
|
||
│ ├── services/ # 业务编排层（Server Actions + tRPC Router）
|
||
│ └── 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 页面与布局，以及唯一的 tRPC Route Handler |
|
||
| `components/` | 可复用的 Ant Design 组件 |
|
||
| `lib/` | 纯后端逻辑（平台 API 请求、模板解析、工具函数），无 React 依赖 |
|
||
| `services/` | 业务编排层，注入全局 client 单例，通过 Server Actions 暴露给前端或 tRPC Router 调用 |
|
||
| `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 原文
|