手册主要包括移动产品的主要架构、开发指南等。

文档说明

目的

本文档根据ITSMOB产品的基础技术架构,为移动端内部开发人员提供入门指南,同时起到对前期工作进行总结、完善的作用。

范围

本文主要描述ITSMOB开发过程并为技术开发人员提供必要的开发规范和约定。

前提

移动终端的开发,涉及到如下知识:

  • 环境方面,熟悉android操作系统及简单操作运用流程;了解服务台Fvsd3.x产品整体框架、所用到的技术、并熟悉ITIL 流程。

  • 语言方面,必须熟练掌握Java语法和android基础知识,熟练掌握android2.3.3以上的SDK;Java EE知识也是不可或缺的。其中客户端和服务端均用由java 进行原生应用开发、移动端报表部分采用JavaScript、HTML5、jQuery Mobile等前端开发工具。

  • IDE工具,必须熟练掌握Eclipse平台开发工具。

  • 技术工具方面,必须了解Mac(Linux)常用命令操作,熟悉adt相关客户端工具和常用操作,当然SVN也是必不可少的。

  • 其他方面,了解android程序交付设计规范。

整体架构

整体采用异步方式,采用传统的3层架构,数据存储/产品端、业务处理/中间层、数据展现层/客户端,产品接口端 基于特定产品,针对移动端进行功能封装;中间层基于云服务器,定位于数据集成服务器,完成数据的分流、过滤等数据处理与运算操作,展示的数据的集成能力;客户端主要采用UI与数据分离的模式,只提供数据的渲染显示和录入推送。 结构如下:

使用文档图片

采用三层架构的优势是:无论是客户端还是产品接口层不需要修改设计和结构,数据协议、格式由产品自行定义,中间服务器端按照API规范进行调用和适配处理。最大程度降低了客户端和产品端的压力。

环境安装与配置

客户端

(IPhone)

基础环境准备:IDE:Xcode 5 、Mac OS 10.8.5、iOS5.0 以上的SDK、Versions。

  • 首先配置好开发工具Xcode ,目前最新的是5.02版本,支持iOS 7,直接在App Store 中找到Xcode 并安装下载即可,安装完毕会在Dock 或者在Finder中应用程序中出现Xcode 的图标 。安装完毕后需要下载iOS 的SDK 包和文档,这里默认采用iOS6.1的SDK 和模拟器。如图所示:

  • 使用文档图片
  • 配置好上述开发环境,就可以下载客户端工程源码,下载地址:由于Xcode 自带的版本管理工具功能简单,建议采用第三方版本管理工具进行下载和版本管理,例如:Versions 。 SVN地址:https:// 104.122.newidc2.cn/svn/itom/concept。下载后的代码结构如下:

  • 使用文档图片
  • 双击ITSMOB.xcworkspace, 直接就可以打开工程,右键双击ITSMOB工程,进入工程配置界面,这里可以对工程相关的环境进行详细配置,包括SDK,支持版本等;如果是真机测试,还会涉及到签名相关的选择,会在后面进行介绍。如图所示:

使用文档图片

通过Command+R快捷方式,可以在模拟器中运行该工程。

(Android)

基础环境准备:eclipse3.5以上、android 2.3.3以上sdk、adt。

  • Eclipse的安装;Eclipse集成开发环境是开放的软件,可到Eclipse的网站上去下载: http://www.eclipse.org/downloads/ 。下载使用最新Eclipse IDE for Java Developers或者eclipse IDE for java EE Developers。这个包不需要安装,直接解压缩即可,解压缩后执行其中的eclipse.exe文件。

  • 2、Android SDK 安装;在Android Developers下载adt-bundle-windows-x86-20130219.zip,下载完成后解压到任意路径。 运行SDK Manager.exe,选中所要下载的android版本,点击Install packages...、Accept All、Install Accepted,开始下载安装所选包。

  • 使用文档图片
  • ADT安装; 打开 Eclipse IDE,进入菜单中的 "Help" ->"Install New Software" 点击Add...按钮,弹出对话框要求输入Name和Location:Name自己随便取,Location输入http://dl-ssl.google.com/android/eclipse。如下图所示:

使用文档图片

确定返回后,在work with后的下拉列表中选择我们刚才添加的ADT,我们会看到下面出有Developer Tools,展开它会有Android DDMS和Android Development Tool,勾选他们。 如下图所示:

使用文档图片

然后就是按提示一步一步next。完成之后:选择Window > Preferences...在左边的面板选择Android,然后在右侧点击Browse...并选中SDK路径,本机为: D:AndroidDevelopandroid-sdk-windows点击Apply、OK。配置完成。

4、创建AVD; 为使Android应用程序可以在模拟器上运行,必须创建AVD。

  • 在Eclipse中。选择Windows > Android SDK and AVD Manager。
  • b、点击左侧面板的Virtual Devices,再右侧点击New。
  • 填入Name,选择Target的API,SD Card大小任意,Skin随便选,Hardware目前保持默认值。
  • 点击Create AVD即可完成创建AVD。
注意:如果你点击左侧面板的Virtual Devices,再右侧点击New ,而target下拉列表没有可选项时,点击左侧面板的Available Packages,在右侧勾选https://dl-ssl.google.com/android/repository/repository.xml,如下图所示:

使用文档图片

然后点击Install Selected按钮,接下来就是按提示做就行了要做这两步,原因是在1.3、Android SDK安装中没有安装一些必要的可用包(Available Packages)。

中间服务器

中间服务器端采用java 开发,其主要的作用在于适配客户端与产品之间的数据交互;对客户端请求的数据进行封装后然后传递到产品指定接口;并对产品返回的数据进行过滤、分流处理后传递到客户端进行渲染,中间服务器的存在,分流了产品的数据访问压力,降低了直接网络连接时的数据流量,同时也保证了客户端与产品端的独立性。

中间服务器端代码是通过Git 进行管理,源码全部托管在Github上的,首先需要配置好Github的帐号、配置、环境等。由于网络上这方面的资料比较多,这里就不再描述其详细的安装配置。我们在开发中采用的是Eclipse的EGit 插件配合命令行的方式来进行操作,EGit 插件可以通过Eclipse Marketplace进行下载,这里以EGit 插件来进行演示,也可以采用git 命令来进行来进行工程的源码管理。

服务器端分两个工程,git地址如下:
cellcloud:https://github.com/xujiangwei/cellcloud-java.git
smart-server: https://github.com/xujiangwei/smart-server.git

其中cellcloud为开源的面向云计算应用系统开发者的云计算引擎,前者作为依赖工程为后者提供云计算服务。 在Eclipse 中点击如下图标,切换到Git Repository 视图中,如图:

使用文档图片

将上述两个工程clone 到本地工作空间,如图所示:

使用文档图片

将上图所示Working Directory中的4个子工程通过右键导入到workspace中,并作为普通的Java工程。

使用文档图片

最后切换到Eclipse的Java视图,配置各工程之间的依赖和引用,其中,cell工程依赖nucleus, smart-common依赖nucleus,smart-cellet工程依赖上述三个工程;同时,smart-cellet 工程内置Jetty 服务器,需要导入jetty 相关的jar包,smart-cellet 工程也是我们需要做二次开发的核心工程,nucleus 是核心依赖工程。

在smart-cellet工程中需要重点关注如下核心类:

  • HostConfig.java :主机配置,确定不同产品接口端的信息。采用策略模式,能够任意切换不同的产品端,和API.java 类配合,能够确定完整的接口请求URL。
  • ServiceDeskHostConfig.java:服务台产品的配置信息,由服务器开发人员和产品接口开发人员协同维护。
  • API.java: 定义所有接口请求的URL地址。
  • Action.java:定义客户端与中间服务器端协商好的请求标识。通过请求标识得到接口URL,完成数据的传递与交互。
  • ActionListener:监听器的顶层接口,所有业务请求必须实现该接口。
  • SmartCellet.java:工程核心类,配置HTTP协议,加载所有的监听器等。

通过以上配置和核心类,就可以进入到服务器端的开发。

产品端

产品接口端基于服务台Fvsd3.7,目前所有的接口都建立在Action 层面,这样做的优势在于减少对服务台产品底层结构的浸入,产品开发人员与接口开发人员可以相互独立工作,接口开发人员直接对现有业务功能模块单元进行封装,大大减少了接口开发的工作量,同时也保证了产品的独立性。

相关环境与配置见产品相关文档,这里不再复述。目前已经完成的功能结构如下:

使用文档图片
注意:
  • 工程的所有代码都采用UTF-8编码,请在安装完eclipse后将工作空间的默认编码设置为UTF-8以免出现中文乱码问题。
  • TortoiseSVN 和subclipse的版本必须保持一致。
  • 数据库在安装时需要将数据库的默认编码设置为UTF-8。

开发指南

此处分别对客户端和服务器接口端的核心代码进行分析,让技术人员对关键技术有深入的了解,对于产品端接口的开发,前面提到已经很多,如下不再复述,请参考产品相关文档。

客户端开发

(IPhone)

代码结构如图所示:

使用文档图片
目录 子目录 描述
ITSMOB 客户端工程核心目录,所有的业务代码全部集中在该包中
Problem 问题模块
Incident 故障模块
common 公用模块(包括故障和问题的附件和日志模块等)
Collection、Order、Notice、Setting、Own 用户管理模块,包括消息设置等
HomeView 导航与门户
Asset sqlite数据库
Signin 登陆模块
introductFunction 引导页模块
Model 数据模型
Core 引擎核心代码
FrameWorks 依赖库,类似java工程中的第三方jar 包
libnucleus.a 与服务器端进行交互的工程依赖库
libJSONKit.a json 工具库
libMBProcessHUD.a 提示框
libsqlite3.0.dylib sqlite数据库操作库
ThirdParty 第三方工具包
RetableViewManager 表单工具包,解决流程表单的个性化定制
NavigationMenuView 自定义NavigationBar
RESideMenu 侧滑菜单
DAcossssntentMenuCell 自定义侧滑菜单
MBProgressHUD HUD显示
Popover 弹出菜单
TimeLine 时间轴工具
TSMessage 弹出提示工具
DataBase 数据库工具

(Android)

代码结构如图所示:

使用文档图片
目录 子目录 描述
Src 客户端工程的后台代码
Activity/login 登录模块,包括闪图、引导图、网络配置等。
Activity/notice 消息模块,包括消息接收、查看、发送等
Activity/todo 待办模块,包括故障、问题、变更、巡检任务等
Activity/user 用户模块,包括账户设置、账户信息管理等
MainActivity 系统主界面
UtilTitleActivity 公共继承类,用于头部共用
Adapter 代码适配器
Bean 各模块需要用到的实体类
Db/data 用来处理和解析数据类
Db/engineListener 处理远程数据
Db/manager 本地数据库的存储
Util 静态变量公共类
View 封装原生的视图组件
Assets 处理非原生的webview代码。
Res/Layout xml页面布局文件
Res/anim 组间动画文件
Res/ drawable-hdpi 存放程序所需要的图片文件
Res/ drawable-ldpi 图片样式的xml文件
Res/ values 存放程序所需的属性值
AndroidManifest.xml 整个android程序的总xml,用于注册acitivity
Libs 依赖库,类似java工程中的第三方jar 包
android-support-v4.jar android原生组件类
core.jar 公共使用jar
nineoldandroids-2.4.0.jar 主界面侧滑框jar
nucleus-android 远程数据交互依赖工程

中间服务器端开发

移动云服务器端工程的代码结构如下:

使用文档图片

对于后端服务器,作为二次开发人员,只需要重点关注smart-cellet工程中所有的业务代码。核心代码结构在环境安装中已经着重介绍过,如下只对具体运作过程进行详细阐述:

a、SmartCellet.java:工程核心类,配置HTTP协议,加载所有的监听器等,所有的业务监听接口开发完毕后,必须加入到该类。
LoginListener login = new LoginListener(this);
login.setHttpClient(this.httpClient);
dispatcher.addListener(Action.LOGIN, login);
b、ActionListener:监听器的顶层接口。主要作用为用户界面根据自身需求监听指定的数据事件。其中AbstractListener是实现该接口的抽象类,该类也是我们所有业务类监听模型的超类,所有业务操作必须实现该类。我们以获取待办故障工单列表为例来详细说明。
确定客户端请求指向产品的完整的URL:
HostConfig config = new ServiceDeskHostConfig();
HostConfigContext context = new HostConfigContext(config);
StringBuilder url = new StringBuilder(context.getAPIHost()).append("/").append(API.LOGIN);
接受参数:
JSONObject json;
String username = null;
String password = null;
try {
  json = new JSONObject(action.getParamAsString("data"));
  System.out.println("登录参数:" + json);
  username = json.getString("username");
  password = json.getString("password");
} catch (JSONException e1) {
  e1.printStackTrace();
}
创建请求:
Request request = this.getHttpClient().newRequest(url.toString());
request.method(HttpMethod.GET);
填写数据内容:
DeferredContentProvider dcp = new DeferredContentProvider();
RequestContentCapsule capsule = new RequestContentCapsule();
capsule.append("username", username);
capsule.append("password", password);
dcp.offer(capsule.toBuffer());
dcp.close();
request.content(dcp);
发送请求:
ContentResponse response = request.send();
获取远程接口返回的数据并进行封装:
JSONObject jo = null;
   switch (response.getStatus()) {
   case HttpStatus.OK_200:
   byte[] bytes = response.getContent();
   if (null != bytes) {
      String content = new String(bytes, Charset.forName("UTF-8"));
      try {
        jo = new JSONObject(content);
        if ("success".equals(jo.getString("status"))) {
           jo.put("status", 300);
           JSONObject j = jo.getJSONObject("userInfo");
           j.put("userID", 9980000000000000l);
          }
          params.addProperty(new StringProperty("username", username));
          params.addProperty(new ObjectProperty("data", jo));
          this.response(Action.LOGIN, params);
         } catch (JSONException e) {
            e.printStackTrace();
         }
         } else {
            this.reportHTTPError(username, Action.LOGIN);
         }
        break;
        default:
            Logger.w(LoginListener.class, "返回响应码:" + response.getStatus());
            jo = new JSONObject();
            try {
                jo.put("status", 900);
            } catch (JSONException e) {
                e.printStackTrace();
            }
            params.addProperty(new ObjectProperty("data", jo));
            this.response(Action.LOGIN, params);
            break;
        }
    }
                    

产品端开发

服务器接口端代码结构如下图所示:

使用文档图片

由于我们采用服务器端的产品版本是3.7,所以我们需要通过svn,下载相应的版本进行接口设计,接口代码统一放于mobile包下,在原有的工程下编辑移动端所需json的接口类,并将json通过print传于移动客户端。

测试与交付

测试

模拟器测试

(IPhone)

在Xcode左上角的导航中,选中工程以及需要进行测试的SDK 和终端设备类型、测试版本,这里以测试iPhone ,iOS7.1版本为例。

使用文档图片

点击“RUN”或者执行command+R快捷键,即可以启动apple 提供的模拟器进行测试。如图展示了客户端在iOS7.1的模拟器中的菜单与界面。

使用文档图片
(Android)

Android模拟器能够模拟除了接听和拨打电话外的所有移动设备上的典型功能和行为。Android模拟器提供了大量的导航和控制键,你可以通过鼠标或键盘点击这些按键来为你的应用程序产生事件。同时它还有一个屏幕用于显示Android自带应用程序和你自己的应用程序。Android模拟器具有很强大的调试能力,但效率没真机测试快,通常依赖于电脑硬件。

第一步,点击菜单栏红框部分,出现模拟器列表窗口,你可根据需求选择相应的android版本。

使用文档图片

第二步,选择后点击红框内的start,开启模拟器进行模拟测试。

使用文档图片

开启模拟器后,右键点击FVMSD0.2出现如下图所示的列表框,按图点击红框部分,将工程软件发布下载到了模拟器中。

使用文档图片

进行上一步后,在模拟器中经过闪图后,出现FVMSD的登录界面,如此可进行登录操作后,对程序进行测试了。

使用文档图片

真机测试

(IPhone)

真机测试相对比较麻烦,需要涉及到apple 的开发者帐号、Mac OS 证书与环境、真机测试设备、Xcode工具,只有这四者配置齐全,才能将App 发布到真机进行测试。

  • 开发者证书(分为开发和发布两种,类型为iOS Development, iOS Distribution),这个是最基础的,不论是真机调试,还是上传到App Store都是需要的,是一个基证书,用来证明自己开发者身份的;
  • App ID,这是每一个应用的独立标识,在设置项中可以配置该应用的权限,比如是否用到了Game Center,以及更常见的push服务,如果选中了push服务,那么就可以创建生成下面第3条所提到的推送证书,所以,在所有和推送相关的配置中,首先要做的就是先开通支持推送服务的App ID;
  • 推送证书(分为开发和发布两种,类型分别为APNS Development ios,APNS Distribution ios),该证书在App ID配置中创建生成,和开发者证书一样,安装到开发电脑上;
  • Provisioning Profiles。这个东西是很有苹果特色的一个东西,我一般称之为PP文件,该文件将App ID、开发者证书,硬件Device绑定到一起,在开发者中心配置好后可以添加到Xcode上,也可以直接在Xcode上连接开发者中心生成,真机调试时需要在PP文件中添加真机的UDID。

平常我们的制作流程一般都是按以上序列进行,先利用开发者帐号登陆开发者中心,创建开发者证书,App ID,在App ID中开通推送服务,在开通推送服务的选项下面创建推送证书(服务器端的推送证书见下文),之后在PP文件中绑定所有的证书id,添加调试真机等。具体操作流程如下:

• 制作开发者证书

首先登陆到开发者中心,找到证书配置的版块,点击https://developer.apple.com/account/ios/certificate/certificateList.action 进入,点进证书,会显示如下界面,点击右上角的加号:

使用文档图片

会出现以下界面,该操作重复两次,分别创建开发测试证书和发布证书,开发测试证书用于真机调试,发布证书用于提交到App Store,我们以开发测试证书为例,选择第一个红框中的内容():

使用文档图片
注意:
  • 由于本机已经创建好证书,所以会以灰色显示
  • 开发阶段只需要创建测试证书,只有到产品发布到App Store 中才需要创建发布证书。

然后下一步,会提示创建CSR文件,也就是证书签名请求文件,会有很详细的操作说明。

使用文档图片
使用文档图片

之后将该CSR文件保存到一处;之后在开发者中心将该CSR文件提交;提交上去后就会生成一个cer证书。如图所示,有效期为一年,如图所示:

使用文档图片

• 创建App ID

App ID是识别不同应用程序的唯一编码。如果你的程序要连接Apple Push Notification服务(一种push通知),需要用到App ID。如果应用程序之间要共享钥匙串数据,也会用到App ID。总之,App ID在iOS设备上大量被使用。在这里App ID的最大用处是制作真机调试用的Provision Profile(它需要提供一个App ID)。

一个App ID有两部分构成:一个10位字符的Bundle Seed ID前缀,这个Bundle Seed ID由Apple分配,全球唯一,保证不会重复;一个Bundle Identifier后缀,这个Bundle Identifier由Team管理员指派,Apple建议用反域名规则命名这个Bundle Identifier。例如: 8E549T7128.com.apple.AddressBook.

以管理员登录Provision Portal,点击“App ID”页面中的“New App ID”按钮。 App ID Name:给这个App ID一个名字。如果存在多个App ID,每个App ID需要一个易于识别的名称。

使用文档图片

• 添加真机设备

添加真机测试设备,这里需要优先找到设备的UDID,所谓设备ID(device ID又称UDID)是Apple 设备上的40位16进制码,每台Apple设备的device ID都是唯一的,Apple以此来识别不同的iOS设备。

我们通过在Provision Portal中录入设备的device ID,可以允许开发者在指定真实设备上进行调试。在Provision Portal中最多允许输入100个device ID。

因此,录入device ID是后续制作Provision Profile的必需步骤(而Provision Profile又是真机调试的必需步骤)。 有两种方式可以获取device ID的方式:

a、把Apple 设备(iPhone,iPad)连接电脑,打开Xcode的Orgnizer:
使用文档图片
b、把Apple 设备(iPhone,iPod)连接电脑,打开iTunes:
使用文档图片

登录Provision Portal,点击Devices页面中的“+”按钮,输入:

  • Name:设备名称,输入一个描述该设备的名字。

  • UDID:即device ID。

点击提交即可,如图所示:

使用文档图片

• 制作PP证书

登录Provision Portal,在“Provisioning->Development”,点击“+”按钮,选择“iOS App Development”,如图所示:

使用文档图片

选择App ID:

使用文档图片

选择证书:

使用文档图片

选择设备:

使用文档图片

输入Profile Name,可随意;选择完成后,点击“Generate”,即可生成PP文件。

使用文档图片

注意: 只有对个人开发者和公司开发者证书需要选择测试设备,企业开发者帐号没有此环节。

• 证书安装

所有Team成员都可以下载Development Provision Profile。但只有Profile中记录了设备ID的设备以及iOS开发者证书所指定的开发者能够使用这个Profile。 在Portal的“Provisioning Profiles-->Development”,选中自己创建的Profiles 记录,点击某展开的“download”按钮。

使用文档图片

下载profile后,将下载到的文件拖拽到桌面Dock面板的Xcode图标上(或者直接拖到Xcode的Orgnizer中)。这会将profile文件拷贝到~/Library/MobileDevice/Provisioning Profiles目录。添加到Xcode 的效果如下:

使用文档图片

• 签名并调试

在Xcode中打开工程,选中 Target,打开Build Settings窗口,在Build面板中找到“Code Signing Identify”,打开并点击下面的“Any iOS Device” 在弹出菜单菜单中选择你的签名,该签名应当和一个灰色的Profile对应。这个Profile就是我们前面安装的Development Provision Profile。

使用文档图片

配置好以上信息后,就可以选择真机设备,并进行调试。

(Android)

真机测试,顾名思义为在有android系统手机上进行的测试,比起ios上的真机测试,android测试相对于简单许多,需要涉及到android系统手机、相对应的数据线。下面进行详细操作流程介绍。

第一步,将android手机设置为调试模式。方法为:设置—应用程序—开发—USB调试,打上√即可。

第二步,将数据线连接至电脑,在电脑上安装豌豆荚或360等手机卫士,此时手机卫士会帮你安装驱动,安装好驱动后就可以连接上手机了。

第三步,打开devices视图,看到下图的手机设备信息后,说明准备已经就绪,可以开始对android手机进行测试了。

使用文档图片

第四步,测试方式跟模拟器测试相同,右键点击—Run As—Android Application。

使用文档图片

交付

交付方式

开发测试完毕,就进入移动应用的交付阶段。

不同于一般的消费者应用通过App Store 下载到达客户终端,Iphone客户端不同于传统通过App Store下载的方式,我们的App通过apple 的企业开发者帐号构建企业内部的的App Store,无须经过苹果漫长的审核周期,开发出来的App 直接交付给用户。

交付条件

a、项目实施企业应当拥有企业开发者帐号,其中会涉及到DUNS码的申请,会产生额外的费用。(必须)

b、支持能够外部访问的网络环境。

c、满足相应的硬件系统条件。

附件

用户操作手册主要介绍ITSMOB的各大模块功能,方便用户操作。

文档说明

本文档根据需求规格说明书中描述的数据需求和功能需求,设计满足需求的软件人机界面及功能实现的操作流程,为用户提供一个良好的使用环境。

本文档描述范围在于:

  • 说明界面布局;
  • 阐述具体功能的操作流程。

系统功能介绍

个人信息管理模块

个人信息管理模块功能包括:

  • 用户登录及退出。
  • 服务器信息配置。
  • 系统设置及账号信息修改。

用户登录及退出

用户登录及退出的个具体功能如下:

  • 点击桌面图标进入系统。
  • 输入用户名和密码完成登录。
  • 注销及退出当前账户。
步骤 截图 说明
1 点击移动桌面上的图标,进入ITSMOB系统。
2 进入系统后,即出现如图的蓝色闪图。
3 此图为系统的登录页面,用户可通过输入用户名与密码,登录进入该系统。当系统无法连接到服务器时,会出现图中的提示。
4 该图为ITSMOB的主界面,也是各大部分的入口。用户登录成功后,系统将会跳转到此页面,并提示登录成功。
5 点击主界面的头部右上角的图标,出现侧滑窗口。该窗口上呈现出系统消息的入口和知识库模块的订阅和收藏信息入口以及账号设置的入口。

网关配置

网关配置具体功能如下:

  • 服务器信息未配置提示。
  • 测试连接。
  • 确认连接。
步骤 截图 说明
1 当用户没有配置连接服务器的IP和端口信息时,将会出现如图所示的提示框。选择“现在设置”系统将会跳转到网络配置页面。
2 该图为网络配置页面。用户输入服务器的IP和端口号之后,点击测试按钮,即可测试连接;点击确认按钮后,若连接成功系统将跳转到登录页面,否则提示连接失败。
3 该图为系统连接服务器的进度提示框。
4 此图为测试连接成功后的系统提示测试连接成功。

系统设置及账号信息修改

系统设置及账号信息修改的具体功能如下:

  • 修改账号信息。
  • 系统声音设置。
  • 查看关于系统的介绍。
  • 切换账号。
步骤 截图 说明
1 该图红色框部分为账号设置入口,点击此处可进入账号设置页面。
2 该图为系统设置页面,该页面为用户提供修改账号信息入口、查看关于itsmob系统介绍入口和系统声音设置功能以及切换账号功能。
3 此图为用户账号信息修改界面,用户点击“账号管理”,将会进入此页面。用户选择要修改的信息项,则可进入编辑窗口进行修改。
4 用户通过控制声音提示开关来设置系统声音。当系统声音打开或关闭时,系统将会进行提示。
5 此图为关于ITSMOB系统介绍页面。
6 用户点击“切换账号”后,系统将弹出确认窗口,提示用户是否好切换账号。若用户选择确定,系统将会跳转至登录页面。

消息模块

消息模块的具体功能有:

  • 收件箱、发件箱、草稿箱信息列表显示。
  • 查看消息详情。
  • 新建草稿。
  • 发送消息。
步骤 截图 说明
1 该图红色框部分为消息入口,点击此处可进入消息中心页面。
2 该图为消息中心页面。点击页面切换按钮,可进行页面切换。页面头部标题栏右边的操作按钮从左往右依次为同步消息、新建消息。图中的蓝色小点表示该条消息未读。
3 将消息往左滑,则会出现删除按钮,点击删除按钮即可删除对应的消息。
4 点击一条消息,即可查看该条消息的详细内容。页面头部标题栏右边的操作图标为新建消息。
5 点击新建消息操作按钮,即可进入新建消息页面。用户输入相应的信息内容后,点击页面右上角的第一个操作按钮即可将消息保存为草稿;点击第二个操作按钮即可发送消息。

任务待办模块

代办包括故障和问题,具体功能有:

  • 待办工单的展示和查询。
  • 查看具体详细信息。
  • 对工单进行处理。
步骤 截图 说明
1 该图红色框部分为消息入口,点击此处可进入消息中心页面。
2 点击流程待办出现故障列表。
3 故障列表平移侧滑,出现问题列表。
4 图为故障列表,点击故障下拉图标,出现过滤和排序的辅助功能。问题列表同图。
5 图为流程故障详细信息。具有快速定位功能。问题详情页面同图。
6 点击详单页面的操作按钮,将会出现相应的操作列表。
7 点击上图操作列表中的项,出现相应操作页面,点击页面右上角的操作图标进行受理。问题流程页面同图。
8 此图为故障详情关联工单列表页面。
9 图为故障详情未下载附件页面。左滑将会出现下载和删除按钮,点击即可进行相应操作。下载成功的附件将会在已下载列表显示。
10 图为故障详情已下载附件页面。左滑将会出现查看和删除按钮,点击即可进行相应操作。点击查看后系统将调用第三方软件打开附件。
11 此图为流程的处理日志页面。问题流程日志也如图所示。

该文档包括各大模块所需的数据结构约束,便于开发人员使用。

前言

接口规范需注意以下几点:

  • 某些页面的具体内容属性,请在相对应接口的参数和返回结果中去寻;
  • 每个页面模块显示的数据必须与接口一致;
  • 大部分数据都需运用SQLite做数据缓存,需分页列表均通过本地数据库,不传入系统服务器;
  • 当token失效时,返回unauthorized,故接收值时,均先判断此值;
  • 所有空值移动端显示可用“暂无”,传入服务器时,请将“暂无”替换为空值;

公共部分

特定人员信息

编号 IB-01
名称 获取转派(一线、二线)、分派人员等列表信息。
URL common/listNextTaskActors.html
参数名 描述
token 用户令牌
bpiId 工单id
leavingTransitonName 获取列表的名字 其值如:转派一线
返回格式 JSON(Array)
返回结果 {success:成功或失败,total:总共人数,root:[{ id:人员ID,xingMing:人员名称,department:部门]}

关闭代码

编号 IB-02
名称 获取关闭代码列表。
URL common/listCloseCodes.html
参数名 描述
token 用户令牌
bpiId 工单id
返回格式 JSON(Array)
返回结果 {success:成功或失败, root:[{id:关闭代码ID, name:关闭名称]}

影响程度

编号 IB-03
名称 获取影响程度信息。
URL common/listImpacts.html
参数名 描述
token 用户令牌
bpiId 工单id
返回格式 JSON(Array)
返回结果 {success:成功或失败,root:[{id: Id,name:名称}]}

紧急程度

编号 IB-04
名称 获取紧急程度信息。
URL common/listUrgents.html
参数名 描述
token 用户令牌
bpiId 工单id
返回格式 JSON(Array)
返回结果 {success:成功或失败,root:[{id: Id,name:名称}]}

优先级

编号 IB-05
名称 获取优先级信息。
URL common/listServerLevels.html
参数名 描述
token 用户令牌
bpiId 工单id
返回格式 JSON(Array)
返回结果 {success:成功或失败,root:[{id: Id,name:名称}]}

类别

编号 IB-06
名称 获取类别信息。
URL common/listCategorys.html
参数名 描述
token 用户令牌
bpiId 工单id
返回格式 JSON(Array)
返回结果 {success:成功或失败,root:[{id: Id,name:名称}]}

职位

编号 IB-07
名称 获取职位信息。
URL common/listJobTitles.html
参数名 描述
token 用户令牌
返回格式 JSON(Array)
返回结果 {success:成功或失败,root:[{id: Id,name:名称}]}

附件上传

编号 IB-08
名称 附件上传。
URL common/saveAttachment.html
参数名 描述
token 用户令牌
bpiId 工单id
url 上传的地址
alias 名称
name 文件名
comment 描述
返回格式 JSON
返回结果 {success:成功或失败}

附件下载

编号 IB-09
名称 下载附件(先虚设,后因具体下载方法而定)。
URL common/downAttachment.html
参数名 描述
token 用户令牌
url 附件地址
返回格式 JSON
返回结果 {success:成功或失败}

附件删除

编号 IB-10
名称 删除附件信息。
URL common/deleteAttachment.html
参数名 描述
token 用户令牌
attachmentsIds 附件id
返回格式 JSON
返回结果 {success:成功或失败}

账户管理

用户登录及验证

编号 IB-11
名称 用户登陆及验证。
URL userm/login.html
参数名 描述
username 用户名
password 密码
返回格式 JSON
返回结果 { success:成功或失败, root:[{id:用户id, xingMing:用户名,jobTitles:[{id:职位Id, name:职位名称}],phone:电话,mobile:手机,email:邮箱,token:用户令牌}]}

人员列表

编号 IB-12
名称 获取全部的人员列表信息。
URL userm/loadAllUser.html
参数名 描述
token 用户令牌
leavingTransitonName 获取列表的名字 其值如:转派一线
返回格式 JSON
返回结果 {success:成功或失败,total:总共人数,root:[{id:人员ID,xingMing:人员名称}]}

账户信息修改

编号 IB-13
名称 修改账户信息(照片暂不管,提交后的数据需保存在本地数据库)
URL userm/updateUserInfo.html
参数名 描述
userId 用户id
username 用户名
jobTitleId(多选) 职位
phone 电话
mobile 手机
email 邮箱
返回格式 JSON
返回结果 {success:成功或失败}

消息中心

消息列表

编号 IB-14
名称 获取消息列表(收件箱、发件箱通过本地缓存的接收人和发送人获取,草稿箱在本地保存未提交服务器的数据,可多存isSubmitted进行识别)。
URL noticem/listNotices.html
参数名 描述
token 用户令牌
返回格式 JSON(Array:条数较多,暂且返回最近200条)
返回结果 {success:成功或失败,total:工单数目,root:[{id:工单Id, sendTime :发送时间,title:消息标题,reciever:{id:接收人id,name:接收人名称},sender:{id:接收人id,name:接收人名称},readed:已读未读}]}

单条消息推送

编号 IB-14
名称 单条消息推送。
URL SendMsg()
参数名 描述
token 用户令牌
返回格式 JSON
返回结果 {success:成功或失败, root:[{id:工单Id, sendTime :发送时间,title:消息标题,reciever:{id:接收人id,name:接收人名称},sender:{id:接收人id,name:接收人名称},readed:已读未读}]}

消息详单

编号 IB-15
名称 获取详单信息。
URL noticem/getNoticeInfo.html(只传内容,其余信息将从列表缓存中获取,记得将readed属性改为1)
参数名 描述
token 用户令牌
noticeId 消息Id
返回格式 JSON
返回结果 {success:成功或失败, root:[{content:消息内容}]}

消息发送

编号 IB-16
名称 支持点对点和批量发送(新编辑数据返回结果应存入本地数据库中)。
URL noticem/sendNotice.html
参数名 描述
token 用户令牌
recieverIds 接收人Id
title 标题
content 内容
返回格式 JSON(Array:因为接收人可为多个,每个接收人对应一条消息)
返回结果 {success:成功或失败, root:[{id:工单Id, sendTime :发送时间,title:消息标题,reciever:{id:接收人id,name:接收人名称},sender:{id:接收人id,name:接收人名称},readed:已读未读}]}

消息删除

编号 IB-14
名称 删除消息列表(收件箱、发件箱通过本地缓存的接收人和发送人获取,草稿箱在本地保存未提交服务器的数据,可多存isSubmitted进行识别)。
URL noticem/deleteNotices.html
参数名 描述
token 用户令牌
noticeIds 信息id集合(Id1,id2)
返回格式 JSON
返回结果 {success:成功或失败}

故障管理

故障列表

编号 IB-17
名称 故障列表展示。
URL incidentm/listIncidents.html
参数名 描述
token 用户令牌
filterId 过滤传参 待受理 ff80818128f78aab0128f81931c5007b
待处理 ff80818128f78aab0128f8197f45007c
待回访 ff80818128f78aab0128f819ff08007d
待关闭 ff80818128f78aab0128f81aa010007e
本地参数名 描述
sequence 排序传参(在本地缓存中查询,不传入服务器) 时间 updatedOn
优先级 servicelevelSymbol
返回格式 JSON(Array)
返回结果 {success:成功或失败, root:[{id:关闭代码ID, name:关闭名称]}

故障详单

编号 IB-18
名称 故障详单展示。
URL incidentm/getIncidentInfo.html
内容描述(解决与关闭信息需进行状态判定才可显示,定选的具体选项参照4.3) 工单信息 id: 工单 ID, code :工单号,state :工单的状态, creator :创建者,createdOn :创建时间
基本信息 summary :摘要,description :内容, category :类别(单选), occurTime:发生时间(日期)
报告源 reportWays:报告方式(定选), source:报告源(定选), applicantName: 申报人(单选), applicantPhone申报电话, influencer: 影响人(单选)
优先级信息 urgent :紧急程度(单选), impact:影响程度(单选), serviceLevel :优先级(单选), isMajor:是否重大(开关)
联系人信息 contactName :联系人(单选), phone:电话, mobile :手机,email :邮箱
(已解决)解决信息 investDiagn :调查诊断, reason:产生原因、 resolution :解决方案,solver:解决人, solvedTime :解决时间
(已关闭)关闭信息 closeCodeName:关闭代码, closeTime:关闭时间
参数名 描述
token 用户令牌
bpiId 工单id
返回格式 JSON
返回结果 {success:成功或失败,root:[{id:工单ID,code:工单号,createdOn:创建时间,stateName:工单的状态,creatorName:创建者,summary:摘要,description:内容,category:{id:类别id,name:类别名},occurTime:发生时间,reportWays:报告方式,source:报告源,applicant:{id:申报人id,name:姓名,phone:电话},influencer:{id:影响人id,name:影响人姓名}, impact:{id:影响id,name:影响名},urgent:{id:紧急id,name:紧急名},serviceLevel:{id:优先级id,name:优先级名},isMajor:是否重大(开关),contact:{id:联系人id,name:联系人名,phone:电话,mobile:手机,email:邮箱},investDiagn:调查诊断,reason:产生原因,resolution:解决方案,solverName:解决人,solvedTime:解决时间,closeCodeName:关闭代码,closeTime:关闭时间, associatedWorkOrders:[{id:关联工单Id,code:工单号,associateType:关联类型,summary:摘要}],processlogs:[{name:操作人,comment:备注,time:时间,operateName:操作名称}],transitions:[{operationName:操作方式1},{operationName:操作方式2}],attachments:[{id:附件Id,alias:名称,measurements:文件大小(需转成kb),address:地址,name:文件名}]}]}

故障操作

编号 IB-19
名称 故障操作。
URL incidentm/saveAndSubmit.html
参数名 描述
页面描述(根据操作类型,给页面放上特定表单项,如有缺少,欢迎联系补充;上传数据时,必须传递所有参数,根据操作名传递相应值,其余为空值(null)传递) 受理 报告源 报告方式 reportWays、报告源reportSource、申报人 applicantId 、影响人influencerId
基本信息 摘要summary 、描述 description、类别 categoryId
优先级 紧急度 urgencyId 、影响程impactId 、优级 serviceLevelId 、重大故障isMajor
备注 备注comment
退回 优先级 紧急程度 urgencyId 、影响程度impactId
基本信息 描述description
退回原因 退回原因comment
解决 解决信息 调查诊断 investDiagn 、产生原因reason 、解决方案 resolution
转派(一线) 报告源 报告方式 reportWays、报告源reportSource 、申报人 applicantId 、影响人influencerId
优先级 人员紧急程度 urgencyId 、影响程度impactId 、优先级 serviceLevelId、重大故障isMajor
转派(一线) 转派(一线)( actors )、备注comment
转派(二线) 基本信息 描述 description
转派(二线) 转派(二线)(人员actors)、备注comment
回访 回访信息 是否解决(开关 isSolved[0,1] )、备注comment
关闭 关闭信息 关闭代码(单 closeCodeId )、备注comment
评价 评价信息 满意度(星级 1,2,3,4,5 )satisfaction 、备注 comment
分派 分派信息 分派(人员 actors )、备注comment
token 用户令牌
bpiId 工单id
jbpmTransition 操作名(如受理)
reportWay 报告方式(电话1、短信2、邮件3、自服务台4、其他5、监控工具6)
reportSource 报告源(个人1、部门2、单位地点3)
applicantId 申报人
influencerId 影响人
summary 摘要
description 描述
categoryId 类别
urgencyId 紧急程度
impactId 影响程度
serviceLevelId 优先级
isMajor 重大故障(否0、是1)
comment 备注
investDiagn 调查诊断
reason 产生原因
resolution 解决方案
actors 人员
satisfaction 满意度(1、2、3、4、5)
isSolved 是否解决(否0、是1)
closeCodeId 关闭代码
返回格式 JSON(Array)
返回结果 {success:成功或失败, root:[{id:关闭代码ID, name:关闭名称]}

问题管理

问题列表

编号 IB-20
名称 问题列表展示。
URL problemm/listProblems.html
参数名 描述
token 用户令牌
filterId 过滤传参 待受理 ff8081812ad0f8c1012ad617a212009f
待处理 ff8081812ad0f8c1012ad61839ab00a0
待评审 ff8081812ad0f8c1012ad619d56f00a3
待归档 ff8081812ad0f8c1012ad618b42400a1
待关闭 ff8081812ad0f8c1012ad619633400a2
本地参数名 描述
sequence 排序传参(在本地缓存中查询,不传入服务器) 时间 updatedOn
优先级 servicelevelSymbol
返回格式 JSON(Array)
返回结果 {success:成功或失败,total:工单数目,root:[{id:工单Id, code:工单号,summary:工单概要,stateName:工单状态,updatedOn更新时间,servicelevelSymbol:优先级}]}

问题详单

编号 IB-21
名称 问题列表展示。
URL problemm/getProblemInfo.html
参数名 描述
内容描述(处理和关闭的显示根据状态而定) 工单信息 id:工单ID,code:工单号,stateName工单状态,creatorName:创建者,createdOn:创建时间
基本信息 summary:摘要,description:症状及描述,category:问题类别(单)
优先级信息 urgency:紧急程度(单),impact:影响程度(单),serviceLevel:优先级(单)
用户信息 applicant:申报人(单),phone:电话,mobile:手机,email:邮箱,influencer:影响人(单)
(已解决)处理信息 reason:根本原因、workarround:临时解决方案、emergencySolution:应急解决方案、resolution:解决方案,solver:解决人,solverMobile:解决人手机,solverPhone:解决人电话、solvedTime:解决时间
(已关闭)关闭信息 closeCodeName:关闭代码、closeTime:关闭时间, reviewType:是否有效
token 用户令牌
bpiId 工单id
返回格式 JSON
返回结果 {success: 成功或失败,root:[{id:工单ID,code:工单号,stateName:工单状态,creatorName:创建者,createdOn:创建时间,summary:摘要,description:症状及描述,category : {id:类别 id ,name :类别名 },impact :{id: 影响 id, name :影响名} , urgent: {id: 紧急id , name:紧急名 } ,serviceLevel : {id:优先级 id ,name :优先级名 }, applicant :{ name :姓名, phone :电话,mobile :手机,email :邮箱} , influencer: {id: 影响人id , name:影响人姓名 } ,reason:根本原因、workarround:临时解决方案、emergencySolution:应急解决方案、resolution:解决方案,solver:{name:解决人,mobile:解决人手机,phone:解决人电话},solvedTime:解决时间,closeCodeName:关闭代码,closeTime:关闭时间,reviewType :是否有效,associatedWorkOrders :[{id: 关联工单Id , code:工单号, associateType: 关联类型,summary: 摘要 }], processlogs :[{name:操作人, comment :备注,time: 时间, operateName:操作名称 }] ,transitions :[{operationName: 操作方式1} , {operationName:操作方式 2}] ,attachments :[{id: 附件Id , alias:名称, measurements :文件大小(需转成 kb), address :地址,name: 文件名 }]}]}

问题操作

编号 IB-22
名称 问题操作。
URL problemm/getProblemInfo.html
页面描述(根据操作类型,给页面放上特定表单项,如有缺少,欢迎联系补充; 上传数据时,必须传递所有参数,根据操作名传递相应值,其余为空值(null)传递) 拒绝 基本信息 症状及描述description、问题类别categoryId、紧急程度urgentId、影响程度impactId
拒绝信息 拒绝理由comment、关闭代码closeCodeId(单)
分派 基本信息 症状及描述description、问题类别categoryId、紧急程度urgentId、影响程度impactId
分派信息 负责人actors(单)、小组成员(单)xingMing、工作日志comment
退回 基本信息 症状及描述description、问题类别categoryId、紧急程度urgentId、影响程度impactId
退回信息 退回理由comment;
受理 基本信息 症状及描述description、问题类别categoryId、紧急程度urgentId、影响程度impactId
受理信息 工作日志comment
处理 问题处理方案信息 调查诊断活动comment、根本原因reason、原因分类(单)reasonCategoryId、解决方案resolution、临时解决方案workarround、应急解决方案emergencySolution
解决 基本信息 症状及描述description、问题类别category、紧急程度urgentId、影响程度impactId
问题解决过程 工作日志comment
关闭 关闭信息 closeCodeId:关闭代码(单)、isMajor:重大问题(开关)、解决方案是否有效(开关)reviewType、备注comment
协助 协助信息 备注 comment
评审 评审信息 备注 comment
参数名 描述
token 用户令牌
bpiId 工单id
jbpmTransition 操作名(如受理)
description 症状及描述
categoryId 问题类别
urgentId 紧急程度
impactId 影响程度
comment 拒绝理由/工作日志/退回理由/调查诊断活动/备注
closeCodeId 关闭代码
actors 负责人
xingMing 小组成员
reason 根本原因
reasonCategoryId 原因分类
resolution 解决方案
workarround 临时解决方案
emergencySolution 应急解决方案
isMajor 重大问题(否0、是1)
reviewType 解决方案是否有效(否0、是1)
返回格式 JSON
返回结果 {success:成功或失败}