@tushi11/elpis 1.0.1 → 1.0.2

package/.eslintrc.js

@@ -0,0 +1,71 @@
+module.exports = {
+  // 继承的规则集：从已定义的规则集中扩展基础配置
+  extends: [
+    // 'plugin:vue/base',  // Vue 基础规则集（适用于所有 Vue 版本），包含最核心的语法校验（如模板语法错误、组件基础规范），无版本特定规则
+    // 'plugin:vue/recommended',  // Vue 2 推荐规则集（基于 base 扩展），包含 Vue 2 最佳实践（如组件命名、Props 规范等），不兼容 Vue 3 语法
+    // 'plugin:vue/vue3-essential', // Vue 3 核心基础规则集，包含 Vue 3 必备语法校验（如 <template v-for> 支持、Composition API 规范），确保代码可运行
+    'plugin:vue/vue3-recommended', // Vue 3 推荐规则集（基于 vue3-essential 扩展），添加 Vue 3 最佳实践（如避免 XSS 风险、单向数据流规范），适合生产环境
+  ],
+
+  // 启用的 ESLint 插件：这里使用 'vue' 插件（eslint-plugin-vue），提供 Vue 语法校验能力
+  plugins: ['vue'],
+
+  // 运行环境：指定代码运行的环境，ESLint 会识别对应环境的全局变量（如 window、process）
+  env: {
+    browser: true, // 浏览器环境（识别 window、document 等全局变量）
+    node: true, // Node.js 环境（识别 process、require 等全局变量）
+  },
+
+  // 解析器：指定用于解析 Vue 单文件组件（.vue）的专用解析器
+  parser: 'vue-eslint-parser',
+  // 解析器选项：配置解析器的行为
+  parserOptions: {
+    parser: 'babel-eslint', // 指定用于解析 JavaScript 部分的解析器（注：该包已废弃，建议替换为 @babel/eslint-parser）
+    ecmaVersion: 2017, // 支持的 ECMAScript 版本（2017 及以下语法）
+    sourceType: 'module', // 代码模块类型（使用 ES 模块语法：import/export）
+  },
+
+  // 自定义规则：覆盖或补充继承的规则，值含义："off"（关闭）、"warn"（警告）、"error"（报错）// 详细规则说明：https://eslint.org/docs/rules/
+  rules: {
+    // JavaScript 核心规则
+    'no-unused-vars': [2, { args: 'none' }], // 严格检查未使用的变量（报错级别），忽略未使用的函数参数
+    strict: 'off', // 关闭严格模式检查（不强制使用 'use strict'）
+    'valid-jsdoc': 'off', // 关闭 JSDoc 语法有效性检查
+    'jsdoc/require-param-description': 'off', // 关闭 JSDoc 参数描述必填校验
+    'jsdoc/require-param-type': 'off', // 关闭 JSDoc 参数类型必填校验
+    'jsdoc/check-param-names': 'off', // 关闭 JSDoc 参数名一致性检查
+    'jsdoc/require-param': 'off', // 关闭 JSDoc 强制参数说明校验
+    'jsdoc/check-tag-names': 'off', // 关闭 JSDoc 标签名合法性检查
+    'linebreak-style': 'off', // 关闭换行符风格检查（不强制 LF/CRLF）
+    'array-bracket-spacing': 'off', // 关闭数组括号间距检查（如 [1, 2] 与 [ 1, 2 ]）
+    'prefer-promise-reject-errors': 'off', // 关闭 Promise.reject() 必须传入 Error 实例的检查
+    'comma-dangle': 'off', // 关闭对象/数组末尾逗号检查（如 {a:1} 与 {a:1,}）
+    'newline-per-chained-call': 'off', // 关闭链式调用强制换行检查（如 a.b().c()）
+    'no-loop-func': 'off', // 允许在循环中定义函数（可能导致闭包问题，按需开启）
+    'no-empty': 'off', // 允许空代码块（如 if () {}）
+    'no-else-return': 'off', // 允许 else 块中使用 return（不强制提前 return）
+    'no-unneeded-ternary': 'off', // 允许不必要的三元表达式（如 condition ? true : false）
+    'no-eval': 'off', // 允许使用 eval()（存在安全风险，不建议在生产环境关闭）
+    'prefer-destructuring': 'off', // 不强制使用解构赋值（如 const {a} = obj）
+    'no-param-reassign': 'off', // 允许修改函数参数（可能导致副作用，按需开启）
+    'max-len': 'off', // 关闭单行代码长度限制
+    'no-restricted-syntax': 'off', // 不限制使用特定语法（如 for...in 循环）
+    'no-plusplus': 'off', // 允许使用 ++/-- 运算符
+    'no-useless-escape': 'off', // 允许不必要的转义字符（如 \' 在双引号字符串中）
+    'no-nested-ternary': 'off', // 允许嵌套三元表达式
+    radix: 'off', // 关闭 parseInt 必须指定基数的检查
+    'arrow-body-style': 'off', // 不强制箭头函数体风格（如 (a) => { return a } 与 (a) => a）
+    'arrow-parens': 'off', // 不强制箭头函数参数是否带括号（如 a => a 与 (a) => a）
+    // Vue 相关规则
+    'vue/multi-word-component-names': 'off', // 允许组件使用单单词命名（默认要求多单词避免与 HTML 标签冲突）
+    'vue/valid-v-for': 'off', // 关闭 v-for 语法合法性检查（使用自定义校验逻辑）
+    'vue/no-multiple-template-root': 'off', // 允许多根模板（Vue 3 原生支持，默认开启）
+  },
+
+  // 全局变量声明：指定代码中可直接使用的全局变量，无需显式声明
+  globals: {
+    $: true, // 允许使用全局 jQuery 变量（如 $.ajax()）
+    axios: true, // 允许使用全局 axios 变量（如 axios.get()）
+    Vue: true, // 允许使用全局 Vue 变量（如 Vue.createApp()）
+  },
+};

package/README.md

@@ -2,47 +2,53 @@
 
 ## 一个企业级应用框架，通过全栈实现。
 
-### model配置
+### model 配置
+
 ```javascript
 {
   mode: 'dashboard', // 模板类型，不同模板类型对应不一样的模板数据结构
-  name: '', // 名称
-  desc: '', // 描述
-  icon: '', // 图标
-  homePage: '', // 首页(项目配置)
+  name: '', // 模板名称
+  desc: '', // 模板描述
+  icon: '', // 模板图标
+  homePage: '/schema?proj_key=pdd&key=product', // 模板首页(项目配置) // proj_key=项目的文件名 || key=头部菜单栏的默认选中项 || sider_key=左侧菜单栏的默认选中项
   // 头部菜单
   menu: [
     {
       key: '', // 菜单唯一描述
       name: '', // 菜单名称
-      menuType: '', // 枚举值， group / module
+      menuType: '', // 菜单类型(菜单目录、菜单项) group | module
 
       // 当menuType == group时，可填
       subMenu: [
         {
-          // 可递归 menuItem
+          // 可递归的菜单项 menuItem
         },
+          // ...
       ],
 
       // 当menuType == module时，可填
-      moduleType: '', // 枚举值: sider/iframe/custom/schema
+      moduleType: '', // 模块类型: sider | iframe | custom | schema
 
       // 当moduleType == sider 时
       siderConfig: {
         menu: [
           {
-            // 可递归 menuItem(除 moduleType === sider)
+            // 可递归的菜单项 menuItem (除 moduleType === sider)
           },
+            // ...
         ],
       },
+
       // 当moduleType == iframe 时
       iframeConfig: {
-        path: '', // iframe 路径
+        path: '', // iframe 模块路径
       },
+
       // 当moduleType == custom 时
       customConfig: {
         path: '', // 自定义路由路径
       },
+
       // 当moduleType == schema 时
       schemaConfig: {
         api: '', // 数据源API（遵循 RESTFUL 规范）
@@ -50,14 +56,14 @@
           // 板块数据结构
           type: 'object',
           properties: {
-            key: {
-              ...schema, // 标准 schema 配置
+            key1: {
+              ...schema, // 标准 schema 配置 ???
               type: '', // 字段类型
               label: '', // 字段的中文名
               // 字段在 table 中的相关配置
               tableOption: {
                 ...elTableColumnConfig, // 标准 el-table-column 配置
-                toFixed: 0, // 保留小数点后几位
+                toFixed: 0, // 保留几位小数点（数字字段）
                 visible: true, // 默认为 true（为 false 时，表示不在 table 中显示）
               },
               // 字段在 search-bar 中的相关配置
@@ -76,7 +82,7 @@
               // 字段在 createForm 中相关配置
               createFormOption: {
                 ...elComponentConfig, // 标准 el-component 配置
-                comType: '', // 控件型（如 input/select/...）
+                comType: '', // 控件类型（如 input/select/...）
                 visible: true, // 是否展示（true/false）,默认为 true
                 disabled: false, // 是否禁用（true/false）,默认为 false
                 default: '', // 默认值
@@ -104,36 +110,46 @@
         },
         // table 相关配置
         tableConfig: {
+          // 表格头部按钮
           headerButtons: [
             {
               label: '', // 按钮名称
               eventKey: '', // 按钮事件名称
               // 按钮事件具体配置
               eventOption: {
-                // 当 eventKey === 'showComponent'
+                // 当 eventKey === 'showComponent'时，启用 comName,决定调用哪个组件
                 comName: '', // 组件名称
               },
               ...elButtonConfig, // 标准 el-button 配置
             },
-          ], // 表头按钮
+            // ...
+          ],
+          // 表格行内按钮
           rowButtons: [
+           // 按钮事件具体配置
             {
               label: '', // 按钮名称
               eventKey: '', // 按钮事件名称
               eventOption: {
-                // 当 eventKey === 'showComponent'
+                // 当 eventKey === 'showComponent'时，启用 comName,决定调用哪个组件
                 comName: '', // 组件名称
 
+                // 当 eventKey === 'useApi'
+                apiOption: {
+                  api: '', // 接口地址
+                },
+
                 // 当 eventKey === 'remove'时，可填
                 params: {
                   // paramsKey 等于 参数的键值
                   // rowValueKey 等于 参数值，格式为 schema::tableKey，到 table 中找相应的字段
-                  paramsKey: rowValueKey,
+                  paramsKey: rowValueKey, // 【 例如 product_id: 'schema::product_id' 】
                 },
-              }, // 按钮事件具体配置
+              },
               ...elButtonConfig, // 标准 el-button 配置
             },
-          ], // 行按钮
+            // ...
+          ],
         },
         // search-bar 相关配置
         searchConfig: {},
@@ -163,77 +179,290 @@
 }
 ```
 
-
-
 ### 服务端启动
+
 ```javascript
 const { serverStart } = require('@tushi11/elpis');
 
 // 启动 elpis 服务
-const app = serverStart({});
+const app = serverStart({
+    title: 'elpis应用',
+    // 其他配置项
+});
 ```
 
-
-
 ### 自定义服务端
+
 - router-schema
+
+  - app/router-schema/\*\*.js （一定是放在一级目录下的，每份都是配置）
+
+  - ```js
+    module.exports = {
+       '${api1}': ${jsonSchema},
+       '${api2}': ${jsonSchema},
+       '${api3}': ${jsonSchema},
+       '${api4}': ${jsonSchema},
+     }
+    ```
+
 - router
+
 - controller
+
+  - 通过这样的方式去访问 ==> app.controller.customModule.customController
+
 - service
+
 - extend
+
 - config
 
+  - 目录下对应的 config 配置 （app/config/config.xxxx.js）
+
+  * 默认配置 config/config.default.js
+  * 本地配置 config/config.local.js
+  * 测试配置 config/config.beta.js
+  * 生产配置 config/config.prod.js
+
+    ```js
+    // config.prod.js
+    module.exports = {
+      name: 'demo-prod'
+    }
+    ```
+
+
+
+
+
+1. 在 router-schema 定义接口的入参出参的json-schema，实现接口的入参出参校验能力，这一能力的提供者是elpis的中间件```api-params-verify```。
+
+   ```js
+   module.exports = {
+     '/api/demo': {
+       get: {
+         query: {
+           type: 'object',
+           properties: {
+             key: {
+               type: 'string',
+             }
+           }
+         }
+       }
+     }
+   }
+   ```
+
+
+
+2. 在router中定义接口路由。
+
+   ```js
+   module.exports = (app, router) => {
+     const { demo: demoController } = app.controller;
+     router.get('/api/demo', demoController.get.bind(demoController));
+   }
+   ```
+
+
+
+3. 在controller中定义接口处理器。
+
+   ```js
+   module.exports = (app) => {
+     return class DemoController {
+       get(ctx) {
+         this.success(ctx, [{a: 1, b: 'demo'}], {
+           total: 3,
+         })
+       }
+     }
+   }
+   ```
+
+
+
+4. 在service中定义接口处理服务。
+
+   ```js
+   module.exports = (app) => class DemoService {
+     // sevice 能力
+   }
+   ```
+
+5. 在extend中定义其他扩展能力。elpis内置了日志功能，基于log4js。
+
+6. 在根目录的config中定义项目的变量。
+
+   ```js
+   // config.dev.js
+   module.exports = {
+     name: 'demo-default'
+   }
+   ```
+
+   ```js
+   // config.prod.js
+   module.exports = {
+     name: 'demo-prod'
+   }
+   ```
+
+
+
 
 
 ### 前端构建
+
 ```javascript
+// build.js
 const { frontendBuild } = require('@tushi11/elpis');
 
-// 编译构建前端工程
+// 编译构建前端工程 - 这里会根据环境变量自动选择启动开发环境还是打包生产环境
 frontendBuild(process.env._ENV);
 ```
 
 
 
-### 自定义页面拓展
-* 在 `app/pages/` 目录下写入口 entry.xxx.js
+### 拓展开发
+
+#### 自定义页面拓展
+
+- 在 `app/pages/` 目录下写入口 entry.xxx.js
+
+  定义一个demo页面
+
+  ```js
+  // app/pages/demo/entry.demo.js
+  import elpisBoot from '@elpisBoot';
+  import DemoVue from './demo.vue'
+  elpisBoot(DemoVue);
 
-### dashboard / custom-view 自定义页面扩展
-* 在 `app/pages/dashboard/xxx` 下写页面
+  // demo.vue
+  <template>
+    <div style="color: red;">
+      demo
+      <el-input v-model="value" />
+    </div>
+  </template>
+
+  <script setup>
+  import { ref, watch } from 'vue'
+  const value = ref('');
+
+  watch(value, (newvalue, oldvalue) => {
+    console.log(oldvalue, newvalue);
+  })
+  </script>
+
+  <style scoped lang="less"></style>
+  ```
+
+
+
+#### dashboard / custom-view 自定义页面扩展
+
+- 在 `app/pages/dashboard/xxx` 下写页面
+
+#### dashboard / schema-view / components 动态组件扩展
 
-### dashboard / schema-view / components 动态组件扩展
 1. 在 `app/pages/dashboard/complex-view/schema-view/components` 下写组件
 2. 配置到 `app/pages/dashboard/complex-view/schema-view/components/components-config.js`
 
-### schema-form 控件扩展
-1. 在 `app/widgets/schema-form/complex-view` 下写控件
-2. 配置到 `app/widgets/schema-form/form-item-config.js`
+#### schema-form 控件扩展
+
+1. 在 `app/pages/widgets/schema-form/complex-view` 下写控件
+2. 配置到 `app/pages/widgets/schema-form/form-item-config.js`
+
+#### schema-search-bar 控件扩展
+
+1. 在 `app/pages/widgets/schema-search-bar/complex-view` 下写控件
+2. 配置到 `app/pages/widgets/schema-search-bar/search-item-config.js`
+
+#### header-container 控件扩展
 
-### schema-search-bar 控件扩展
-1. 在 `app/widgets/schema-search-bar/complex-view` 下写控件
-2. 配置到 `app/widgets/schema-search-bar/search-item-config.js`
+1. 在 `app/pages/widgets/header-container/complex-view` 下写控件
+2. 配置到 `app/pages/widgets/header-container/header-config.js`
 
 
 
-## 规范
+## 规范(约定优于配置)
 
 ### 引入组件
+
 1. 在 JS 中，用 大写开头的驼峰
+
    ```
    import HeaderContainer from '$elpisWidgets/header-container/header-container.vue';
    ```
 
-2. 在template中，用【小写 + '-'】连接（传参数，命名都用这个规则）
+2. 在 template 中，用【小写 + '-'】连接（传参数，命名都用这个规则）
    ```
    <header-container :title="'项目列表'"></header-container>
    ```
 
 ### 组件传参
+
 1. 组件传参用【'-'】，不用驼峰。
    ```
    <sub-menu :menu-item="item"></sub-menu>
    ```
 2. 组件接收参数可以用驼峰
-   ```
+   ```js
    const { menuItem } = defineProps(['menuItem']);
    ```
+
+### 方法命名
+
+onMenuSelect：用户点击的事件方法
+
+- 比如做埋点的时候，不是用户点击而是逻辑中调用的，那么记录就有问题了
+
+handleMenuSelect：逻辑中调用方法
+
+### pages的目录结构
+
+- pages里所有entry开头的js文件都是多页面。
+- 多页面进去以后每一个页面渲染后都是用vue启动的vue实例，所以进来以后又是一个spa的单页面应用。
+  - 比如进入到dashboard页面，又因为dashboard是用boot方法来启动的（用了vue3的createApp构建出来的），所以它又是一个单页面应用
+
+- 子模块/子组件，统一放到complex-view下面
+
+  - 子模块的内容与该页面是强相关，所以放在同一个页面下。全局使用的组件放在widgets下。
+
+  ```
+  |--pages
+  	|--dashboard
+  		|--complex-view
+  			|--header-view // 子模块父文件夹
+  				|--asserts // 里面放只应用在该子模块的资源
+  					|--xxx.png
+  				|--header-view.vue // 必须用一个父文件夹包裹。因为把资源单独放在了通用的资源文件夹里，容易在删除整个模块时漏删了。
+  		|--dashboard.vue
+  		|--entry.dashboard.js
+  ```
+
+
+
+
+
+### 后端定义路由
+
+- 渲染页面的用 `/view/` 开头： router.get('/view/:page', viewController.renderPage.bind(viewController));
+- 接口用 `/api/` 开头：router.post('/api/auth/login', authController.login.bind(authController));
+  - 如果携带 proj_key 的业务api要用`/api/proj/`开头： router.get('/api/proj/user', userController.get.bind(userController));
+
+
+### model模型配置的目录结构
+
+```js
+// modelList => projectList => menuList
+|--app
+|--model
+	|-- xxx（自定义的模型名称，如buiness/people）
+		|-- model.js (基类。需要放在自定义的model模型目录下)
+		|-- project
+			|-- xxx.js (子类。如jd.js/pdd.js。项目文件必须放在project目录下)
+```

package/app/controller/base.js

@@ -5,9 +5,9 @@ module.exports = (app) =>
      * 统一收拢 controller 相关的公共方法
      */
     constructor() {
-      this.app = app;
-      this.config = app.config;
-      this.service = app.service;
+      // this.app = app;
+      // this.config = app.config;
+      // this.service = app.service;
     }
 
     /**
@@ -32,7 +32,6 @@ module.exports = (app) =>
      * @param {object} code 错误码
      */
     fail(ctx, message, code) {
-      // ctx.status = 200;
       ctx.body = {
         success: false,
         message,

package/app/controller/project.js

@@ -1,3 +1,4 @@
+const axios = require('axios');
 module.exports = (app) => {
   const BaseController = require('./base')(app);
   return class ProjectController extends BaseController {
@@ -14,6 +15,10 @@ module.exports = (app) => {
         this.fail(ctx, '获取项目异常', 50000);
         return;
       }
+      if (!projConfig.homePage) {
+        this.fail(ctx, `${projConfig.name} - 未找到homePage`, 50000);
+        return;
+      }
 
       this.success(ctx, projConfig);
     }
@@ -23,17 +28,24 @@ module.exports = (app) => {
      */
     getList(ctx) {
       const { proj_key: projKey } = ctx.request.query;
-
       const { project: projectService } = app.service;
       const projectList = projectService.getList({ projKey });
+      let errorMsg = null;
 
       // 构造关键数据 list
       const dtoProjectList = projectList.map((item) => {
         const { modelKey, key, name, desc, homePage } = item;
+        if (!homePage) {
+          return (errorMsg = item);
+        }
         return { modelKey, key, name, desc, homePage };
       });
 
-      this.success(ctx, dtoProjectList);
+      if (errorMsg) {
+        return this.fail(ctx, `${errorMsg.name} - 未找到homePage`, 50000);
+      } else {
+        this.success(ctx, dtoProjectList);
+      }
     }
 
     /**
@@ -42,6 +54,7 @@ module.exports = (app) => {
     async getModelList(ctx) {
       const { project: projectService } = app.service;
       const modelList = await projectService.getModelList();
+      let errorMsg = null;
 
       // 构造返回结果，只返回关键数据
       const dtoModelList = modelList.reduce((preList, item) => {
@@ -53,8 +66,11 @@ module.exports = (app) => {
 
         // 构造 project 关键数据
         const dtoProject = Object.keys(project).reduce((preObj, projKey) => {
-          const { key, name, desc, homePage } = project[projKey];
-          preObj[projKey] = { key, name, desc, homePage };
+          const { key, name, desc, homePage, modelKey } = project[projKey];
+          if (!homePage) {
+            return (errorMsg = project[projKey]);
+          }
+          preObj[projKey] = { key, name, desc, homePage, modelKey };
           return preObj;
         }, {});
         // 另一种写法
@@ -72,7 +88,44 @@ module.exports = (app) => {
 
         return preList;
       }, []);
-      this.success(ctx, dtoModelList);
+
+      if (errorMsg) {
+        this.fail(ctx, `${errorMsg.name} - 未找到homePage`, 50000);
+      } else {
+        this.success(ctx, dtoModelList);
+      }
+    }
+
+    /**
+     * 获取城市天气信息
+     * @param {string} city 城市名称
+     * @example https://api.bugpk.com/api/citywid?city=朝阳
+     */
+    async getCityWeather(ctx) {
+      const { city } = ctx.request.query;
+
+      const res = await axios({
+        method: 'get',
+        url: 'https://api.bugpk.com/api/citywid',
+        params: {
+          city: city || '朝阳',
+        },
+      });
+      if (res.status !== 200) return this.fail(ctx, '获取天气信息失败', 50000);
+
+      const dtoRes = JSON.parse(JSON.stringify(res.data));
+
+      if (dtoRes.success === true) {
+        return this.success(ctx, dtoRes.results, { total: dtoRes.count });
+      }
+
+      try {
+        const firstJsonStr = dtoRes.split('}')[0] + '}'; // 拼接回完整的第一个JSON
+        const firstJson = JSON.parse(firstJsonStr);
+        return this.fail(ctx, firstJson.error, 50000);
+      } catch (e) {
+        return this.fail(ctx, '获取天气信息失败', 50000);
+      }
     }
   };
 };

package/app/controller/view.js

@@ -9,6 +9,7 @@ module.exports = (app) => {
       app.logger.info(`[ViewController] query: ${JSON.stringify(query)}`);
       app.logger.info(`[ViewController] params: ${JSON.stringify(params)}`);
       await ctx.render(`dist/entry.${ctx.params.page}`, {
+        // 利用 SSR 服务端渲染，将参数注入到前端模板中。
         projKey: ctx.query?.proj_key,
         name: app.options?.name,
         env: app.env.get(),

package/app/extend/moment.js

@@ -0,0 +1,3 @@
+module.exports = (app) => {
+  return require('moment');
+};

package/app/middleware/error-handler.js

@@ -9,7 +9,7 @@ module.exports = (app) => {
     } catch (err) {
       // 异常处理
       const { status, message, detail } = err;
-      app.logger.info(JSON.stringify(err));
+      app.logger.info('[-- exception --]:', JSON.stringify(err));
       app.logger.error('[-- exception --]:', err);
       app.logger.error('[-- exception --]:', status, message, detail);