# 安装模块

本文档介绍如何将 DarkM 模块集成到现有项目中。

# 📦 安装方式

DarkM 模块通过 NuGet（后端）和 NPM（前端）包管理，实现即装即用。

类型	包管理	示例
后端模块	NuGet	`DarkM.Module.Quartz.Web`
前端模块	NPM	`darkm-module-quartz`

# 🎯 场景示例：集成 Quartz 任务调度模块

假设您有一个 Vacation（请假）模块，现在需要添加定时任务功能。

# 一、后端集成

# 步骤 1：安装 NuGet 包

使用 Visual Studio 或命令行安装：

# 方式一：Visual Studio 包管理器控制台
Install-Package DarkM.Module.Quartz.Web -Version 1.0.2

# 方式二：.NET CLI
dotnet add package DarkM.Module.Quartz.Web --version 1.0.2

# 方式三：编辑 .csproj 文件
<PackageReference Include="DarkM.Module.Quartz.Web" Version="1.0.2" />

1
2
3
4
5
6
7
8

# 步骤 2：配置数据库

在 appsettings.json 中添加 Quartz 模块配置：

{
  "Db": {
    "Modules": [
      {
        "Name": "Admin",
        "Database": "Nm_Admin"
      },
      {
        "Name": "Vacation",
        "Database": "Nm_Vacation"
      },
      {
        "Name": "Quartz",              // ← 新增 Quartz 模块
        "Database": "Nm_Quartz"
      }
    ]
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

配置说明：

字段	说明	是否必需
`Name`	模块名称（必须与包名一致）	✓
`Database`	数据库名称	✓
`Prefix`	表前缀（可选）	✗
`ConnectionString`	自定义连接字符串（可选）	✗
`Version`	指定版本号（可选，默认最新版）	✗

# 步骤 3：初始化数据库

启动应用时会自动创建数据库和表：

dotnet run

启动日志：

[INFO] 正在初始化模块：Admin
[INFO] 数据库 Nm_Admin 创建成功
[INFO] 正在初始化模块：Quartz
[INFO] 数据库 Nm_Quartz 创建成功
[INFO] 模块初始化完成

1
2
3
4
5

# 步骤 4：验证安装

访问 Swagger 查看 Quartz 相关接口：

http://localhost:6220/swagger (opens new window)

应该能看到以下接口：

POST /api/quartz/job - 创建任务
GET /api/quartz/job - 查询任务列表
PUT /api/quartz/job/{id} - 更新任务
DELETE /api/quartz/job/{id} - 删除任务
POST /api/quartz/job/{id}/start - 启动任务
POST /api/quartz/job/{id}/stop - 停止任务

# 二、前端集成

# 步骤 1：安装 NPM 包

# 进入前端项目目录
cd src/Admin/UI/module-admin

# 安装 Quartz 模块
npm i -S darkm-module-quartz

1
2
3
4
5

# 步骤 2：注册模块

编辑 src/main.js 文件：

import WebHost from 'darkm-module-admin'
import Quartz from 'darkm-module-quartz'  // ← 导入 Quartz 模块
import Vacation from './index'
import config from './config'

// 注册模块
WebHost.registerModule(Quartz)           // ← 注册 Quartz
WebHost.registerModule(Vacation)

// 启动应用
WebHost.start(config)

1
2
3
4
5
6
7
8
9
10
11

# 步骤 3：配置路由（可选）

如果需要自定义菜单，编辑 src/config/routes.js：

export default [
  {
    path: '/quartz',
    name: 'Quartz',
    component: () => import('@/views/quartz/index'),
    meta: {
      title: '任务调度',
      icon: 'el-icon-time'
    }
  }
]

1
2
3
4
5
6
7
8
9
10
11

# 步骤 4：启动前端

npm run serve

访问：http://localhost:5220/app/ (opens new window)

# 📋 完整模块列表

以下是常用模块的安装命令：

# 后端 NuGet 包

模块	包名	版本
权限管理	`DarkM.Module.Admin.Web`	1.0.2
通用模块	`DarkM.Module.Common.Web`	1.0.2
任务调度	`DarkM.Module.Quartz.Web`	1.0.2
代码生成器	`DarkM.Module.CodeGenerator.Web`	1.0.2
人事管理	`DarkM.Module.HumanResources.Web`	1.0.2
工作流	`DarkM.Module.WorkFlow.Web`	1.0.2

# 前端 NPM 包

模块	包名	版本
权限管理	`darkm-module-admin`	1.0.2
通用模块	`darkm-module-common`	1.0.2
任务调度	`darkm-module-quartz`	1.0.2
代码生成器	`darkm-module-codegenerator`	1.0.2
人事管理	`darkm-module-humanresources`	1.0.2
工作流	`darkm-module-workflow`	1.0.2

# 🔧 高级配置

# 1. 多数据库配置

不同模块可以使用不同的数据库：

{
  "Db": {
    "Modules": [
      {
        "Name": "Admin",
        "Database": "Nm_Admin",
        "Dialect": 0,  // SqlServer
        "Server": "192.168.1.100",
        "UserId": "sa",
        "Password": "***"
      },
      {
        "Name": "Quartz",
        "Database": "Nm_Quartz",
        "Dialect": 2,  // SQLite
        "Server": "../../data/quartz.db"
      }
    ]
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# 2. 自定义模块版本

{
  "Db": {
    "Modules": [
      {
        "Name": "Quartz",
        "Database": "Nm_Quartz",
        "Version": "1.0.2"  // 指定版本
      }
    ]
  }
}

1
2
3
4
5
6
7
8
9
10
11

# 3. 禁用模块

{
  "Db": {
    "Modules": [
      {
        "Name": "Quartz",
        "Database": "Nm_Quartz",
        "Enabled": false  // 禁用模块
      }
    ]
  }
}

1
2
3
4
5
6
7
8
9
10
11

# 🎯 配置菜单和权限

模块安装后，需要配置菜单和权限才能访问。

# 步骤 1：添加菜单

登录系统
进入 系统管理 → 菜单管理
点击添加按钮
填写菜单信息

字段	示例
菜单名称	任务调度
菜单类型	菜单
父级菜单	系统管理
路由地址	/quartz
组件路径	quartz/index
图标	el-icon-time
排序	10

# 步骤 2：添加按钮权限

在菜单下添加按钮
填写按钮信息

字段	示例
按钮名称	新增任务
按钮标识	quartz:job:add
按钮类型	按钮

# 步骤 3：角色分配

进入 系统管理 → 角色管理
选择角色
点击 权限分配
勾选菜单和按钮权限
保存

# 步骤 4：刷新页面

重新登录或刷新页面，即可看到新菜单。

# 🔍 常见问题

# 1. NuGet 包安装失败

错误： Unable to find package

解决：

# 检查 NuGet 源
dotnet nuget list source

# 添加私有 NuGet 源
dotnet nuget add source http://nuget.woowis.com/v3/index.json -n DarkM

# 清除缓存
dotnet nuget locals all --clear

1
2
3
4
5
6
7
8

# 2. 模块初始化失败

错误： Module initialization failed

解决：

检查模块名称是否正确
检查数据库连接是否正常
查看日志文件定位具体错误

# 3. 前端模块无法加载

错误： Module not found: darkm-module-quartz

解决：

# 删除 node_modules 和 package-lock.json
rm -rf node_modules package-lock.json

# 重新安装
npm install

# 清理缓存
npm cache clean --force

1
2
3
4
5
6
7
8

# 4. 跨域问题

错误： CORS policy

解决：

{
  "Host": {
    "Proxy": true
  }
}

1
2
3
4
5

# 📚 最佳实践

# 1. 版本管理

{
  "dependencies": {
    "darkm-module-admin": "^1.0.2",
    "darkm-module-quartz": "^1.0.2",
    "darkm-module-common": "^1.0.2"
  }
}

1
2
3
4
5
6
7

建议：

✅ 使用 ^ 锁定主版本
✅ 所有模块使用相同版本
✅ 更新前备份项目

# 2. 模块依赖

Vacation 模块
├── Admin（必需）
├── Common（必需）
└── Quartz（可选）

1
2
3
4

在模块描述文件中声明依赖：

[ModuleDescriptor(
    Name = "Vacation",
    Version = "1.0.0",
    Dependencies = new[] { "Admin", "Common" }
)]

1
2
3
4
5

# 3. 数据库迁移

生产环境建议关闭自动创建：

{
  "Db": {
    "CreateDatabase": false,
    "InitData": false
  }
}

1
2
3
4
5
6

使用数据库迁移脚本：

# 生成迁移脚本
dotnet ef migrations add InitialCreate

# 应用迁移
dotnet ef database update

1
2
3
4
5

# 🔗 相关文档

快速上手 - 项目启动指南
创建模块 - 代码生成器使用
模块化理念 - 设计思想
模块目录 - 完整模块清单

最后更新: 2022-08-07

← 创建一个模块系统架构总览 →