快速开始

环境：Node.js（建议 LTS）、MySQL 5.7+ / 8.x（utf8mb4）。

1. 安装依赖

• 项目根目录：npm install
• 管理端：cd admin && npm install（根目录 npm run dev 会进入 admin，但首次建议两处各装一次依赖）

2. 数据库与 sql/init.sql

1. 在 MySQL 中建空库，例如：CREATE DATABASE your_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
2. USE your_db;
3. 执行 sql/init.sql（与 migrations/init.sql 内容一致）。会 DROP/CREATE 系统表并写入：默认租户、超级管理员角色、用户 admin / 123456、zc / zc123（MD5 与框架一致）、sys_title / sys_logo、菜单等。库名须与下一步 config.development.js 里的 db.database 一致。
4. 需要「演示数据」列表时，再执行 sql/tpl_demo.sql。

3. 配置 config/config.development.js

• 填写 db：username、password、database、host、port、dialect: "mysql"。框架要求 password 非空（不能留空字符串）。
• 可选：用环境变量覆盖数据库——DB_HOST、DB_PORT、DB_USER、DB_PASSWORD、DB_NAME（与文件内默认值二选一，以你本机为准）。
• 阿里云 OSS：本地可保留非空占位 accessKeyId / accessKeySecret / bucket，避免 sys_file 依赖加载失败；真实 OSS 再改为控制台密钥，或通过 ALIYUN_ACCESS_KEY_ID、ALIYUN_ACCESS_KEY_SECRET、ALIYUN_OSS_URL、ALIYUN_OSS_BUCKET 注入。

4. 启动后端

• 根目录：npm run api（nodemon）或 npm start（node app.js）。
• 默认 API 端口见 config/config.js 的 port.node（模板为 9098）。
• 文档：http://localhost:<port>/api/docs

5. 启动管理端

• 根目录：npm run dev（默认 9000 端口，见根目录 package.json 脚本）。
• 接口根地址在 admin/config/index.js 的 apiUrl，须与后端端口一致（模板为 http://localhost:9098/admin_api/）。

6. 登录与排错

• 默认：admin / 123456 ；租户可不传或按 sys_tenant.code（如 default）。
• sys_file 加载失败：检查 aliyun 字段是否非空或已配置环境变量。
• 连库失败：核对 db、防火墙、是否已执行 init.sql。

---

前后端项目模板

基于 admin-framework（管理端 Vue2 + ViewUI）与 node-core-framework（Koa2 + Sequelize）的最小可运行骨架，已去掉原 WMS 业务，仅保留一条演示业务链与系统接口。

结构

• framework/：node-core-framework 核心（勿与业务混写）
• admin/src/framework/：admin-framework UMD
• api/controller_admin/：管理端业务控制器（模板保留 tpl_demo、sys_file、sys_parameter、sys_tenant）
• api/model/：业务模型（模板保留 tpl_demo、sys_tenant）
• config/：config.js 白名单、framework.config.js 框架项、环境库表连接

菜单与演示页

在 sys_menu 中增加一条菜单：component 填 demo/tpl_demo（与 admin/src/router/component-map.js 一致），分配权限后即可打开「演示数据」列表页。

从模板扩展

• 后端：在 api/model 增加模型、在 api/controller_admin 增加控制器导出 GET/POST /xxx/...；若有关联，写在 config/model.associations.js
• 前端：在 admin/src/views 增加页面，并在 component-map.js 注册；列表可参考 views/demo/tpl_demo.vue + tableMixin