@slice_cy/mint 1.2.0

package/README.md

@@ -0,0 +1,697 @@
+# @slice_cy/mint
+
+`@slice_cy/mint` 是一个基于 Koa、Vue、Webpack 的约定式中后台框架包。业务应用安装这个包后，主要做三件事：
+
+- 用 `start()` 启动 Node 服务。
+- 用 `frontendBuild()` 构建前端页面。
+- 在约定目录下编写后端模块、前端扩展和 DSL 模型。
+
+## 安装
+
+```bash
+pnpm add @slice_cy/mint
+```
+
+安装 mint 后，业务项目可以在 mint 的前端构建体系里直接写 Ant Design Vue 组件。mint 已经把 `ant-design-vue` 放在生产依赖里，并在 webpack 中配置了解析别名，用来保证软链接、pnpm workspace 等场景下也能解析到正确包目录。
+
+## 启动
+
+业务项目根目录创建 `index.js`：
+
+```js
+const { start } = require("@slice_cy/mint");
+
+start({
+  name: "mint-demo",
+});
+```
+
+创建 `build.js`：
+
+```js
+const { frontendBuild } = require("@slice_cy/mint");
+
+frontendBuild(process.env.NODE_ENV);
+```
+
+`package.json` 建议脚本：
+
+```json
+{
+  "scripts": {
+    "start": "nodemon index.js",
+    "build:dev": "cross-env NODE_ENV=development node build.js",
+    "build:prod": "cross-env NODE_ENV=production node build.js"
+  }
+}
+```
+
+常用命令：
+
+```bash
+pnpm start
+pnpm build:dev
+pnpm build:prod
+```
+
+运行时环境变量：
+
+- `PORT`：Node 服务端口，默认 `8080`。
+- `HOST`：Node 服务监听地址，默认 `0.0.0.0`。
+- `_ENV`：配置环境，支持 `local`、`beta`、`production`，默认按本地环境处理。
+
+## 目录约定
+
+业务项目推荐结构：
+
+```text
+.
+├── index.js
+├── build.js
+├── config/
+│   ├── config.default.js
+│   ├── config.local.js
+│   ├── config.beta.js
+│   └── config.production.js
+├── model/
+│   └── <modelKey>/
+│       ├── model.js
+│       └── project/
+│           └── <projectKey>.js
+└── app/
+    ├── controller/
+    ├── service/
+    ├── middleware/
+    ├── router/
+    ├── router-schema/
+    ├── pre-middleware.js
+    ├── post-router.js
+    ├── webpack.config.js
+    ├── public/
+    └── pages/
+        ├── <page>/
+        │   └── entry.<page>.js
+        ├── dashboard/
+        │   ├── router.js
+        │   └── schema-view/
+        │       └── components/
+        │           └── component-cofnig.js
+        └── widgets/
+            ├── schema-form/
+            │   └── form-item-cofnig.js
+            └── schema-search-bar/
+                └── search-item-cofnig.js
+```
+
+注意：当前 webpack 约定里 `component-cofnig.js`、`form-item-cofnig.js`、`search-item-cofnig.js` 的文件名就是这样拼写。业务扩展文件如果写成 `*-config.js`，不会被Mint自动扫描
+
+## 后端约定
+
+### 配置
+
+配置文件放在 `config/`：
+
+```text
+config/config.default.js
+config/config.local.js
+config/config.beta.js
+config/config.production.js
+```
+
+每个配置文件导出函数：
+
+```js
+module.exports = (app) => ({
+  // config
+});
+```
+
+最终配置会挂载到 `app.config`，环境配置会覆盖 `config.default.js`。
+
+### Controller
+
+业务 Controller 放在 `app/controller/**/*.js`，会合并到 `app.controller`。
+
+```js
+module.exports = (app) => {
+  const BaseController = require("@slice_cy/mint").Controller.Base(app);
+
+  return class UserController extends BaseController {
+    async list(ctx) {
+      ctx.body = { success: true };
+    }
+  };
+};
+```
+
+路径会转换为对象路径，例如：
+
+```text
+app/controller/user.js -> app.controller.user
+app/controller/admin/user-profile.js -> app.controller.admin.userProfile
+```
+
+### Service
+
+业务 Service 放在 `app/service/**/*.js`，会合并到 `app.service`。
+
+```js
+module.exports = (app) => {
+  const BaseService = require("@slice_cy/mint").Service.Base(app);
+
+  return class UserService extends BaseService {
+    async list() {
+      return [];
+    }
+  };
+};
+```
+
+路径转换规则和 Controller 一致。
+
+### Middleware
+
+业务中间件放在 `app/middleware/**/*.js`，会加载到 `app.middlewares`，但不会自动 `app.use()`。
+
+```js
+module.exports = (app) => {
+  return async (ctx, next) => {
+    await next();
+  };
+};
+```
+
+需要全局注册时，在 `app/pre-middleware.js` 中使用：
+
+```js
+module.exports = (app) => {
+  app.use(app.middlewares.errHandler);
+};
+```
+
+### Router
+
+业务路由放在 `app/router/**/*.js`。router loader 会创建同一个 `router` 实例，并把 `app` 和 `router` 传给每个路由文件：
+
+```js
+module.exports = (app, router) => {
+  router.get("/api/user/list", app.controller.user.list.bind(app.controller.user));
+};
+```
+
+如果需要在所有业务路由注册后追加兜底逻辑，放在 `app/post-router.js`：
+
+```js
+module.exports = (app, router) => {
+  router.all("(.*)", async (ctx) => {
+    ctx.status = 404;
+    ctx.body = { success: false, message: "Not Found" };
+  });
+};
+```
+
+接口参数校验 schema 放在 `app/router-schema/**/*.js`，会合并到 `app.routerSchema`。业务可以结合 `app.paramsValid` 或自己的中间件使用。
+
+## 前端约定
+
+### 页面入口
+
+mint 会扫描两类入口：
+
+```text
+@slice_cy/mint/app/pages/**/entry.*.js
+业务项目/app/pages/**/entry.*.js
+```
+
+例如：
+
+```text
+app/pages/project-list/entry.project-list.js
+```
+
+构建后会输出模板：
+
+```text
+app/public/dist/entry.project-list.tpl
+```
+
+### webpack 扩展
+
+业务项目可以创建 `app/webpack.config.js` 扩展 mint 的 webpack 配置：
+
+```js
+module.exports = {
+  resolve: {
+    alias: {
+      demo: "demo",
+    },
+  },
+};
+```
+
+mint 内置常用 alias：
+
+- `$mintPage`
+- `$mintService`
+- `$mintWidgets`
+- `$mintHeaderContainer`
+- `$mintSchemaForm`
+- `$mintSchemaSearchBar`
+- `$mintSchemaTable`
+- `$mintSiderContainer`
+- `$mintBootstrap`
+- `$mintStore`
+- `$mintUtils`
+
+### Dashboard 扩展
+
+dashboard 支持以下业务扩展文件：
+
+```text
+app/pages/dashboard/router.js
+app/pages/dashboard/schema-view/components/component-cofnig.js
+app/pages/widgets/schema-form/form-item-cofnig.js
+app/pages/widgets/schema-search-bar/search-item-cofnig.js
+```
+
+用途：
+
+- `router.js`：扩展 dashboard 内的前端路由。
+- `component-cofnig.js`：扩展 schema-view 的动态业务组件。
+- `form-item-cofnig.js`：扩展 schema-form 的表单控件。
+- `search-item-cofnig.js`：扩展 schema-search-bar 的搜索控件。
+
+这些配置文件建议导出对象。组件建议使用异步导入，避免业务组件被同步打进首屏包：
+
+```js
+const { defineAsyncComponent } = require("vue");
+
+module.exports = {
+  demoForm: {
+    component: defineAsyncComponent(() => import("./demoForm/index.vue")),
+  },
+};
+```
+
+## DSL 模型
+
+DSL 放在业务项目的 `model/` 目录下，用来描述站点、菜单、schema 页面、表格、搜索、表单和动态组件。
+
+### 模型目录
+
+```text
+model/
+└── business/
+    ├── model.js
+    └── project/
+        ├── taobao.js
+        └── pdd.js
+```
+
+含义：
+
+- `model/<modelKey>/model.js`：领域模型基础配置。
+- `model/<modelKey>/project/<projectKey>.js`：项目模型配置。
+- 项目模型会继承并覆盖领域模型。
+- 数组合并时会按 `key` 匹配，同 key 合并，不同 key 追加。
+
+访问项目列表和项目模型的内置接口：
+
+```text
+GET /api/project/modelList
+GET /api/project/list?project_key=<modelKey>
+GET /api/project?project_key=<projectKey>
+```
+
+### 顶层结构
+
+```js
+module.exports = {
+  model: "dashboard",
+  name: "电商领域模型",
+  desc: "",
+  icon: "",
+  homePage: "",
+  menu: [],
+};
+```
+
+字段说明：
+
+- `model`：渲染模板标识，目前 dashboard 页面使用 `dashboard`。
+- `name`：站点或模型名称。
+- `desc`：描述。
+- `icon`：图标。
+- `homePage`：首页路由。
+- `menu`：菜单和功能模块配置。
+
+### Menu 配置
+
+```js
+{
+  key: "user",
+  name: "用户管理",
+  menuType: "module",
+  moduleType: "schema",
+  schemaConfig: {}
+}
+```
+
+字段说明：
+
+- `key`：菜单唯一标识，同一份 DSL 中不要重复。
+- `name`：菜单展示名称。
+- `menuType`：`group` 或 `module`。
+- `moduleType`：`custom`、`schema`、`iframe`、`sider`。
+- `subMenu`：`menuType: "group"` 时使用。
+
+不同模块类型的配置：
+
+```js
+{
+  moduleType: "custom",
+  customConfig: {
+    path: "/todo"
+  }
+}
+```
+
+```js
+{
+  moduleType: "iframe",
+  iframeConfig: {
+    path: "https://example.com"
+  }
+}
+```
+
+```js
+{
+  moduleType: "sider",
+  siderConfig: {
+    menu: []
+  }
+}
+```
+
+```js
+{
+  moduleType: "schema",
+  schemaConfig: {}
+}
+```
+
+### Schema 页面配置
+
+`schemaConfig` 描述标准 CRUD 页面：
+
+```js
+schemaConfig: {
+  api: "/api/proj/user",
+  schema: {
+    type: "object",
+    properties: {},
+    required: []
+  },
+  tableConfig: {
+    antdTableConfig: {},
+    headerButtons: [],
+    rowButtons: []
+  },
+  searchBarConfig: {},
+  componentConfig: {}
+}
+```
+
+接口约定：
+
+- `GET <api>/list`：列表查询。
+- `GET <api>/:id`：详情。
+- `POST <api>`：新增。
+- `PUT <api>/:id`：编辑。
+- `DELETE <api>/:id`：删除。
+
+### 字段配置
+
+`schema.properties` 中每个字段描述一个业务字段：
+
+```js
+id: {
+  type: "string",
+  label: "用户ID",
+  tableOption: {
+    uiTableColumnConfig: {},
+    visible: true
+  },
+  searchOption: {
+    comType: "input",
+    default: ""
+  },
+  createFormOption: {
+    comType: "input",
+    default: "",
+    disabled: false
+  },
+  editFormOption: {
+    comType: "input"
+  },
+  detailPanelOption: {
+    comType: "input",
+    disabled: true
+  }
+}
+```
+
+通用字段：
+
+- `type`：字段类型。
+- `label`：展示名称。
+- `tableOption`：字段在表格中的展示配置；不配置则不展示。
+- `searchOption`：字段在搜索栏中的展示配置；不配置则不展示。
+- `[comName]Option`：字段在动态组件中的展示配置，例如 `createFormOption`、`editFormOption`、`detailPanelOption`。
+- `required`：写在 `schema.required` 数组中，会影响表单必填校验。
+
+`tableOption` 常用配置：
+
+- `uiTableColumnConfig`：透传给 Ant Design Vue Table column 的配置。
+- `visible`：显式为 `false` 时隐藏。
+- `toFixed`：数字字段小数位处理。
+
+`searchOption` 常用配置：
+
+- `comType`：搜索控件类型，内置 `input`、`select`、`dynamicSelect`、`dateRangePicker`。
+- `uiComponentConfig`：透传给控件的 UI 配置。
+- `enumList`：`select` 选项。
+- `api`：`dynamicSelect` 拉取选项的接口。
+- `default`：默认值。
+- `visible`：显式为 `false` 时隐藏。
+
+表单动态组件内置 `comType`：
+
+- `input`
+- `select`
+- `inputNumber`
+
+需要更多控件时，放到 `app/pages/widgets/schema-form/form-item-cofnig.js` 扩展。
+
+### 表格按钮
+
+```js
+tableConfig: {
+  headerButtons: [
+    {
+      label: "新增",
+      eventKey: "showComponent",
+      eventOption: {
+        comName: "createForm"
+      },
+      uiButtonConfig: {
+        type: "primary"
+      }
+    }
+  ],
+  rowButtons: [
+    {
+      label: "删除",
+      eventKey: "remove",
+      eventOption: {
+        params: {
+          id: "schema::id"
+        }
+      },
+      uiButtonConfig: {
+        type: "link",
+        danger: true
+      }
+    }
+  ]
+}
+```
+
+内置事件：
+
+- `showComponent`：打开 `componentConfig` 中指定的动态组件。
+- `remove`：按 `eventOption.params` 取当前行参数并调用删除接口。
+
+`eventOption.params` 支持：
+
+- 固定值：直接写值。
+- 行字段：`schema::id` 表示取当前行的 `id` 字段。
+
+### 动态组件
+
+`componentConfig` 描述 schema-view 的动态区域：
+
+```js
+componentConfig: {
+  createForm: {
+    title: "新增用户",
+    saveBtnText: "保存",
+    eventKey: "loadTableList"
+  },
+  editForm: {
+    title: "编辑用户",
+    saveBtnText: "保存",
+    eventKey: "loadTableList",
+    mainKey: "id"
+  },
+  detailPanel: {
+    title: "查看用户",
+    mainKey: "id"
+  },
+  demoForm: {}
+}
+```
+
+内置组件名：
+
+- `createForm`
+- `editForm`
+- `detailPanel`
+
+业务自定义组件需要在 `app/pages/dashboard/schema-view/components/component-cofnig.js` 中注册。
+
+## 最小 DSL 示例
+
+```js
+module.exports = {
+  model: "dashboard",
+  name: "电商领域模型",
+  menu: [
+    {
+      key: "user",
+      name: "用户管理",
+      menuType: "module",
+      moduleType: "schema",
+      schemaConfig: {
+        api: "/api/proj/user",
+        schema: {
+          type: "object",
+          properties: {
+            id: {
+              type: "string",
+              label: "用户ID",
+              tableOption: {},
+              searchOption: {
+                comType: "input",
+              },
+              createFormOption: {
+                comType: "input",
+              },
+              editFormOption: {
+                comType: "input",
+              },
+              detailPanelOption: {
+                comType: "input",
+                disabled: true,
+              },
+            },
+            role: {
+              type: "string",
+              label: "角色",
+              tableOption: {},
+              searchOption: {
+                comType: "select",
+                enumList: [
+                  { label: "管理员", value: "admin" },
+                  { label: "普通用户", value: "user" },
+                ],
+              },
+            },
+          },
+          required: ["id"],
+        },
+        tableConfig: {
+          headerButtons: [
+            {
+              label: "新增",
+              eventKey: "showComponent",
+              eventOption: {
+                comName: "createForm",
+              },
+              uiButtonConfig: {
+                type: "primary",
+              },
+            },
+          ],
+          rowButtons: [
+            {
+              label: "查看",
+              eventKey: "showComponent",
+              eventOption: {
+                comName: "detailPanel",
+              },
+              uiButtonConfig: {
+                type: "link",
+              },
+            },
+          ],
+        },
+        componentConfig: {
+          createForm: {
+            title: "新增用户",
+            saveBtnText: "保存",
+            eventKey: "loadTableList",
+          },
+          detailPanel: {
+            title: "查看用户",
+            mainKey: "id",
+          },
+        },
+      },
+    },
+  ],
+};
+```
+
+项目覆盖示例：
+
+```js
+module.exports = {
+  name: "淘宝项目",
+  homePage: "/dashboard/user",
+  menu: [
+    {
+      key: "user",
+      schemaConfig: {
+        schema: {
+          properties: {
+            role: {
+              searchOption: {
+                visible: false,
+              },
+            },
+          },
+        },
+      },
+    },
+  ],
+};
+```
+
+## 开发建议
+
+- 领域通用配置写在 `model/<modelKey>/model.js`，项目差异写在 `model/<modelKey>/project/<projectKey>.js`。
+- 表格、搜索、表单都围绕同一份 `schema.properties` 描述，避免在页面组件里重复写字段。
+- 业务自定义组件、搜索控件、表单控件优先使用异步导入，降低首屏包体积。
+- 不需要覆盖 mint 内部 webpack 时，不要创建过多业务 webpack 配置；需要覆盖时集中写在 `app/webpack.config.js`。

package/app/common/base-response.js

@@ -0,0 +1,10 @@
+class BaseResponse {
+  constructor({ code, message, data = null, metaData = {} } = {}) {
+    this.code = code;
+    this.message = message;
+    this.data = data;
+    this.metaData = metaData;
+  }
+}
+
+module.exports = BaseResponse;

package/app/common/business-error.js

@@ -0,0 +1,10 @@
+class BusinessError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "BusinessError";
+    this.code = code;
+    this.isBusinessError = true;
+  }
+}
+
+module.exports = BusinessError;