@jiangliffey/elpis 1.0.0

package/.eslintignore

@@ -0,0 +1,3 @@
+node_modules/
+public/
+docs/

package/.eslintrc

@@ -0,0 +1,55 @@
+{
+  "extends": [
+    "plugin:vue/base",
+    "plugin:vue/recommended"
+  ],
+  "plugins": ["vue"],
+  "env": {
+    "browser": true,
+    "node": true
+  },
+  "parser": "vue-eslint-parser",
+  "parserOptions": {
+    "parser": "babel-eslint",
+    "ecmaVersion": 2017,
+    "sourceType": "module"
+  },
+  "rules": {
+    "no-unused-vars": [2, {"args": "none"}],
+    "strict": "off",
+    "valid-jsdoc": "off",
+    "jsdoc/require-param-description": "off",
+    "jsdoc/require-param-type": "off",
+    "jsdoc/check-param-names": "off",
+    "jsdoc/require-param": "off",
+    "jsdoc/check-tag-names": "off",
+    "linebreak-style": "off",
+    "array-bracket-spacing": "off",
+    "prefer-promise-reject-errors": "off",
+    "comma-dangle": "off",
+    "newline-per-chained-call": "off",
+    "no-loop-func": "off",
+    "no-empty": "off",
+    "no-else-return": "off",
+    "no-unneeded-ternary": "off",
+    "no-eval": "off",
+    "prefer-destructuring": "off",
+    "no-param-reassign": "off",
+    "max-len": "off",
+    "no-restricted-syntax": "off",
+    "no-plusplus": "off",
+    "no-useless-escape": "off",
+    "no-nested-ternary": "off",
+    "radix": "off",
+    "arrow-body-style": "off",
+    "arrow-parens": "off",
+    "vue/multi-word-component-names": "off",
+    "vue/valid-v-for": "off",
+    "vue/no-multiple-template-root": "off"
+  },
+  "globals": {
+    "$": true,
+    "axios": true,
+    "Vue": true
+  }
+}

package/CLAUDE.md

@@ -0,0 +1,81 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+npm run dev      # Start dev server with nodemon (env: local)
+npm run beta     # Start beta server (env: beta)
+npm run prod     # Start production server (env: production)
+npm run build:dev   # Webpack dev build (HMR dev server on port 9002)
+npm run build:prod  # Webpack production build
+npm run lint     # ESLint --quiet on .js/.vue files
+```
+
+- Server listens on port 8080 by default (set `PORT` env var to override).
+- Tests use Mocha + Supertest (no dedicated test script in package.json — run `npx mocha`).
+
+## Project Architecture
+
+Full-stack enterprise application framework powered by a custom **elpis-core** bootstrap.
+
+### elpis-core Framework (`elpis-core/`)
+
+Custom Koa-based framework that auto-discovers and loads app components. Bootstrap order:
+
+1. **middleware** — loads `app/middleware/**/*.js` into `app.middlewares.{dir}.{name}`
+2. **router-schema** — loads `app/router-schema/**/*.js` into `app.routerSchema` (JSON Schema for API param validation via ajv)
+3. **controller** — loads `app/controller/**/*.js` into `app.controller.{dir}.{name}` (instantiated as classes)
+4. **service** — loads `app/service/**/*.js` into `app.service.{dir}.{name}` (instantiated as classes)
+5. **config** — merges `config/config.default.js` with env-specific override (`config.local.js`/`config.beta.js`/`config.prod.js`) into `app.config`
+6. **extend** — loads `app/extend/**/*.js`, mounted directly onto `app` object (conflict-protected)
+
+Then registers global middleware from `app/middleware.js`, then routes from `app/router/`, then starts the server.
+
+### Global Middleware Pipeline (`app/middleware.js`)
+
+1. `koa-static` — serves `app/public`
+2. `koa-nunjucks-2` — template rendering (`.tpl` files)
+3. `koa-bodyparser` — request body parsing (json/form/text, 1000mb limit)
+4. `app.middlewares.errorHandler` — catches and formats errors
+5. `app.middlewares.apiSignVerify` — MD5-based signature verification on `/api/*` routes
+6. `app.middlewares.apiParamsVerify` — JSON Schema param validation against `app.routerSchema`
+
+### API Conventions
+
+- All API routes under `/api/`
+- Response format: `{ success: true, data, metadata }` or `{ success: false, message, code }`
+- Signature auth: MD5 of `{signKey}_{timestamp}` sent in headers `s_sign`/`s_t` (600s expiry)
+- Base controller (`app/controller/base.js`) provides `success(ctx, data, metadata)` and `fail(ctx, message, code)` helpers
+- Base service (`app/service/base.js`) exposes `this.curl` (superagent) and `this.config`
+
+### Frontend (`app/pages/`)
+
+Vue 3 + Element Plus + Pinia + Vue Router. Pages are auto-discovered via glob `app/pages/**/entry.*.js`.
+
+- `boot.js` — Vue app bootstrap (creates app, mounts Element Plus/Pinia/Router)
+- Each page has `entry.{page}.js` + `{page}.vue`
+- Webpack splits bundles: vendor (node_modules), common (shared modules), entry.{page} (page-specific)
+- Dev: HMR-enabled on port 9002, outputs to `app/public/dist/dev/`
+- Prod: outputs to `app/public/dist/`
+- Path aliases: `$elpisPages`, `$elpisCommon`, `$elpisWidgets`, `$elpisStore`
+
+### Directory Layout
+
+```
+app/
+  controller/    # Controllers (class per file, receives `app` in factory)
+  service/       # Services (class per file, extends BaseService)
+  middleware/    # Koa middleware (function(app) => async fn)
+  router/        # Route definitions (receives app + koa-router)
+  router-schema/ # JSON Schema for API param validation
+  extend/        # Extensions merged into Koa app instance
+  pages/         # Vue 3 frontend pages
+  webpack/       # Webpack config (base/dev/prod)
+  view/          # Nunjucks templates (.tpl)
+  public/        # Static assets
+  middleware.js  # Global middleware registration
+config/          # Environment configs (default/local/beta/prod)
+elpis-core/      # Custom framework bootstrap & loaders
+```

package/README.md

@@ -0,0 +1,200 @@
+# elpis
+## 一个企业级应用框架，通过全栈实现。
+
+### model配置
+```javascript
+{
+    model: 'dashboard'; // 模板类型，不同模板类型对应不一样的模板数据结构
+    name: ''; // 名称
+    desc: ''; // 描述
+    icon: ''; // 图标
+    homePage: ''; // 首页（项目配置）
+    // 头部菜单
+    menu: [{
+        key: '', // 菜单唯一描述
+        name: '', // 菜单名称
+        menuType: '', // 枚举值：group/module
+
+        // 当 menuType == group 时，可填
+        subMenu: [{
+            // 可递归 menuItem
+        },],
+
+        // 当 menuType == module 时，可填
+        moduleType: '', // 枚举值：sider/iframe/custom/schema
+
+        // 当 moduleType == sider 时
+        siderConfig: {
+            menu: [{
+                // 可递归 menuItem（除了menuType == sider外）
+            }]
+        },
+
+        // 当 moduleType == iframe 时
+        iframeConfig: {
+            path: '', // iframe路径
+        },
+
+        // 当 moduleType == custom 时
+        customConfig: {
+            path: '', // 自定义路由路径
+        },
+
+        // 当 moduleType == schema 时
+        schemaConfig: {
+            api: '', // 数据源API（遵循 RESTFUL 规范）
+            schema: { // 板块数据结构
+                type: 'object',
+                properties: {
+                    key: {
+                        ...schema, // 标准 schema 配置
+                        type: '', // 字段类型
+                        label: '', // 字段中文名
+                        // 字段在 table 中的相关配置
+                        tableOption: {
+                            ...elTableColumnConfig, // 标准 el-table-column 配置
+                            toFixed: 0, // 保留小数点后几位
+                            visible: true, // 默认为 true （false时，表示不在表单中显示）
+                        },
+                        // 字段在 search-bar 中的相关配置
+                        searchOption: {
+                            ...elComponentConfig, // 标准 el-table-column 配置
+                            comType: '', // 配置组件类型 input/select/...
+                            default: '', // 默认值
+
+                            // comType === 'select' 时的相关配置
+                            enumList: [], // 下拉框可选项
+
+                            // comType === 'dynamicSelect' 时的相关配置
+                            api: ''
+                        },
+                        // 字段在不同动态 component 中的相关配置，前缀对应 componentConfig 中的键值
+                        // 如：componentConfig.createForm，这里对应 createFormOption
+                        // 字段在 createForm 中的相关配置
+                        createFormOption: {
+                            ...elComponentConfig, // 标准 el-component 配置
+                            comType: '', // 控件类型 input/select/...
+                            visible: true, // 默认为 true
+                            disable: false, // 是否禁用，默认false
+                            default: '', // 默认值
+
+                            // comType === 'select' 时生效
+                            enumList: [], // 枚举列表
+                        },
+                        // 字段在 editForm 表单中的相关配置
+                        editFormOption: {
+                            ...elComponentConfig, // 标准 el-component 配置
+                            comType: '', // 控件类型 input/select/...
+                            visible: true, // 默认为 true
+                            disable: false, // 是否禁用，默认false
+                            default: '', // 默认值
+
+                            // comType === 'select' 时生效
+                            enumList: [], // 枚举列表
+                        },
+                        // 字段在 detail-panel 中的相关配置
+                        detailPanelOption: {
+                            ...elComponentConfig, // 标准 el-component 配置
+                        }
+                    },
+                    ...
+                },
+                required: [], // 标记哪些字段是必填项
+            },
+            // table 相关配置
+            tableConfig: {
+                headerButtons: [{
+                    label: '', // 按钮中文名
+                    eventKey: '', // 按钮事件名
+                    // 按钮事件具体配置
+                    eventOption: {
+                        // 当 eventKey === 'showComponent'
+                        comName: '', // 组件名称
+                    },
+                    ...elButtonConfig // 标准el-button 配置
+                },...],
+                rowButtons: [{
+                    label: '', // 按钮中文名
+                    eventKey: '', // 按钮事件名
+                    eventOption: {
+                        // 当 eventKey === 'showComponent'
+                        comName: '', // 组件名称
+
+                        // 当 eventKey === 'remove'
+                        params: {
+                            // paramsKey = 参数的键值
+                            // rowValueKey = 参数值，格式为 schema::tableKey 的时候，到table中找相应的字段
+                            paramsKey: rowValueKey
+                        }
+                    }, // 按钮事件具体配置
+                    ...elButtonConfig // 标准el-button 配置
+                },...],
+            },
+            // search-bar 相关配置
+            searchConfig: {},
+            // 动态组件 相关配置 
+            componentConfig: {
+                // create-form 表单相关配置
+                createForm: {
+                    title: '', // 表单标题
+                    saveBtnText: '', // 保存按钮文案
+                },
+                // edit-form 表单相关配置
+                editForm: {
+                    mainKey: '', // 表单主键，用于唯一标识要修改的数据对象
+                    title: '', // 表单标题
+                    saveBtnText: '', // 保存按钮文案
+                },
+                detailPanel: {
+                    mainKey: '', // 表单主键，用于唯一标识要修改的数据对象
+                    title: '', // 表单标题
+                }
+                // detail-panel 相关配置
+                // ...支持用户动态拓展
+            }, 
+        },
+
+    },]
+}
+```
+
+### 服务端启动
+```javascript
+const { serverStart } = require('@jiangliffey/elpis');
+
+// 启动 elpis 服务
+const app = serverStart({});
+```
+
+### 自定义服务端
+- router-schema
+- router
+- controller
+- service
+- extend
+- config
+
+### 前端构建
+```javascript
+const { fontendBuild } = require('@jiangliffey/elpis');
+
+// 编译构建前端工程
+fontendBuild(process.env._ENV);
+```
+### 自定义页面扩展
+* 在 `app/pages/` 目录下写入口 entry.xxx.js
+
+### dashboard / custom-view 自定义页面扩展
+* 在 `app/pages/dashboard/xxx` 下写页面
+
+### dashboard / schema-view / components 动态组件扩展
+1. 在 `app/pages/dashboard/complex-view/schema-view/components` 下写组件
+2. 配置到 `app/pages/dashboard/complex-view/schema-view/components/component-config.js`
+
+### schema-form 控件扩展
+1. 在 `app/widgets/schema-form/complex-view` 下写控件
+2. 配置到 `app/widgets/schema-form/form-item-config.js`
+
+### schema-search-bar 控件扩展
+1. 在 `app/widgets/schema-search-bar/complex-view` 下写控件
+2. 配置到 `app/widgets/schema-search-bar/search-item-config.js`

package/app/controller/base.js

@@ -0,0 +1,38 @@
+module.exports = (app) => class BaseController {
+    /**
+     * controller 基类，所有 controller 都继承自这个类，可以在这里定义一些公共方法或者属性
+     */
+    constructor() {
+        this.app = app;
+        this.config = app.config;
+    }
+
+    /**
+     * API处理成功时的响应，统一返回结构
+     * @param {object} ctx 上下文
+     * @param {object} data 核心数据
+     * @param {object} metadata 附加数据
+     */
+    success(ctx, data = null, metadata = {}) {
+        ctx.status = 200;
+        ctx.body = {
+            success: true,
+            data,
+            metadata
+        }
+    }
+
+    /**
+     * API处理失败时的响应，统一返回结构
+     * @param {object} ctx 上下文
+     * @param {object} message 错误信息
+     * @param {object} code 错误码
+     */
+    fail(ctx, message, code) {
+        ctx.body = {
+            success: false,
+            message,
+            code
+        }
+    }
+}

package/app/controller/project.js

@@ -0,0 +1,74 @@
+module.exports = (app) => {
+    const BaseController = require('./base')(app);
+    return class ProjectController extends BaseController {
+        /**
+         * 根据 proj_key 获取项目配置
+         */
+        get(ctx) {
+            const { proj_key: projKey } = ctx.request.query;
+
+            const { project: projectService } = app.service;
+            const projConfig = projectService.get(projKey);
+
+            if(!projConfig) {
+                this.fail(ctx, '获取项目异常', 50000);
+                return;
+            }
+
+            this.success(ctx, projConfig);
+        }
+
+        /**
+         * 获取当前 projectKey 对应模型下的项目列表（如果无 projKey，全量获取）
+         */
+        getList(ctx) {
+            const { proj_key: projKey } = ctx.request.query;
+
+            const { project: projectService } = app.service;
+            const projectList = projectService.getList({ projKey });
+
+            // 构造关键数据 list
+            const dtoProjectList = projectList.map(item => {
+                const { modelKey, key, name, desc, homePage } = item;
+                return { modelKey, key, name, desc, homePage };
+            });
+
+            this.success(ctx, dtoProjectList);
+        }
+
+        /**
+         * 获取所有模型与项目的结构化数据
+         * @param {Object} ctx - 上下文对象
+         */
+        async getModelList(ctx) {
+            const { project: projectService } = app.service;
+            const modelList = await projectService.getModelList();
+
+            // 构造返回结果，只返回关键数据
+            const dtoModelList = modelList.reduce((preList, item) => {
+                const { model, project } = item;
+
+                // 构造 model 关键数据
+                const { key, name, desc } = model;
+                const dtoModel = { key, name, desc };
+
+                // 构造 project 关键数据
+                const dtoProject = Object.keys(project).reduce((preObj, proKey) => {
+                    const { key, name, desc, homePage } = project[proKey];
+                    preObj[proKey] = { key, name, desc, homePage };
+                    return preObj;
+                }, {});
+
+                // 整合返回结构
+                preList.push({
+                    model: dtoModel,
+                    project: dtoProject
+                });
+
+                return preList;
+            }, []);
+            
+            this.success(ctx, dtoModelList);
+        }
+    }
+}

package/app/controller/view.js

@@ -0,0 +1,22 @@
+module.exports = (app) => {
+    return class ViewController {
+        /**
+         * 渲染页面
+         * @param {Object} ctx - 上下文对象
+         */
+        async renderPage(ctx) {
+            const { query, params } = ctx;
+            const { proj_key: projKey } = ctx.request.query;
+
+            app.logger.info(`[ViewController] query: ${JSON.stringify(query)}`);
+            app.logger.info(`[ViewController] params: ${JSON.stringify(params)}`);
+
+            await ctx.render(`dist/entry.${ctx.params.page}`, {
+                projKey: projKey || '',
+                name: app.options?.name,
+                env: app.env.getEnv(),
+                options: JSON.stringify(app.options)
+            });
+        }
+    }
+}

package/app/extend/logger.js

@@ -0,0 +1,35 @@
+const log4js = require('log4js');
+
+/**
+ * 日志工具
+ * 外部调用 app.logger.info、app.logger.error
+ */
+module.exports = (app) => {
+    let logger;
+
+    if(app.env.isLocal()) {
+        // 打印在控制台即可
+        logger = console;
+    } else {
+        // 把日志输出并落地到磁盘（日志落盘）
+        log4js.configure({
+            appenders: {
+                console: { type: 'console' },
+                // 日志文件切分
+                dateFile: {
+                    type: 'dateFile',
+                    filename: './logs/application.log',
+                    pattern: 'yyyy-MM-dd',
+                }
+            },
+            categories: {
+                default: { 
+                    appenders: ['console', 'dateFile'], 
+                    level: 'trace' 
+                }
+            }
+        });
+        logger = log4js.getLogger();
+    }
+    return logger;
+}

package/app/middleware/api-params-verify.js

@@ -0,0 +1,81 @@
+const Ajv = require("ajv");
+const ajv = new Ajv();
+
+/**
+ * API 参数校验
+ */
+module.exports = (app) => {
+    // 校验规则的版本声明(因为JSON Schema 不是只有一个固定版本，不同版本之间会有一些差异)
+    const $schema = 'http://json-schema.org/draft-07/schema#';
+    return async (ctx, next) => {
+        // 只对API请求做参数校验，其他请求直接放行
+        if(ctx.path.indexOf('/api/') < 0) {
+            return await next();
+        }
+
+        // 获取请求参数
+        const { query, body, headers } = ctx.request;
+        const { params, path, method } = ctx;
+
+        app.logger.info(`[-- api params verify ${method} ${path} --] body: ${JSON.stringify(body)}`);
+        app.logger.info(`[-- api params verify ${method} ${path} --] query: ${JSON.stringify(query)}`);
+        app.logger.info(`[-- api params verify ${method} ${path} --] params: ${JSON.stringify(params)}`);
+        app.logger.info(`[-- api params verify ${method} ${path} --] headers: ${JSON.stringify(headers)}`);
+
+        const schema = app.routerSchema[path]?.[method.toLowerCase()];
+        if (!schema) {
+            app.logger.warn(`[-- api params verify --]: no schema defined for path=${path}, method=${method}`);
+            return await next();
+        }
+
+        let valid = true;
+
+        // ajv检验器
+        let validate;
+
+        // 校验headers
+        if (valid && headers && schema.headers) {
+            const headerSchema = { $schema, ...schema.headers};
+            validate = ajv.compile(headerSchema);
+            
+            // schema.headers.$schema = $schema;
+            // validate = ajv.compile(schema.headers);
+            valid = validate(headers);
+        }
+
+        // 校验body
+        if (valid && body && schema.body) {
+            const bodySchema = { $schema, ...schema.body};
+            validate = ajv.compile(bodySchema);
+            // schema.body.$schema = $schema;
+            // validate = ajv.compile(schema.body);
+            valid = validate(body);
+        }
+
+        // 校验query
+        if (valid && query && schema.query) {
+            const querySchema = { $schema, ...schema.query};
+            validate = ajv.compile(querySchema);
+            valid = validate(query);
+        }
+
+        // 校验params
+        if (valid && params && schema.params) {
+            const paramsSchema = { $schema, ...schema.params};
+            validate = ajv.compile(paramsSchema);
+            valid = validate(params);
+        }
+
+        if (!valid) {
+            ctx.status = 200;
+            ctx.body = {
+                success: false,
+                message: `参数校验失败: ${ajv.errorsText(validate.errors)}`,
+                code: 442
+            }
+            return;
+        }
+
+        await next();
+    }
+}

package/app/middleware/api-sign-verify.js

@@ -0,0 +1,35 @@
+
+const md5 = require('md5');
+/**
+ * API 签名合法性校验
+ * 1. 从请求头中获取签名信息
+ * 2. 验证签名的合法性
+ */
+
+module.exports = (app) => {
+    return async (ctx, next) => {
+        // 只对API请求做签名校验，其他请求直接放行
+        if(ctx.path.indexOf('/api/') < 0) {
+            return await next();
+        }
+        const { path, method } = ctx;
+        const { headers } = ctx.request;
+        const { s_sign: sSign, s_t: st } = headers;
+
+        const signKey = 'dftgyh84adsuh462wef46ef5s6d4fiop'; // 签名密钥，实际项目中应该放在环境变量中
+        const signature = md5(`${signKey}_${st}`);
+        app.logger.info(`[-- api sign verify --]: path=${path}, method=${method}, s_sign=${sSign}, s_t=${st}, signature=${signature}`);
+
+        if(!sSign || !st || signature !== sSign.toLowerCase() || Date.now() -st > 600000) {
+            ctx.status = 200;
+            ctx.body = {
+                success: false,
+                message: 'signature verification failed or api timeout!!!',
+                code: 445
+            }
+            return;
+        }
+
+        await next();
+    }
+}

package/app/middleware/error-handler.js

@@ -0,0 +1,33 @@
+/**
+ * 运行时异常错误处理，兜底所有异常
+ * @param {object} app koa实例
+ */
+module.exports = (app) => {
+    return async (ctx, next) => {
+        try {
+            await next();
+        } catch (err) {
+            // 处理异常
+            const { status, message, details } = err;
+            app.logger.info(JSON.stringify(err));
+            app.logger.error('[-- exception --]:', err);
+            app.logger.error('[-- exception --]:', status, message, details);
+
+            if(message && message.indexOf('template not found') > -1) {
+                // 页面重定向
+                ctx.status = 302; // 临时重定向
+                ctx.redirect(`${app?.options?.homePage}`);
+                return;
+            }
+
+            const resBody = {
+                success: false,
+                code: 50000,
+                message: '网络异常，请稍后再试'
+            }
+
+            ctx.status = 200;
+            ctx.body = resBody;
+        }
+    }
+}