# YwxApp 企业级应用框架

> 基于 ThinkPHP 6 的多应用 + 插件化企业建站/应用市场框架。框架免费，通过插件与模板商业化变现（Discuz! 式闭环：提交 → 审核 → 上架 → 购买 → 支付 → 授权 → 域名绑定 → 运行期巡检 → 分润提现）。

- **版本**：`1.0.16`
- **官网**：https://www.ywxapp.cn
- **运行环境**：PHP >= 7.4（推荐 8.0+）、MySQL >= 5.7、Redis（可选，用于缓存/队列）

---

## 一、特性

| 特性 | 说明 |
| --- | --- |
| 多应用架构 | `frontend`（企业站/官网，默认首页）、`backend`（后台，入口 `/admin`）、`member`（会员中心，入口 `/user`）、`api`（接口，入口 `/api`） |
| 插件化体系 | 业务功能以插件形式存在（`addon/<name>/`），支持在线安装、离线包安装、热重载、一键修复 |
| 应用市场 | 内置 `appmall` 插件（中心站），对接自托管市场，支持购买、授权、域名绑定、升级巡检 |
| 数据库自愈 | 模型壳内置 `ensureSchema()`，缺表建表、缺列补列，部署无需手跑 SQL |
| 可视化设计器 | 开发模式下后台「设计插件」可可视化生成插件骨架、配置项、菜单、路由、页面 |
| 前后台皮肤 | 支持模板/皮肤叠加（`SkinOverlay`），核心后台布局与业务视图分离 |
| 命令行工具 | 插件管理、脚手架生成、健康检测、授权校验、框架升级等全套 CLI |

---

## 二、环境要求与准备

- PHP 7.4+（推荐 8.0+），需开启扩展：`pdo_mysql`、`mbstring`、`curl`、`openssl`、`fileinfo`、`redis`（可选）
- MySQL 5.7+ / MariaDB 10.2+
- Composer 2.x
- Web 服务器：Nginx / Apache（推荐 Nginx，已内置伪静态规则）

### 目录权限

部署后请确保以下目录可写（Linux 下建议 `755`，运行时目录 `777`）：

```
runtime/            运行时缓存、日志
public/static/      插件静态资源发布目录（安装/重载时写入）
addon/              插件源码目录
```

---

## 三、安装部署

### 方式一：Web 安装器（推荐）

项目内置 Web 安装向导，访问站点根目录即可进入：

```
http://your-domain.com/install/
```

安装器位于 `public/install/`，流程：

1. 环境检测（PHP 版本、扩展、目录权限）
2. 配置数据库连接（读取/生成 `.env`）
3. 导入 `public/install/install.sql` 初始化数据表与管理员账号
4. 安装完成，**务必删除 `public/install/` 目录**以防被重复触发

> 注意：`.env` 含数据库敏感配置，请勿将其整体覆盖或提交到公开仓库；修改配置请用局部 `replace_in_file`。

### 方式二：手动部署（已有数据库）

```bash
# 1. 安装依赖
composer install --no-dev -o

# 2. 复制环境变量模板并填写
cp .env.example .env        # 如无模板则手动创建 .env

# 3. 导入数据库（自行执行 install.sql 或已有库）

# 4. 生成应用密钥并设置运行时权限
php think key:generate      # 如支持
chmod -R 755 runtime addon public/static
```

### 伪静态（Nginx 示例）

```nginx
location / {
    if (!-e $request_filename) {
        rewrite  ^(.*)$  /index.php?s=/$1  last;
        break;
    }
}
```

Apache 已内置 `.htaccess`。

---

## 四、目录结构

```
ywxapp_dev/
├── addon/                  # 插件目录（核心业务以插件交付）
│   ├── blog/               # 博客插件
│   ├── forum/              # 论坛插件
│   ├── articles/           # 内容管理(CMS)插件
│   ├── haonav/             # 网址导航插件
│   ├── appmall/            # 应用市场（中心站）
│   └── wxchat/             # 微信客服插件
├── app/                    # 多应用（系统级）
│   ├── frontend/           # 企业站/官网（默认首页）
│   ├── backend/            # 后台管理（入口 /admin）
│   ├── member/             # 会员中心（入口 /user）
│   └── api/                # 接口应用（入口 /api）
├── ywxapp/                 # 框架核心库
│   ├── AddonBase.php       # 插件基类（插件控制器须 use ywxapp\AddonBase）
│   ├── service/            # AppService(启动/命令注册/路由加载)、AddonService、MarketService…
│   ├── model/              # BaseModel（数据库自愈引擎）
│   ├── command/            # 命令行（addon:manage / repair / make / health / license-check / ywxapp:upgrade）
│   └── controller/         # BackendBase / FrontendBase / MemberBase 基类
├── config/                 # 全局配置
│   ├── ywxapp.php          # 框架主配置（验证码/多语言/API地址/插件开关…）
│   ├── app.php             # 多应用配置（default_app / app_map）
│   ├── route.php           # 路由
│   └── database.php        # 数据库
├── public/                 # Web 根目录
│   ├── install/            # Web 安装器（安装后删除）
│   ├── static/             # 静态资源（插件资源发布到此）
│   └── index.php           # 入口
├── runtime/                # 运行时（缓存/日志，可写）
├── extend/                 # 扩展目录
├── composer.json
└── README.md
```

> 旧版 `addons/`（复数）已重命名为 `addon/`（单数），核心基类 `ywxapp/Addons.php` 已重命名为 `AddonBase.php`，请勿再使用旧的 `use ywxapp\Addons`。

---

## 五、多应用与访问入口

`config/app.php` 配置多应用映射（`app_map`）：

| 访问入口 | 应用目录 | 说明 |
| --- | --- | --- |
| `/`（默认） | `app/frontend` | 企业站/官网，`default_app=frontend` |
| `/admin/*` | `app/backend` | 后台管理（登录页 `/admin/login/index`） |
| `/user/*` | `app/member` | 会员中心（登录页 `/user/login/index`） |
| `/api/*` | `app/api` | 接口应用 |

后台升级相关控制器使用 `framework` 前缀路由（如 `framework/check`、`framework/upgrade`），请勿改回 `upgrade`。

---

## 六、插件开发

### 6.1 插件目录约定

```
addon/<name>/
├── info.php            # 插件元信息（name/title/version/state/config…）
├── menu.json           # 后台/会员/前台菜单（backend/member/frontend 三段）
├── route/
│   └── app.php         # 路由（写相对组名，由 AppService 自动补全插件前缀）
├── controller/
│   ├── Index.php               # 前台控制器
│   ├── backend/Article.php     # 后台控制器
│   └── member/Article.php      # 会员控制器
├── model/              # 模型（含 ensureSchema() 自愈）
├── service/           # 业务服务
├── view/              # 模板
├── install.sql        # 安装 SQL（CREATE TABLE + 种子；禁 -- 注释、禁 \' 转义）
├── upgrade.sql        # 升级 SQL
└── config.php         # 插件配置（支持 .env 覆盖）
```

### 6.2 插件元信息 `info.php`

```php
return [
    'name'    => 'blog',
    'title'   => '博客应用',
    'version' => '1.0.2',
    'state'   => 1,                       // 1=启用
    'url'     => '/blog',
    'config'  => [],                      // 插件配置项
];
```

### 6.3 控制器基类

插件控制器继承框架基类，后台控制器绑定 `AdminAuth` 须用 `static::class`：

```php
<?php
namespace addons\blog\controller\backend;

use ywxapp\AddonBase;   // 注意：是 AddonBase，不是 Addons
use ywxapp\controller\BackendBase;

class Article extends BackendBase
{
    // 禁止无参 fetch()，须 fetch('backend/article/index')
}
```

### 6.4 路由与菜单

- 插件 `route/app.php` 写相对组名，由 `AppService::loadAddonRoutes()` 的 `Route::group('<插件名>')` 补全，**不要**加前缀或 `->prefix('api/')`。
- **后台 URL 必须用「带点」形式**（`blog/backend.article/index`），因为 `Route::group` 下出现 `backend` 层级 TP 会拼成点分隔；斜杠形式恒 404。
- 修改 `menu.json` 后执行 `php think addon:repair <name> --menu` 重载菜单。
- **改完路由务必清路由缓存**：`Remove-Item runtime/route_list.php`，否则旧规则导致 404/500。

### 6.5 模型与数据库自愈

每个模型壳内置静态 `ensureSchema()` 自建表，`BaseModel` 提供 `ensureTable/ensureColumn/tableExists/ensureAutoIncrementPk/currentPrefix/ensureTableFromInstall`。部署时缺表缺列会自动补齐，无需手跑 SQL。

> 时间字段统一：`create_at` / `update_at` / `delete_at`（软删除 int 时间戳，0=未删）。
> 后台表 `admin_*` → `backend_*`；用户中心 `user_*` → `member_*`。

---

## 七、命令行工具

命令在 `ywxapp/service/AppService.php` 的 `boot()` 中显式注册（`config/console.php` 的 commands 不生效）。

| 命令 | 说明 |
| --- | --- |
| `php think addon:manage <name> -a develop` | 开发者模式安装（源码已在 `addon/<name>`，原地建表/注入菜单/启用，免打包） |
| `php think addon:manage <name> -a install [--local=<zip>] [--force]` | 在线/离线安装插件 |
| `php think addon:manage [<name>] -a reload [--force] [--status]` | 热重载插件（重导菜单/资源） |
| `php think addon:repair <name> [--menu\|--db\|--config]` | 一键修复：菜单重载 + 数据库自愈 + 配置补全；`<name>` 可为 `all` |
| `php think addon:make <name> -a <action> [--name=<类>]` | 脚手架：生成 controller/model/middleware/validate/event/listener/service/subscribe |
| `php think addon:health` | 插件健康检测（依赖/表/菜单完整性） |
| `php think addon:license-check` | 运行期授权校验 |
| `php think ywxapp:upgrade` | 框架在线升级（`framework` 路由配套） |

示例：

```bash
# 安装 blog 插件（开发者模式）
php think addon:manage blog -a develop

# 修复所有插件的菜单与数据库
php think addon:repair all

# 用脚手架生成一个后台控制器
php think addon:make blog -a controller --name=backend/Stat
```

---

## 八、后台使用与配置

- 后台入口：`/admin`（映射 `app/backend`），登录页 `/admin/login/index`
- 会员中心：`/user`，登录页 `/user/login/index`
- 主配置：`config/ywxapp.php`
  - `usercenter`：是否开启前台会员中心
  - `login_captcha` / `user_register_captcha`：登录/注册验证码
  - `api_url`：应用市场 API 地址（中心站留空或 `market_mode=center`，客户机指向中心站域名）
  - `addon_developer`：开发模式开关（开启后后台出现「设计插件」入口）
  - `addon_license_check`：运行期授权校验开关
  - `lang_switch_on`：多语言开关

### 中心站 / 客户机模式

由 `config/ywxapp.php` 的 `market_mode`（auto/center/client）决定，`auto` 时按 `api_url` 推导（空=中心站，指向他机=客户机）。解耦设计：中心站逻辑全在 `addon/appmall/`，`ywxapp/`、`app/` 禁直读 `appmall_*` 表；插件控制器只做分发（客户机 → 远程服务，中心站 → `MarketService`，缺失 → 503）。

---

## 九、打包与分发

- 插件包：`scripts/package_addon.php`（版本号自动递增）
- 框架包：`scripts/package_framework.php`（排除 `config/`、`.env`、`addon/`、`public/static/<插件名>/`）
- 升级：`AddonService::onlineUpgrade($version)`；`importsql` 仅放行 `CREATE TABLE`/`INSERT`，拒绝 `ALTER`/`DROP`（旧库迁移须手动 `RENAME TABLE`）

---

## 十、常见问题（FAQ）

**Q1：后台菜单点了 404？**
先确认 `menu.json` 的 `jump`/路由用的是「带点」形式（`blog/backend.article/index`），再 `php think addon:repair <name> --menu`，最后清路由缓存 `Remove-Item runtime/route_list.php`。

**Q2：插件装完页面破图 / 资源 404？**
执行 `php think addon:manage <name> -a reload` 重新发布静态资源到 `public/static/<name>/`。

**Q3：数据库表不存在报错？**
模型壳的 `ensureSchema()` 通常会自动建表；若仍报错执行 `php think addon:repair <name> --db`。

**Q4：改了插件代码不生效？**
多半是路由缓存。`Remove-Item runtime/route_list.php` 后重试；生产环境关闭 `APP_DEBUG` 前请先清缓存。

**Q5：PHP 文件上传后报「已发送头」/ 乱码？**
`write_to_file` 可能产生 UTF-8 BOM，上线前请去 BOM（或 `php -l` 校验）。

---

## 十一、许可与商业化

- 框架核心基于 ThinkPHP 协议，免费使用。
- 商业化通过 `addon/appmall` 应用市场分发插件与模板，支持购买、授权、域名绑定、分润提现。
- 详细商业化与运营文档见 `docs/`。

---

© 2026-2036 YwxApp. All rights reserved.  https://www.ywxapp.cn