MAGICODES.ADMIN起步教程

简要介绍 Magicodes.Admin后台服务以及后台前端(Angular)如何获取、上手使用等等。

获取源代码

后台服务git库：https://gitee.com/magicodes/Magicodes.Admin.Core

后台UI git库：https://gitee.com/magicodes/Magicodes.Admin.UI(新版)

起步教程

ASP.NET Core应用

在 Visual Studio 2017中打开看到解决方案如下

该解决方案具有分层结构(基于域驱动设计), 其中:

• Web为是表示层.

• Application 为应用层.

• Core 为领域层.

• Data 为 EF Core集成

• Unity 为通用服务层

• Test 为单元测试层

• Docker-compose 是一个用于定义和运行多容器Docker应用程序的工具

解决方案还包含配置好的的单元&集成测试项目, 以便与 EF
Core 和 SQLite内存中 数据库配合使用

创建数据库

查看Web解决方案文件夹下项目Admin.Host 中 appsettings.json文件中的 连接字符串:

“ConnectionStrings”: {

“Default”: “Server=(localdb)\\MSSQLLocalDB; Database=Magicodes.Admin;
Trusted_Connection=True;”

}

解决方案使用 Entity Framework Core 和 MS SQL Server. EF
Core支持各种数据库提供程序,因此你可以根据实际需要使用其他DBMS

右键单击Admin.Host项目并设置启动项目

打开包管理器控制台(Package Manager Console),
选择.EntityFrameworkCore项目作为默认项目并运行Update-Database命令:

这将基于配置的连接字符串创建新数据库.可以打开SQL Server Management
Studio以检查是否创建了数据库：

运行后台api服务

完成配置后，就可以运行应用程序了。服务器端应用程序仅包含API。因此，默认页面是一个
Swagger UI 的交互界面。

Angular 应用

预序要求

Angular 应用需要安装以下工具

• nodejs 6.9+ 或者npm 3.10+

• Typescript 2.0+

• Yarn

• VS Code

还原Packages

打开项目在VScode终端管理运行npm i (或者yarn)命令

注意：我们建议使用yarn，因为npm有一些问题。它速度慢，不能一致地解决依赖关系，yarn解决了这些问题，而且它也与npm兼容。

修改API路径

找到src/assets/appconfig.json文件中的remoteServiceBaseUrl节点值

{

“remoteServiceBaseUrl”: “http://localhost:2000",

}

运行angular应用

在VScode终端管理运行npm star (或者yarn start)命令

编译应用程序后，可以在浏览器中浏览http://localhost:4200。

登陆

一切就绪后运行解决方案进入登录页面，输入用户名admin, 密码123456abcD, 单击
登录 按钮。

应用程序界面

登录到应用程序后，将看到如下页面：

开发指南

介绍

在开发指南中，创建了一个名为“CMS”的新示例项目。本文档是开发项目时的指南。我们绝对建议在开始开发之前阅读本文档。

本示例项目前端运用Angular。服务器端使用 ASP.NET
Core。

总体架构

下图显示了总体架构：

• Angular项目是可以独立于后端ASP.NET
  Core解决方案部署到同一服务器中的不同端口或不同的服务器。部署后，它实际上是一个普通的HTML+JS+CSS
  Web应用程序，可以在任何操作系统和任何Web服务器上使用。

• Angular 解决方案由两个基本模块组成：

  • AccountModule：用于登陆注册和记住密码等，主要用于在服务端使用tokenauthcontroller对用户进行身份验证。

  • AppMoudule：用于经过身份认证后的用户，一旦用户登陆成功将重定向到主应用程序，通过使用基于请求头部的token的Ajax请求执行的通信。

• Asp.Net Core
  解决方案没有任何HTML、JS或CSS代码。它只提供基于token的身份验证和使用应用程序服务端。

Angualr 解决方案

Angular解决方案的入口是src/main.ts，它是引用Angular根模块下的：RootModule.解决方案的基本模块如下图所示：

• RootModule：只负责引导应用程序

• AccountModule ：它提供登录、双因子身份验证、注册、密码忘记/重置、电子邮件激活等功能。但它是懒加载。

• AppModule ：它是对应用程序模块进行分组并提供基本布局，其中包含两个字模块。

  • AdminModule：它包含用户管理、角色管理、租户管理、语言管理、设置等页面。但同样它也是懒加载的。

  • MainModule：是开发自己的应用程序的主要模块，它包含了仪表盘等功能。建议将应用程序划分为更小的模块，类似启动项目中那样。而不是将所有功能都添加到主模块中。它同样是懒加载的。

基础模块都有自己的路由，例如：AccountMould视图用“/account”开头（例：“/account/login”）.Angular路由懒加载是基于父级模块url上完成的。比如当你的url以“app/admin”开头时，AdminModule及其所有组件都已加载，如果你不请求这些页面，则不会加载他们。（因为他们独立分割开了，所以更便于扩展）

除了这些基础模块还提供他了一些公用模块

• app/shared/common/app-common.module：main和admin的共享模块。

• shared/common/common.module：Account和app模块(及子模块)共享模块。

• shared/utils/utils.module：所有的模块(及其子模块)的通用模块，在不同的应用程序中都可以用。

• shared/service-proxies/service-proxy.module：通过nswag自动生成的代码，用于和后端ASP.NET
  Core API进行通信。

配置

Angular解决方案 src/assets/appconfig.json 中包含客户端配置的文件

• remoteServiceBaseUrl: 用于配置服务器端API的地址。默认值：http：//
  localhost：2000

• appBaseUrl：用于配置客户端应用程序的地址。默认值：http：//
  localhost：4200

• localeMappings: 用于配置与现有本地化不兼容的第三方库的本地化

appBaseUrl：我们想将租户名称用作多租户应用程序的子域名，那么我们可以将appBaseUrl定义为
http://{TENANCY_NAME}. localhost:4200

{TENANCY_NAME} 是租户名称的占位符，我们同样也可以为remoteServiceBaseUrl配置租户名称。要使租户名称子域正常工作，我们还需要在应在应用程序旁边进行两种配置：

• 我们应该配置DNS以将所有子域重定向到静态IP地址。要声明“所有子域名”，我们可以使用*
  . localhost之类的通配符。

• 我们应该配置IIS的静态IP绑定到我们的应用程序。

账户模块(AccountModule)

账户模块包括登录，注册，忘记密码和电子邮件激活页面并位于src/account目录下

account.component是account.module的根组件。
account-routing.module定义帐户应用程序的路由

登陆

AccountModule的默认路由是login / login.component

登录部分上方的租户选择功能仅在启用多租户时候显示，并且如果无法从URL中检测出租户名称（例：如果使用子域名作为租户名称，就不必要显示租户选择）。当我们点击更改链接时，会出现租户更改对话框，我们可以更改租户。
初始数据库中有一个名为Default的租户。 将租户名称输入留空以Hots登录。

我们首次使用admin用户名和123456abcD密码登录时，会提示修改管理员密码(该功能暂时移除掉了，为了兼容新版UI)

更改密码后，我们将重定向到（app.module）

社交登陆

两步认证

Magicodes已经提供两步认证登陆，但默认情况下已禁用。
您可以在Host设置页面（在“安全”选项卡中）轻松启用它：

注意：在多租户应用程序中，只有在Host设置中启用了两步认证登陆租户才可以使用。此外，电子邮件验证和短信验证设置仅在Host可用。

启用后，系统会要求用户在输入用户名和密码后选择验证提供程序

选择后确认的验证码将发送给选定的提供者，用户在下一页中输入验证码。

邮箱验证码

如果选择邮箱验证，在本地调试模式下可以通过日志查看验证码，在正式环境下可以通过完善相应的配置使邮箱接受到邮件验证码

短信验证码

如果选择短信验证码，SMS发送实际上没有实现（因为它需要集成SMS供应商的配置）,同样也会将验证码写入日志。如果完善了相关配置就可以收到短信验证码。

*Twilio集成

启用Twilio集成，只需取消注释CoreModule中的以下行（在.Core项目中）：Configuration.ReplaceService
<ISmsSender，TwilioSmsSender>（）;
您还需要在appsetting.json文件中配置AccountSid，AuthToken和SenderNumber。

用户锁定

可以配置用户锁定设置。当用户输入错误密码达到指定的计数和持续时间时，用户将被锁定。

注册

当我们在登录页面中单击“新租户”链接（仅适用于多租户应用程序的租户）时，会显示一个注册表单：

注：安全问题是可选的，它使用的是谷歌的recaptcha服务，为了其正常的运行需要在https://www.google.com/recaptcha
上创建自己的私钥和公钥，并替换掉服务端appconfig.json中appsettings.json文件中的密钥.

邮箱激活

当用户如上所示注册时，验证码将会已电子邮件的方式发送到你的邮箱地址。如果用户由于某种原因未收到此电子邮件，则可以单击“电子邮件激活”并重新发送确认代码。

忘记密码

如果忘记密码，可以单击“忘记密码”链接以获取重置密码的电子邮件

租户注册

在Host环境时，才会在登录表单上显示租户注册链接。当您单击该链接时，将显示一个注册表单：

APP模块(AppModule)

登陆后应用程序模块。主要完善和展示业务需求

源代码目录结构

它由3个子模块组成。 app.component是所有视图的根组件。

主菜单和布局

主菜单和布局目录结构

主菜单在nav/side-bar.component中定义和呈现。您可以在此处添加新菜单项。通常将菜单项与Angular路由相关联。Angular路由在几个模块中定义：

• app/admin/admin-routing.module：管理模块路由

• app/main/main-routing.module：主模块路由

• app/app-routing.module：普通模块和默认模块路由

版本管理

版本管理只有开启了多租户才会显示

大多数SaaS(多租户)应用程序都拥有不同版本，因此，可以根据不同版本提供不同的价格和服务。版本页可以管理不同的版本及价格。

版本管理按照特征进行分组并分配给租户，可以通过点击创建新版本来创建版本。

版本可以选择免费\付费，如果是付费版需要输入月费用和年费用。也可以允许租户在指定日期内使用试用版。可以设置过期策略，订阅到期后设置使用天数，也可以不延长订阅，停用或者分配免费版本。

特性选项用于确定版本可用功能

租户管理

以Host的用户身份登录，则会显示租户页面(如果没有开发多租户应用程序则不会显示租户管理)

租户的实体类是 Tenant
Class，可以通过添加新属性来扩展这个类。默认只有一个租户(Default)，租户名称是租户的唯一标识(也可以用来当子域名用)，租户分为激活和未激活的状态，如果租户处于未激活状态则不能登陆。

点击”添加租户”时，会显示如下界面

租户名称应该是唯一的，它不能包含空格和特殊字符因为它可以用来当子域名用(例:
tenancyname.xin-lai.com)