docs: 增加文档

Change-Id: Ic52b02e89c54f15a9f57e52356f55bce732a7723

show/api_pos.php

@@ -25,6 +25,11 @@ if(strlen($s1) > 2000) {
 	$s1 = substr($s1, 0, 2000).'..';
 }
 
+// 于请求中获取了serialno、remote_addr信息
+// 通过serialno从数据库中获取了设备信息，在顶层中获取了记录id、company_id、dining_hall_id和channel_id信息
+// 并于请求的POST参数中获取了sign和其他详细信息
+// 同时将记录插入到日志中
+
 // 插入POS机日志记录
 $db->query("insert into tb_pos_device_log set device_id = {$device_id}, serialno = '".addslashes($serialno)."', ip = '".addslashes($ip)."', path = '".addslashes($qs)."', request = '".addslashes($s1)."', response = '', addtime = now() ");
 $log_id = $db->insert_id();
@@ -46,6 +51,7 @@ if($sign2 !== $post['sign']) { //签名错误
 }
 
 // 将api和data数据处理编码后插入到tb_pos_device_log表，并终止脚本运行
+// 回应时填充参数、返回的API接口数据、错误提示等。
 function response_pos($api, $data) {
 	global $deviceInfo, $post, $log_id, $db;
 	$noncestr = md5(microtime().'_'.rand());
@@ -117,47 +123,62 @@ function pos_check_user() {
 // 顶层代码，判断qs中参数
 if($qs == 'heartbeat' || $qs == 'addperson' || $qs == 'delperson') { //心跳
 	// 新增人员
+	// 设备收到服务器心跳包响应需要执行人员增加之后，向服务器发送设备增加名单完成应答接口
 	if($qs == 'addperson' && $post['whitelist']) {
-
+		// 循环遍历人员名单
 		foreach($post['whitelist'] as $item) {
+			// 将account_id中的yzms_前缀去掉
 			$uid = intval(str_replace('yzms_', '', $item['account_id']));
+			// 获取记录
 			$rec_id = intval($item['rec_id']);
+			// 更新用户设备表中对应记录rec_id和对应用户uid的状态，status=2表示确认增加成功
 			$db->query("update tb_pos_device_user set status=2,rs='".$item['result_code']."' where id = '{$rec_id}' and uid = '{$uid}'");
 		}
 	}
 	// 删除人员
 	if($qs == 'delperson' && $post['whitelist']) {
-
+		// 循环遍历人员名单
 		foreach($post['whitelist'] as $item) {
+			// 从account_id中去掉yzms_前缀
 			$uid = intval(str_replace('yzms_', '', $item['account_id']));
+			// 获取记录id
 			$rec_id = intval($item['rec_id']);
 			$db->query("delete from tb_pos_device_user where id = '{$rec_id}' and uid = '{$uid}'");
 		}
 	}
 
-	// 心跳
+	// 如果当前查询并非心跳，或者当前时间和设备的synctime差超过1分钟，则执行
 	if($qs != 'heartbeat' || (time() - strtotime($deviceInfo['synctime']) > 60)) { //1分钟检测一次用户同步
 
+		// 更新posdevice表的同步时间
 		$db->query("update tb_pos_device set synctime=now() where id = ".$device_id);
 	
-
+		// 从tb_user表中获取所有启用且属于公司公司的用户列表，
 		$userList_s = $db->get_all("select id, username, cellphone, deptname from tb_user where enabled = '1' and company_id = '{$company_id}'");
+		// 从tb_pos_device_user表中获取对应用户设备信息
+		// 新版Android取餐机，宇航用于下发人脸、用户信息到Android取餐机用的记录表，方便知道每台机现在的同步情况
 		$userList_d = $db->get_all("select * from tb_pos_device_user where device_id = '{$device_id}'");
 
+		// tb_user_face和tb_user表关联，获取对应信息
 		$data = $db->get_all("select a.* from tb_user_face a, tb_user b where a.user_id=b.id and b.company_id = '{$company_id}'");
 		$faceInfo = array();
+		// 提取上一步得到的关联信息并添加到faceInfo数组中，判断此文件是否存在于服务器后台目录，存在则将item信息存进dict数据中，key是user_id，value是item	
 		foreach($data as $item) {
 			if(is_file("../backstage/".$item['path'])) {
 				$faceInfo[$item['user_id']] = $item;
 			}
 		}
 
+		// 关联用户表和用户id卡表，获取信息
 		$data = $db->get_all("select a.* from tb_user_idcard a, tb_user b where a.user_id=b.id and b.company_id = '{$company_id}' and a.state=1 order by a.id");
 		$cardInfo = array();
+		// 提取上一步获取的信息并将数据循环加入到卡信息数组中，类似List[Dict]，key是user_id，value是item
 		foreach($data as $item) {
 			$cardInfo[$item['user_id']] = $item;
 		}
 
+		// 从获取的该公司user_list表信息中循环遍历，获取对应用户id的facecode,path,cardno信息，添加到userList_s数组中
+		// 最终facecode,path和cardno作为用户设备需要下发的信息添加到userList_s中
 		foreach($userList_s as $key => $item) {
 			$uid = $item['id'];
 			$info1 = $faceInfo[$uid];
@@ -169,28 +190,40 @@ if($qs == 'heartbeat' || $qs == 'addperson' || $qs == 'delperson') { //心跳
 		}
 
 		$sUserInfo = array();
+		// 遍历更新完成的userList_s中数据，存入sUserInfo数组中，key是用户id，value是对应的item信息
+		// ["id1" => {xx}, "id2" => {xx}, "id3" => {xx}]
 		foreach($userList_s as $item) {
 			$sUserInfo[$item['id']] = $item;
 		}
 
 		$dUserInfo = array();
+		// 遍历获取的tb_pos_device_user表，即用户设备表，将其数据通过循环变为uid => item数据的数组
+		// 最终得到uid => item信息的数组
 		foreach($userList_d as $item) {
 			$dUserInfo[$item['uid']] = $item;
 		}
 		
+		// 从全局配置表中获取域名，需要注意新版表中将class字段更改成了name字段
 		$row = $db->get_one("select * from tb_config where class = 'HOST'");
+		// 设置域名
 		$host = $row['value'];
 
+
 		$addList = array(); //增加列表
 		$maxcount = 100;
+		// 遍历用户表
 		foreach($userList_s as $item) {
 			$uid = $item['id'];
+			// 设备用户表不存在对应用户的信息
 			if(!$dUserInfo[$uid]) {
+				// 往数组末尾添加一个item
 				$addList[] = $item;
 				if(count($addList) >= $maxcount) break; //限制一次20个
 				continue;
 			}
+			// 设备表的用户信息
 			$item2 = $dUserInfo[$uid];
+			// 如果设备用户表的记录和用户表的记录不一致
 			if(
 				($item2['facecode'].'') !== ($item['facecode'].'') 
 				|| ($item2['cardno'].'') !== ($item['cardno'].'') 
@@ -198,12 +231,15 @@ if($qs == 'heartbeat' || $qs == 'addperson' || $qs == 'delperson') { //心跳
 				|| ($item2['cellphone'].'') !== ($item['cellphone'].'') 
 				|| ($item2['deptname'].'') !== ($item['deptname'].'')
 			) {
+				// 则将item加到addList末尾
 				$addList[] = $item;
 				if(count($addList) >= $maxcount) break;
 				continue;
 			}
 
+			// 设备用户表的status为1，表示已下发增加，但还未收到确认，并且距上次下发5分钟后还没收到确认
 			if($item2['status'] == 1 && time()-strtotime($item2['sendtime']) > 300) { //距上次下发5分钟后还没收到确认
+				// 增加item到addList
 				$addList[] = $item;
 				if(count($addList) >= $maxcount) break;
 				continue;
@@ -216,21 +252,26 @@ if($qs == 'heartbeat' || $qs == 'addperson' || $qs == 'delperson') { //心跳
 			foreach($addList as $item) {
 				$uid = $item['id'];
 				$face_url = '';
+				// 拼接人脸路径
 				if($item['facepath']) {
 					$face_url = 'https://'.$host.'/backstage/'.$item['facepath'];
 				}
 
 				$row1 = $db->get_one("select * from tb_pos_device_user where device_id = '".addslashes($device_id)."' and uid = '".addslashes($uid)."'");
+				// sql拓展字符串
 				$sqlext = " name = '".addslashes($item['username'])."', cellphone = '".addslashes($item['cellphone'])."', deptname = '".addslashes($item['deptname'])."', cardno = '".addslashes($item['cardno'])."', facecode = '".addslashes($item['facecode'])."', sendtime = now(), status = 1, rs = '' ";
+				// 如果用户设备表中没有对应设备id和用户id的数据
 				if(!$row1) {
+					// 插入记录
 					$db->query("insert into tb_pos_device_user set device_id = '".addslashes($device_id)."', uid = '".addslashes($uid)."', {$sqlext}, addtime = now() ", 'SILENT');
 					$log_id1 = $db->insert_id();
 				} else {
+					// 有则更新
 					$db->query("update tb_pos_device_user set {$sqlext} where id=".$row1['id']);
 					$log_id1 = $row1['id'];
 				}
 				
-
+				// 人员名单
 				$whitelist[] = array (
 				  'rec_id' => $log_id1.'',	//可为数据库中的唯一id，可以是字符串，可以是整数，可为空字符
 				  'account_id' => 'yzms_'.$uid, //帐号，唯一，50个字符，必填
@@ -262,6 +303,7 @@ if($qs == 'heartbeat' || $qs == 'addperson' || $qs == 'delperson') { //心跳
 			  'whitelist' => $whitelist,
 			);
 			
+			// 响应增加人员的api，向设备回送数据，往设备增加人员信息
 			response_pos('addperson', $arr);
 			exit;
 		}
@@ -275,19 +317,25 @@ if($qs == 'heartbeat' || $qs == 'addperson' || $qs == 'delperson') { //心跳
 		foreach($userList_d as $item) {
 			$uid = $item['uid'];
 
+			// status为4，表示已下发删除
 			if($item['status'] == 4) {
 				if(time()-strtotime($item['sendtime']) > 300) { //距上次下发删除5分钟后还没收到确认
+					// 错误次数小于3
 					if($item['err_num'] < 3) {
+						// 更新用户设备表错误次数
 						$db->query("update tb_pos_device_user set sendtime = now(), status = 4, rs = '',err_num=err_num+1 where id=".$item['id']);
+						// 追加删除列表
 						$delList[] = $item;
 						if(count($delList) >= $maxcount) break; //限制一次20个
 					} else {
+						// 错误次数大于等于3，直接删除记录
 						$db->query("delete from tb_pos_device_user where id=".$item['id']);
 					}
 				}
 				continue;
 			}	
 
+			// 不在用户表中，添加item到删除列表
 			if(!$sUserInfo[$uid]) {
 				$delList[] = $item;
 				if(count($delList) >= $maxcount) break; //限制一次20个
@@ -295,6 +343,7 @@ if($qs == 'heartbeat' || $qs == 'addperson' || $qs == 'delperson') { //心跳
 			}
 		}
 
+		// 数据更新完成，开始删除列表
 		if($delList) {
 			$whitelist = array();
 			foreach($delList as $item) {
@@ -314,23 +363,29 @@ if($qs == 'heartbeat' || $qs == 'addperson' || $qs == 'delperson') { //心跳
 			  'whitelist' => $whitelist,
 			);
 			
+			// 删除人员
 			response_pos('delperson', $arr);
 			exit;
 		}
 
 	}
 
+	// 记录
 	$records = $post['records'];
 	$arr = array (
 	  'setmname' => '',
 	);
+	// 如果有记录
 	if($records) {
 		$records2 = array();
+		// 遍历记录并将record的记录变成"id" => realid，加入到record2中
+		// like: [[id => 1], [id => 2], [id => 3]...]
 		foreach($records as $item) {
 			$records2[] = array('id' => $item['id']);
 		}
 		$arr['records'] = $records2;
 	}
+	// 服务器向设备回送心跳包，包括记录
 	response_pos('heartbeat', $arr);
 
 } 
@@ -503,7 +558,6 @@ else if($qs == 'real') {
 			  'sign' => '',
 			  'Corrections' => '',
 			)
- 
 		  ),
 		  'title' => '云中美食',
 		  'emp_fname' => $uInfo['username'],
@@ -542,6 +596,7 @@ else if($qs == 'real') {
 			exit;
 		}
 
+		// 服务器向本机/api/usr/qrpay接口发送数据
 		$s = self_query("/api/user/qrpay", $post);
 		$rs = json_decode($s, true);
 		if($rs['status'] != 1) {