better-staridc-MNBT
1---
2title: 插件商店 & 主题商店
3description: MNBT 插件商店与主题商店 Web 应用的需求规格，含架构、数据库、API、页面与业务流程
4---
5
6# 插件商店 & 主题商店
7
8为 MNBT 平台搭建独立的「插件商店」与「主题商店」Web 应用，供开发者上传、分发，用户浏览、下载。
9
10---
11
12## 技术架构
13
14| 层 | 选型 |
15|----|------|
16| 后端 | Node.js + TypeScript（Express） |
17| 前端 | 原生 HTML + LayUI |
18| 数据库 | SQLite |
19| 文件存储 | 本地文件系统（zip/图片存放于可配置目录） |
20
21---
22
23## 识别规则
24
25### 插件识别
26
27| 项目 | 规则 |
28|------|------|
29| 目录名 | 插件 slug，仅允许 `a-z A-Z 0-9 _ -`，最长 63 字符 |
30| 必含文件 | `plugin.json` + `bootstrap.php` |
31| `plugin.json` 必填字段 | `name`（显示名）、`version`（版本号） |
32| `plugin.json` 可选字段 | `id`、`author`、`description`、`requires_mnbt`、`type` |
33| 可选目录 | `admin/`、`user/`、`assets/`、`install.sql`、`uninstall.sql` |
34| zip 根层 | 解压后第一层必须有且仅有一个目录 |
35
36### 主题识别
37
38| 项目 | 规则 |
39|------|------|
40| 目录名 | 主题 ID，仅允许 `a-zA-Z0-9_-` |
41| 必含文件 | `theme.json` |
42| `theme.json` 必填字段 | `title`（显示名） |
43| `theme.json` 可选字段 | `name`、`version`、`description`、`author`、`scope` |
44| 可选目录 | `user/`、`admin/`（至少存在一个视为有效） |
45| zip 根层 | 解压后第一层必须有且仅有一个目录 |
46
47---
48
49## 数据库表
50
51| 表 | 说明 |
52|----|------|
53| `users` | 用户（username/password/email/role/status） |
54| `items` | 插件/主题主表（type/slug/name/version/price/downloads/status） |
55| `item_versions` | 版本历史 |
56| `download_logs` | 下载日志 |
57| `reviews` | 评价表（预留） |
58| `edit_requests` | 修改审核表 |
59
60联合唯一约束 `(type, slug)`。
61
62---
63
64## API 设计
65
66所有 API 以 `/api` 为前缀，Session 鉴权。
67
68### 认证
69
70| 方法 | 路径 | 说明 |
71|------|------|------|
72| POST | `/api/auth/register` | 用户注册 |
73| POST | `/api/auth/login` | 用户登录 |
74| POST | `/api/auth/logout` | 退出登录 |
75| GET | `/api/auth/me` | 当前用户信息 |
76| PUT | `/api/auth/password` | 修改密码 |
77
78### 商店公开接口
79
80| 方法 | 路径 | 说明 |
81|------|------|------|
82| GET | `/api/items` | 列表（筛选/分页/排序） |
83| GET | `/api/items/:id` | 详情 |
84| GET | `/api/items/:id/download` | 下载 |
85| GET | `/api/items/:id/versions` | 版本历史 |
86
87### 开发者接口
88
89| 方法 | 路径 | 说明 |
90|------|------|------|
91| GET | `/api/developer/items` | 我的列表 |
92| POST | `/api/developer/items` | 提交新插件/主题 |
93| PUT | `/api/developer/items/:id` | 修改信息 |
94| POST | `/api/developer/items/:id/versions` | 上传新版本 |
95
96### 管理员接口
97
98| 方法 | 路径 | 说明 |
99|------|------|------|
100| PUT | `/api/admin/items/:id/approve` | 审核通过 |
101| PUT | `/api/admin/items/:id/reject` | 驳回 |
102| PUT | `/api/admin/items/:id/suspend` | 下架 |
103| GET | `/api/admin/stats` | 统计概览 |
104
105---
106
107## 前端页面
108
109| 页面 | 路由 | 说明 |
110|------|------|------|
111| 首页 | `/` | 列表/搜索/分类筛选/排序/分页 |
112| 详情页 | `/detail.html?id={id}` | 介绍/版本/截图/下载 |
113| 登录页 | `/login.html` | 用户名/密码 |
114| 注册页 | `/register.html` | 用户名/邮箱/密码 |
115| 提交页 | `/submit.html` | 开发者提交 |
116| 开发者中心 | `/developer.html` | 管理已提交列表 |
117| 管理员后台 | `/admin.html` | 审核、用户管理 |
118
119---
120
121## 提交流程
122
123```
124开发者提交 → 系统校验 zip（路径穿越/文件数/大小/必含文件）
125 ↓
126校验失败 → 返回错误
127校验成功 → 读取 metadata → 入库（status=pending）
128 ↓
129管理员审核 → 通过（approved，公开可见）/ 驳回（rejected，附备注）
130```
131
132---
133
134## 安全规范
135
136- 密码 bcrypt 哈希存储
137- Session/Cookie httpOnly
138- zip 最大 50MB，图片最大 5MB
139- zip 解压前校验路径穿越、文件数 ≤500、单文件 ≤10MB
140- HTML 简介使用 DOMPurify/sanitize-html 防 XSS
141- 上传目录不可直接 URL 访问
142
143> 完整 API 文档见 [商店 API](./api.md)