# 项目介绍

## 一、项目概述

**webman-builadmin** 是基于 **Webman**（Workerman）的 BuildAdmin 后台管理系统，将原 ThinkPHP8 版 BuildAdmin 迁移到 Webman 框架，实现前后端分离、常驻内存运行，提供高性能、可扩展的后台管理能力。

### 核心特性

- **常驻内存**：基于 Workerman，避免传统 PHP-FPM 的进程反复创建开销
- **前后端分离**：Vue 3 + TypeScript 前端，RESTful API 后端
- **CRUD 代码生成**：可视化设计表结构，自动生成控制器、模型、验证器、前端页面
- **权限管理**：RBAC 权限模型，支持管理员分组、菜单规则
- **多语言**：中文、英文等多语言支持
- **安全特性**：XSS 过滤、敏感数据脱敏、数据回收站等

---

## 二、技术栈

### 后端（PHP）

| 技术 | 版本 | 说明 |
|------|------|------|
| PHP | >= 8.1 | 运行环境 |
| workerman/webman-framework | ^2.1 | Webman 框架 |
| webman/think-orm | ^2.1 | ThinkORM 数据库 |
| webman/validation | ^2.2 | 表单验证 |
| topthink/think-validate | ^3.0 | 验证器 |
| vlucas/phpdotenv | ^5.6 | 环境变量 |
| robmorgan/phinx | ^0.15 | 数据库迁移 |
| voku/anti-xss | ^4.1 | XSS 防护 |

### 前端

| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3.5.13 | 前端框架 |
| Element Plus | 2.9.1 | UI 组件库 |
| TypeScript | 5.7.2 | 类型系统 |
| Vite | 6.3.5 | 构建工具 |
| Pinia | 2.3.0 | 状态管理 |
| Vue Router | 4.5.0 | 路由 |
| Axios | 1.9.0 | HTTP 客户端 |
| ECharts | 5.5.1 | 图表 |
| Vue I18n | 11.1.3 | 国际化 |

---

## 三、项目结构

```
webman-builadmin/
├── app/                    # 应用代码
│   ├── admin/              # 后台管理
│   │   ├── controller/     # 控制器（auth、user、routine、crud、security、mall 等）
│   │   ├── model/          # 模型
│   │   ├── validate/       # 验证器
│   │   ├── lang/           # 语言包
│   │   └── library/       # 库（Auth、CRUD、traits）
│   ├── api/                # 前台 API
│   ├── common/             # 公共模块
│   └── support/            # 基础类
├── config/                 # 配置文件
│   ├── app.php             # 应用配置
│   ├── route.php           # 路由
│   ├── database.php        # Webman 数据库连接池
│   ├── thinkorm.php        # ThinkORM 配置（主 ORM）
│   └── buildadmin.php      # BuildAdmin 业务配置
├── database/
│   └── migrations/         # 数据库迁移
├── extend/                 # 扩展
├── modules/               # 模块
├── public/                # 入口与静态资源
├── web/                   # 前端 Vue 源码
│   └── src/
│       ├── api/           # API 封装
│       ├── components/    # 通用组件
│       ├── lang/          # 多语言
│       ├── router/        # 路由
│       ├── stores/        # Pinia
│       ├── utils/         # 工具
│       └── views/         # 页面
├── start.php              # 主启动
├── windows.php            # Windows 启动
└── composer.json
```

---

## 四、主要功能模块

### 4.1 权限管理（auth）

- 管理员管理（admin）
- 管理员分组（group）
- 菜单规则（rule）

### 4.2 用户管理（user）

- 用户管理（user）
- 用户分组（group）
- 用户规则（rule）
- 余额日志（moneyLog）
- 积分日志（scoreLog）

### 4.3 常规配置（routine）

- 系统配置（config）
- 管理员资料（adminInfo）
- 附件管理（attachment）

### 4.4 安全中心（security）

- 敏感数据管理

### 4.5 积分商城（mall）

- 积分商城用户（player）

### 4.6 CRUD 设计（crud）

- 可视化表设计
- 一键生成控制器、模型、验证器、前端页面

---

## 五、快速开始

### 5.1 环境要求

- PHP >= 8.1
- MySQL >= 5.7
- Composer
- Node.js >= 18（前端开发）

### 5.2 安装

```bash
# 进入项目目录
cd webman-builadmin

# 安装 PHP 依赖
composer install

# 安装前端依赖
cd web && pnpm install
```

### 5.3 配置

1. 复制 `.env.example` 为 `.env`
2. 配置数据库连接（`database.hostname`、`database.database`、`database.username`、`database.password`）

### 5.4 数据库迁移

```bash
php webman migrate
```

### 5.5 启动

**开发环境需同时启动后端与前端：**

1. **启动后端（API 服务，端口 8787）：**

   **Linux / Mac：**
   ```bash
   php start.php start
   ```

   **Windows：**
   ```bash
   php windows.php
   ```

2. **启动前端（Vue 开发服务，端口 1818）：**
   ```bash
   cd web
   pnpm dev
   ```

3. **访问地址：**
   - 安装向导：http://localhost:1818/install/
   - 前台地址：http://localhost:1818/index.html/#/
   - 后台地址：http://localhost:1818/index.html/#/admin

> 注意：前端通过 Vite 代理将 `/api`、`/admin`、`/install` 转发到后端 8787 端口，请勿直接访问 8787 端口的前端页面，否则可能出现 404。

---

## 六、路由说明

- **后台 API**：`/admin/{module}.{Controller}/{action}`
  - 示例：`/admin/mall.User/index` → `app\admin\controller\mall\User::index`
- **前台 API**：`/api/...`
- **安装**：`/api/Install/...`

---

## 七、已修复问题

| 问题 | 修复说明 |
|------|----------|
| 数据库配置不一致 | 统一 `database.php` 与 `thinkorm.php` 默认值为 `webman-builadmin` |
| 语言 key 命名错误 | `quick Search Fields` 改为 `quickSearchFields` |
| 编辑时密码必填 | 编辑时密码可选，仅新增时必填；后端支持密码加密与重置 |
| 多余表单校验 | 移除 `create_time`、`update_time` 的表单校验 |
| mall_user 与 PlayX 资产口径混用 | 新增重构迁移并改为 `mall_user` 一对一扩展资产表 |

---

## 八、注意事项

1. **错误目录**：若存在 `webman-builadmin` 目录，为路径拼写错误，建议删除或修正为 `webman-builadmin/web`。
2. **生产环境**：建议将 `config/app.php` 中 `debug` 改为从 `.env` 读取，例如 `env('app_debug', false)`。
3. **密码加密**：使用 `hash_password()` 存储密码，`verify_password()` 校验。

---

## 九、相关文档

- [CRUD 生成逻辑说明](docs/CRUD生成逻辑说明.md)
- [Webman 官方文档](https://webman.workerman.net)
- [BuildAdmin 官网](https://wonderful-code.gitee.io/buildadmin/)

---

## 十、许可证

MIT License