# 快速开始

**环境**：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`