微淘-大家来找茬-概要设计说明书
一．引言
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&[email protected]_iphone_3.4.1.0¬TmallShop=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开发
微淘-大家来找茬-概要设计说明书