[[TOC]]

== 项目说明 ==

计划5月18日开始公测，5月25日、5月26日分别送审Android、iOS版本。

** 一、电脑网聚超值APPv2.0.0主要需求： **

* 1、新增分类、标签、电商搜索；优化订阅推送功能；增加推荐试用和推荐优惠券；个人中心优化；增加“广场栏目”；UI及交互优化等。

* 2、ios重构。

* 需求框架地址：http://trac.pc.com.cn/iphone/wiki/pconline_price_2.0.0

** 二、项目主要成员： **

* 电脑编辑部：杜建荣；
* 移动产品规划：杨幸、吴凯达；
* 项目支持中心：黄丽玲；
* 设计部：黄颖欣、林俊丽、林耿佳、刘文聪 ；
* 应用产品开发部：黄育才、彭展旋、吴远博 ；
* 移动产品中心：许忠洲、欧建强、朱妙森、吴泽祥、谢德荣、许子轩、阮鹏飞、傅兴方、巫小玲、陈子洋；
* DBA/测试部：张菊婷 、何芬 。

** 三、项目主要时间点： **

* 1、2.26-3.31设计，3.23-4.2制作，3.2-3.20应用开发，3.23-4.16 APP开发；
* 2、应用接口测试：3.23-4.3；mrobot接口测试：4.7-4.27；app整体测试：5.11-5.22
* 3、公测时间：iOS-5.18-5.25；Android-5.18-5.22。

** 四、近期工作安排：  **

* 1、4.2完成全部制作页面并确认； 
* 2、4.16完成后台接口测试。

[http://trac.pc.com.cn/pc_best/attachment/wiki/app2.0/project-description/%E7%94%B5%E8%84%91%E7%BD%91%E8%81%9A%E8%B6%85%E5%80%BCAPP2.0.0%E6%8E%92%E6%9C%9F%E8%A1%A8-150324.xlsx 排期表]

== 1、相关文件 ==

=== 1.1、原型图： ===
* [http://trac.pc.com.cn/iphone/wiki/pconline_price_2.0.0 原型图]

=== 1.2、接口文档： ===
* [http://trac.pc.com.cn/pc_best/wiki/app2.0 接口文档]

=== 1.3、设计稿： ===
* [http://192.168.50.117/2015/2015.02.09dn/index.html 设计稿]


=== 1.4、客户端跳转协议说明： ===
* [http://trac.pc.com.cn/pc_best/wiki/app2.0/protocol 客户端跳转协议说明]

类似于站内跳转，客户端的此种实现都需要根据文档中预先声明好的跳转协议进行跳转，所以在对应的地方需要提供这些协议的url给客户端。

文档刚刚给到，可能有些需要跳转到还需要配合客户端进行调整（跟mrobot协商是把跳转协议放在哪边比较好的，一般放到mrobot那边实现）

=== 1.5、客户端图片尺寸问题： ===
* [http://trac.pc.com.cn/pc_best/wiki/app2.0/image 客户端图片尺寸问题]

接口原则上只返回原图给客户端，客户端根据自己的需要读取具体尺寸的图片。

=== 1.6、App 2.0页面组装说明文档： ===
* [http://trac.pc.com.cn/pc_best/attachment/wiki/app2.0/%E8%81%9A%E8%B6%85%E5%80%BC2.0%E6%8E%A5%E5%8F%A3%E8%AF%B7%E6%B1%82%E5%92%8C%E5%B1%9E%E6%80%A7%E8%AF%BB%E5%8F%96%E8%A7%84%E5%88%99.doc App 2.0页面组装说明文档]

客户端开发根据这个文档读取接口数据

=== 1.7、app2.0接口规范说明： ===
* [http://trac.pc.com.cn/pc_best/attachment/wiki/app2.0/ app2.0接口规范说明]


== 2、代码结构： ==

=== 2.1、代码分支 ===

目前app2.0开发使用了独立的分支：

[[Image(20150408001.png)]]

{{{
#!java
http://svn.demo.pc.com.cn/svn/pc_best/branches/app2.0
}}}

最新的app2.0接口相关代码已经提交到app2.0分支中，并且把该分支合并到了v7.0中，以后使用v7.0继续开发即可，app2.0分支作为一个备份。

=== 2.2、代码结构 ===

App2.0的代码存放到了一个单独的包中：

[[Image(20150408002.png)]]

=== 2.3、下面是每个包的相关说明： ===

> controller

App接口相关的controller，使用Spring MVC的Controller编写的接口（非JSP）存放到这里，目前该目录没有使用，都以JSP的方式进行编写。

> interceptor

Spring的自定义拦截器，一般配合controller包使用，现在暂时没有用到

> json

JSON相关的辅助类。由于接口都是JSON格式的数据，所以返回的数据需要统一转换为JSON格式，目前接口都是使用[https://github.com/alibaba/fastjson fastjson]进行解析的，这个包也是fastjson相关的辅助类。

> result

接口返回结果辅助类，通过使用该包中提供的方法自动把接口转化为约定的格式。

> servlet

接口相关过滤器

> utils

辅助类

> vo

接口相关的VO类，不建议其他地方也使用这里的vo，因为里面很多属性都是按照客户端的要求特别编写的，用在其他的地方不太恰当。

>> 注意：不能随意改动这里的方法名称，因为生成的属性名称跟方法名称挂钩了，改动之后可能会导致mrobot那边程序读取出错。

=== 一个接口的格式大致如下： ===

[[Image(20150408003.png)]]

=== 2.3、接口开发说明 ===
* 每一个接口开头处需要使用如下方法对接口进行初始化设置
{{{
#!java
WebUtils.initAppResponse( response, 0 );
}}}

* 之后必须使用如下方法初始化结果模板：
{{{
#!java
ResultHandler<JSONObject> result = ResultHandler.extract(request, false);
}}}

* pageNo, pageSize, limit, commonSessionId这几个固定的参数需要直接从result中获取，无需在从request中拿去
{{{
#!java
int pageNo = result.getPageNo();
int pageSize = result.getPageSize();
int limit = result.getLimit();
String commonSessionid = result.getCommonSessionId();
}}}

* 对于需要登录的接口，直接放到 /intf/app/my/文件夹里面，在接口里面直接从request里面可以获取到用户登录信息：
{{{
#!java
Account account = (Account)request.getAttribute("account");
}}}

* 每一个接口必须使用try catch 捕获异常，防止服务器抛出RunTimeException导致接口出错

* 在接口中存在集群并发访问同步问题，可以使用 cn.pconline.best.util.sync.McSyncUtils，参考如下接口：
[http://trac.pc.com.cn/pc_best/wiki/app2.0/13_collect#收藏1 /app/my/collect/collectForApp.do  // 收藏接口][[BR]]

* 对于需要限制为post提交的，直接用下面语句判断即可，无需再额外编写代码：
{{{
#!java
if(!result.limitPost()){
    out.print(result.toStringResult());
    return;
}
}}}

* 对于返回结果，如果需要返回VO或者VoList，可以使用 cn.pconline.best.app.vo.VoUtils 中的 toVo(Object entity, Class<T> clazz) 或者 toVoList(List<?> list, Class<T> clazz) 方法进行转换

* 如果Vo里面需要包含其他的实体，不能直接包含其他的实体，而应该先转换为Vo，因为直接包含其他实体，有可能导致转换JSON过程中出现引用循环。转换方式如下：
{{{
#!java
public List<TopicTagVo> getTopicBabyTagList() {
    return VoUtils.toVoList(topic.getTopicBabyTagList(), TopicTagVo.class);
}
}}}

* 关于获取爆料类型的方法：
"TopicService.getTypeIdForAppDetail(long topicId)"是旧app使用的方法，当时栏目id置顶的有歧义，跟网站端的不一致，所以现在废弃了这个方法，以后所有获取栏目类型都用如下的方法：
{{{
#!java
TopicService.getTypeIdForApp(long section);
// 或者
TopicService.getTypeIdByTopicForApp(long topicId);
}}}

=== 2.4、JSP文件结构： ===

[[Image(20150408004.png)]]

{{{
#!java
http://best.pconline.com.cn/intf/app/topic/getTopicList.jsp...

// 通过Nginx配置，接口路径映射为：

http://best.pconline.com.cn/app/topic/getTopicList.do...
}}}

按照模块把接口存放到不同的文件夹中，其中 /my 文件加下表示需要登录才可以访问的接口。

== 3、新增项目配置 ==

[http://trac.pc.com.cn/pc_best/wiki/app2.0/new-nginx-conf Nginx配置]

[http://trac.pc.com.cn/pc_best/wiki/app2.0/new-script 新增数据脚本]

[http://trac.pc.com.cn/pc_best/wiki/app2.0/new-conf 新增项目配置]


== 4、现在app的开发模式 ==

[[Image(20150408005.png)]]

聚超值提供纯JSON数据的后台接口

mrobot对聚超值后台的接口进行转发，获取到需要的属性，并渲染成wap页面。

== 5、开发测试环境 ==

* 开发环境：http://dev34.pconline.com.cn:81/app/topic/cache/getTopicList.do
* 测试环境：v42.pconline.com.cn/app/topic/cache/getTopicList.do?pageNo=1&pageSize=10&sectionId=1

== 6、测试说明 ==

=== 功能测试 ===

* 主要测试app接口查询结果是否和sql查询的一致；

* 接口的参数是否有效；

* 对照wiki文档查看接口参数路径是否拼写错误；

* 查看wiki文档中的说明是否全面，是否有说明歧义的地方

=== 性能测试 ===

对接口进行压力测试，要求响应时间0.8秒内，以下是线上旧接口的测试结果

[http://trac.pc.com.cn/pc_best/attachment/wiki/app2.0/project-description/%E7%BA%BF%E4%B8%8A%E6%8E%A5%E5%8F%A3%E5%88%86%E6%9E%90%E7%BB%93%E6%9E%9C.xls 线上接口分析结果]

== 7、关于集群多线程并发的说明 ==

在集群多线程并发的情况下，我们的一些接口会出现允许重复提交的情况，可以通过一下工具进行测试：
[http://trac.pc.com.cn/pc_best/attachment/wiki/app2.0/project-description/HttpTest%2B2.zip 并发测试工具]

目前的解决办法是暂时写了以下的辅助类：
{{{
#!java
cn.pconline.best.util.sync.McSyncUtils.java
}}}

分别用到了以下几个接口中：

[http://trac.pc.com.cn/pc_best/wiki/app2.0/13_collect#收藏1 /app/my/collect/collectForApp.do  // 收藏接口][[BR]]
[http://trac.pc.com.cn/pc_best/wiki/app2.0/01_topic#添加爆料 /app/topic/addTopic.do  // 添加爆料][[BR]]
[http://trac.pc.com.cn/pc_best/wiki/app2.0/01_topic#赞或者踩 /app/topic/likeAndDislike.do  // 点赞接口][[BR]]

== 8、订阅接口加密说明 ==

以下接口使用了加密的方式进行传送token：
* http://trac.pc.com.cn/pc_best/wiki/app2.0/14_subscription#设置分类订阅
* http://trac.pc.com.cn/pc_best/wiki/app2.0/14_subscription#添加精准订阅
* http://trac.pc.com.cn/pc_best/wiki/app2.0/14_subscription#删除精准订阅

加密方式：客户端请求接口的时候，先用DES进行加密，传到服务器端的时候，再通过DES解密，DES辅助类：
> cn.pconline.best.util.DESUtils
通过 DESUtils.encryptDES(String encryptString)对 token-时间戳(秒)  进行加密，如：
{{{
#!java
4772B355B03F2C68C0338AFD13EB24DC332B2CE8204411E6CA8A53C16D1540D4-1428483376  // token-time
加密为：
gX0N8nM4rPyhrcWm0mE99MYJgmj3nUJHyo31QnoXohuQavW6NBp3Xj5J3/z7fwf6kesQn1OpzaxuIGcNGt1rGZr+heFwRIgUFqloOQCNY00=
}}}
服务器端拿到加密后的字符串进行解密，解密得到token 和time（时间戳）如果解密后判定附加的时间戳是在10分钟以内，则判定为有效的token

> 测试生成加密字符串的地址: http://v42.pconline.com.cn:8001/intf/app/getAddition.jsp

== 9、跟进计划（2015/04/08） ==

根据mrobot开发的反馈进行调整

= 附录 =
[http://trac.pc.com.cn/pc_best/wiki/app1.x app旧版接口]