|
|
|
TDS模块接入文档 |
|
[键入文档副标题] |
|
|
|
|
|
|
|
|
目录
活动拆解结构图：
蓝色部分为0.2设计一些概念。
模块： 完成一类功能需求的集合。例如抽奖、调研、报名。
功能块：模块内按操作界面来分的功能集合，分拆原则是这些部分同属于一个模块，但是会在活动的不同地方进行展示。例如抽奖中分三块：领取记录、轮播、抽奖按钮。
接口：即一个单独的程序。目前可以是http或idip。按照AME规范输出。
条件：执行动作的前提。由接口和AME的配置（比如根据返回值配置大于，小于等）组合而成。
动作：通过调用接口来完成需求。
资格：属于AME内置，由条件返回结果换算而来。当资格未耗尽的时候，不会去调用条件。
白模版：由功能块提供的模板，完成功能语义。
流程：对外即一个通过AME配置的程序调用。他通过条件+资格+动作配置而成。满足条件或资格后会执行动作。
默认流程：每个功能块有特定的逻辑。这些逻辑是预先可以知道的，例如领取按钮，肯定要调用领取的接口。目第是默认配置好，减少创建活动时候重复配置。
自定义流程：用户按需对条件和动作自由组合。
默认流程和自定义一样，功能一致，差别就是预先配置的还是自定义配置的。
TDS核心主要以下面两块进行：
一），TDS管理端界面。
这是大家配置活动时都能看到的界面；但是在这里配置完成后，并不能用。
打个比喻：每配置一个活动，就好比造一辆车。在TDS管理端界面配置完成以后，就相当于生成了一个“蓝图”。
这个时候的“蓝图”，方向盘并不能控制方向，不能刹车，不能油门，不能坐乘客…. … 那怎样，才能让这个“蓝图”实际有用呢？ 那就是AME。
二），AME，E就是 Engine，“引擎”(用户端的主要部分)。
有了这个引擎，前面所说的“蓝图”，就能起作用了，方向盘能控制方向了，能刹车了，能油门了，能坐乘客了…. …
这两块的职责：
一） TDS管理端配置。能够很好地获取用户的活动配置需求，能够造好一个用户想要的“蓝图”。
包括模块接口管理，功能块管理，活动配置，创建模块，模块配置，流程配置，规则及关系配置，条件及关系配置，动作配置，活动发布，白模版生成，运营管理等。
二） AME（引擎）。能够真正执行用户的需求，将管理端所造好的“蓝图”变得真正有用。
包括活动时间控制，流程执行，规则执行及规则关系控制，条件检测及条件组合关系检测，资格频率控制，资格回滚，动作执行，动作补发，调用各模块，解析各类接口等。
所以大家在使用ams配置时，一般是看不到AME的bug的。但是并不是说这块就高枕无忧了。
AME的bug，主要是由活动测试人员及用户发起的，例如有可能：并发问题，资格回滚问题，补发问题，规则关系控制题，条件检测问题，各类接口请求问题等等。而且这类bug，大多数来说，时间一般比较紧急，一旦出现就得尽快解决的。若处理不好，就引起“突发”。
这两块的关系：
一） TDS管理端配置界面的改动，可能会带来AME的逻辑结构的增加修改。
例如：在管理端配置界面上，需要增加IDIP,积分类的配置,抽奖V3条件CGI的配置； 那么在AME里，得增加IDIP的处理，抽奖V3条件CGI的处理。
例如：在管理端配置界面上，需要增加一些变量参数的配置，例如{date},{dateTime}等； 那么在AME里，得增加对这种变量参数的处理。
否则，TDS管理端配置界面改动了也无效。
二） AME的一些逻辑结构的增加修改，可能会带来TDS管理端界面的改动
例如：AME增加了对动态参数的支持；那么TDS管理端界面得增加配置，让用户可以配置选择动态参数；当然管理端可以想个好的方式去展现界面。
例如：AME规则关系改为了“全部执行”、“成功退出”，“失败退出”；那么TDS管理端界面的规则关系也得这样改；当然管理端可以想个好的方式去展现界面。
否则，AME就算支持了该功能，TDS管理端界面无相应配置，AME也是白做。
总之，这两者的关系就是相辅相成的， 是相连的。
这两块是如何相连合作的呢?
管理端界面配置完成以后，会生成一个“蓝图”，也就是AME的描述文件。然后AME引擎，根据这个“蓝图”，来执行。
所以这个“蓝图”非常重要。如果管理端在生成“蓝图”的时候，把放“刹车”的位置，误生成了“油门”。那么就会出现“误把刹车当油门”的悲剧了。
除了条件cgi，剩下在ams里配置的都会有以下3个必要项目
一共4个状态
l 测试：只有维护人可以看到并使用
l 运行中：千万不要修改，有可能导致活动出问题
l 待下线：可以看到，但是无法添加新的，只能修改老的
l 下线：谁都无法看到
就是个名字，配置活动的时候看的
只有维护人可以修改配置信息
请求：http协议get方式
说明：由于创建时的参数较多，而且参数名称在2个系统间存在差异，需要在ams系统上配置对应关系
返回：json格式。纯json格式，不带前面的”var xxx=”
|
项目 |
值（类型） |
说明 |
|
ret |
0|1 |
状态说明，-1失败，0成功 |
|
msg |
字符串 |
返回信息描述 |
|
id |
字符串 |
创建的模块id |
例：{"id":"226","ret":0,"msg":"ok"}
配置页面样例如下：
请求：http协议get方式，参数信息需要配置，和系统信息关联对应
说明：这个接口用来检查模块配置的完成度，活动的相关模块必须都返回可发布，整个活动才能发布。
返回：json格式
|
项目 |
值（类型） |
说明 |
|
ret |
0|1 |
状态说明，-1失败，0成功 |
|
msg |
字符串 |
返回信息描述 |
|
complete |
字符串 |
完成度的一个百分比，0-100 |
|
canpub |
0|1 |
是否可以发布，0不可以，1可以 |
请求：http协议get方式，参数信息需要配置，和系统信息关联对应
说明：用来发布模块的必要信息以及文件。
返回：json格式
|
项目 |
值（类型） |
说明 |
|
ret |
0|1 |
状态说明，-1失败，0成功 |
|
msg |
字符串 |
返回信息描述 |
配置管理的地址（名称+地址），可以有多个
请求：http协议get方式，直接点击显示。
说明： 配置页面样例如下：
这个地址会显示在下面的页面上
1. 配置好流程之后会生成一个流程对应的唯一的标签，类似 {moduleFunction_xxxx}，这个标签就是需要放在白模板上的标签，ams的程序会将这个标签替换为实际的id值，
2. {activityId}是另外一个ams会替换的标签，就是实际的活动编号，放在白模板中适合的位置
Js通用部分
1. 统一jquery引用
2. 不使用相对路径、
3. 每个模块最好能统一成2个js，一个是主逻辑，一个是活动的配置
框架页面统一加载公用js
<script src="http://ossweb-img.qq.com/images/js/jquery/jquery-1.5.min.js"></script>
<script src="http://ossweb-img.qq.com/images/js/login/loginmanagerv3.js"></script>
<script src="../amshtml/script/core/milo.js"></script>
<script src="/comm-htdocs/js/ams/flowEngine.js"></script>
页面可用标签
需要引用的css的开始和结束标签
<!-- css start -->
<!-- css end -->
模块div的开始和结束标签
<!-- div start -->
<!-- div end -->
白模板页面的js初始化部分，模块需要加载的js可以放这里，内部带script标签
<!-- jsInit start -->
<!-- jsInit end -->
白模板页面的js初始化部分，模块需要加载的js可以放这里，如果是这个标签，则同一模块下的相同标签的内容会只有一份，内部带script标签
<!-- jsInit canMerge start -->
<!-- jsInit canMerge end -->
白模板页面的js部分，内部带script标签
<!-- js start -->
<!-- js end -->
模块中开始就要执行的内容，不带script标签
//jsAutoLoad start
//jsAutoLoad end
所有标签切忌不能交叉，一个页面也不能同时出现多个
以上页面标签必须在
<!--{loopStart}--> <!--{loopEnd}-->
//{loopStart} //{loopEnd}
这2类循环标签以外，不能在里面也不能交叉
白模板举例
http://gameact.qq.com/ams/amstest_lottery/mileStoneMain.html
http://ams.ied.com/module/invite/ams/tpl.php?Action=InviteSubmit&MiloFlag=1&ActivID={modId}
业务接口因实际情况比较复杂，所以这里只列出了通用的内容。配置页面如下：
重点在返回值部分
返回值为JSON格式，如下：
{"iRet" : "0" , "sMsg" : "提示信息" , "jData" : {"XXX" : "XXX"} }
其中：
iRet 返回值 (必须)
sMsg 返回信息(必须)
jData 其他 (可选 也就是模块开发人员 在管理端所配置的返回值。）
例如可以在管理端配置答题接口的返回值里 iCorrectNum 为答对题目数量,iErrorNum 为 答错题目数量。那么，成功返回值应该如下：
{"iRet":"0","sMsg":"答题成功","jData":{"iCorrectNum":"3","iErrorNum":"4"}}
iRet的详细情况:
1， iRet = 0; 接口成功调用。
例如题目展示的接口，调用成功，则正确返回前端需要展示的题目：
{"iRet":"0","sMsg":"ok","jData":{"action_id":"541","i_total_page":20,"i_question_num":20,"form_key":"9958RQwcYzMjYfRzRutkTyWL2z6PEDohHrPgWjvzBGRv7H+ZZmPz9D\/t\/CPn4Wu+","question":{"page":[{"pindex":0,"question":[{"Fid":"8038","FmaxLength":"0","FminLength":"0","FneedInput":"1","FcheckType":"0","FdataType":"int(11)","FinputType":"3","FieldDesc":"\u63a2\u7d22\u4e2d\u635f\u5931\u7684\u6c14\u8840\uff0c\u4f1a\u4e0d\u4f1a\u4ece\u6c14\u8840\u5305\u4e2d\u6263\u9664\uff1f","FLimitType":"0","FchooseNum":"0","option":{"1":{"Fscore":"1","Ftext":"\u4f1a","Fvalue":"1"},"2":{"Fscore":"1","Ftext":"\u4e0d\u4f1a","Fvalue":"2"}},"Fanswer":"","ctrl_type":"radio","ctrl_index":"1","ques_index":1,"cname":"s_field1","sname":"user_field1"},{"FinputType":6,"show_last":"0","show_next":"1","next_index":1}]}]}}}
2， iRet>0; 接口调用错误
此类错误，往往是一些逻辑上的错误，系统也不会自动补调接口。
|
编号 |
说明 |
|
100 |
用户访问太频繁 |
|
101 |
用户未登录 |
模块接口可自定义大于0的错误，可以设在1000以上。
3， iRet < 0; 接口调用错误。
此类错误，<=-100的错误情况下，如果接口配置了补发接口(例如资源以及抽奖模块的接口)，系统会自动补调。会在前端提示给玩家“赠送积分失败，系统会在12小时内补送”等。
6. Idip接口配置
在TDS上可以直接配置IDIP接口，例如，目前已经有部分IDIP接口：
下面示范一下如何配置IDIP接口，以“七雄查询活跃度” 为例。
首页，我们查到该IDIP的命令如下：
打开TDS的“创建接口”：
选择IDIP，将上面所查到的IDIP命令及返回值分别填入。
例如“七雄查询活跃度”的命令串：cmd=36054&area=1023&uin=732945400, 返回值：result=0&uin=732945400&point=13。
那么我们直接在下面的表单里将cmd, area,uin,以及返回值result,uin,point填入：
这样配置完毕以后，就可以直接在活动里使用了：
例如，我们要配置一个条件，玩家的活跃度要大于2000，不满足则提示“对不起，您的活跃度未达到2000！”
返回值为json格式如：{"id":"226","i
Ret":0,"msg":"ok"}
也可以返回var xxx =
{"id":"226","ret":0,"msg":"ok"};系统会自动忽略将第一个大括号之前以及最后一个分号之后的内容
返回的json需要是标准格式，汉字需要转换成Unicode编码。查看json标准
返回格式千万不能是<script type="text/javascript">这样的带js标签的语句