@niping9542/create-nova-admin 1.0.4 → 1.0.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +221 -47
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,89 +1,263 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Create Nova Admin
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
使用命令行创建 Vue 3 + TypeScript + Element Plus + Pinia 后台管理项目，请求使用 `@npora/request`，多语言使用 Vue I18n，并同步 Element Plus、Day.js 与页面日期格式。
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
npm 包名：`@niping9542/create-nova-admin`；[生成器源码](https://github.com/ni9542/create-nova-admin)。生成器从 [Npora Admin Template](https://github.com/npora/admin-template) 获取模板，默认使用 `main` 分支，按所选预设生成项目文件。
|
|
6
|
+
|
|
7
|
+
## 在线演示
|
|
8
|
+
|
|
9
|
+
[打开 Npora Admin 展示网站](https://admin-demo.npora.workers.dev)
|
|
10
|
+
|
|
11
|
+
| 账号 | 密码 |
|
|
12
|
+
| ------- | -------- |
|
|
13
|
+
| `admin` | `123456` |
|
|
14
|
+
|
|
15
|
+
以上账号仅用于在线演示和默认测试 API。纯净版、自己部署的后端和正式 SQL 不会自动获得这个账号。
|
|
16
|
+
|
|
17
|
+
## 环境要求
|
|
18
|
+
|
|
19
|
+
- 创建项目和开发前端：Node.js 22.12.0 或更高版本。
|
|
20
|
+
- 检查 Worker 后端：Node.js 22.13.0 或更高版本。
|
|
21
|
+
- 生成项目后，使用其 `package.json` 中 `packageManager` 指定的 pnpm 版本。
|
|
22
|
+
- 在线创建需要能够访问 npm 和 GitHub；完整演示的默认测试 API 也需要网络。
|
|
23
|
+
|
|
24
|
+
## 创建项目
|
|
25
|
+
|
|
26
|
+
### 交互选择
|
|
6
27
|
|
|
7
28
|
```sh
|
|
8
29
|
npx @niping9542/create-nova-admin@latest
|
|
9
30
|
```
|
|
10
31
|
|
|
11
|
-
|
|
32
|
+
按提示输入项目名，选择模板。直接回车使用默认纯净版：
|
|
33
|
+
|
|
34
|
+
```text
|
|
35
|
+
选择模板：
|
|
36
|
+
1. 纯净后台（默认）
|
|
37
|
+
2. 后台 + Worker 后端
|
|
38
|
+
3. 完整演示
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### 三个模板的区别
|
|
12
42
|
|
|
13
|
-
|
|
|
14
|
-
|
|
|
15
|
-
|
|
|
16
|
-
|
|
|
17
|
-
|
|
|
43
|
+
| 内容 | `starter` 纯净版 | `worker` 后端版 | `demo` 完整演示 |
|
|
44
|
+
| -------------------------------- | ---------------- | --------------- | --------------- |
|
|
45
|
+
| 登录页、后台布局、导航与标签页 | 保留 | 保留 | 保留 |
|
|
46
|
+
| 首页 | 核心首页 | 核心首页 | 美化演示首页 |
|
|
47
|
+
| 用户、部门、角色、菜单及权限管理 | 保留 | 保留 | 保留 |
|
|
48
|
+
| 个人中心、公共组件、主题和多语言 | 保留 | 保留 | 保留 |
|
|
49
|
+
| 请求封装与前端 API 定义 | 保留 | 保留 | 保留 |
|
|
50
|
+
| 正式 MySQL 权限 SQL | 保留 | 保留 | 保留 |
|
|
51
|
+
| Worker 后端源码与 SQLite 迁移 | 不生成 | 生成 | 生成 |
|
|
52
|
+
| 表格、表单、下载、缓存等示例页面 | 不生成 | 不生成 | 生成 |
|
|
53
|
+
| 展示站部署辅助 | 不生成 | 不生成 | 生成 |
|
|
18
54
|
|
|
19
|
-
|
|
55
|
+
**纯净版包含登录页和首页，也保留完整的核心后台功能。** 它不附带 Worker 后端、示例页面和展示站部署工具，相关依赖、插件和命令也不生成。
|
|
20
56
|
|
|
21
|
-
|
|
57
|
+
所有预设使用真实 HTTP 请求，不附带本地 Mock。纯净版的登录流程、动态菜单和系统管理数据需要对接使用者自己的后端；Worker 版提供可独立部署的后端源码，但需要先初始化并运行后端。完整演示默认连接现有测试 API。
|
|
58
|
+
|
|
59
|
+
### 创建纯净版
|
|
22
60
|
|
|
23
61
|
```sh
|
|
24
62
|
npx @niping9542/create-nova-admin@latest my-admin --preset starter
|
|
63
|
+
cd my-admin
|
|
64
|
+
pnpm install
|
|
65
|
+
pnpm dev
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
开发地址默认 `http://localhost:3000`，端口被占用时以终端打印的地址为准。登录页面可以正常打开；完成真实登录并进入首页，需要可用的后端认证接口。
|
|
69
|
+
|
|
70
|
+
### 创建 Worker 版
|
|
71
|
+
|
|
72
|
+
```sh
|
|
25
73
|
npx @niping9542/create-nova-admin@latest my-worker --preset worker
|
|
26
|
-
|
|
74
|
+
cd my-worker
|
|
75
|
+
pnpm install
|
|
76
|
+
pnpm dev
|
|
27
77
|
```
|
|
28
78
|
|
|
29
|
-
|
|
79
|
+
该预设在纯净版基础上增加 `workers/api/`，后端菜单仅引用核心页面。按生成项目中的 `workers/api/README.md` 完成数据库迁移、密钥与账号初始化，并配置可访问的后端地址。
|
|
30
80
|
|
|
31
|
-
|
|
81
|
+
`pnpm dev` 只启动前端，不会自动启动或部署 Worker。根目录的 `pnpm run check:backend` 用于检查后端构建与测试。
|
|
32
82
|
|
|
33
|
-
|
|
83
|
+
### 创建完整演示
|
|
34
84
|
|
|
35
85
|
```sh
|
|
36
|
-
|
|
86
|
+
npx @niping9542/create-nova-admin@latest my-demo --preset demo
|
|
87
|
+
cd my-demo
|
|
37
88
|
pnpm install
|
|
38
|
-
pnpm dev
|
|
89
|
+
pnpm dev:demo
|
|
39
90
|
```
|
|
40
91
|
|
|
41
|
-
|
|
92
|
+
兼容快捷选项：
|
|
42
93
|
|
|
43
|
-
|
|
94
|
+
```sh
|
|
95
|
+
npx @niping9542/create-nova-admin@latest my-demo --demo
|
|
96
|
+
```
|
|
44
97
|
|
|
45
|
-
|
|
98
|
+
完整演示默认使用测试 API，可使用前面的演示账号。`--demo` 等同于 `--preset demo`，不能同时指定其他预设。
|
|
46
99
|
|
|
47
|
-
##
|
|
100
|
+
## 接入自己的后端
|
|
48
101
|
|
|
49
|
-
|
|
50
|
-
| ---------------------- | -------------------------------------- |
|
|
51
|
-
| `src/` | 核心后台与权限管理 |
|
|
52
|
-
| `database/mysql/` | 所有预设始终保留的正式表结构与基础授权 |
|
|
53
|
-
| `public/`、`build/` | 静态资源与公共构建配置 |
|
|
54
|
-
| `scripts/`、`tests/` | 验证命令与回归测试 |
|
|
55
|
-
| `docs/` | 与所选预设匹配的使用和接口说明 |
|
|
56
|
-
| `workers/api/` | Worker 与 demo 预设的独立后端 |
|
|
57
|
-
| `examples/`、`deploy/` | 仅完整演示预设包含 |
|
|
102
|
+
在创建时指定接口地址：
|
|
58
103
|
|
|
59
|
-
|
|
104
|
+
```sh
|
|
105
|
+
npx @niping9542/create-nova-admin@latest my-admin --preset starter --api-url https://api.example.com
|
|
106
|
+
```
|
|
60
107
|
|
|
61
|
-
|
|
108
|
+
也可以创建后修改生成项目中的 `.env.development.local`：
|
|
62
109
|
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
| `-y, --yes` | 无交互，缺省名称 `nova-admin-app`、缺省纯净版 |
|
|
67
|
-
| `--preset <preset>` | `starter`、`worker`、`demo` |
|
|
68
|
-
| `--demo` | `--preset demo` 的快捷方式 |
|
|
69
|
-
| `--api-url <url>` | HTTP/HTTPS 后端，不包含账号密码、查询参数或片段 |
|
|
70
|
-
| `--ref <ref>` | 模板分支/标签，须支持当前预设目录结构 |
|
|
71
|
-
| `--template-dir <directory>` | 使用本地模板，不下载仓库 |
|
|
72
|
-
| `--version`、`--help` | 版本和帮助 |
|
|
110
|
+
```dotenv
|
|
111
|
+
VITE_API_URL=https://api.example.com
|
|
112
|
+
```
|
|
73
113
|
|
|
74
|
-
|
|
114
|
+
修改后重启开发服务。默认 API 前缀为 `/api`，开发代理会移除该前缀后转发给后端。此地址只配置开发代理；生产环境需要由站点服务器将 `/api` 转发到实际后端。
|
|
75
115
|
|
|
76
|
-
|
|
116
|
+
前端 API 定义位于生成项目的 `src/api/`，接口契约见其中的 `docs/api.md`；后端响应格式有差异时，集中调整 `src/api/protocol/`。
|
|
117
|
+
|
|
118
|
+
完整演示指定自定义 API 后，生成器会写入接口地址并启用演示页面，此时使用打印的 `pnpm dev` 命令启动：
|
|
119
|
+
|
|
120
|
+
```sh
|
|
121
|
+
npx @niping9542/create-nova-admin@latest my-demo --preset demo --api-url https://api.example.com
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
## 生成项目的目录
|
|
125
|
+
|
|
126
|
+
以下是创建后的后台项目目录，不是本生成器仓库的目录。
|
|
127
|
+
|
|
128
|
+
| 目录 | 用途 | 包含的预设 |
|
|
129
|
+
| ----------------- | ---------------------------------------------------------- | ---------------- |
|
|
130
|
+
| `src/` | 登录、首页、布局、权限、系统管理、状态管理、请求与公共组件 | 全部 |
|
|
131
|
+
| `public/` | 网站图标等原样输出的静态资源 | 全部 |
|
|
132
|
+
| `build/` | 公共构建配置和启动加载层 | 全部 |
|
|
133
|
+
| `database/mysql/` | 正式权限表结构与基础授权 SQL | 全部 |
|
|
134
|
+
| `scripts/` | 所选预设需要的开发与检查工具 | 全部 |
|
|
135
|
+
| `tests/` | 前端核心回归与测试辅助 | 全部 |
|
|
136
|
+
| `docs/` | 与所选预设匹配的目录、开发、接口和权限说明 | 全部 |
|
|
137
|
+
| `workers/api/` | 独立后端源码、SQLite 迁移、初始化脚本及测试 | `worker`、`demo` |
|
|
138
|
+
| `examples/` | 演示首页、示例页面、统计 API 与示例测试 | `demo` |
|
|
139
|
+
| `deploy/` | 展示站部署辅助 | `demo` |
|
|
140
|
+
|
|
141
|
+
生成器按预设准备文件，使用者无需先删除 Worker 或演示目录。`node_modules/` 和 `dist/` 等安装、构建产物在本机生成，不随模板复制。
|
|
142
|
+
|
|
143
|
+
### 正式权限 SQL
|
|
144
|
+
|
|
145
|
+
所有预设都保留以下文件，在空 MySQL 数据库中按顺序导入：
|
|
146
|
+
|
|
147
|
+
1. `database/mysql/01-schema.sql`：用户、部门、角色、菜单及关联表，包含索引与约束。
|
|
148
|
+
2. `database/mysql/02-seed.sql`：基础部门、角色、系统管理菜单、按钮权限和授权关系。
|
|
149
|
+
|
|
150
|
+
使用方法见生成项目的 `database/mysql/README.md`。正式 SQL 不包含演示账号，不替使用者选择密码哈希算法；管理员账号由实际后端初始化。Worker 使用独立的 SQLite 迁移，不能把 MySQL 脚本当作 Worker 迁移执行。
|
|
151
|
+
|
|
152
|
+
### 常用命令
|
|
153
|
+
|
|
154
|
+
在生成的后台项目根目录执行：
|
|
155
|
+
|
|
156
|
+
| 命令 | 用途 | 包含的预设 |
|
|
157
|
+
| ------------------------- | -------------------------------------- | ---------------- |
|
|
158
|
+
| `pnpm dev` | 启动前端，按所选预设与本机配置加载页面 | 全部 |
|
|
159
|
+
| `pnpm build` | 类型检查并构建到 `dist/` | 全部 |
|
|
160
|
+
| `pnpm preview` | 预览构建产物，API 转发仍需自行提供 | 全部 |
|
|
161
|
+
| `pnpm run check` | 格式、类型与核心回归检查 | 全部 |
|
|
162
|
+
| `pnpm run check:backend` | 后端构建与回归检查 | `worker`、`demo` |
|
|
163
|
+
| `pnpm dev:demo` | 启动完整演示，默认连接测试 API | `demo` |
|
|
164
|
+
| `pnpm build:demo` | 类型检查并构建完整演示 | `demo` |
|
|
165
|
+
| `pnpm run check:examples` | 示例页面与路由检查 | `demo` |
|
|
166
|
+
| `pnpm run check:all` | 完整演示仓库回归检查 | `demo` |
|
|
167
|
+
|
|
168
|
+
## 命令行选项
|
|
169
|
+
|
|
170
|
+
```sh
|
|
171
|
+
npx @niping9542/create-nova-admin@latest --help
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
| 选项 | 说明 |
|
|
175
|
+
| ---------------------------- | -------------------------------------------------------------------------- |
|
|
176
|
+
| `[project-name]` | 当前目录下的单级项目名，使用小写字母、数字、连字符、下划线或点，不接受路径 |
|
|
177
|
+
| `-y, --yes` | 无交互创建；未指定名称时使用 `nova-admin-app`，未指定预设时使用 `starter` |
|
|
178
|
+
| `--preset <preset>` | 指定 `starter`、`worker` 或 `demo` |
|
|
179
|
+
| `--demo` | `--preset demo` 的快捷方式 |
|
|
180
|
+
| `--api-url <url>` | 自定义 HTTP/HTTPS 后端地址，不接受账号密码、查询参数或片段 |
|
|
181
|
+
| `--ref <ref>` | 模板分支或标签，默认 `main`；目标版本须支持当前预设结构 |
|
|
182
|
+
| `--template-dir <directory>` | 使用本地模板目录，跳过远程模板下载 |
|
|
183
|
+
| `-V, --version` | 显示生成器版本 |
|
|
184
|
+
| `-h, --help` | 显示帮助 |
|
|
185
|
+
|
|
186
|
+
例如，无交互创建默认纯净版：
|
|
187
|
+
|
|
188
|
+
```sh
|
|
189
|
+
npx @niping9542/create-nova-admin@latest my-admin --yes
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
`--yes` 可以与 `--preset worker` 或 `--preset demo` 一起使用。非交互终端不会询问模板，未指定预设时使用纯净版；项目名仍须明确提供，或使用 `--yes` 采用默认名称。
|
|
193
|
+
|
|
194
|
+
已存在的目标目录会导致创建失败，不会被覆盖。生成器不自动安装项目依赖、启动后端、执行 SQL 或部署网站，也不会复制模板中的 Git 历史、本机配置、密钥目录及符号链接。
|
|
195
|
+
|
|
196
|
+
## 维护生成器
|
|
197
|
+
|
|
198
|
+
以下操作在本仓库 `create-nova-admin` 中执行。
|
|
199
|
+
|
|
200
|
+
### 本仓库结构
|
|
201
|
+
|
|
202
|
+
| 路径 | 用途 |
|
|
203
|
+
| ----------------------- | -------------------------------------------------- |
|
|
204
|
+
| `bin/index.js` | CLI 入口，处理项目名称、模板选择、参数和提示 |
|
|
205
|
+
| `src/create-project.js` | 模板获取、输入校验、本机配置写入及创建失败后的清理 |
|
|
206
|
+
| `src/presets.js` | 三种预设的文件组合、依赖快照校验及文档选择 |
|
|
207
|
+
| `tests/` | 参数、预设、目录保护和创建流程的回归测试 |
|
|
208
|
+
| `package.json` | npm 包信息、命令入口、依赖与发布文件清单 |
|
|
209
|
+
| `package-lock.json` | 生成器自身依赖的 npm 锁文件 |
|
|
210
|
+
| `README.md` | GitHub 与 npm 展示的使用说明 |
|
|
211
|
+
|
|
212
|
+
npm 包只包含 CLI 入口、生成逻辑、包信息和本说明，不把后台模板源码打进 npm 包。模板在创建项目时获取。
|
|
213
|
+
|
|
214
|
+
### 本机检查
|
|
77
215
|
|
|
78
216
|
```sh
|
|
79
217
|
npm ci
|
|
80
218
|
npm run check
|
|
81
219
|
npm pack --dry-run
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
如果后台模板和生成器放在同一父目录，可通过本地模板验证：
|
|
223
|
+
|
|
224
|
+
```sh
|
|
82
225
|
node bin/index.js local-admin --yes --preset starter --template-dir ../admin-template
|
|
83
226
|
```
|
|
84
227
|
|
|
85
|
-
|
|
228
|
+
本地模板也必须是包含当前预设差异文件的完整模板仓库。
|
|
229
|
+
|
|
230
|
+
### 更新模板与发布
|
|
231
|
+
|
|
232
|
+
- 只修改后台页面或公共组件时，提交并推送 `admin-template` 的模板分支；之后新创建的项目会获取对应分支内容，已经生成的项目不会自动更新。
|
|
233
|
+
- 修改生成器逻辑或本仓库 README 后，需要发布新的 npm 版本，才能更新 npm 用户拿到的生成器及包说明。
|
|
234
|
+
- 修改模板依赖或核心命令后，在 `admin-template` 执行 `pnpm run update:presets`，同步并提交纯净版依赖和锁文件快照。
|
|
235
|
+
|
|
236
|
+
生成器采用手动发布。在本仓库执行：
|
|
237
|
+
|
|
238
|
+
```sh
|
|
239
|
+
npm version patch --no-git-tag-version
|
|
240
|
+
npm run check
|
|
241
|
+
npm pack --dry-run
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
将本次改动及同步更新的 `package.json`、`package-lock.json` 提交并推送 Git，确认 npm 登录账号具有发布权限后执行：
|
|
245
|
+
|
|
246
|
+
```sh
|
|
247
|
+
npm whoami --registry=https://registry.npmjs.org/
|
|
248
|
+
npm publish --access public --registry=https://registry.npmjs.org/
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
如果登录失效，先执行 `npm login --auth-type=web --registry=https://registry.npmjs.org/`，按终端提示完成认证。
|
|
252
|
+
|
|
253
|
+
发布后检查公开版本：
|
|
254
|
+
|
|
255
|
+
```sh
|
|
256
|
+
npm view @niping9542/create-nova-admin version dist-tags --json --registry=https://registry.npmjs.org/
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
发布命令提示仍在处理时，稍后再查询公开版本。Git 提交和推送不会自动发布 npm，已经发布的版本不能覆盖；重新发布修改后的内容需要递增版本号。
|
|
86
260
|
|
|
87
|
-
|
|
261
|
+
## 许可证
|
|
88
262
|
|
|
89
|
-
|
|
263
|
+
MIT
|