软件技术规范文档格式.docx
《软件技术规范文档格式.docx》由会员分享，可在线阅读，更多相关《软件技术规范文档格式.docx（35页珍藏版）》请在冰豆网上搜索。
TaskGuid采用标准的GUID格式，TaskGuid的值由系统建设主管单位统一定义，在数据规范文档中描述，一项应用只能定义一个应用标识。
数据标识用DataGuid表示。
每个唯一的数据必须具备一个唯一的标识，使用该标识区分不同的数据。
由于数据的增加、删除和修改操作都是以DataGuid作为关键字的，不同的系统都要按照GUID标准统一生成DataGuid，以保证数据在不同的系统和平台中不被其他数据覆盖。
数据类型用DataType表示。
每一项数据规范都要定义一个唯一的数据类型，应用软件是按照DataType对应的数据规范解析写入的数据，不同应用的数据类型可以重复。
符合数据规范格式的XML数据用XmlData表示。
表示写入的具体数据，如果与数据类型对应的数据标识的元数据不存在，就执行数据增加操作；
如果与数据类型对应的数据标识的元数据已存在，就执行数据更新操作；
如果XmlData是空值或是没有子节点的XML数据，就将数据标识对应的元数据删除；
写入操作的返回结果表示数据在软件中的写入情况。
返回0表示数据写入操作成功，返回-1表示数据格式不符合要求，返回-2表示写入数据的逻辑不对，表示返回-3表示没有数据写入权限，返回其它值可以查询“数据写入操作错误信息”来获取具体含义，查询时使用读取操作，其中TaskGuid参数为应用标识，DataGuid参数固定为"
c61ed474-e8b1-4fb4-8975-74b356caa22b"
，DataType参数为“ErrorList"
。
返回数据格式统一为：
<
DocumentTaskGuid="
应用标识"
DataGuid="
DataType="
ErrorList"
>
ErrorInfoCode="
错误代码"
错误信息描述<
/ErrorInfo>
……
/Document>
错误代码要求大于100或小于负100，正负100之间的错误码作为保留值不能使用。
读取操作主要参数有：
用户标识、应用标识、数据标识和数据类型。
用户标识用UserID表示，具体含义与写入操作参数相同。
应用标识用TaskGuid表示，具体含义与写入操作参数相同。
数据标识用DataGuid表示，每个唯一的数据必须具备一个唯一的标识，使用该标识区分不同的数据。
读取操作中数据标识表示需要读取的唯一数据。
每一项数据规范都要定义一个唯一的数据类型，应用软件是按照DataType对应的数据规范生成读取的数据，不同应用的数据类型可以重复。
读取操作的返回结果是符合数据规范格式的XML数据。
如果对应的数据不存在也必须返回符合数据规范格式并包含所有节点的空数据。
返回空值表示无对应数据的读取权限或者是应用软件不支持该类型的数据。
查询操作主要参数有：
用户标识、应用标识、符合数据规范格式的XML查询命令。
符合数据规范格式的XML查询命令用XmlTransform表示。
在查询操作中包含需要查询的条件。
查询操作的返回结果是符合查询条件的具体数据。
大批量数据的返回要实现数据分页的查询操作。
即使查询结果没有符合条件的数据也必须返回符合格式的数据，返回空值表示无对应数据的查询权限或者是应用软件不支持对应的查询操作。
1.接口的实现方式
考虑到不同层面的对接要求系统接口的实现定义了网页、Web服务和Socket三种方式，应用软件至少需要实现其中一种接口方式，具体实现哪几种接口方式，将由建设单位明确。
网页方式。
该方式是专供JaveScript调用的一种方式，使用浏览器的XMLHttpRequest对象向对应的网页发出请求或发送数据可以调用应用软件的写入、读取和查询操作。
写入操作使用“POST”方式将符合数据规范格式的XML字符串发送到提供写入操作的网页上。
用户标识、应用标识、数据标识、数据类型等参数通过在网页后面跟上字符串：
UserID=…&
TaskGuid=…&
DataGuid=…&
DataType=…的方式传递，返回值为数值型的字符串。
读取操作使用“GET”方法调用提供读取操作的网页。
用户标识、应用标识、数据标识和数据类型，等参数通过在网页后面跟上字符串：
UserID=…&
DataType=…的方式传递，返回值为符合数据规范格式的XML字符串。
查询操作使用“POST”方式将符合数据规范格式的XML查询命令发送到提供查询操作的网页上。
用户标识、应用标识等参数通过在网页后面跟上字符串：
TaskGuid=…的方式传递，返回值为符合数据规范格式的查询结果字符串。
提供写入、读取和查询操作的网页可以通过一个网页文件来完成对应的功能。
Web服务方式。
该方式是提供给函数方式调用的一种接口，凡是能够支持Web服务调用的软件都可以使用这种接口调用应用软件的写入、读取和查询操作。
Web服务必须遵循附件一的WSDL定义，实现下面三个函数：
写入操作调用Web服务的SetData函数，参数按照函数的方式传递，返回值为数值型。
函数原型如下：
SetData（UserIDAsstring,
TaskGuidAsstring,
DataGuidAsstring,
DataTypeAsstring,
XmlDataAsstring）Asint
读取操作调用Web服务的GetData函数，参数按照函数的方式传递，返回值为符合数据规范格式的XML字符串。
GetData（UserIDAsstring,
DataTypeAsstring）Asstring
查询操作调用Web服务的TransformData函数，参数按照函数的方式传递，返回值为符合数据规范格式的查询结果字符串。
TransformData（UserIDAsstring,
XmlTransformAsstring）Asstring
Socket方式。
该方式是采用通讯端口方式进行操作的接口。
通过向通讯端口发送指定格式的数据实现对应用软件的写入、读取和查询操作。
写入操作发送如下格式的数据到通讯端口：
CommandSystemName="
系统名称"
Type="
SetData"
<
UserID>
用户标识<
/UserID>
TaskGuid>
应用标识<
/TaskGuid>
DataGuid>
数据标识<
/DataGuid>
DataType>
数据类型<
/DataType>
XmlData>
……//符合数据规范格式的XML数据
/XmlData>
/Command>
返回值是数值型的字符串。
读取操作发送如下格式的数据到通讯端口：
GetData"
返回值是符合数据规范格式的字符串。
查询操作发送如下格式的数据到通讯端口：
TransformData"
XmlTransform>
……//符合数据规范格式的XML查询命令
/XmlTransform>
返回值是符合数据规范格式的查询结果字符串。
3.批量数据处理
由于系统接口采用XML作为传输数据的格式，在实际应用中发现传输数据的时间要比处理数据的时间大很多，在大数据交互应用中如果每个写入、读取和查询操作只写入或反馈一个数据将会大大影响系统效率，为此定义了批量数据处理方式来满足大数据量应用的要求。
批量数据以Documents作为根节点，内含一组符合数据规范的Document子节点。
数据格式如下：
<
Documents>
数据标识"
数据类型"
……
/Documents>
写入操作中使用批量数据表示对数据中的每个Document都执行一次独立的写入操作，写入每个Document时使用其包含的应用标识、数据标识和数据类型代替TaskGuid、DataGuid和DataType参数，批量写入操作中提供的这三个参数忽略。
读取和查询操作中使用批量数据可以根据实际逻辑定义批量数据反馈格式。
四、数据格式规范
要想让同一种数据在不同的软件接口中使用，必须让数据遵循共同的描述方式，为了让数据通俗易懂便于计算机处理和人理解特采用XML格式作为所有数据的标准格式，按照特定的XML格式定义的数据描述称做数据规范。
采用数据规范后应用软件的功能实现就具备一定的灵活性
数据规范在应用软件接口中涉及写入和读取操作中的“XML数据”，查询操作中的“XML查询命令”和“XML查询结果”。
大型应用软件的数据规范聘请专业单位进行独立设计，小型应用软件的数据规范由软件开发单位负责设计。
1.数据规范的基本结构
基本的数据规范必须符合下面的基本格式：
[其他属性="
内容"
]>
属性节点Type="
类型"
属性值<
/属性节点>
根节点命名为Document表示这是一个按本文数据规范定义的数据。
应用标识表示数据规范与哪一个应用有关。
在某项应用的数据规范设计中必须首先明确应用标识采用的值。
例如：
"
0690f841-7773-445c-9f48-a7a0427686d5"
就表示是组织结构管理功能的数据。
一个应用软件可以包含多个应用，不同应用具备独立的应用标识，可以独立开发。
数据标识表示数据的唯一值，对于元数据应用软件就是依靠该值执行增加、删除和修改操作。
在数据规范设计中该值不要明确具体的内容，在实际数据生成时必需按照GUID的标准生成具体值，这样可以保证不同的系统生成的数据不会重复。
数据类型表示数据对应哪一个类型，一个应用可以包含多个数据类型，相同类型的数据必须遵守相同的格式。
调用系统接口的软件和系统接口实现的软件都依靠数据类型来确定数据的分析和生成方法。
文档根节点还可以叠加与整个文档有关的其他属性，具体可以根据不同的设计方案扩展。
属性节点表示数据属性，一个数据有多少个属性就列多少个属性节点。
属性节点名称可以重复，名称相同的属性值可以存在次序关系，不同属性名称的节点不存在先后次序关系。
类型表示属性节点的具体类型。
类型及其表示方式将在第2节中详细介绍。
属性值表示属性节点的具体内容。
属性节点还可以叠加与属性相关的其他内容，具体可以根据不同的设计方案扩展。
2.数据类型描述
标准数据类型及其格式。
标准数据类型共定义八种，主要有：
LOGICAL、LONG、DOUBLE、CURRENCY、DATE、BINARY、TEXT、GUID。
它们的含义、取值范围、格式和默认值如下：
LOGICAL逻辑型，值为：
true或false，不能为空且必须为小写，默认值false。
LONG整数型，数据位数在设计时不限长度，不能为空，默认值0。
DOUBLE小数型，数据位数和小数位数在设计时不限长度，不能为空，默认值0.0。
CURRENCY货币型，仅含两位小数的数据，不能为空，默认值0.00。
DATE日期型，格式为“YYYY-MM-DDHH:
MM:
SS”，默认值为空。
BINARY二进制型，二进制数据的BASE64编码，默认值为空。
TEXT文本型，长度不限，默认值为空。
GUID数据标识型，格式“7adab85a-e2cd-4a17-a23b-4044b0d72560”小写格式，每一位必须是’0-9’，’a-f’十六个字符之一，按照标准GUID算法生成的内容。
扩展数据类型及其格式。
扩展数据类型在本文中先定义四种，今后将根据情况进行补充，主要有：
文件数据、附件数据、枚举数据和组织结构数据。
文件数据。
文件数据以二进制的方式读入内存后转换成BASE64的字符串写入文档中。
文件数据包含文件名，扩展名，MIME信息等属性。
数据格式例子：
属性节点FileName="
文件名"
Ext="
扩展名"
MIME="
数据格式描述"
BINARY"
二进制的BASE64编码<
附件数据。
用于描述一组文件数据，由于涉及多个文件数据，附件数据由两级节点组成。
ATTACHMENT"
FileInfoDescript="
附件说明"
文件数据的二进制的BASE64编码<
/FileInfo>
枚举数据。
用于描述一组字符串，实际数据只能是这组字符串数据中的一个。
属性节点Type="
枚举名称"
[枚举值一|枚举值二|枚举值三|……]<
组织单元数据。
用于描述单个组织单元信息。
组织单元数据包括：
标识、名称、类型、所属单位标识等信息。
OUDataInfoGUID="
组织结构标识"
Name="
名称"
OUType="
CompanyGuid="
单位标识"
/>
其中类型定义了Company（单位）、Branch（部门）、Member（人员）、Group（群组）、Application（应用软件）等五种。
组织单元列表数据。
用于描述一组组织单元信息。
ListOUDataInfo>
/ListOUDataInfo>
1.常用数据规范设计原则
在这里列举了一些常用数据规范的设计方式，一般情况下需要遵循这些方式设计数据规范。
元数据的规范设计。
元数据是指信息系统中的最基本数据，如果一个数据被拆开后在整个信息系统中不再具备其他意义，那么这个数据就叫做元数据。
在系统完成功能设计后就可以初步分析出系统建设需要的各类元数据，系统开发和系统试运行过程中元数据可能会存在一些变化，系统投入正式运行前元数据基本可以固定下来。
元数据以Document为根节点的，元数据包含的子节点就是具体的数据属性，如果属性过多（20个以上）并且可以进一步分类那么可以多设计一层子节点，但是一般不要超过三层节点。
下面是组织结构管理模块中的人员数据定义：
人员标识"
Member"
GuidType="
TEXT"
人员标识<
/Guid>
NameType="
人员名称<
/Name>
BranchGuidType="
部门标识<
/BranchGuid>
TelephoneType="
联系电话<
/Telephone>
Handphone1Type="
移动电话<
/Handphone1>
Handphone2Type="
/Handphone2>
EmailType="
电子邮件<
/Email>
LoginNameType="
账户名称<
/LoginName>
PasswordType="
口令<
/Password>
SortType="
LONG"
序号<
/Sort>
LockType="
LOGICAL"
账户锁定状态<
/Lock>
应用标识统一为：
，人员标识由生成人员数据的模块按标准GUID算法生成，数据类型为：
Member，数据属性中的Guid和DataGuid取同一个值，适度的属性冗余可以用来验证数据完整性。
其他数据属性是描述人员信息需要提供的附加内容。
从这个例子可以看出，任何一个属性独立出来后在组织结构管理功能中都不在具备其它意义，因此人员数据可以认为是元数据。
元数据中的属性可以引用其它元数据，但是不能包含其它元数据，如果包含其它元数据那么它本身就不是元数据。
元数据可以包含状态属性，状态属性在设计文档中可以定义多种状态，但是在元数据的实例中状态属性只有一个值。
元数据中相同名称的属性如果存在多个那么对应的属性值是有先后次序的，不同名称的属性是不存在先后次序的，下面两个数据规范可以认为是同一个规范。
规范一
规范二
元数据的实例可以包含元数据定义的节点以外的其他数据节点，只要数据规范定义的节点数据都存在依旧可以认为是一个符合元数据规范的实例数据。
元数据主要用于写入和读取操作，执行写入操作时应用标识、数据标识和数据类型在参数和数据中要同时出现并且值要相同，应用软件负责符合性检查，如果值不相同应用软件可以不执行写入操作。
读取操作时返回的元数据包含应用标识、数据标识和数据类型与读取参数要相同。
数据标识和类型相同的元数据表示同一个元数据
升级会员 