微淘-大家来找茬-概要设计说明书

微淘-大家来找茬-概要设计说明书

一．引言

 1．编写目的

能够快速进入项目，实施项目开发工作，为后续的编码和测试提供技术参考依据。
本书的读者包括：开发人员、界面开发人员、系统架构人员、产品部门所有人员

2．项目背景

项目参与人员包括开发人员、界面开发人员、系统架构人员、产品部门所有人员
开发人员负责具体开发工作，
界面开发人员负责界面设计以及前台页面编码工作，
系统架构人员负责制定核心技术的以及技术规范，
产品人员根据制定的标准进行验收工作
本系统运行在淘宝的JAE平台上，属于微淘插件的一种。 

3．术语

JAE ：JAE是一个基于云计算基础架构的网络应用程序托管环境，帮助开发者简化应用程序的构建和维护。
微淘: 微淘是手机淘宝变形的重要产品之一，定位是基于移动消费领域的入口，在消费者生活细分领域，为其提供方便快捷省钱的手机购物服务。
淘宝开放平台：大淘宝电子商务基础的重要开放途径，推动各行各业定制、创新、进化，并促成新商业文明生态圈。
API：API（Application Programming Interface,应用程序编程接口）是一些预先定义的函数，目的是提供应用程序与开发人员基于某软件或硬件的以访问一组例程的能力，而又无需访问源码，或理解内部工作机制的细节。
JFinal：JFinal 是基于Java 语言的极速 web 开发框架，其核心设计目标是开发迅速、代码量少、学习简单、功能强大、轻量级、易扩展、Restful。
Kissy：KISSY 是由淘宝前端工程师们发起创建的一个开源 JS 类库，她遵循的原则是 小巧灵活、简洁实用、愉悦编码、快乐开发。
FreeMarker：FreeMarker是一个用Java语言编写的模板引擎，它基于模板来生成文本输出。
微淘Feeds：微淘共享内容的一种简易方式、简称微淘广播。

4．参考资料

JAE技术文档：http://jae.taobao.com/
微淘无线插件接入文档：http://jae.taobao.com/jaedocs/docs.html?spm=0.0.0.0.o9rTM1&path=dcc440152c0f798e86163031006de1e5
JFinal手册：http://code.google.com/p/jfinal/downloads/list
Kissy手册：http://docs.kissyui.com
FreeMarker手册：http://freemarker.org/
淘宝微淘API手册1：http://open.taobao.com//doc/api_cat_detail.htm?scope_id=11283&category_id=102
淘宝微淘API手册2:
http://open.taobao.com//doc/api_cat_detail.htm?scope_id=11252&category_id=102
淘宝多媒体API手册:
http://open.taobao.com/doc/api_cat_detail.htm?category_id=102&cat_id=10122

5．规范

Java官方编码规范 Code Conventions
Kissy前端编码规范
FreeMarker标准规范
CRSF编码规范

二．任务概述 

1．目标

 能够在规定的运行环境中正常运行，对需求快速理解定位。

2．运行环境

 WEB服务器： 淘宝JAE
JDK：java 1.6
Java框架：JFinal
前台界面框架：Kissy
模板引擎：FreeMarker

3．需求概述

 买家用户通过淘宝手机客户端的微淘功能，进入关注店铺的feeds列表，feed的detail页面进入大家来找茬游戏。
买家通过扫二维码进入大家来找茬游戏。
买家访问的地址最终为http://xx.we.app.jae.m.taobao.com/?seller_nick=%E5%95%86%E5%AE%B6%E6%B5%8B%E8%AF%95%E5%B8%90%E5%8F%B717&a=b&ttid=201200@taobao_iphone_3.4.1.0&notTmallShop=1
地址可以进行分解如下：
    插件的前台回调地址+卖家Nick（经utf-8转码）+feeds发送接口中url_param参数+主客其他参数。
    如果开发者在一个应用中会有多个游戏，则可通过url_param参数来区分处理。
卖家用户通过xx.we.app.jae.taobao.com/admin，进入PC端管理后台，进行活动创建、活动暂停、奖项设置等

4．条件与限制

开发者在开发时需要统一使用UTF-8编码，否则可能会出现乱码的情况
屏蔽Android的feed detail页的分享按钮 ·［如何屏蔽分享按钮，请查看微淘无线插件接入文档.］

三．总体设计

1．处理流程

  

2．总体结构和模块外部设计

  

3．目录结构

  

/finding_fault  ----------------------  项目名称
|--  Src  -----------------  java 源文件
    |--    Controllers  -----------------------  控制器
    |--    Model  -----------------------  model
    |--    Util ------------------------- 常用工具集

    |--    core ------------------------ 数据实体
|--   Lib  ------------------  所需要包含的包
|--   Web ------------------  web所需要的资源文件
    |--  Admin ------------------- 后台js/css/view
        |--  Css ---------------------- 前台css
        |--  Js  ---------------------- 前台js
        |--  View ---------------------- 前台view

四．接口设计 

1．外部接口

参考淘宝提供的API
http://open.taobao.com//doc/api_cat_detail.htm?scope_id=11283&category_id=102
http://open.taobao.com//doc/api_cat_detail.htm?scope_id=11252&category_id=102

2．内部接口

接口数据返回统一为JSON数据。

1）. 游戏资源文件获取接口
请求地址：http://damai.we.app.jae.taobao.com/game/data
前提条件：无
应用输入：

名称	类型	是否必须	默认值	示例	描述
level	int	可选	1	1	关数
buyer_nick	String	可选		百惠行	买家名称

返回结果：

名称	类型	描述
game	GameData	游戏资源数据

2）. 游戏结果上传接口
无

3）. 活动创建接口
请求地址：http://damai.we.app.jae.taobao.com/activity/save
前提条件：卖家用户已经授权
应用输入：

名称	类型	是否必须	默认值	示例	描述
activity_name	String	是		这是一个活动	活动名称
begin_date	Date	是		2014-1-2	开始日期
begin_time	Time	可选	00:00:00	10:00:00	开始时间
end_date	Date	是		2014-2-2	结束日期
end_time	Time	可选	00:00:00	10:00:00	结束时间
coupon_id	int	是		1111	奖励编号
coupon_type	String	是		taobao	奖励类型
banner_url	Url	是		http://img04.taobaocdn.com/734131476.jpg	活动banner
is_send_msg	boolean	是		1	是否发送广播消息

返回结果：

名称	类型	描述
activity	Activity	活动数据

4）. 活动暂停接口
请求地址：http://damai.we.app.jae.taobao.com/activity/stop
前提条件：卖家用户已经授权
应用输入：

名称	类型	是否必须	默认值	示例	描述
activity_id	int	是		11	活动编号
is_stop	Boolean	是		0	是否暂停

返回结果：

名称	类型	描述
activity	Activity	活动数据

5 ) . 自定义奖项创建接口
请求地址：http://damai.we.app.jae.taobao.com/award/create
前提条件：卖家用户已经授权
应用输入：

名称	类型	是否必须	默认值	示例	描述
title	String	是		5元优惠卷	奖励标题
desc	String	否		5元优惠卷	奖励备注

返回结果：

名称	类型	描述
award	Award	奖励数据

6）. 自定义奖项获取接口
请求地址：http://damai.we.app.jae.taobao.com/award/list
前提条件：卖家用户已经授权
应用输入：无
返回结果：

名称	类型	描述
awards	Award[]	奖励列表数据

7）. 官方优惠卷获取接口
请求地址：http://damai.we.app.jae.taobao.com/award/coupons
前提条件：卖家用户已经授权
应用输入：

名称	类型	是否必须	默认值	示例	描述
page	int	否	1	1	页数

返回结果：

名称	类型	描述
coupons	Coupon[]	官方优惠卷列表数据

8）. 发送奖项接口
请求地址：http://damai.we.app.jae.taobao.com/game/award
前提条件：无
应用输入：

名称	类型	是否必须	默认值	示例	描述
activity_id	int	是		11	活动编号
buyer_nick	String	可选		百惠行	买家名称
seller_nick	String	可选		百惠行	卖家名称

返回结果：

名称	类型	描述
buyer_award	BuyerAward	买家得到的活动数据

9）.发送广播接口
请求地址：http://damai.we.app.jae.taobao.com/feed/create
前提条件：卖家用户已经授权
应用输入：

名称	类型	是否必须	默认值	示例	描述
title	String	是		送优惠卷活动	广播标题
cover_pic	URL	是		http://img04.taobaocdn.com/734131476.jpg	广播banner
activity_id	String	是		11	活动编号

返回结果：

名称	类型	描述
feed	Feed	广播信息

10).活动banner图片上传到卖家淘宝空间接口
请求地址：http://damai.we.app.jae.taobao.com/banner/upload
前提条件：卖家用户已经授权
应用输入：

名称	类型	是否必须	默认值	示例	描述
file_bin	bin	特殊可选			图片文件二进制文件
file_url	URL	特殊可选			图片ＵＲＬ地址

返回结果

名称	类型	描述
picture	Picture	图片信息

五．数据结构设计 

1．逻辑结构设计

1） 游戏资源数据结构
2） 活动数据结构
3） 奖项数据结构
4） 广播数据结构
5） 买家获取奖项数据结构
6） 买家通过游戏关数的数据结构

2．物理结构设计

1） 游戏资源数据结构分为两个部分：卖家信息、基础图片信息和差异坐标点。
2） 活动数据结构包括：卖家信息、基础信息、活动时间设置、游戏资源设置和奖项设置。
表 活动数据表
 

字段	类型	约束	自增	外键	备注
activity_id	int	pk	是		活动编号
activity_name	varchar（50）				活动名称
seller_nick	varchar（50）			是	商家名称
banner_url	varchar（255）				活动banner
is_send_msg	tinyint				是否发送广播消息
coupon_id	int			是	优惠卷编号
coupon_type	enum				优惠卷类型
begin_time	datetime				生效时间
end_time	datetime				截止日期
is_stop	tinyint				是否暂停
create_time	datetime				创建时间
update_time	datetime				更新时间

3）奖项数据结构包括：卖家信息、奖项名称、奖项描述。
表 自定义奖项表

字段	类型	约束	自增	外键	备注
award_id	int	pk	是		奖励编号
seller_nick	vachar（50）			是	卖家名称
title	varchar（50）				奖励名称
desc	varchar（200）				奖励描述

表 官方优惠卷表

字段	类型	约束	自增	外键	备注
coupon_id	int	pk			优惠卷id
seller_nick	varchar(50)			是	商家名称
denominations	int				优惠卷面额,单位分
start_time	datetime				生效日期
end_time	datetime				截止日期
condition	int				使用条件

4）广播数据结构包括：卖家信息、标题、封面地址、业务参数、链接地址、发表时间。
5）买家获取奖项数据结构包括：买家信息、卖家信息、活动信息和得到的奖项信息。
表 买家获取奖项数据
 

字段	类型	约束	自增	外键	备注
id	int	PK	是		编号
buyer_nick	varchar（50）			是	买家名称
saller_nick	varchar（50）			是	买家名称
activity_id	int			是	活动编号
activity_name	varchar（50）				活动名称
coupon_id	int			是	奖励编号
coupon_type	enum				奖励类型
coupon_name	varchar（50）				奖励名称
log_time	datetime				获取时间

6）买家通过游戏关数的数据结构包括：买家信息、卖家信息、活动信息和关数信息。

3．数据结构与程序的关系 

表名	描述	业务数据对象	Model实体对象
game_img	游戏基础图片信息表	GameData	GameImg
game_point	游戏差异坐标点	GameData	GamePoint
activity	活动数据	Activity	Activity
award	奖项数据	Award	Award
feed	广播数据	Feed	Feed
buyer_award	买家获取奖项	BuyerAward	BuyerAward
buyer_game	买家通过游戏关数	BuyerGame	BuyerGame

六．运行设计 

1．运行模块的组合

 1） 创建活动、创建奖项、创建游戏资源数据和发送广播组合

2．运行控制

 1）单条程序功能运行内存以及cpu的消耗不能超过20%。

3．运行时间

 1）单条程序功能运行不得超过2sec
2）复杂运算功能运行不得超过5sec
3）多功能运行不得超过1minute

七．出错处理设计

1．出错输出信息

 出错信息包括：错误代码，错误英文信息，错误中文描述

错误代码	错误英文信息	错误中文描述
0	error	严重错误
1000	db connection error	数据库连接错误
1001	config setting error	配置文件错误
...	...	...

 

2．出错处理对策

 严重错误信息统一输出错误页面，进行良好的提示，并记录LOG。
一般数据输入错误，提示参数输入错误，有详细的提示。

八．安全保密设计

 编码统一使用CRSF编码规范。
页面输出使用FreeMarker标准规范

九．维护设计

错误进行log记录
异常进行log记录
Log记录格式参照Log4J
版本修订根据实际业务进行v2.0开发