本文档分 主体设计 与 专题设计 两大部分. 每块设计一般包括以下部分:
参考文档:
定义用户使用本系统的主要场景。用于指导[系统建模]和[通讯协议设计]。
系统用例图.
定义系统数据模型,描述基本概念。用于指导[数据库设计]。
系统类图或ER图.
根据[系统建模]设计数据库表结构。
参考doc/后端框架文档的"数据库设计"部分查看定义表及字段类型的基本规则.
[数据库信息]
@Cinf: version, createTm, upgradeTm
产品配置信息表.
[员工]
@Employee: id, uname, phone(s), pwd, name(s), perms
雇员表, 登录后可用于查看和处理业务数据。
[用户]
@User: id, uname, phone(s), pwd, name(s), createTm
[订单]
@Ordr: id, userId, status(2), amount, dscr(l), cmt(l)
注意:
[订单日志]
@OrderLog: id, orderId, action, tm, dscr, empId
例如:某时创建订单,某时付款等。
CR:: Create (订单创建,待付款) PA:: Pay (付款,待服务) RE:: Receive (服务完成, 待评价) CA:: Cancel (取消订单) RA:: Rate (评价) ST:: StartOrder (开始服务) CT:: ChangeOrderTime (修改预约时间) AS:: Assign (分派订单给员工) AC:: Accept (员工接单) CL:: Close (订单结算)
[订单-图片关联]
@OrderAtt: id, orderId, attId
[附件]
@Attachment: id, path, orgPicId, exif(t), tm
{"DateTime": "2015:10:08 11:03:02", "GPSLongtitude": [121,42,7.19], "GPSLatitude": [31,14,45.8]}
路径使用以下规则: upload/{type}/{date:YYYYMM}/{randnum}.{ext}
例如, 商家图片路径可以为 upload_store/201501/101.jpg. 用户上传的某图片路径可能为 upload/201501/102.jpg
[API调用日志]
@ApiLog: id, tm, addr, ua(l), app, ses, userId, ac, t&, retval&, req(t), res(t), reqsz&, ressz&, ver
[密码字典]
@Pwd: id, pwd, cnt&
[插件相关]
@include server/plugin/*/DESIGN.wiki
本章根据[主要用例]定义应用客户端与服务端的交互接口。关于通讯协议基本规则,可参考文档后端框架 -> 通讯协议设计章节。
注意:对于注册、登录、修改密码这些操作,客户端应使用HTTPS协议与服务端通信以确保安全。参考[HTTPS服务]章节。
genCode(phone, type?="d6", debug?) -> {code?}
根据手机号后台生成验证码。1分钟内不允许重复发送(除非设置了debug参数)。 手机号要求11位数字.
[权限]
[参数]
[返回]
[示例]
请求
genCode(phone=13712345678)
成功时无返回内容。
[示例]
请求
genCode(phone=13712345678, debug=1)
返回
{code: 123456}
用户注册与登录共享同一个API. 请参考“登录”章节。
login(uname, code)
login(uname, pwd/code, wantAll?) -> {id, _token, _expire, _isNew?} login(token, wantAll?) -> (与得到该token的登录返回相同内容, 但不包括_token, _expire, _isNew字段).
该API根据当前app类型确定是用户或雇员或管理员登录(apptype分别为user, emp, admin)。支持用户名密码、用户名动态口令、token三种登录方式。
对于用户登录,如果code验证成功, 但手机号不存在, 就以该手机号自动注册用户, 密码为空(由于登录时密码不允许空,所以空密码意味着无法用密码登录)。
客户端登录页建议逻辑如下:
User.get
查看是否已登录,是则直接进入主页;否则如果有token,则尝试用login(token)
登录。
User.set
或chpwd(oldpwd=_none,pwd)
, 注意:pwd字段在新注册后1小时内可免认证修改。
后端逻辑:
[参数]
[返回]
其它User表字段。
为支持自动重登录, 以上除login(token)外所有login接口都返回以下字段:
[示例]
用户登录
login(uname=13012345678, pwd=1234)
管理员登录
login(uname=liang, pwd=liang123, _app=admin)
logout(_app?, force?)
删除session, 注销当前登录的用户。如果未登录过会报错.
[权限]
[参数]
chpwd(oldpwd|code?, pwd, _app?) -> {_token, _expire}
服务端需要先验证当前密码(oldpwd)或动态验证码正确, 然后才能修改为新密码;
仅当新注册时1小时内,可以免认证直接修改密码。
建议使用HTTPS通讯以保证安全.
[权限]
[参数]
[返回]
[示例]
请求
chpwd(oldpwd=1234, pwd=12345678) 或 chpwd(code=533114, pwd=12345678) (之前生成了动态验证码为533114)
User.set([id])(fields...)
字段fields请参考"User"表定义. 原理请参考"通用表操作"章节。
应用逻辑:
[权限]
[示例]
上传一个头像并设置到该用户:
upload(type=user, genThumb=1)(content of picture) (得到thumbId) User.set()(pidId={thumbId})
更新用户手机号:
User.set()(phone=18912345678)
app类型为"user".
使用Ordr.add/set/query/get方法添加、修改、查询和查看订单。 不允许删除订单(可以取消)。
注: 订单状态定义请在本文档内搜索OrderStatus.
Ordr.add()(Ordr表字段) -> id
应用逻辑:
[参数]
[返回]
操作成功时返回新添加的订单id.
[示例]
Ordr.query() -> tbl(id, status, ...) Ordr.get(id) -> {id, status, ..., @orderLog, @atts}
用Ordr.query
取用户所有订单概要;
用Ordr.get
取订单主表字段及其相关子表.
[权限]
[参数]
[返回]
主表返回字段请查询表定义"@Ordr"。
本节API需要员工登录权限。 app类型为"emp".
Employee.get(id?) Employee.set(id?)(POST fields)
如果不指定id, 则操作当前登录的员工. 如果指定id:
Employee.query(cond?)
Employee.add()(POST fields) Employee.del(id?)
查看订单
Ordr.query() -> tbl(id, status, 参考Ordr表字段...) Ordr.get(id) -> { 同query字段 }
完成订单或取消订单
Ordr.set(id)(status=RE) Ordr.set(id)(status=CA)
[权限]
本节API需要超级管理员权限.
app类型为adm.
定义应用入口及调用参数。每一个应用均应明确定义一个惟一的app代码。
m2/index.html
用户登录, 可以创建和查看订单等.
web/store.html
员工登录, 可以查看和管理订单等.
web/adm.html
使用超级管理员帐号登录.