diff --git a/documents/Principle_zh-CN.md b/documents/Principle_zh-CN.md index 3af268b..e9ef06e 100644 --- a/documents/Principle_zh-CN.md +++ b/documents/Principle_zh-CN.md @@ -10,7 +10,7 @@ 本日历目前无条件限定最小时间为1950年1月1日，最大时间为2200年12月31日。 -API只有在遇到非当前接口应该产生的错误时，才使用外层结构来进行返回错误，例如token无效，应用程序错误，参数错误等。其应当返回的错误应该通过内层进行返回，例如登录接口的登陆成功与失败，删除接口的成功与否，应该通过内层返回true或false来决定。 +API在遇到当前接口产生错误时，使用外层结构来进行返回错误，例如token无效，应用程序错误，参数错误等。请注意捕获错误。如果没有错误，则表示data字段为有效数据。 ## 数据库 @@ -280,11 +280,12 @@ Calendar类下的为日历请求接口 Collection类下的为日历集合请求接口 尾缀为Own的为对自己拥有集合的操作，尾缀为Sharing的表示对自己拥有的某个集合的分享人员进行操作，尾缀为Shared的表示对由他人分享的日历集合的操作。 +其中Own结尾的get请求与日历事件获取请求相似，也有两种，一种是设计给网页使用的getFull。另一种是为客户端同步设计的getList和getDetail。 需要注意的是，在数据表中这3部分由2个表描述，collection和share，在进行Sharing结尾的操作时（也就是操作share表），同时也会更新其在collection对应条目的lastChange。因此share表里没有lastChange而全部lastChange都在collection表里。 -#### getOwn +#### getFullOwn -请求地址：`/api/collection/getOwn` +请求地址：`/api/collection/getFullOwn` 请求参数： @@ -294,6 +295,31 @@ Collection类下的为日历集合请求接口 返回参数：一个json，返回collection数据表中符合条件的条目组合成的数组 +#### getListOwn + +请求地址：`/api/collection/getListOwn` + +请求参数： + +|参数名|参数类型|参数解释| +|:---|:---|:---| +|token|string|用于用户鉴权的字符串| + +返回参数：一个json，返回collection数据表中符合条件的条目的uuid组合成的数组 + +#### getDetailOwn + +请求地址：`/api/collection/getDetailOwn` + +请求参数： + +|参数名|参数类型|参数解释| +|:---|:---|:---| +|token|string|用于用户鉴权的字符串| +|uuid|string|需要获取集合的uuid| + +返回参数：一个json，返回collection数据表中对应uuid的条目 + #### addOwn 请求地址：`/api/collection/addOwn` @@ -504,7 +530,7 @@ Admin类的操作不涉及任何客户端存储，因此不需要lastChange来 |token|string|用于用户鉴权的字符串| |username|string|新的用户名| -返回参数：一个bool，用于表示是否创建成功，创建成功的用户具有一个随机的密码，并且默认非管理员 +返回参数：一个json，返回新建用户的对应条目，与get接口返回字段一致。创建成功的用户具有一个随机的密码，并且默认非管理员。创建失败返回null #### update diff --git a/src/static/js/api.js b/src/static/js/api.js index bfbd434..5b83774 100644 --- a/src/static/js/api.js +++ b/src/static/js/api.js @@ -52,9 +52,45 @@ function ccn_api_common_login(_username, password) { } */ +// ============================================ template +// all api can be implemented by these 2 function, except 3 token related func. +// so all api func should use these 2 func except 3 token process api. +function ccn_api_dataTemplate(_url, _data) { + // return data or undefined + var gotten_data = undefined; + $.ajax({ + url: _url, + type: "POST", + async: false, + data: _data, + success: function (data) { + gotten_data = data; + } + }); + + if (IsResponseOK(gotten_data) && !(gotten_data['data'] === null)) return gotten_data['data']; + else return undefined; +} + +function ccn_api_boolTemplate(_url, _data) { + // return true or false + var gotten_data = undefined; + $.ajax({ + url: _url, + type: "POST", + async: false, + data: _data, + success: function (data) { + gotten_data = data; + } + }); + + return (IsResponseOK(gotten_data) && gotten_data['data']); +} + // ====================================================== common -function ccn_api_common_webLogin(_username, password) { +function ccn_api_common_webLogin(_username, _password) { var gotten_data = undefined; $.ajax({ url: '/api/common/webLogin', @@ -62,7 +98,7 @@ function ccn_api_common_webLogin(_username, password) { async: false, data: { username: _username, - password: password + password: _password }, success: function (data) { gotten_data = data; @@ -121,99 +157,273 @@ function ccn_api_common_tokenValid() { } } +function ccn_api_common_isAdmin() { + return ccn_api_boolTemplate( + '/api/common/isAdmin', + { + token: GetApiToken() + } + ); +} + +function ccn_api_common_changePassword(_password) { + return ccn_api_boolTemplate( + '/api/common/changePassword', + { + token: GetApiToken(), + password: _password + } + ); +} + // ====================================================== calendar +function ccn_api_calendar_getFull(_startDateTime, _endDateTime) { + return ccn_api_dataTemplate( + '/api/calendar/getFull', + { + token: GetApiToken(), + startDateTime: _startDateTime, + endDateTime: _endDateTime + } + ); +} +function ccn_api_calendar_getDetail(_uuid) { + return ccn_api_dataTemplate( + '/api/calendar/getDetail', + { + token: GetApiToken(), + uuid: _uuid + } + ); +} +function ccn_api_calendar_update(_uuid, _belongTo, _title, _description, _eventDateTimeStart, _eventDateTimeEnd, _loopRules, _timezoneOffset, _lastChange) { + return ccn_api_dataTemplate( + '/api/calendar/update', + { + token: GetApiToken(), + uuid: _uuid, + belongTo: _belongTo, + title: _title, + description: _description, + eventDateTimeStart: _eventDateTimeStart, + eventDateTimeEnd: _eventDateTimeEnd, + loopRules: _loopRules, + timezoneOffset: _timezoneOffset, + lastChange: _lastChange + } + ); +} +function ccn_api_calendar_add(_belongTo, _title, _description, _eventDateTimeStart, _eventDateTimeEnd, _loopRules, _timezoneOffset) { + return ccn_api_dataTemplate( + '/api/calendar/add', + { + token: GetApiToken(), + belongTo: _belongTo, + title: _title, + description: _description, + eventDateTimeStart: _eventDateTimeStart, + eventDateTimeEnd: _eventDateTimeEnd, + loopRules: _loopRules, + timezoneOffset: _timezoneOffset + } + ); +} + +function ccn_api_calendar_delete(_uuid, _lastChange) { + return ccn_api_boolTemplate( + '/api/calendar/delete', + { + token: GetApiToken(), + uuid: _uuid, + lastChange: _lastChange + } + ); +} // ====================================================== collection +function ccn_api_collection_getFullOwn() { + return ccn_api_dataTemplate( + '/api/collection/getFullOwn', + { + token: GetApiToken() + } + ); +} +function ccn_api_collection_getDetailOwn(_uuid) { + return ccn_api_dataTemplate( + '/api/collection/getDetailOwn', + { + token: GetApiToken(), + uuid: _uuid + } + ); +} + +function ccn_api_collection_addOwn(_name) { + return ccn_api_dataTemplate( + '/api/collection/addOwn', + { + token: GetApiToken(), + name: _name + } + ); +} + +function ccn_api_collection_updateOwn(_uuid, _name, _lastChange) { + return ccn_api_dataTemplate( + '/api/collection/updateOwn', + { + token: GetApiToken(), + uuid: _uuid, + name: _name, + lastChange: _lastChange + } + ); +} + +function ccn_api_collection_deleteOwn(_uuid, _lastChange) { + return ccn_api_boolTemplate( + '/api/collection/deleteOwn', + { + token: GetApiToken(), + uuid: _uuid, + lastChange: _lastChange + } + ); +} + +function ccn_api_collection_getSharing(_uuid) { + return ccn_api_dataTemplate( + '/api/collection/getSharing', + { + token: GetApiToken(), + uuid: _uuid + } + ); +} + +function ccn_api_collection_deleteSharing(_uuid, _target, _lastChange) { + return ccn_api_dataTemplate( + '/api/collection/deleteSharing', + { + token: GetApiToken(), + uuid: _uuid, + target: _target, + lastChange: _lastChange + } + ); +} + +function ccn_api_collection_addSharing(_uuid, _target, _lastChange) { + return ccn_api_dataTemplate( + '/api/collection/addSharing', + { + token: GetApiToken(), + uuid: _uuid, + target: _target, + lastChange: _lastChange + } + ); +} + +function ccn_api_collection_getShared() { + return ccn_api_dataTemplate( + '/api/collection/addSharing', + { + token: GetApiToken() + } + ); +} // ====================================================== todo function ccn_api_todo_getFull() { - // return data or undefined - var gotten_data = undefined; - $.ajax({ - url: '/api/todo/getFull', - type: "POST", - async: false, - data: { + return ccn_api_dataTemplate( + '/api/todo/getFull', + { token: GetApiToken() - }, - success: function (data) { - gotten_data = data; } - }); - - if (IsResponseOK(gotten_data)) return gotten_data['data']; - else return undefined; + ); } function ccn_api_todo_add() { - // return data or undefined - var gotten_data = undefined; - $.ajax({ - url: '/api/todo/add', - type: "POST", - async: false, - data: { + return ccn_api_dataTemplate( + '/api/todo/add', + { token: GetApiToken() - }, - success: function (data) { - gotten_data = data; } - }); - - if (IsResponseOK(gotten_data)) return gotten_data['data']; - else return undefined; + ); } function ccn_api_todo_update(_uuid, _data, _lastChange) { - // return data or undefined - var gotten_data = undefined; - $.ajax({ - url: '/api/todo/update', - type: "POST", - async: false, - data: { + return ccn_api_dataTemplate( + '/api/todo/update', + { token: GetApiToken(), uuid: _uuid, data: _data, lastChange: _lastChange - }, - success: function (data) { - gotten_data = data; } - }); - - if (IsResponseOK(gotten_data)) return gotten_data['data']; - else return undefined; + ); } function ccn_api_todo_delete(_uuid, _lastChange) { - // return true or false - var gotten_data = undefined; - $.ajax({ - url: '/api/todo/delete', - type: "POST", - async: false, - data: { + return ccn_api_boolTemplate( + '/api/todo/delete', + { token: GetApiToken(), uuid: _uuid, lastChange: _lastChange - }, - success: function (data) { - gotten_data = data; } - }); - - return (IsResponseOK(gotten_data) && gotten_data['data']); + ); } // ====================================================== admin +function ccn_api_admin_get() { + return ccn_api_dataTemplate( + '/api/admin/get', + { + token: GetApiToken() + } + ); +} +function ccn_api_admin_add(_username) { + return ccn_api_dataTemplate( + '/api/admin/add', + { + token: GetApiToken(), + username: _username + } + ); +} + +function ccn_api_admin_update(_username, _password, _isAdmin) { + return ccn_api_dataTemplate( + '/api/admin/update', + { + token: GetApiToken(), + username: _username, + password: _password, + isAdmin: _isAdmin + } + ); +} + +function ccn_api_admin_delete(_username) { + return ccn_api_boolTemplate( + '/api/admin/delete', + { + token: GetApiToken(), + username: _username + } + ); +}