better-staridc-MNBT
1---
2title: MNBT Store API 文档
3description: MNBT 插件商店与主题商店的完整 REST API 文档（英文原文）
4---
5
6# MNBT Store API Documentation
7
8**Base URL:** `http://localhost:3000/api`
9**Authentication:** Session-based (Cookie-based)
10**Content-Type:** `application/json` (except file uploads: `multipart/form-data`)
11
12---
13
14## Authentication
15
16### Register
17
18```
19POST /auth/register
20```
21
22```json
23{
24 "username": "string (2-30 chars)",
25 "password": "string (min 6 chars)",
26 "email": "string (email format)",
27 "captcha": "string (4 chars from captcha)"
28}
29```
30
31### Login
32
33```
34POST /auth/login
35```
36
37```json
38{
39 "username": "string",
40 "password": "string",
41 "captcha": "string (4 chars from captcha)"
42}
43```
44
45**Session:** Sets `req.session.userId`, `req.session.username`, `req.session.role`
46
47### Logout
48
49```
50POST /auth/logout
51```
52
53### Get Current User
54
55```
56GET /auth/me
57```
58
59**Auth Required:** Yes (Developer or Admin)
60
61### Change Password
62
63```
64PUT /auth/password
65```
66
67```json
68{
69 "oldPassword": "string",
70 "newPassword": "string (min 6 chars)"
71}
72```
73
74---
75
76## Public Item APIs (No Auth)
77
78### List Items
79
80```
81GET /items
82```
83
84| Query | Type | Default | Description |
85|-------|------|---------|-------------|
86| type | string | - | `plugin` or `theme` |
87| keyword | string | - | Search name, description, slug |
88| category | string | - | Filter by category |
89| author_id | number | - | Author filter |
90| min_price | number | - | Minimum price |
91| max_price | number | - | Maximum price |
92| sort | string | newest | `newest`, `downloads`, `price` |
93| page | number | 1 | Page number |
94| page_size | number | 12 | Items per page |
95
96### Get Categories
97
98```
99GET /items/categories
100```
101
102### Get Item Detail
103
104```
105GET /items/:id
106```
107
108### Download Item
109
110```
111GET /items/:id/download
112```
113
114**Response:** File download (ZIP), logs download with userId if logged in.
115
116### Get Item Versions
117
118```
119GET /items/:id/versions
120```
121
122---
123
124## Developer APIs
125
126**Auth:** Developer or Admin role required.
127
128### List My Items
129
130```
131GET /developer/items
132```
133
134| Query | Type | Default |
135|-------|------|---------|
136| type | string | - |
137| page | number | 1 |
138| page_size | number | 20 |
139
140### Submit New Item
141
142```
143POST /developer/items
144```
145
146**Content-Type:** `multipart/form-data`
147
148| Field | Type | Required | Description |
149|-------|------|----------|-------------|
150| type | string | Yes | `plugin` or `theme` |
151| slug | string | Yes | Unique identifier |
152| name | string | Yes | Display name |
153| version | string | Yes | Version string |
154| price | number | No | Default: 0 |
155| description | string | Yes | HTML (sanitized) |
156| category | string | No | Category |
157| tags | string | No | JSON array `["tag1", "tag2"]` |
158| homepage | string | No | Project URL |
159| zipfile | file | Yes | ZIP (max 50MB) |
160
161**ZIP Validation:** Root folder must match slug, max 500 files, max 10MB per file, no path traversal.
162
163### Update Item Info
164
165```
166PUT /developer/items/:id
167```
168
169Changes create edit requests for admin review.
170
171### Add New Version
172
173```
174POST /developer/items/:id/versions
175```
176
177**Content-Type:** `multipart/form-data`
178
179| Field | Type | Required | Description |
180|-------|------|----------|-------------|
181| version | string | Yes | New version number |
182| changelog | string | No | Changelog |
183| zipfile | file | Yes | ZIP file |
184
185---
186
187## Upload APIs
188
189### Upload Image
190
191```
192POST /upload/image
193```
194
195**Auth:** Any logged-in user
196**Fields:** `image` (file, max 5MB, jpg/png/gif/webp)
197**Response:** `{ "url": "/uploads/images/uuid.png" }`
198
199---
200
201## Admin APIs
202
203**Auth:** Admin role required.
204
205### Get Statistics
206
207```
208GET /admin/stats
209```
210
211### List All Items
212
213```
214GET /admin/items
215```
216
217| Query | Type | Default |
218|-------|------|---------|
219| type | string | - |
220| status | string | - |
221| keyword | string | - |
222
223### Approve / Reject / Suspend Item
224
225```
226PUT /admin/items/:id/approve
227PUT /admin/items/:id/reject
228PUT /admin/items/:id/suspend
229```
230
231### Delete Item
232
233```
234DELETE /admin/items/:id
235```
236
237### List / Approve / Reject Edit Requests
238
239```
240GET /admin/edit-requests
241PUT /admin/edit-requests/:id/approve
242PUT /admin/edit-requests/:id/reject
243```
244
245### List / Update Users
246
247```
248GET /admin/users
249PUT /admin/users/:id
250```
251
252---
253
254## Error Response
255
256```json
257{
258 "code": 400,
259 "msg": "Error message",
260 "data": null
261}
262```
263
264| HTTP | Meaning |
265|------|---------|
266| 200 | Success |
267| 400 | Validation error |
268| 401 | Unauthorized |
269| 403 | Forbidden |
270| 404 | Not Found |
271
272---
273
274## Database Schema
275
276**Users:** `id, username, password(bcrypt), email, role(admin/developer), avatar, bio, status(active/banned)`
277**Items:** `id, type(plugin/theme), slug, name, version, author_id, price, description, zip_path, downloads, status(pending/approved/rejected/suspended)` — UNIQUE `(type, slug)`
278**Item Versions:** `id, item_id, version, zip_path, changelog, status`
279**Download Logs:** `id, item_id, user_id(nullable), ip`
280**Edit Requests:** `id, item_id, field, old_value, new_value, status`
281
282---
283
284## Default Admin
285
286- **Username:** `admin`
287- **Password:** `admin123`
288
289---
290
291## Development
292
293```bash
294npm install
295npm run dev # Development server
296npm run build # Build production
297npm start # Start production
298```
299
300**Server:** `http://localhost:3000` (or `PORT` env var)