微淘-你們來找茬-概要設計說明書

微淘-你們來找茬-概要設計說明書

一．引言

 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開發