高级 web 开发规范

组员

13302010006 田添星
13302010020 郭一鸣
13302010032 周奕
13302010038 季灵阳
13302010043 朱荣斌

技术栈

概述

本次 PJ 采取 前后端分离 的技术，后端开放 RESTful 的接口，前端通过 ajax 获取后端数据，并展示出来。项目协作采用 github。

后台开发

框架 Spring + Spring MVC + MyBatis
服务器 GlassFish
数据库 MySQL

前台开发

框架 MUI(HTML5+) + Angular.js

测试

框架 jUnit + jMock

开发约定

前后端交互接口 部分，规定了前端读取数据的 地址、返回值，返回值采取 JSON 格式。

开发样例：在首页，前端显示“近代公园”类型的所有景点，使用 ajax 访问的地址是 ADDRESS/views/0，这时返回的是一个 JSON 格式的 景点数组，记为 data。根据 数据结构 里 景点表 的内容，可以通过 data[0].vid 获得景点ID，通过 data[0].name 获得景点类别，诸如此类。

数据结构

用户表 user

景点表 view

约定: 景观类别暂定为2个，如下：

用户行为表 action

约定：用户行为有四种类型，如下：

注意：评分不会保存在 用户行为表 里，而是专门保存在后面的 评论表 里，但是为了统一，把它纳入用户行为的体系。

标识表 flag

约定：参考 PJ 文档第 6 页，约定以下内容，其中

• 0~4 是 活动类型 标识类型为0
• 5~9 是 场所类型 标识类型为1
• 10~14 是 建议 标识类型为2

评论表 comment

评论资源表 resource

前后端交互接口

服务器地址：ADDRESS 待定。

主页

地图

功能：获取所有的景点信息
地址：ADDRESS/views
返回：成功返回景点数组，失败返回null
样例：

[{"vid":1,"category":0,"name":"复旦大学张江校区","longitude":121.606,"latitude":31.1951,"detail":"复旦是个好学校","picture":null},{"vid":2,"category":0,"name":"上海中医药大学","longitude":121.603,"latitude":31.2003,"detail":"上海中医药大学","picture":null}]

功能：根据景点名称搜索景点列表
地址：ADDRESS/search/用户ID/景点名称
返回：成功返回景点ID和名称数组,失败返回null
样例：

[{"vid":1,"category":0,"name":"复旦大学张江校区","longitude":121.606,"latitude":31.1951,"detail":"复旦是个好学校","picture":null},{...}]

功能：根据用户id和行为Id对搜索进行排序
地址：ADDRESS/history/search/用户Id/用户行为Id
返回：成功返回景点Id和名称数组，失败返回null
样例：[{"vid":1,"name":"复旦大学张江校区","track_number":2},{"vid":2,"name":"上海中医药大学","track_number":1}]
注释：collect_number 可以为track_number,grade_number,wish_number分别为足迹数量，分数(可以为小数),心愿数量

顶部栏

功能：以某一用户行为指标的数量和景观类别ID为依据，对经典进行排名并降序显示
地址：ADDRESS/rankings/景观类别ID/用户行为ID
返回：成功返回景点及其相应指标数量的数组,失败返回null
样例：[{"vid":1,"name":"复旦大学张江校区","track_number":2},{"vid":2,"name":"上海中医药大学","track_number":1}]
注释：collect_number 可以为track_number,grade_number,wish_number分别为足迹数量，分数(可以为小数),心愿数量

底部工具栏

注：项目列表和顶部栏相同

功能：获取景点的总评分和各星级评分比例
地址：ADDRESS/grade/景点ID
返回：成功返回总评分、一星级到五星级的占比,失败返回null
样例：{"avg_star":3.5,"one_star":2,"two_star":3,"three_star":4,"four_star":1,"five_star":5}

功能：获取景点所有评论，包含用户名、评分和评论内容
地址：ADDRESS/comment/show/景点ID
返回：成功返回评论数组，失败返回null
样例：[{"vid":1,"uid":1,"grade":3,"detail":"111","url":"-1","cid":1}]
注释：url=-1表示没有图片

功能：获取景点详细信息
地址：ADDRESS/info/景点ID
返回：成功景点详细信息、图片、地址，失败返回null
样例：{"vid":1,"category":0,"name":"复旦大学张江校区","longitude":121.606,"latitude":31.1951,"detail":"复旦是个好学校","picture":"-1"}

功能：添加景点到用户的足迹/心愿/收藏
地址：ADDRESS/action/add/用户ID/景点ID/用户行为ID
返回：成功返回true 错误返回false

功能：删除景点到用户的足迹/心愿/收藏
地址：ADDRESS/action/delete/用户ID/景点ID/用户行为ID
返回：成功返回true 错误返回false

功能：根据标识类型获取对应的标识信息
地址：ADDRESS/flag/show/标识类型ID/景点ID
返回：成功返回标识数组，失败返回空
样例：[{"fid":1,"vid":1,"latitude":111.0,"longitude":111.0},{}]

功能：在景点的内部某个地址设置一个标识，可能还会添加附加信息，如“其他”，附加信息为空则设置为-1。
地址：ADDRESS/flag/add/标识ID/景点ID/经纬度/附加信息
返回：成功返回true,失败返回false
注释：没有附加信息则传入-1

功能：添加评论，评论内容、资源为空则设置为-1，资源ID用逗号隔开。
地址：ADDRESS/comment/add/用户ID/景观ID/评分/评论内容/url/type/addition
返回：
注释：没有图片则url,type,addition 都为-1

功能：上传图片获取url
地址：/comment/picture
返回：url
样例：{value:"http://s11.sinaimg.cn/orignal/48d703704e150311a52ea"}

TODO：图片上传 API，参考 http://my.oschina.net/pingdy/blog/199592

功能：根据景点ID，获取景点区域构成的点
地址：ADDRESS/view/area/景点ID
返回：成功返回一组经纬度数组,失败返回null
样例：["121.601307","31.197314","121.607451","31.198056","121.607972","31.191708","121.605475","31.191353","121.604073","31.194581","121.601864","31.194272"]

附近

功能：根据某个用户行为指标，对当前位置附近的景点进行排序
地址：ADDRESS/neighbour/用户行为ID/longitude/latitude
返回：成功返回附近景点及其指标数量的数组，失败返回null
样例：{"vid":1,"latitude":31.1951,"name":"复旦大学张江校区","track_number":2,"category":0,"longitude":121.606},{"vid":2,"latitude":31.2003,"name":"上海中医药大学","track_number":1,"category":0,"longitude":121.603}]
注释：可以为track_number,grade_number,wish_number分别为足迹数量，评分（可以为小数）,心愿数量

路线规划

自行调用百度地图API
功能： 路线中获取途径景点
地址：ADDRESS/route/schedule/第一个点经度/第一个点纬度/第二个点经度/第二个点纬度
返回： 成功返回景点数组，失败返回null
样例：[{"vid":1,"category":0,"name":"复旦大学张江校区","longitude":121.606,"latitude":31.1951,"detail":"复旦是个好学校","picture":"-1"},{"vid":2,"category":0,"name":"上海中医药大学","longitude":121.603,"latitude":31.2003,"detail":"上海中医药大学","picture":"-1"}]

我的

功能：注册用户
地址：ADDRESS/register/用户名/密码
返回：成功，返回用户ID；失败，返回-1。
样例：{"uid":-1}

功能：登陆
地址：ADDRESS/login/用户名/密码
返回：成功，返回用户ID；用户名不存在，返回-1；密码错误，返回-2。
样例：{"uid":-1}

功能：上传用户头像
地址：ADDRESS/setPortrait/用户ID
返回：成功，返回头像资源地址
样例：{value:"http://img4q.duitang.com/uploads/item/201502/09/20150209203903_ZRyKL.jpeg"}

<!-- action 里面传入用户 id-->
<form id="uploadForm" action="../portrait/1" method="post" enctype="multipart/form-data">
    <div>
        <!-- name 一定要是 fileData -->
        <input type="file" id="fileData" name="fileData"/>
        <input type="submit" id="submitContent" value="upload"/>
    </div>
</form>
<script>
    $("#uploadForm").submit(function (e) {
        e.preventDefault();
        var $form = $("#uploadForm");
        var fd = new FormData($(this)[0]);
        console.info(fd);
        $.ajax({
            type: 'POST',
            url: $form.attr('action'),
            data: fd,
            cache: false,
            processData: false,
            contentType: false,
            success: function (response) {
                //在这里处理 responce
            },
            error: function (XMLHttpRequest, textStatus, errorThrown) {
            }
        });
    })
</script>

功能：查看用户行为
地址：ADDRESS/action/show/用户ID/用户行为ID
返回：景点数组
样例：[{"vid":1,"detail":"xx","name":"1933"},{}]