# NodeVueUniAppX

**Repository Path**: Jopfree/NodeVueUniAppX

## Basic Information

- **Project Name**: NodeVueUniAppX
- **Description**: 面向 UniApp X + GeekerAdmin Vue的 Vue3 + NestJS 管理后台：真 API、SQLite 开箱即用、pnpm 一键构建发布
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-28
- **Last Updated**: 2026-08-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# NodeVueUniAppX

一套可本地跑通的管理端全栈脚手架：**Vue3 Web 管理后台 + NestJS API + uni-app x 跨端客户端**，三端共用同一套 JWT / 菜单与系统管理 API。

| 端 | 目录 | 定位 | 状态 |
|----|------|------|------|
| 后端 API | `node-api/` | NestJS + TypeORM，默认 SQLite | ✅ 可运行（`:3100`） |
| Web 管理端 | `web/` | PC 后台（Geeker-Admin 体验，真 API） | ✅ MVP 完成（`:8888`） |
| 跨端客户端 | `uniappx/` | uni-app x（App / H5 / 微信小程序） | ✅ 已对接 node-api（登录 / 首页 / 我的 / 头像） |

> **范围**：单租户后台；**不做多租户**。  
> **进度**：Web + API 的 MVP（P0～P4）**100%**；uniappx 基础对接（P5-00）**已完成**；下一阶段见 [docs/PROJECT_PLAN.md](./docs/PROJECT_PLAN.md)。  
> **工程**：三端各自独立安装与启动，**无**根目录 workspace / 一键脚本。

---

## 界面预览

### 后端 · Swagger

<p align="center">
  <img src="./screenshot/000.png" alt="Swagger 文档登录" width="48%" />
  <img src="./screenshot/111.png" alt="Swagger API 文档" width="48%" />
</p>

### Web 管理端

<p align="center">
  <img src="./screenshot/222.png" alt="Web 登录页" width="80%" />
</p>

<p align="center">
  <img src="./screenshot/333.png" alt="Web 首页 · 系统管理菜单" width="48%" />
  <img src="./screenshot/444.png" alt="Web 首页 · 完整侧栏" width="48%" />
</p>

### 跨端 · JomoUniX（uniappx）

<p align="center">
  <img src="./screenshot/555.png" alt="uniappx 登录" width="36%" />
  &nbsp;
  <img src="./screenshot/666.png" alt="uniappx 首页" width="36%" />
</p>

---

## 架构一览

```text
                    ┌─────────────────┐
                    │   node-api      │  NestJS · JWT · TypeORM
                    │   :3100 /api    │  SQLite（默认）/ PostgreSQL
                    └────────┬────────┘
           ┌─────────────────┼─────────────────┐
           ▼                 ▼                 ▼
    ┌────────────┐    ┌────────────┐    ┌────────────┐
    │   web/     │    │  uniappx/  │    │  各端构建  │
    │ Vue3 后台  │    │ JomoUniX   │    │ 见各端     │
    │ :8888      │    │ App/H5/MP  │    │ README     │
    └────────────┘    └────────────┘    └────────────┘
```

- **开发**：先起 `node-api`，再起 `web` 或 `uniappx`（HBuilderX）。
- **发布**：在各端目录内按该端 README 构建；无根目录统一 `dist/` 汇总。

---

## 技术栈


| 端           | 技术                                                           |
| ----------- | ------------------------------------------------------------ |
| `node-api/` | NestJS、TypeORM、JWT、Swagger、exceljs、SQLite / PostgreSQL       |
| `web/`      | Vue 3、TypeScript、Vite 5、Pinia、Element Plus、vue-i18n、ProTable |
| `uniappx/`  | uni-app x（UTS + uvue）、UnoCSS、lime-i18n、e-chart、OpenAPI 生成    |


---

## 快速开始

### 环境要求


| 项       | 要求                                             |
| ------- | ---------------------------------------------- |
| Node.js | ≥ 18（推荐 20 LTS）                                |
| pnpm    | ≥ 9（本机若为 pnpm 11，见下方 node-api 说明）              |
| 数据库     | 默认 **SQLite**（零依赖）；生产可选 **PostgreSQL**         |
| 其它      | `uniappx` 建议用 **HBuilderX** 运行到 App / H5 / 小程序 |


### ① 后端 API（先启动）

```bash
cd node-api
pnpm install          # pnpm 11：本目录 pnpm-workspace.yaml 已含 allowBuilds
pnpm start:dev        # 或 pnpm dev
```


| 服务      | 地址                                                               |
| ------- | ---------------------------------------------------------------- |
| API     | [http://localhost:3100](http://localhost:3100)                   |
| Swagger | [http://localhost:3100/api/docs](http://localhost:3100/api/docs) |


**演示账号**：`admin` / `123456`（密码入库前 MD5，再 bcrypt）

若去掉根 workspace 后起不来：在 `node-api` 删除 `node_modules` 后重新 `pnpm install`（详见 [node-api/README.md](./node-api/README.md)）。

### ② Web 管理端

另开终端：

```bash
cd web
pnpm install
pnpm dev
```


| 服务  | 地址                                             |
| --- | ---------------------------------------------- |
| 前端  | [http://localhost:8888](http://localhost:8888) |


开发代理：`/api` → `http://localhost:3100/api`（见 `web/.env.development`）。

### ③ 跨端客户端 `uniappx/`（JomoUniX）

另开终端（需已启动 node-api）：

```bash
cd uniappx
pnpm i
pnpm pages            # 生成 pages.json；或用 pnpm dev（pages → openapi → icons）
```

再用 **HBuilderX** 打开 `uniappx/` 运行到 App / 浏览器 / 微信小程序。


| 项    | 说明                                                   |
| ---- | ---------------------------------------------------- |
| 请求基址 | `uniappx/config/env.uts`（默认 `http://localhost:3100`） |
| 鉴权   | `Authorization: Bearer` + `x-access-token`；登录密码 MD5  |
| 已对接  | 登录、首页监控、我的、个人中心头像、本周登录图表                             |
| 真机调试 | 将 `env.uts` 改为电脑局域网 IP（勿用 `localhost`）               |


详细说明见 [uniappx/README.md](./uniappx/README.md)。

---

## 功能概览

### Web + API（真 API，无本地 mock）

- 登录鉴权（JWT：`x-access-token` / Bearer）
- 动态菜单路由、按钮级权限
- 系统管理：账号（导入/导出/头像）、角色（菜单授权）、菜单、部门、字典、操作日志
- 文件上传、个人中心改密 / 头像
- 国际化（中 / 英）、多布局与主题
- Geeker 风格演示页（部分接真上传 / 导入）

### uniappx（已对接 node-api）

- 登录 / 退出、当前用户信息
- 首页监控（API / 鉴权 / DB 探测）、本周登录趋势（系统日志）
- 我的、个人中心头像上传

**下一阶段（可选）**：定时任务、通知 / 参数 / 岗位、uniappx 业务页等 — 见 [docs/PROJECT_PLAN.md](./docs/PROJECT_PLAN.md)。

---

## 构建

各端在本目录内构建：

```bash
cd web && pnpm build:pro
cd node-api && pnpm build
```

`web/dist/`、`node-api/dist/` 均已 gitignore，**不要提交构建产物**。  
部署细节见 [web/README.md](./web/README.md)、[node-api/README.md](./node-api/README.md)。

---

## 目录结构

```text
NodeVueUniAppX/
├── docs/                 # 续作入口、会话交接、进度计划
├── screenshot/           # README 界面预览截图
├── node-api/             # NestJS API（独立 package）
├── web/                  # Vue3 管理端（独立 package）
└── uniappx/              # uni-app x 跨端客户端（独立 package）
```

---

## 配置说明

### 前端 `web/.env.development`


| 变量                    | 说明                                 |
| --------------------- | ---------------------------------- |
| `VITE_GLOB_APP_TITLE` | 页面标题（默认 `Node Admin Vue`）          |
| `VITE_API_URL`        | 接口前缀（默认 `/api`）                    |
| `VITE_PROXY`          | 开发代理 → `http://localhost:3100/api` |


### 后端 `node-api/.env`

默认 SQLite：

```env
DB_TYPE=sqlite
DB_DATABASE=./data/geeker-admin.db
PORT=3100
```

可选 PostgreSQL：

```env
DB_TYPE=postgres
DB_HOST=localhost
DB_PORT=5432
DB_USERNAME=postgres
DB_PASSWORD=postgres
DB_DATABASE=geeker_admin
```

首次启动会自动建表，并写入演示账号与菜单。

### 跨端 `uniappx/config/env.uts`

开发默认 `http://localhost:3100`；H5 本地 `getBaseUrl()` 为空，走 Vite `/api` 代理。

---

## 文档与续作


| 文档                                                   | 用途                  |
| ---------------------------------------------------- | ------------------- |
| [docs/README.md](./docs/README.md)                   | 续作入口索引              |
| [docs/SESSION_HANDOFF.md](./docs/SESSION_HANDOFF.md) | 最近会话摘要、建议下一步        |
| [docs/PROJECT_PLAN.md](./docs/PROJECT_PLAN.md)       | 总进度与 P5 backlog     |
| [web/docs/](./web/docs/)                             | 前端专项（技术栈、Swagger 等） |
| [node-api/README.md](./node-api/README.md)           | API 启动与 Swagger     |
| [uniappx/README.md](./uniappx/README.md)             | 跨端脚手架与对接契约          |


新对话可复制：

```text
请先阅读 docs/SESSION_HANDOFF.md 与 docs/PROJECT_PLAN.md，从「建议下一步」继续。
```

---

## 开发约定

1. Web / uniappx 业务数据一律走 `node-api`，不要使用本地 mock JSON。
2. 登录 / 菜单 / 按钮权限：`web/src/api/modules/login.ts`；系统 CRUD：`web/src/api/modules/system/*`。
3. 后端统一响应：`{ code: 200, msg: "success", data }`。
4. 表单弹窗优先 `ProDialog`；全局头像用 `UserAvatar`。
5. uniappx 业务封装放 `api/service/*.uts`；请求基址只维护在 `config/env.uts`。
6. 完成重要改动后，同步更新 `docs/SESSION_HANDOFF.md` 与 `docs/PROJECT_PLAN.md`。