-
Notifications
You must be signed in to change notification settings - Fork 3
/
Copy pathDESIGN.html
259 lines (250 loc) · 12.2 KB
/
DESIGN.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no">
<title>筋斗云产品设计</title>
<style type="text/css">code{white-space: pre;}</style>
<link rel="stylesheet" href="doc/style.css" />
<link rel="stylesheet" href="doc/doc.css" />
<script src="doc/doc.js"></script>
</head>
<body>
<h1 id="筋斗云产品设计">筋斗云产品设计</h1>
<p>本文档分 <strong>主体设计</strong> 与 <strong>专题设计</strong> 两大部分. 每块设计一般包括以下部分:</p>
<dl>
<dt>概要设计</dt>
<dd>简述需求, 定义概念/术语, 简述实现方式.
</dd>
<dt>数据库设计</dt>
<dd>定义数据库表及字段
</dd>
<dt>交互接口</dt>
<dd>定义前端访问后端的API接口
</dd>
<dt>前端应用接口</dt>
<dd>定义前端应用接口或应用内的页面.
</dd>
</dl>
<p>参考文档：</p>
<ul>
<li><a href="doc/后端框架.html">后端框架：关于数据库设计、通讯协议设计、测试设计的惯例</a></li>
<li><a href="doc/index.html">技术文档目录</a></li>
</ul>
<div id="TOC" class="toc">
<ul>
<li><a href="#筋斗云产品设计">筋斗云产品设计</a><ul>
<li><a href="#概要设计"><span class="toc-section-number">1</span> 概要设计</a><ul>
<li><a href="#主要用例"><span class="toc-section-number">1.1</span> 主要用例</a></li>
<li><a href="#系统建模"><span class="toc-section-number">1.2</span> 系统建模</a></li>
</ul></li>
<li><a href="#数据库设计"><span class="toc-section-number">2</span> 数据库设计</a></li>
<li><a href="#交互接口设计"><span class="toc-section-number">3</span> 交互接口设计</a><ul>
<li><a href="#客户端"><span class="toc-section-number">3.1</span> 客户端</a><ul>
<li><a href="#用户信息修改"><span class="toc-section-number">3.1.1</span> 用户信息修改</a></li>
<li><a href="#订单管理"><span class="toc-section-number">3.1.2</span> 订单管理</a></li>
</ul></li>
<li><a href="#员工端后台管理端"><span class="toc-section-number">3.2</span> 员工端/后台管理端</a><ul>
<li><a href="#员工管理"><span class="toc-section-number">3.2.1</span> 员工管理</a></li>
<li><a href="#订单管理-1"><span class="toc-section-number">3.2.2</span> 订单管理</a></li>
</ul></li>
</ul></li>
<li><a href="#前端应用接口"><span class="toc-section-number">4</span> 前端应用接口</a><ul>
<li><a href="#移动客户端appuser"><span class="toc-section-number">4.1</span> 移动客户端(app=user)</a></li>
<li><a href="#管理端appemp-adm"><span class="toc-section-number">4.2</span> 管理端(app=emp-adm)</a></li>
<li><a href="#超级管理端appadmin"><span class="toc-section-number">4.3</span> 超级管理端(app=admin)</a></li>
</ul></li>
<li><a href="#后端内部接口"><span class="toc-section-number">5</span> 后端内部接口</a></li>
</ul></li>
<li><a href="#专题设计">专题设计</a><ul>
<li><a href="#用户登录"><span class="toc-section-number">1</span> 用户登录</a></li>
<li><a href="#附件与上传"><span class="toc-section-number">2</span> 附件与上传</a></li>
<li><a href="#运营统计"><span class="toc-section-number">3</span> 运营统计</a></li>
</ul></li>
</ul></div>
<h2 id="概要设计"><span class="header-section-number">1</span> 概要设计</h2>
<h3 id="主要用例"><span class="header-section-number">1.1</span> 主要用例</h3>
<p>定义用户使用本系统的主要场景。用于指导<a href="#系统建模">系统建模</a>和<a href="#交互接口设计">交互接口设计</a>。</p>
<p>系统主要用例见下图：</p>
<div class="figure">
<img src="doc/pic/usecase.dio.png" />
</div>
<h3 id="系统建模"><span class="header-section-number">1.2</span> 系统建模</h3>
<p>定义系统数据模型，描述基本概念。用于指导<a href="#数据库设计">数据库设计</a>。</p>
<p>系统核心概念及关系见下图：</p>
<div class="figure">
<img src="doc/pic/datamodel.dio.png" />
</div>
<h2 id="数据库设计"><span class="header-section-number">2</span> 数据库设计</h2>
<p>根据<a href="#系统建模">系统建模</a>设计数据库表结构。</p>
<p>参考<a href="doc/后端框架.html#数据库设计">后端框架-数据库设计</a>查看定义表及字段类型的基本规则.</p>
<p>【系统配置项】</p>
<p><span class="citation">@Cinf</span>: id, name(s), value(t)</p>
<ul>
<li>name: 配置项名。由应用定义。下面文档中将使用<code>Cinf.xxx</code>来定义各配置项，比如<code>Cinf.version</code>表示name为"version"的配置项。</li>
</ul>
<p>【员工】</p>
<p><span class="citation">@Employee</span>: id, uname, phone(s), pwd, name(s), perms</p>
<p>雇员表, 登录后可用于查看和处理业务数据。</p>
<ul>
<li>uname: 用于登录的用户名，不可数字开头。</li>
<li>phone: 员工手机号，也可用于登录，数字开头。</li>
<li>pwd: 登录密码，采用md5加密。</li>
<li><p>perms: EnumList. 角色列表，多个角色以逗号分隔，如"mgr", "emp,mgr"。</p>
<pre><code>emp: 管理员/AUTH_EMP
mgr: 最高管理员/PERM_MGR</code></pre></li>
</ul>
<p>【用户】</p>
<p><span class="citation">@User</span>: id, uname, phone(s), pwd, name(s), createTm</p>
<ul>
<li>uname: 用于登录的用户名，不可数字开头。</li>
<li>phone: 员工手机号，也可用于登录，数字开头。</li>
<li>pwd: 登录密码，采用md5加密。</li>
<li>createTm: 创建时间。</li>
</ul>
<p>【订单】</p>
<p><span class="citation">@Ordr</span>: id, userId, createTm, status(2), amount, dscr(l), cmt(l)</p>
<dl>
<dt>vcol</dt>
<dd>userName, userPhone, <span class="citation">@orderLog</span>?/订单日志OrderLog, <span class="citation">@atts</span>?/订单图片OrderAtt
</dd>
</dl>
<ul>
<li><p>status: Enum. 订单状态。</p>
<pre><code>CR: 新创建
RE: 已服务
CA: 已取消
其它备用值:
PA: 已付款(待服务)
ST: 开始服务
CL: 已结算</code></pre></li>
<li><span class="citation">@orderLog</span>: [{id, action, dscr, ...}]. 日志子表, 关联表OrderLog</li>
<li><p><span class="citation">@atts</span>: [{id, attId}]. 订单图片，关联表OrderAtt</p></li>
</ul>
<p>注意：使用ordr而不是order是为了避免与sql关键字order冲突</p>
<p>【订单日志】</p>
<p><span class="citation">@OrderLog</span>: id, orderId, action, tm, dscr, empId</p>
<p>例如：某时创建订单，某时付款等。</p>
<ul>
<li><p>action: 参考订单状态(Ordr.status)。可用值参考：</p>
<pre><code>CR: Create (订单创建，待付款)
PA: Pay (付款，待服务)
RE: Receive (服务完成, 待评价)
CA: Cancel (取消订单)
RA: Rate (评价)
ST: StartOrder (开始服务)
CT: ChangeOrderTime (修改预约时间)
AS: Assign (分派订单给员工)
AC: Accept (员工接单)
CL: Close (订单结算)</code></pre></li>
<li><p>empId: 操作该订单的员工号</p></li>
</ul>
<p>【订单-图片关联】</p>
<p><span class="citation">@OrderAtt</span>: id, orderId, attId</p>
<p>【API调用日志】</p>
<p><span class="citation">@ApiLog</span>: id, tm, addr, ua(l), app, ses, userId, ac, t&, retval&, req(t), res(t), reqsz&, ressz&, ver, serverRev(10)</p>
<ul>
<li><p>app: Enum。存储请求的<code>_app</code>参数，常见值：</p>
<pre><code>emp-adm: 电脑管理端(web/index.html)
user: 移动客户端(m2/index.html)</code></pre></li>
<li>ua: userAgent，用于区分客户端类型和版本</li>
<li>ses: 会话标识(HTTP session id)</li>
<li>t: 执行时间(单位：ms)</li>
<li><p>ver: 客户端版本。</p>
<pre><code>web: 表示通用网页(通过ua可查看明细浏览器)
wx/{ver}: 表示微信版本如"wx/6.2.5"
a/{ver}: 表示安卓客户端及版本如"a/1"
ios/{ver}: 表示苹果客户端版本如"ios/15".</code></pre></li>
</ul>
<p><span class="citation">@ApiLog1</span>: id, apiLogId, ac, t&, retval&, req(t), res(t)</p>
<p>batch操作的明细表。</p>
<p>【操作日志】</p>
<p><span class="citation">@ObjLog</span>: id, obj, objId, dscr, apiLogId, apiLog1Id</p>
<p>【插件相关】</p>
<pre><code>@include server\plugin\login\DESIGN.md
@include server\plugin\upload\DESIGN.md</code></pre>
<h2 id="交互接口设计"><span class="header-section-number">3</span> 交互接口设计</h2>
<p>本章根据<a href="#主要用例">主要用例</a>定义应用客户端与服务端的交互接口。关于通讯协议基本规则，可参考<a href="doc/后端框架.html#通讯协议设计">后端框架-通讯协议设计</a>。</p>
<h3 id="客户端"><span class="header-section-number">3.1</span> 客户端</h3>
<p>app类型为"user".</p>
<h4 id="用户信息修改"><span class="header-section-number">3.1.1</span> 用户信息修改</h4>
<pre><code>User.set()(name, ...)</code></pre>
<ul>
<li>权限: AUTH_USER</li>
<li>可修改字段参考User表。注意不可修改字段: uname, phone, pwd, createTm.</li>
</ul>
<p>【示例】</p>
<p>上传一个头像并设置到该用户：</p>
<pre><code>upload(type=user, genThumb=1)(content of picture)
(得到thumbId)
User.set()(pidId={thumbId})</code></pre>
<h4 id="订单管理"><span class="header-section-number">3.1.2</span> 订单管理</h4>
<pre><code>添加订单
Ordr.add()(Ordr表字段) -> id
查看订单
Ordr.query/get() -> tbl(id, status, ..., @orderLog?)</code></pre>
<ul>
<li>权限: AUTH_USER</li>
<li>添加订单后, 订单状态为"CR"; 且在OrderLog中添加一条创建记录(action=CR)</li>
<li>不允许删除订单（可以取消）。</li>
</ul>
<h3 id="员工端后台管理端"><span class="header-section-number">3.2</span> 员工端/后台管理端</h3>
<p>本节API需要员工登录权限。 app类型为"emp".</p>
<h4 id="员工管理"><span class="header-section-number">3.2.1</span> 员工管理</h4>
<pre><code>Employee.query()
Employee.get(id?)
Employee.set(id?)(POST fields)</code></pre>
<ul>
<li>权限: AUTH_EMP</li>
<li>get/set操作如果不指定id, 则操作当前登录的员工。仅当具有 PERM_MGR 权限时, 可任意指定id.</li>
<li>query操作：如果没有PERM_MGR权限只能获取当前登录的员工，否则可获取所有的员工。</li>
</ul>
<p>以下仅当PERM_MGR权限可用：</p>
<pre><code>Employee.add()(POST fields)
Employee.del(id?)</code></pre>
<ul>
<li>当Employee被其它对象（如Ordr）引用时，不允许删除，只能做禁用等其它处理。</li>
</ul>
<h4 id="订单管理-1"><span class="header-section-number">3.2.2</span> 订单管理</h4>
<p>查看订单</p>
<pre><code>Ordr.query
Ordr.get</code></pre>
<p>完成订单或取消订单</p>
<pre><code>Ordr.set(id)(status=RE)
Ordr.set(id)(status=CA)</code></pre>
<ul>
<li>权限：AUTH_EMP</li>
<li>订单状态必须为"CR"才能完成或取消.</li>
<li>更新操作应生成相应订单日志(OrderLog).</li>
</ul>
<h2 id="前端应用接口"><span class="header-section-number">4</span> 前端应用接口</h2>
<p>定义应用入口及调用参数。每一个应用均应明确定义一个惟一的app代码。</p>
<h3 id="移动客户端appuser"><span class="header-section-number">4.1</span> 移动客户端(app=user)</h3>
<pre><code>m2/index.html</code></pre>
<p>用户登录, 可以创建和查看订单等.</p>
<h3 id="管理端appemp-adm"><span class="header-section-number">4.2</span> 管理端(app=emp-adm)</h3>
<pre><code>web/store.html</code></pre>
<p>员工登录, 可以查看和管理订单等.</p>
<h3 id="超级管理端appadmin"><span class="header-section-number">4.3</span> 超级管理端(app=admin)</h3>
<pre><code>web/adm.html</code></pre>
<p>使用超级管理员帐号登录.</p>
<h2 id="后端内部接口"><span class="header-section-number">5</span> 后端内部接口</h2>
<p>会话变量：</p>
<ul>
<li>用户登录
<ul>
<li>uid: 用户编号</li>
</ul></li>
<li>员工登录
<ul>
<li>empId: 员工编号</li>
</ul></li>
</ul>
<h1 id="专题设计">专题设计</h1>
<h2 id="用户登录"><span class="header-section-number">1</span> 用户登录</h2>
<p>参考插件login <span class="citation">@include</span> server.md</p>
<h2 id="附件与上传"><span class="header-section-number">2</span> 附件与上传</h2>
<p>参考插件upload <span class="citation">@include</span> server.md</p>
<h2 id="运营统计"><span class="header-section-number">3</span> 运营统计</h2>
</body>
</html>