[关闭]
@42withyou 2015-02-28T06:51:20.000000Z 字数 4402 阅读 758

青基会购物车设计及接口文档

文档

文档地址：https://www.zybuluo.com/42withyou/note/71149

修订记录

版本号 内容 制定人 制定时间
1.0 根据服务接口需求撰写文档 叶科忠 2015.2.10

需求

  1. 实现青基会下属网站登陆后，在页面右下角显示捐款车框架。
  2. 实现统一的捐款订单管理，支付流程。
  3. 提供相应接口。

实现方式

  1. 前端捐赠车框架 frame 通过嵌入iframe呈现。
    通过代理frame实现跨主域级别的前端消息传递，以实现购物车frame自适应高度，购物车更新通知等功能。
  2. 后端提供简化的RESTful接口。

技术要点

1. 跨主域frame通信

说明

在单点登陆系统中，我们通过jsonp的302重定向来实现跨域传递登陆信息。
在购物车里，我们需要解决的问题是应用前台和购物车框架之间需要交流一些信息，而仍然是由于浏览器的同源策略，不允许跨域调用其他页面的对象。
但仍有一些曲折的办法实现跨域消息的传递，跨域 frame 通信相关问题，请先阅读 http://www.cnblogs.com/rainman/archive/2011/02/20/1959325.html 了解。

解决方案

A : 当前应用
B : 购物车
C : 当前应用实现的代理页面
Page A include Page B
Page B include Page C
A和B属于两个域，A和C在同一个域中
A向B通信：通过url hash
B向C通信：通过url hash
B向A通信：先把消息给C，由于A和C属于同一个域下，C可以直接将消息传递给A（使用 url hash 向C中传参数，然后在C中获取参数并调用parent.parent调用A中的函数即可）

实现流程：

js文件均提供 .min.js 版本

1. 捐款车用户端JS接口：cydf_cart_client.js (http://cart.cydf.org.cn//styles/js/cydf_cart_client.js)

  1. // cydf_cart_client.js
  2. // 捐款车用户端文件，提供CydfCartClient变量及以下接口
  3. var CydfCartClient = function() {
  4.     return {
  5.         // 加载并初始化购物车，请在用户登陆后再调用，未登陆状态下捐款车不会显示，而是持续刷新直到获取到单点登陆信息或已登陆。
  6.         /*
  7.             参数：
  8.             cart_agent_page_url 由您实现的代理页面，实现方法请参照下文
  9.             cart_user_style_file_url （可选）捐款车外部自定义样式文件地址，即捐款车位置，大小，弹窗样式
  10.             cart_frame_user_style_file_url （可选）捐款车frame内部自定义样式文件地址
  11.             如果您提供了这两个样式自定义文件参数，购物车将加载您提供的样式文件，而不加载购物车原始样式文件
  12.         */
  13.         init: function(cart_agent_page_url, cart_user_style_file_url, cart_frame_user_style_file_url) {},
  15.         // 下面三个接口用于不刷新页面，来提示用户和通知购物车框架内容有变
  16.         // 在您不使用ajax来提交商品信息时，无需使用到这些接口。
  18.         // 告知捐款车内容有变化，捐款车会重新加载，与dialog接口配合使用
  19.         change: function() {},
  20.         // 通过ajax请求在应用后台通过CartApi接口将商品信息提交到购物车后，调用此方法弹出成功加载到购物车的提示窗口，并需调用change接口来刷新购物车
  21.         dialog: function() {},
  22.         // 关闭弹窗，弹窗上有关闭按钮调用此方法，您无需自己调用
  23.         dialogClose: function() {}
  24.     }
  25. }();
  27. // 使用方法
  28. if (user_login == true) {
  29.     CydfCartClient.init();
  30. }

2. 捐款车代理frame页面功能实现 cydf_cart_agent.js (http://cart.cydf.org.cn/styles/js/cydf_cart_agent.js)

您无需关注该文件的细节，但需实现代理页面，非常简单，您只需实现一个页面，输出以下内容：
如：http://jlxd.cydf.org.cn/cart_agent

  1. <html>
  2.     <head>
  3.         <title>捐赠车代理</title>
  4.         <script src='http://cart.cydf.org.cn/styles/js/cydf_cart_agent.js'></script>
  5.     </head>
  6.     <body>
  7.     </body>
  8. </html>

3. 后端提供简化的RESTful接口文件 CartApi.class.php

  1. class CartApi {
  3.     static protected $_accessUser = 'xszz'; // 应用接入时提供
  4.     static protected $_accessKey  = 'xxxxxxxxxxx'; // 应用接入时提供
  5.     static protected $_geteway    = 'http://cart.cydf.org.cn/';
  7.     static public function get($api, $data = NULL) {}
  9.     // 为了简化设计，通常您只需使用这个接口调用 api 即可!
  10.     // 虽然提供了RESTful的四个语义接口，但实际上他们都干的一样的事...
  11.     static public function post($api, $data = NULL) {}
  13.     static public function put($api, $data = NULL) {}
  15.     static public function delete($api, $data = NULL) {}
  16. }
  18. /* 返回值
  19.     array(
  20.         status => 状态
  21.         status_message => 状态信息
  22.         data => 数据
  23.     )
  24. */

4. Cart 服务器提供的接口

  1. /*
  2.     接口名：save
  3.     功能：提交捐款商品信息
  4.     参数：
  5.         $data = array(
  6.             project_id => 公益项目id
  7.             project_item_id => 公益产品类型id （可选？这个是每个项目都有的吧，如果没有就不用传了）
  8.             item_money => 商品金额
  9.             project_desc => 产品描述（希望工程1+1等）
  10.             source_desc => 意愿（用户留言） （可选）
  11.             source_web => 来源网站域名（例如：http://jlxd.cydf.org.cn）
  12.             source_detail_url => 详情url（例如 http://jlxd.cydf.org.cn/donate/detail/1546）
  13.             source_url =>  来源的url（例如：http://jlxd.cydf.org.cn/project/4946）
  14.             source_desc => 来源描述（例如：激励行动-“海洋天堂”——关爱自闭症儿童公益行动）
  15.             user_id => 用户id
  16.             source_img_uri => 来源图片地址 （可选，没有会很难看哦～！）
  17.             source_detail_data => serialize(array( 详细列表数据，如学生资助的学生列表，记得序列化哦 （可选）
  18.                 keys => 列表列标题
  19.                 datas =>  列表列数据
  20.             ))
  21.         );
  22.     返回值：
  23.     data['cart_item_id'] = 捐款车商品id
  24. */
  26. // 使用方法示例
  27. $cart_item_data = array();
  28. $cart_item_data['project_id']        = $param['ProjectID'];
  29. $cart_item_data['item_money']        = $param['DonMoney'];
  30. $cart_item_data['project_desc']      = "激励行动";
  31. $cart_item_data['source_desc']       = $param['ProductDesc'];
  32. $cart_item_data['source_web']        = Utility::GetCurrentWebRoot();
  33. $cart_item_data['source_detail_url'] = $_SERVER['HTTP_REFERER'];
  34. $cart_item_data['source_url']        = Utility::GetCurrentWebRoot() . '/project/' . $project_id;
  35. $cart_item_data['user_id']           = $this->login_user['UserGUID'];
  36. $cart_item_data['source_img_uri']    = Utility::GetCurrentWebRoot() . '/styles/css/images/bg_img/logo.jpg';
  37. $source_detail_data['keys'] = array('ID', '姓名', '学校', '性别', '民族', 'xxx', '还有什么');
  38. $source_detail_data['datas'] = array(
  39.    array(50,"科忠",   "其他合作项目", "7d0c0d04-60a8-4923-8fb6-5e6e253f9c81",   "111", "上海家化公益基金", "B1405000001"),
  40.    array(100 , "双虎",  "其他合作项目",    "7d0c0d04-60a8-4923-8fb6-5e6e253f9c81",    "sdf",    "上海家化公益基金", "B1405000001"),
  41.    array(200 , "侯哥", "其他合作项目", "7d0c0d04-60a8-4923-8fb6-5e6e253f9c81", "asdf", "上海家化公益基金", "B1405000001"),
  42.    array("0", "哈哈",  "其他合作项目", "7d0c0d04-60a8-4923-8fb6-5e6e253f9c81",   "asdf",   "上海家化公益基金", "B1405000001"),
  43.    );
  44. $cart_item_data['source_detail_data'] = serialize($source_detail_data);
  45. $result = CartApi::post('save', $cart_item_data);
添加新批注
在作者公开此批注前，只有你和作者可见。
回复批注