AI 模块导入指南

本指南说明如何将完整的 AI 模块整合到 NiuCloud 系统中，包括文件结构、导入步骤、菜单配置等。

一、模块概述

AI 模块是一个完整的业务模块，包含：

后台管理功能（Admin）
API 接口（API）
数据库表结构（SQL）
前端页面（Vue）
菜单配置（PHP）
语言包（i18n）

二、文件结构说明

2.1 code 目录（可直接覆盖）

code 目录包含完整的源代码文件，可以直接复制到系统中使用。

模块名/
├── code/
│   ├── backend/                    # 后端文件
│   │   └── app/
│   │       ├── adminapi/
│   │       │   ├── controller/    # 后台控制器
│   │       │   └── route/        # 后台路由
│   │       ├── api/
│   │       │   ├── controller/    # API控制器
│   │       │   └── route/        # API路由
│   │       ├── service/
│   │       │   ├── admin/        # 后台服务
│   │       │   └── api/          # API服务
│   │       ├── model/            # 数据模型
│   │       ├── dict/             # 字典配置
│   │       └── lang/             # 语言包
│   ├── frontend/
│   │   ├── admin/                # 后台前端
│   │   │   └── src/
│   │   │       ├── api/          # API接口
│   │   │       ├── lang/         # 语言包
│   │   │       └── views/        # 页面组件
│   │   └── uni-app/             # 移动端前端
│   │       └── src/
│   │           ├── api/          # API接口
│   │           ├── pages/        # 页面
│   │           └── styles/       # 样式
├── files/                         # 需要合并的文件
│   ├── backend/                  # 后端合并文件
│   └── frontend/                 # 前端合并文件
└── sql/
    └── tables.sql               # 数据库表结构

2.2 各层文件对应关系

层级	文件位置	说明
后台控制器	`app/adminapi/controller/{模块}/`	处理后台管理请求
后台路由	`app/adminapi/route/{模块}.php`	后台路由配置
API控制器	`app/api/controller/{模块}/`	处理前端请求
API路由	`app/api/route/{模块}.php`	API路由配置
后台服务	`app/service/admin/{模块}/`	后台业务逻辑
API服务	`app/service/api/{模块}/`	API业务逻辑
数据模型	`app/model/{模块}/`	数据库操作
字典配置	`app/dict/{模块}/`	枚举/常量配置
语言包	`app/lang/`	多语言支持

三、导入步骤

3.1 第一步：执行数据库表结构

找到模块目录下的 sql/tables.sql 文件，执行 SQL 语句创建数据库表。

bash

# 登录数据库
mysql -u root -p

# 选择数据库
use niucloud;

# 执行SQL
source sql/tables.sql;

3.2 第二步：复制后端代码

将 code/backend/ 目录下的所有文件复制到项目后端对应目录：

code/backend/app/  →  项目根目录/app/

注意：如果提示文件已存在，选择"合并"或"跳过"，确保不覆盖已有的核心文件。

3.3 第三步：复制前端代码

将 code/frontend/ 目录下的所有文件复制到前端项目对应目录：

code/frontend/admin/src/  →  admin项目/src/
code/frontend/uni-app/src/  →  uni-app项目/src/

3.4 第四步：合并 files 目录文件

files 目录包含需要合并的文件（如路由文件、API接口文件），不能直接覆盖。

4.4.1 后台路由合并

找到 files/backend/app/adminapi/route/{模块}.php，复制其内容追加到已有的路由文件中。

php

// 原路由文件：app/adminapi/route/member.php
// 需要添加的内容（从 files 目录的对应文件复制）

use app\adminapi\middleware\AdminCheckToken;
use app\adminapi\middleware\AdminCheckRole;
use app\adminapi\middleware\AdminLog;
use think\facade\Route;

Route::group('member', function() {
    // ... 已有路由

    // 添加新的签到路由
    Route::put('sign/config', 'member.MemberSign/setConfig');
    Route::get('sign/config', 'member.MemberSign/config');
    Route::get('sign', 'member.MemberSign/lists');

})->middleware([
    AdminCheckToken::class,
    AdminCheckRole::class,
    AdminLog::class
]);

4.4.2 API路由合并

同样方式合并 files/backend/app/api/route/{模块}.php 到 API 路由文件。

4.4.3 前端API接口合并

复制 files/frontend/admin/src/api/{模块}.ts 内容追加到后台前端 API 文件。

复制 files/frontend/uni-app/src/api/{模块}.ts 内容追加到移动端 API 文件。

4.4.4 页面路由合并（如有）

复制 files/frontend/uni-app/src/pages.json 内容合并到 uni-app 的 pages.json。

3.5 第五步：配置菜单

菜单采用 PHP 配置文件方式，配置在 app/dict/menu/admin.php 中。

5.5.1 菜单配置结构

php

[
    'menu_name' => '签到管理',           // 菜单显示名称
    'menu_key' => 'sign',                // 菜单唯一标识
    'menu_short_name' => '签到管理',     // 简称
    'parent_key' => 'app',              // 父级菜单key
    'menu_type' => '0',                  // 0-目录/页面，1-按钮，2-操作
    'icon' => 'element FolderChecked',  // 菜单图标
    'api_url' => 'member/sign',          // API地址（按钮类型必填）
    'router_path' => 'marketing/sign',  // 前端路由路径
    'view_path' => 'marketing/sign_list', # 前端视图路径
    'methods' => 'get',                  // HTTP方法
    'sort' => '30',                      // 排序
    'status' => '1',                    // 状态：0-禁用，1-启用
    'is_show' => '1',                   // 是否显示：0-隐藏，1-显示
    'children' => [
        // 子菜单
    ]
]

5.5.2 菜单类型说明

menu_type	类型	说明	必填字段
0	目录/页面	页面菜单	icon, router_path, view_path
1	按钮	页面按钮	api_url, methods
2	操作	行内操作	api_url, methods

5.5.3 菜单层级规范

一级菜单（应用目录 menu_type=0）
└── 二级菜单（功能页面 menu_type=0）
    └── 三级菜单（操作按钮 menu_type=1 或 menu_type=2）

5.5.4 菜单配置示例

php

// app/dict/menu/admin.php

return [
    // ========== 一级菜单（应用目录）==========
    [
        'menu_name' => '应用管理',
        'menu_key' => 'app',
        'menu_short_name' => '应用',
        'parent_key' => '',
        'menu_type' => '0',
        'icon' => 'iconfont iconyingyong21',
        'api_url' => '',
        'router_path' => '',
        'view_path' => '',
        'methods' => '',
        'sort' => '86',
        'status' => '1',
        'is_show' => '1',
        'children' => [],
    ],

    // ========== 二级菜单（功能页面）==========
    [
        'menu_name' => '签到管理',
        'menu_key' => 'sign',
        'parent_key' => 'app',
        'menu_short_name' => '签到管理',
        'menu_type' => '0',
        'icon' => 'element FolderChecked',
        'api_url' => '',
        'router_path' => 'marketing/sign/config',
        'view_path' => '',
        'methods' => 'get',
        'sort' => '30',
        'status' => '1',
        'is_show' => '1',
        'children' => [
            // ========== 三级菜单（操作按钮）==========
            [
                'menu_name' => '签到设置',
                'menu_key' => 'sign_set',
                'menu_short_name' => '签到设置',
                'parent_key' => 'sign',
                'menu_type' => '1',
                'icon' => '',
                'api_url' => 'member/sign/config',
                'router_path' => 'marketing/sign/config',
                'view_path' => 'marketing/sign_config',
                'methods' => 'get',
                'sort' => '30',
                'status' => '1',
                'is_show' => '1',
                'children' => [
                    [
                        'menu_name' => '保存',
                        'menu_key' => 'save_sign_set',
                        'menu_short_name' => '保存',
                        'parent_key' => 'sign_set',
                        'menu_type' => '2',
                        'icon' => '',
                        'api_url' => 'member/sign/config',
                        'router_path' => '',
                        'view_path' => '',
                        'methods' => 'put',
                        'sort' => '100',
                        'status' => '1',
                        'is_show' => '1',
                    ]
                ]
            ],
            [
                'menu_name' => '签到记录',
                'menu_key' => 'sign_list',
                'menu_short_name' => '签到记录',
                'parent_key' => 'sign',
                'menu_type' => '1',
                'icon' => '',
                'api_url' => 'member/sign',
                'router_path' => 'marketing/sign',
                'view_path' => 'marketing/sign_list',
                'methods' => 'get',
                'sort' => '30',
                'status' => '1',
                'is_show' => '1',
            ]
        ],
    ],
];

3.6 第六步：配置语言包

将模块的语言包配置添加到系统的语言文件中：

app/lang/zh-cn.php - 中文语言包
app/lang/en.php - 英文语言包

php

// zh-cn.php 添加
'sign_set' => '签到设置',
'sign_list' => '签到记录',
'SIGN_SUCCESS' => '签到成功',

// en.php 添加
'sign_set' => 'Sign Settings',
'sign_list' => 'Sign Records',
'SIGN_SUCCESS' => 'Sign in successful',

3.7 第七步：测试验证

清理缓存：php think clear
访问后台管理页面，检查菜单是否显示
测试各项功能是否正常

四、导入检查清单

步骤	操作	状态
1	执行 sql/tables.sql 创建数据表	☐
2	复制 code/backend/ 到后端目录	☐
3	复制 code/frontend/ 到前端目录	☐
4	合并 files/backend/ 路由文件	☐
5	合并 files/frontend/ API文件	☐
6	添加菜单配置到 admin.php	☐
7	添加语言包配置	☐
8	清理缓存并测试	☐

五、常见问题

5.1 路由冲突

如果合并路由时出现冲突（如路由已存在），检查并调整路由名称。

5.2 菜单不显示

确认菜单配置已添加到 app/dict/menu/admin.php
确认 menu_key 全局唯一
确认父级菜单存在且 status=1

5.3 API 404

检查路由是否正确合并
检查控制器命名空间是否正确
检查路由中间件配置

5.4 前端页面空白

检查 view_path 路径是否正确
检查页面组件是否正确复制
检查路由配置是否正确

系统部署

后台手册

前端手册

Admin 端

UniApp 端

模块开发

附录

AI 模块导入指南

一、模块概述

二、文件结构说明

2.1 code 目录（可直接覆盖）

2.2 各层文件对应关系

三、导入步骤

3.1 第一步：执行数据库表结构

3.2 第二步：复制后端代码

3.3 第三步：复制前端代码

3.4 第四步：合并 files 目录文件

4.4.1 后台路由合并

4.4.2 API路由合并

4.4.3 前端API接口合并

4.4.4 页面路由合并（如有）

3.5 第五步：配置菜单

5.5.1 菜单配置结构

5.5.2 菜单类型说明

5.5.3 菜单层级规范

5.5.4 菜单配置示例

3.6 第六步：配置语言包

3.7 第七步：测试验证

四、导入检查清单

五、常见问题

5.1 路由冲突

5.2 菜单不显示

5.3 API 404

5.4 前端页面空白

Admin 端

UniApp 端

AI 模块导入指南 ​

一、模块概述 ​

二、文件结构说明 ​

2.1 code 目录（可直接覆盖） ​

2.2 各层文件对应关系 ​

三、导入步骤 ​

3.1 第一步：执行数据库表结构 ​

3.2 第二步：复制后端代码 ​

3.3 第三步：复制前端代码 ​

3.4 第四步：合并 files 目录文件 ​

4.4.1 后台路由合并 ​

4.4.2 API路由合并 ​

4.4.3 前端API接口合并 ​

4.4.4 页面路由合并（如有） ​

3.5 第五步：配置菜单 ​

5.5.1 菜单配置结构 ​

5.5.2 菜单类型说明 ​

5.5.3 菜单层级规范 ​

5.5.4 菜单配置示例 ​

3.6 第六步：配置语言包 ​

3.7 第七步：测试验证 ​

四、导入检查清单 ​

五、常见问题 ​

5.1 路由冲突 ​

5.2 菜单不显示 ​

5.3 API 404 ​

5.4 前端页面空白 ​

AI 模块导入指南

一、模块概述

二、文件结构说明

2.1 code 目录（可直接覆盖）

2.2 各层文件对应关系

三、导入步骤

3.1 第一步：执行数据库表结构

3.2 第二步：复制后端代码

3.3 第三步：复制前端代码

3.4 第四步：合并 files 目录文件

4.4.1 后台路由合并

4.4.2 API路由合并

4.4.3 前端API接口合并

4.4.4 页面路由合并（如有）

3.5 第五步：配置菜单

5.5.1 菜单配置结构

5.5.2 菜单类型说明

5.5.3 菜单层级规范

5.5.4 菜单配置示例

3.6 第六步：配置语言包

3.7 第七步：测试验证

四、导入检查清单

五、常见问题

5.1 路由冲突

5.2 菜单不显示

5.3 API 404

5.4 前端页面空白