elpis README

The project's README from github.com/fsiaonma/elpis. As one markdown file: README.md.

elpis

一个企业级全栈应用框架。HTTP 内核已从 Koa 迁移为 NestJS；前端构建器使用 Vite。业务仓（如 elpis-demo）通过 Nest Module 扩展框架能力。

Part2 成果

顶层目录

路径 说明
app/main.ts Nest bootstrap 入口，编译到 dist/main.js
app/app.module.ts 根 Module：ConfigModule + ElpisModule.register()
app/elpis.module.ts 框架 Module 聚合：Extend / Project / View / 扫描模块 / Fallback
app/common/ Guard / Pipe / Filter / Interceptor / 静态兜底
app/config/ 配置 Module
app/extend/ Database / Logger Provider
app/modules/ 框架内置 Module（project、view）
app/pages/ 前端页面入口与组件
app/vite/ Vite 构建器（dev / prod）
app/public/ 框架静态资源
app/view/ .tpl 模板
app/types/ 类型契约（express Request.projKey 增强）
config/ 框架默认配置
model/ model 加载器（index.js）
dist/ Nest 编译产物
index.js 对外入口：serverStart / frontendBuild
nest.js Nest 公共导出（BaseController、ConfigService 等）
app/ai/ Agent / MCP / RAG / Skill / Guardrail 等（Part3，见 sdd/part3-agent/）
test/ 框架回归测试
sdd/ 设计与任务文档（part1–part3）

安装与依赖

包名：@fsiaonma/elpis。对外入口为根目录 index.js（serverStart / frontendBuild）；Nest 侧见 nest.js 与 package.json 的 exports（含 ./types/express）。

克隆并在框架仓安装

node_modules、dist 等不会提交，需在本地生成：

git clone [email protected]:fsiaonma/elpis.git
cd elpis
npm install
npm run build    # 编译 Nest → dist/；index.js 依赖 dist/main.js

开发改 TypeScript 时可开监听编译：

npm run build:watch

在业务项目中安装

在 业务仓（如 elpis-demo）根目录：

npm install @fsiaonma/elpis

未发布到 npm 时，可在业务仓 package.json 用 Git 等方式声明依赖后执行 npm install。

改框架源码时，让业务仓指向本机 elpis 目录：

# 1. 框架仓 elpis：安装依赖并编译，再注册全局 link
cd /path/to/elpis
npm install
npm run build          # 或另开终端 npm run build:watch
npm link

# 2. 业务仓 elpis-demo
cd /path/to/elpis-demo
npm link @fsiaonma/elpis

改完 app/**/*.ts 后需重新 npm run build（或保持 build:watch），业务仓重启 Nest 进程后生效。

取消 link：

cd /path/to/elpis-demo
npm unlink @fsiaonma/elpis
npm install

cd /path/to/elpis
npm unlink    # 可选

常用命令（框架仓）

命令 说明
npm install 安装依赖
npm run build Nest 编译到 dist/
npm run build:watch 监听 TypeScript 编译
npm link 全局注册 @fsiaonma/elpis，供业务仓 link
npm run lint ESLint（pre-commit 会执行）
npm test Mocha 回归（_ENV=local）

本地忽略项（.gitignore）

双终端启动（开发）

在业务仓（elpis-demo）开两个终端：

# 终端 A：Vite Dev Server，出脚本 / HMR
npm run build:dev
# → http://127.0.0.1:9002

# 终端 B：Nest 读页面、渲染 .tpl
npm run dev
# → http://127.0.0.1:8080

生产：

npm run build:prod   # 产物落 app/public/dist/prod，并写 entry.*.tpl
npm run prod         # Nest 8080 读 /dist/prod/

与 1.0 对照

Koa 1.0 Nest（本版）
HTTP 内核 elpis-core + Koa loader NestFactory + Module 扫描
业务扩展 controller / router / service demo app/modules/ → dist/modules/
多入口 扫两棵 entry.*.js 树 merge 同样扫两棵树，进 rollupOptions.input
页面模板 HtmlWebpackPlugin 写 .tpl elpis-tpl-plugin 写 .tpl
开发进程 Vite :9002 + Koa :8080 Vite :9002 + Nest :8080（双终端不变）
对外 API frontendBuild(env) / serverStart() 签名不变

model配置

{
  mode: 'dashboard', // 模版类型，不同模版类型对应不一样的模版数据结构
  name: '', // 名称
  desc: '', // 描述
  icon: '', // icon
  homePage: '', // 首页(项目配置)
  // 头部菜单
  menu: [{
    key: '', // 菜单唯一描述，
    name: '', // 菜单名称
    menuType: '', // 枚举值：group / module

    // 当 menuType == group 时，可填
    subMenu: [{
      // 可递归 menuItem
    }, ...],

    // 当 menuType == module 时，可填
    moduleType: '', // 枚举值：sider/iframe/custom/schema

    // 当 moduleType == sider 时
    siderConfig: {
      menu: [{
        // 可递归 menuItem(除 moduleType === 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: {
              ...eleComponentConfig, // 标准 el-component-column 配置
              comType: '', // 配置组件类型 input/select/.....
              default: '', // 默认值

              // comType === 'select'
              enumList: [], // 下拉框可选项

              // comType === 'dynamicSelect'
              api: ''
            },
            // 字段在不同动态 component 中的相关配置，前缀对应 componentComfig 中的键值
            // 如：componentConfig.createForm，这里对应 createFormOption
            // 字段在 createForm 中相关配置
            createFormOption: {
              ...eleComponentConfig, // 标准 el-component 配置
              comType: '', // 控件类型 input/selct/input-number
              visible: true, // 是否展示 (true/false)，默认为 true
              disabled: false, // 是否禁用 (true/false)，默认为 false
              default: '', // 默认值

              // comType === 'select' 时生效
              enumList: [] // 枚举列表
            },
            // 字段在 editForm 表单中的相关配置
            editFormOption: {
              ...eleComponentConfig, // 标准 el-component 配置
              comType: '', // 控件类型 input/selct/input-number
              visible: true, // 是否展示 (true/false)，默认为 true
              disabled: false, // 是否禁用 (true/false)，默认为 false
              default: '', // 默认值

              // comType === 'select' 时生效
              enumList: [] // 枚举列表
            },
            detailPanelOption: {
              ...eleComponentConfig // 标准 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: {
              // paramKey = 参数的键值
              // rowValueKey = 参数值, 格式为 schema::tableKey，到 table 中找相应的字段
              paramKey: rowValueKey
            }
          }, // 按钮事件具体配置
          ...elButtonConfig // 标准 el-button 配置
        }, ...]
      }, 
      // search-bar 相关配置
      searchConfig: {},
      // 动态组件 相关配置
      componentConfig: {
        // create-form 表单相关配置
        createForm: {
          title: '', // 表单标题
          saveBtnText: '', // 保存按钮文案
        },
        // edit-form 表单相关配置
        editForm: {
          mainKey: '', // 表单主键，用于唯一标识要修改的数据对象
          title: '', // 表单标题
          saveBtnText: '', // 保存按钮文案
        },
        // detail-panel 相关配置
        detailPanel: {
          mainKey: '', // 表单主键，用于唯一标识要修改的数据对象
          title: '', // 表单标题
        }
        // ...支持用户动态扩展
      }
    }
  }, ...]
}

服务端启动

const {
  serverStart
} = require('@fsiaonma/elpis');  

// 启动 elpis 服务
const app = serverStart({});

前端构建

const { frontendBuild } = require('@fsiaonma/elpis');

// 编译构建前端工程（签名不变）
// local → Vite createServer :9002
// production → Vite build → app/public/dist/prod
frontendBuild(process.env._ENV);

自定义页面扩展

dashboard / custom-view 自定义页面扩展

dashboard / shcema-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

elpis (fsiaonma/elpis)

nestjs
Searching Database…

586 ·GitHub
Elpis
What is this?Elpis is an enterprise-grade full-stack application framework whose backend kernel runs on NestJS and whose frontend is built with Vite.
Is this a framework or just a library I import?It is a framework: you build a separate business repo (like 'elpis-demo') on top of it and extend the core's behavior by writing NestJS Modules rather than just calling library functions.
How do I get a project running with elpis?Clone the elpis repo, run npm install and npm run build to compile to dist/, then from your business repo install elpis and run two dev terminals: Vite on port 9002 and the Nest server on port 8080.
Do I need to know NestJS to extend this?Yes, extending the framework means writing standard NestJS building blocks like Guards, Pipes, Filters and Interceptors, plus Controllers and Modules in your business repo.
Is elpis published on npm, so I can just npm install it?Not yet - elpis isn't on npm, so a business repo must declare it as a Git dependency in package.json before running npm install, or use npm link for local development against the framework source.
Who is this framework aimed at?Teams building enterprise full-stack apps who want a NestJS backend and Vite frontend bundled into one opinionated framework they can extend per project.
What does the app/ai/ folder add to the framework?It bundles Agent, MCP, RAG, Skill and Guardrail modules as part of the framework's AI/agent capabilities, with its own design docs under sdd/part3-agent/.
How do I add a custom page to the app?Create a new entry file under app/pages/ (e.g. entry.xxx.js); the Vite builder scans this alongside the framework's built-in page entries.
What actually changed when elpis moved from Koa to NestJS?The old Koa kernel and its loader were deleted and the framework now uses a unified NestJS Module style everywhere, but serverStart()/frontendBuild() signatures, the 8080 port, API response codes (442/445/446) and cookie behavior were kept identical to the 1.0 Koa version.
Can I add custom dashboard widgets or form controls?Yes - write a component under app/pages/dashboard/.../schema-view/components (or app/widgets/schema-form or schema-search-bar) and register it in the matching component-config.js file.
What are similar projects?egg, carno.js, JeecgBoot, wasp, voltagent, nest, reflex, StarLive
Which topics is it in?fullstack, nestjs, web-framework, agent-framework, enterprise, monorepo, vite, rag, backend, ai-agent, framework, agent
Creator
fsiaonma
Size
0.5 MB
Stars
586
Updated
CommitSep 29
Age
18d
Commits · 90 Days