108 lines
3.7 KiB
Markdown
108 lines
3.7 KiB
Markdown
# Mod Releaser
|
||
|
||
一个基于 Web 界面的本地工具，用于通过 API 向 Modrinth 和 CurseForge 一键发布 mod 新版本。
|
||
|
||
## 技术栈
|
||
|
||
- **框架**：Next.js（前后端不分离，WebUI 作为本地界面）
|
||
- **UI 库**：Ant Design
|
||
- **校验库**：Zod（运行时校验 config 文件 + API 响应）
|
||
- **平台 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 层。
|
||
|
||
### `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` — 单个组件语义结构
|