web-admin

类似 Egg.js 的企业级全栈框架，遵循「约定大于配置」，开箱即用。

技术栈

Koa.js + Express.js + Node.js Http + Vue3 + Webpack5 + TypeScript

其他：Less + Element Plus + Pinia + Vue Router

环境要求：Node.js >= 20（@koa/router v15 / Koa 3 依赖）

快速开始（消费者）

# 1. 生成完整工程（脚手架由独立仓库 @wyj-fe/wa-cli 维护，内置 git/eslint/prettier 基建）
npx @wyj-fe/wa-cli create

# 2. 安装依赖（依赖已内置，无需手动安装 peer 依赖；npm/yarn 平铺提升开箱即用，pnpm 会自动生成 .npmrc）
pnpm install   # 或 npm install / yarn

# 3. 启动
pnpm dev        # 开发环境 Koa 服务（8080），业务 TS 源码直接运行
pnpm dev:web    # 开发环境前端构建（9002，HMR）

# 生产环境（本地联调/发布前验证，与线上一致）
pnpm build      # 完整构建：编译业务侧（build:node）+ 前端生产构建（prod）
pnpm prod       # 启动生产服务（node dist/server.js 运行编译后的业务 JS）

生产环境（_ENV=prod）强制加载业务侧编译产物（dist/app/**.js / dist/config/*.js / dist/server.js）， 未执行 web-admin build:node 时启动会明确报错退出，避免本地与线上行为不一致。 业务侧编译产物统一收拢到 dist/ 目录，与 TS 源码完全隔离，不影响开发与代码提交。

web-admin build 等价于 web-admin build:node && web-admin prod： 前者编译服务端业务代码，后者构建前端产物，二者独立、发布前都需要。

pnpm 用户注意：wa-cli create 会自动生成 .npmrc（依赖提升配置）， 首次生成后请重新执行一次 pnpm install 使其生效。 npm / yarn 无需任何额外操作。

手动接入（不通过脚手架）

# 1. 安装框架（运行/构建依赖已内置，开箱即用）
pnpm add @wyj-fe/web-admin

# 2. 安装工程开发依赖（tsx/nodemon 用于 TS 源码直跑，@types/node 提供 Node 类型；eslint 等基建按需自配）
pnpm add -D @types/node tsx nodemon

# 3. 按下方目录结构创建 app / config / model / server.ts，并复制 tsconfig.json、tsconfig.node.json

# 4. package.json 添加脚本
{
  "dev": "_ENV=dev nodemon --exec tsx server.ts",
  "dev:web": "web-admin dev",
  "build:node": "web-admin build:node",
  "build": "web-admin build",
  "prod": "_ENV=prod node dist/server.js"
}

类型导入：直接 import type { Model } from "@wyj-fe/web-admin/types" 即可， 包 exports 已做好映射，无需在 tsconfig 中配置 paths。

消费者侧目录结构（wa-cli create 生成）

|—— 根目录
  |—— app
    |—— controller (示例：user.ts)
    |—— service (示例：user.ts)
    |—— middleware
    |—— router (示例：user.ts)
    |—— router-schema (示例：user.ts)
    |—— extend
    |—— pages
      |—— dashboard
        |—— router.ts / source 示例
      |—— widgets
    |—— middleware.ts
    |—— webpack.config.ts
    |—— public (内置静态资源)
  |—— config
    |—— config.default.ts
    |—— config.dev.ts
    |—— config.prod.ts
  |—— model
    |—— education (领域模型示例，用户只需修改这里即可快速看到效果)
  |—— types
    |—— index.d.ts
  |—— server.ts
  |—— tsconfig.json / tsconfig.node.json（编译产物输出到 dist/）
  |—— eslint.config.mjs / .prettierrc.mjs / commitlint.config.js
  |—— .husky（pre-commit 执行 lint:check，commit-msg 执行 commitlint）
  |—— .npmrc（pnpm 依赖提升）

页面与组件扩展

• 自定义页面：在 app/pages/ 下写入口 entry.xxx.ts + 页面组件
• dashboard 自定义页面：app/pages/dashboard/ 下新增页面
• schema-view 动态组件：app/pages/dashboard/complex-view/schema-view/components/ + component-config.ts
• schema-form 控件：app/pages/widgets/schema-form/complex-view/ + form-item-config.ts
• schema-search-bar 控件：app/pages/widgets/schema-search-bar/complex-view/ + search-item-config.ts
• webpack 扩展：app/webpack.config.ts（与内置配置 webpack-merge）
• 路径别名：$sys* 指向框架内置（如 $sysSchemaTable、$sysCurl），$business* 指向业务侧 （如 $businessPages/*、$businessTypes/*），构建期由框架 webpack 自动解析，IDE 由 tsconfig paths 解析

系统架构

• 整体架构
• BFF 架构 / 服务端引擎实现
• webpack HMR
• 前端与领域模型之间的通信

发布（维护者）

pnpm build               # 编译服务端 + 生成类型 + 拷贝前端源码/模板
npm pack --dry-run       # 检查发布内容（必须包含 dist/）
npm publish              # prepublishOnly 会自动执行 pnpm build

脚手架（维护者）

• 工程脚手架由独立仓库 @wyj-fe/wa-cli 维护
• 框架只负责提供运行时能力（start / frontendBuild / Controller / Service）
• web-admin create 为兼容入口，会自动委托给 @wyj-fe/wa-cli