feat: nest补充docker和开发文档&vue新增开发文档 (opentiny#205)

* fix: nest补充dockerfile和docker-compose.yml * feat: vue新增开发文档 * fix: nest后端dockerfile和docker-compose.yml文件补充 * fix: vue开发文档补充 * fix: vue开发文档修改vite启动命令 * feat: nest新增开发文档 * fix: 更新开发文档&更新package.json文件&添加展示图片
whmmm · Sep 7, 2024 · 348ddf0 · 348ddf0
1 parent 207757d
commit 348ddf0
Show file tree

Hide file tree

Showing 16 changed files with 549 additions and 10 deletions.
diff --git a/docs/images/tiny-pro-show.png b/docs/images/tiny-pro-show.png
diff --git a/docs/tiny-nest.md b/docs/tiny-nest.md
@@ -0,0 +1,161 @@
+# TinyPro 后端部署指南
+
+## 环境准备
+
+请确保您安装了`nodejs`, `npm`, `tiny-cli`
+
+```bash
+tiny init pro
+```
+
+输入完成上述命令后，请根据指引输入您的信息
+
+```
+? 请输入项目名称： tiny-pro
+? 请输入项目描述： 基于TinyPro套件创建的中后台系统
+* 请选择您希望使用的客户端技术栈： vue
+* 请选择您希望使用的服务端技术栈： Nest.js
+* 请选择你想要的构建工具:  Vite
+* 请确保已安装数据库服务（参考文档
+https://www.opentiny.design/tiny-cli/docs/toolkits/pro#database）：
+已完成数据库服务安装，开始配置
+* 请选择数据库类型： MySql
+* 请输入数据库地址： localhost
+* 请输入数据库端口： 3306
+* 请输入数据库名称： ospp-nest
+* 请输入登录用户名： root
+* 请输入密码： [hidden]
+```
+
+## 目录结构
+
+```
+├── .env                        环境变量文件
+├── docker-compose.yml          docker-compose 启动文件
+├── dockerfile                  docker镜像构建问及那
+├── libs                        公用模块
+│   ├── db                      数据库连接
+│   ├── models                  数据库结构
+│   └── redis                   redis链接
+├── locales.json                国际化数据库初始化我呢见
+├── src                         源码
+    ├── app.module.ts
+    ├── auth                    鉴权接口
+    ├── employees
+    ├── global.d.ts             全局类型
+    ├── i18                     后端国际化文件 (报错信息等公用国际化字段)
+    ├── i18n                    国际化接口
+    ├── main.ts                 nest主入口
+    ├── menu                    菜单接口
+    ├── permission              权限接口
+    ├── public                  公共文件(修饰器等)
+    ├── role                    角色接口
+    └── user                    用户接口
+```
+## 环境变量
+
+环境变量存在于 `.env` 文件下，您可以根据需求自行修改.
+
+```properties
+# 数据库IP
+DATABASE_HOST = 'localhost'
+# 数据库端口
+DATABASE_PORT = 3306
+# 数据库用户名
+DATABASE_USERNAME = 'root'
+# 数据库密码
+DATABASE_PASSWORD = 'root'
+# 数据库名 (请确保该库存在)
+DATABASE_NAME = 'ospp-nest'
+# 请阅读: https://www.typeorm.org/migrations
+# 线上环境请关闭
+DATABASE_SYNCHRONIZE = 'true'
+DATABASE_AUTOLOADENTITIES = 'true'
+# jwt secret
+AUTH_SECRET = 'secret'
+REDIS_SECONDS = 7200
+# redis ip
+REDIS_HOST = 'localhost'
+# redis 端口
+REDIS_PORT = 6379
+# token过期时间
+EXPIRES_IN = '2h'
+# 分页默认起始页 (一般可以不修改)
+PAGINATION_PAGE = 1
+# 分页默认大小
+PAGINATION_LIMIT = 10
+```
+
+## 快速上手
+
+### Docker
+
+```bash
+# 该compose文件会启动三个服务
+# 1. mysql
+# 2. redis
+# 3. 业务服务器
+docker compose up -d
+```
+
+### 命令启动
+
+```bash
+npm i
+npm run start
+```
+
+## 权限管理
+
+### Token管理
+
+凡是没有被`Public`修饰器修饰的接口，均会被`auth/auth.guard.ts`进行校验, 如果token不存在、token过期、token不合法，均会不允许访问
+
+### 权限控制
+
+如果一个接口没有被`Permission`修饰器进行修饰, 那么这个接口是允许所有已登录用户访问的，如果该接口被`Permission`修饰器进行修饰，那么该接口只允许拥有该权限的用户访问，其余用户则会返回`403`错误代码
+
+## 新增接口
+
+与普通的`nest.js`项目开发完全一致，请阅读:[nest.js 文档](https://docs.nestjs.com/)
+
+## 国际化
+
+> 这里的国际化指的是报错信息的国际化
+
+后端采用的是`nestjs-i18n`依赖库。国际化词条放在`i18n/<lang>/xxx.json`下
+
+```
+i18n
+  enUS
+    exception.json
+    validation.json
+  zhCN
+    exception.json
+    validation.json
+```
+
+目前仅支持`enUS`与`zhCN`两种语言，且`fallback`为`enUS`.
+
+## 打包构建
+
+> 这里只阐述tiny-pro后端打包, 如果您进行了二次开发，请自行检查dockerfile
+
+### docker打包
+
+```bash
+docker build -t tinypro:latest .
+```
+
+### 命令打包
+
+```bash
+npm run build
+```
+
+## 常见问题
+
+### 提示 `Lock file exists, if you want init agin, please remove dist or dist/lock`
+
+为了避免重复初始化，系统会在第一次初始化的时候在`dist`目录下新建`app/lock`文件，如果您需要再次初始化，那么请您删除`dist/app`或者直接删除`dist`文件夹
+
diff --git a/docs/tinyvue.md b/docs/tinyvue.md
@@ -0,0 +1,152 @@
+# TinyPro of vue3
+
+## 环境准备
+
+请确保您安装了`nodejs`, `npm`, `tiny-cli`
+
+```bash
+tiny init pro
+```
+
+输入完成上述命令后，请根据指引输入您的信息
+
+```
+? 请输入项目名称： tiny-pro
+? 请输入项目描述： 基于TinyPro套件创建的中后台系统
+* 请选择您希望使用的客户端技术栈： vue
+* 请选择您希望使用的服务端技术栈： Nest.js
+* 请选择你想要的构建工具:  Vite
+* 请确保已安装数据库服务（参考文档
+https://www.opentiny.design/tiny-cli/docs/toolkits/pro#database）：
+已完成数据库服务安装，开始配置
+* 请选择数据库类型： MySql
+* 请输入数据库地址： localhost
+* 请输入数据库端口： 3306
+* 请输入数据库名称： ospp-nest
+* 请输入登录用户名： root
+* 请输入密码： [hidden]
+```
+
+```bash
+# terminal 1
+cd web
+npm i
+npm run start
+# terminal 2
+cd nestJs
+npm i
+npm run start
+```
+
+出现下图即代表启动成功
+
+![](./images/tiny-pro-show.png)
+
+## 结构
+
+```
+├─nestJs (后端)
+│  ├─.env                 (环境变量)
+│  └─src
+│      ├─.generate
+│      ├─auth             (鉴权接口)
+│      ├─i18              (国际化接口)
+│      ├─i18n             (后端国际化文件)
+│      ├─menu             (菜单接口)
+│      ├─permission       (权限接口)
+│      ├─public           (公共文件)
+│      ├─role             (角色接口)
+│      └─user             (用户接口)
+└─web                     (前端)
+    ├─config
+    │  ├─plugin
+    │  └─utils
+    ├─docs                (文档)
+    ├─public
+    └─src
+        ├─api             (api管理)
+        ├─assets          (静态资源)
+        ├─components      (全局组件)
+        ├─config
+        ├─directive       (指令)
+        ├─hooks           (通用钩子)
+        ├─layout          (布局组件)
+        ├─locale          (前端国际化文件)
+        ├─mock            (静态资源)
+        ├─router          (路由)
+        ├─store           (全局状态管理)
+        ├─types           (全局类型)
+        ├─utils           (工具函数)
+        └─views           (页面)
+```
+
+## 二次开发
+
+### 菜单与路由
+
+#### 路由
+
+`tiny-pro`除了公共路由之外，其余路由均由后端生成一份特殊的数据结构，前端在`router/guard/menu.ts`下组合并动态添加。这样的好处是用户不会出现「闪现」问题
+
+```ts
+interface ITreeNodeData {
+  // node-key='id' 设置节点的唯一标识
+  id: number | string;
+  // 节点显示文本
+  label: string;
+  // 子节点
+  children?: ITreeNodeData[];
+  // 链接
+  url: string;
+  //组件
+  component: string;
+  //图标
+  customIcon: string;
+  //类型
+  menuType: string;
+  //父节点
+  parentId: number;
+  //排序
+  order: number;
+  //国际化
+  locale: string;
+}
+```
+
+#### 路由
+
+后端返回`ITreeNodeData`的数据结构后，前端将会在`router/guard/menu.ts`下`toRoutes`函数将`ITreeNodeData`转换为符合`vue-router`结构的数据结构，并动态添加。
+
+#### 新增页面
+
+`tiny-pro`的二次开发与普通的页面没有什么显著的差异。唯一的差异则是需要在`系统管理/菜单管理`下新建菜单，而后在`系统管理/角色管理`下为相应的用户绑定菜单即可
+
+> 注：
+>
+>   优先级：菜单上下排列顺序，优先级越小，排列越靠近上方
+>
+>   父菜单ID：可选，选择当前已存在菜单作为父节点
+>
+>   组件：src/views下新增的组件，比如对src/views/board/home/index.vue组件，填写内容为board/home/index，截取views后的相对路径即可
+>
+>   路径：访问新增菜单的url，比如对src/views/board/home/index.vue组件，填写为board
+>
+>   国际化：为新增菜单选择对应的显示词条，若不存在合适词条，在“系统管理/国际化管理”中添加新词条即可
+
+### 权限控制
+
+权限控制由管理员在创建角色时分配角色，角色对应一个权限列表。当用户登录时，后端将会返回token，用户需要携带token请求自身信息与菜单(`ITreeNodeData`结构)。并通过`router/guard/menu.ts`中的`toRoutes`函数，将`ITreeNodeData`结构转为`vue-router`所需要的结构，并动态进行添加。
+
+#### 组件级权限控制
+
+> 组件级权限管理又称按钮级权限管理
+
+`tiny-pro`对按钮级权限控制采用的是指令的方式，对于需要保护的组件只需要使用`v-permission="'<需要的权限>'"`即可。如果用户存在该权限，那么将会展示该组件，否则不会展示该组件。
+
+### 国际化
+
+`tiny-pro`除了登陆页面的国际化会在本地之外，其余国际化字段均需要使用`系统管理/国际化管理`进行添加。这么做的好处是可以很有效的减少产物的大小, 并且对于大型中后台而言, 可以使得国际化小组不与前端工程师产生耦合。
+
+### 打包构建
+
+目前`tiny-pro`支持`vite`, `webpack`, `rspack`三种打包方案（在初始化阶段任选其一）。只需要运行`npm run build`即可
diff --git a/packages/plugins/link/package.json b/packages/plugins/link/package.json
@@ -41,7 +41,7 @@
     "test": "run-s build test:*",
     "test:lint": "tslint --project . && prettier \"src/**/*.ts\" --list-different",
     "test:unit": "nyc --silent ava",
-    "watch": "run-s clean build:main && run-p \"build:main -- -w\" \"test:unit -- --watch\"",
+    "watch": "run-s clean build:main && run-p \"build:main -- -w\"  ",
     "cov": "run-s build test:unit cov:html && open-cli coverage/index.html",
     "cov:html": "nyc report --reporter=html",
     "cov:send": "nyc report --reporter=lcov && codecov",

diff --git a/packages/plugins/lint/package.json b/packages/plugins/lint/package.json
@@ -38,7 +38,7 @@
     "test": "run-s build test:*",
     "test:lint": "tslint --project . && prettier \"src/**/*.ts\" --list-different",
     "test:unit": "nyc --silent ava",
-    "watch": "run-s clean build:main && run-p \"build:main -- -w\" \"test:unit -- --watch\"",
+    "watch": "run-s clean build:main && run-p \"build:main -- -w\"  ",
     "cov": "run-s build test:unit cov:html && open-cli coverage/index.html",
     "cov:html": "nyc report --reporter=html",
     "cov:send": "nyc report --reporter=lcov && codecov",
@@ -66,13 +66,13 @@
   "engines": {
     "node": ">=8.9"
   },
-  "dependencies": {    
+  "dependencies": {
   },
   "devDependencies": {
     "@opentiny/cli-devkit": "^1.0.1",
     "@opentiny/eslint-config": "^1.0.0",
     "chalk": "^2.4.2",
-    "inquirer": "^6.5.1",    
+    "inquirer": "^6.5.1",
     "@bitjson/npm-scripts-info": "1.0.0",
     "@types/node": "12.6.8",
     "ava": "2.2.0",

diff --git a/packages/toolkits/dev/package.json b/packages/toolkits/dev/package.json
@@ -26,7 +26,7 @@
     "test": "run-s build test:*",
     "test:lint": "tslint --project . && prettier \"src/**/*.ts\" --list-different",
     "test:unit": "nyc --silent ava",
-    "watch": "run-s clean build:main && run-p \"build:main -- -w\" \"test:unit -- --watch\"",
+    "watch": "run-s clean build:main && run-p \"build:main -- -w\"",
     "cov": "run-s build test:unit cov:html && open-cli coverage/index.html",
     "cov:html": "nyc report --reporter=html",
     "cov:send": "nyc report --reporter=lcov && codecov",

diff --git a/packages/toolkits/dev/template/plugin/package.json b/packages/toolkits/dev/template/plugin/package.json
@@ -36,7 +36,7 @@
     "test": "run-s build test:*",
     "test:lint": "tslint --project . && prettier \"src/**/*.ts\" --list-different",
     "test:unit": "nyc --silent ava",
-    "watch": "run-s clean build:main && run-p \"build:main -- -w\" \"test:unit -- --watch\"",
+    "watch": "run-s clean build:main && run-p \"build:main -- -w\"  ",
     "cov": "run-s build test:unit cov:html && open-cli coverage/index.html",
     "cov:html": "nyc report --reporter=html",
     "cov:send": "nyc report --reporter=lcov && codecov",

diff --git a/packages/toolkits/dev/template/toolkit/package.json b/packages/toolkits/dev/template/toolkit/package.json
@@ -36,7 +36,7 @@
     "test": "run-s build test:*",
     "test:lint": "tslint --project . && prettier \"src/**/*.ts\" --list-different",
     "test:unit": "nyc --silent ava",
-    "watch": "run-s clean build:main && run-p \"build:main -- -w\" \"test:unit -- --watch\"",
+    "watch": "run-s clean build:main && run-p \"build:main -- -w\"  ",
     "cov": "run-s build test:unit cov:html && open-cli coverage/index.html",
     "cov:html": "nyc report --reporter=html",
     "cov:send": "nyc report --reporter=lcov && codecov",

diff --git a/packages/toolkits/docs/package.json b/packages/toolkits/docs/package.json
@@ -38,7 +38,7 @@
     "test": "run-s build test:*",
     "test:lint": "tslint --project . && prettier \"src/**/*.ts\" --list-different",
     "test:unit": "nyc --silent ava",
-    "watch": "run-s clean build:main && run-p \"build:main -- -w\" \"test:unit -- --watch\"",
+    "watch": "run-s clean build:main && run-p \"build:main -- -w\"  ",
     "cov": "run-s build test:unit cov:html && open-cli coverage/index.html",
     "cov:html": "nyc report --reporter=html",
     "cov:send": "nyc report --reporter=lcov && codecov",

diff --git a/packages/toolkits/pro/package.json b/packages/toolkits/pro/package.json
@@ -25,7 +25,7 @@
     "test": "run-s build test:*",
     "test:lint": "tslint --project . && prettier \"src/**/*.ts\" --list-different",
     "test:unit": "nyc --silent ava",
-    "watch": "run-s clean build:main && run-p \"build:main -- -w\" \"test:unit -- --watch\"",
+    "watch": "run-s clean build:main && run-p \"build:main -- -w\"  ",
     "cov": "run-s build test:unit cov:html && open-cli coverage/index.html",
     "cov:html": "nyc report --reporter=html",
     "cov:send": "nyc report --reporter=lcov && codecov",

diff --git a/packages/toolkits/pro/template/server/nestJs/.dockerignore b/packages/toolkits/pro/template/server/nestJs/.dockerignore
@@ -0,0 +1,3 @@
+node_modules
+.gitignore
+dist