完成前端白名单开发同步更新开发文档

src/views/base/whitelist/index.vue

@@ -51,14 +51,6 @@
           <el-option label="停用" value="0" />
         </el-select>
       </el-form-item>
-      <el-form-item label="有效期" prop="validStatus">
-        <el-select v-model="queryParams.validStatus" placeholder="请选择有效期状态" clearable style="width: 180px">
-          <el-option label="有效" value="valid" />
-          <el-option label="未生效" value="not_started" />
-          <el-option label="已过期" value="expired" />
-          <el-option label="长期有效" value="long_term" />
-        </el-select>
-      </el-form-item>
       <el-form-item>
         <el-button type="primary" icon="Search" @click="handleQuery">搜索</el-button>
         <el-button icon="Refresh" @click="resetQuery">重置</el-button>
@@ -240,6 +232,7 @@
               <image-upload
                 v-model="form.faceImageUrl"
                 :limit="1"
+                :file-size="2"
                 @update:modelValue="handleIdentityInfoChange"
               />
               <div class="form-tip">用于机器人侧照片比对。建议上传清晰正脸照片。</div>
@@ -248,7 +241,6 @@
           <el-col :span="24">
             <el-form-item label="来源类型" prop="sourceType">
               <el-tag type="info">{{ formatSourceType(form.sourceType) }}</el-tag>
-              <div class="form-tip">来源类型由系统自动识别，运维后台新增和导入的数据默认为本地。</div>
             </el-form-item>
           </el-col>
           <el-col :span="24">
@@ -456,8 +448,7 @@ const data = reactive({
     idCardNo: undefined,
     whitelistType: undefined,
     sourceType: undefined,
-    status: undefined,
-    validStatus: undefined
+    status: undefined
   },
   rules: {
     name: [
@@ -577,7 +568,7 @@ function handleUpdate(row) {
 /** 启用/停用白名单 */
 function handleStatusChange(row, status) {
   const actionText = status === "1" ? "启用" : "停用"
-  proxy.$modal.confirm('确认' + actionText + '白名单人员"' + row.name + '"吗？').then(() => {
+  proxy.$modal.confirm('确认' + actionText + '白名单人员“' + row.name + '”吗？').then(() => {
     return updateWhitelist({
       ...row,
       status

迎宾巡逻安防机器人运维端Web管理系统详细设计开发文档_V2.1.html

@@ -150,15 +150,16 @@
     <h4>6.4.3 白名单管理页面</h4>
 <table><thead><tr><th>模块</th><th>详细设计</th></tr></thead><tbody>
 <tr><td>页面目标</td><td>维护可被机器人识别为可信人员的白名单数据，支持通过人脸照片、身份证号、手机号等信息进行白名单匹配。</td></tr>
-<tr><td>查询条件</td><td>姓名、手机号、身份证号、人员类型、来源类型、启用状态、有效期状态。</td></tr>
+<tr><td>查询条件</td><td>姓名、手机号、身份证号、人员类型、来源类型、启用状态。</td></tr>
 <tr><td>列表字段</td><td>姓名、手机号、身份证号、人员类型、是否有人脸照片、来源类型、有效期、启用状态、更新时间、操作。</td></tr>
-<tr><td>编辑字段</td><td>姓名（name）、人员类型（whitelistType，页面显示为"人员类型"）、手机号（mobile）、身份证号（idCardNo）、人脸照片（faceImageUrl）、来源类型（sourceType）、有效开始时间（validStartTime）、有效结束时间（validEndTime）、启用状态（status）、备注（remark）。</td></tr>
+<tr><td>编辑字段</td><td>姓名（name）、人员类型（whitelistType，页面显示为"人员类型"）、手机号（mobile）、身份证号（idCardNo）、人脸照片（faceImageUrl）、来源类型（sourceType，只读展示，不允许人工修改）、有效开始时间（validStartTime）、有效结束时间（validEndTime）、启用状态（status）、备注（remark）。</td></tr>
 <tr><td>人员类型</td><td>人员类型用于描述白名单人员身份，建议字典项为：内部人员、访客、VIP、其他。不建议将"人脸白名单"作为人员类型，因为人脸识别属于匹配方式，不属于人员身份类型。</td></tr>
 <tr><td>操作按钮</td><td>新增、编辑、删除、导入、导出、启用/停用。</td></tr>
-<tr><td>表单校验</td><td>姓名、人员类型、来源类型、启用状态必填；手机号、身份证号、人脸照片三者至少填写一种；有效结束时间如填写，必须大于有效开始时间。</td></tr>
-<tr><td>人脸照片规则</td><td>一期仅保存人脸照片地址（faceImageUrl），不保存人脸特征ID。机器人侧按照片进行人脸比对，后续如算法侧升级为特征库比对，再扩展相关字段。</td></tr>
+<tr><td>表单校验</td><td>姓名、人员类型、来源类型、启用状态必填；手机号、身份证号、人脸照片三者至少填写一种；手机号填写时需符合大陆手机号格式；身份证号填写时需符合 18 位身份证基础格式；有效结束时间如填写，必须大于有效开始时间。</td></tr>
+<tr><td>人脸照片规则</td><td>一期仅保存人脸照片地址（faceImageUrl），不保存人脸特征ID。机器人侧按照片进行人脸比对，建议上传清晰正脸照片；前端上传限制为 2MB，支持 png/jpg/jpeg 格式。</td></tr>
 <tr><td>匹配规则</td><td>白名单不设置单一识别方式字段。机器人或后端根据当前采集到的身份信息进行匹配：人脸识别时通过人脸照片比对；身份证读取或输入时匹配身份证号；手机号输入时匹配手机号。任一方式匹配到启用且在有效期内的白名单人员，即视为白名单命中。</td></tr>
-<tr><td>业务规则</td><td>本地录入、平台同步、机器人采集的数据统一进入白名单管理。后续如对接平台同步，可对平台同步数据增加只读限制或同步标识。</td></tr>
+<tr><td>业务规则</td><td>来源类型由系统自动识别，不允许用户手动修改。运维后台手动新增和导入的数据默认来源类型为 1=本地录入；主控平台同步数据由同步接口写入 2=平台同步；机器人端采集数据由机器人采集接口写入 3=机器人采集。列表中展示来源类型，查询区支持按来源类型筛选。</td></tr>
+<tr><td>有效期规则</td><td>有效开始时间为空表示立即生效；有效结束时间为空表示长期有效。列表中根据当前时间动态展示有效期状态：有效、未生效、已过期、长期有效。一期不提供有效期状态筛选条件。</td></tr>
 </tbody></table>
 
     <h3>6.5 监控管理</h3>
@@ -387,18 +388,20 @@
       <tr><td>/robot-ops/visitor/record/export</td><td>GET</td><td>导出访客记录</td><td>同分页查询条件</td><td>Excel文件</td><td>robot_ops_visitor_record</td></tr>
       <tr><td>/robot-ops/visitor/appointment/page</td><td>GET</td><td>预约记录分页</td><td>appointmentNo、visitorName、mobile、status、appointmentTimeStart、appointmentTimeEnd、pageNum、pageSize</td><td>appointmentNo、visitorName、mobile、visitedPerson、appointmentTime、status、syncTime</td><td>robot_ops_appointment_record</td></tr>
       <tr><td>/robot-ops/visitor/appointment/{id}</td><td>GET</td><td>预约详情</td><td>预约记录ID（id）</td><td>appointmentNo、visitorName、mobile、visitedPerson、appointmentTime、status、syncTime、sourcePlatform、remark</td><td>robot_ops_appointment_record</td></tr>
-      <tr><td>/robot-ops/visitor/whitelist/page</td><td>GET</td><td>白名单分页</td><td>姓名（name）、手机号（mobile）、身份证号（idCardNo）、人员类型（whitelistType）、来源类型（sourceType）、启用状态（status）、有效期状态（validStatus，可选）、pageNum、pageSize</td><td>白名单ID（id）、姓名（name）、手机号（mobile）、身份证号（idCardNo）、人员类型（whitelistType）、人脸照片地址（faceImageUrl）、是否有人脸照片（hasFaceImage）、来源类型（sourceType）、有效开始时间（validStartTime）、有效结束时间（validEndTime）、启用状态（status）、更新时间（updateTime）</td><td>robot_ops_whitelist</td></tr>
+      <tr><td>/robot-ops/visitor/whitelist/page</td><td>GET</td><td>白名单分页</td><td>姓名（name）、手机号（mobile）、身份证号（idCardNo）、人员类型（whitelistType）、来源类型（sourceType）、启用状态（status）、pageNum、pageSize</td><td>白名单ID（id）、姓名（name）、手机号（mobile）、身份证号（idCardNo）、人员类型（whitelistType）、人脸照片地址（faceImageUrl）、是否有人脸照片（hasFaceImage）、来源类型（sourceType）、有效开始时间（validStartTime）、有效结束时间（validEndTime）、启用状态（status）、更新时间（updateTime）</td><td>robot_ops_whitelist</td></tr>
       <tr><td>/robot-ops/visitor/whitelist/{id}</td><td>GET</td><td>白名单详情</td><td>白名单ID（id）</td><td>name、mobile、idCardNo、whitelistType、faceImageUrl、sourceType、validStartTime、validEndTime、status、remark</td><td>robot_ops_whitelist</td></tr>
-      <tr><td>/robot-ops/visitor/whitelist</td><td>POST</td><td>新增白名单</td><td>name、mobile、idCardNo、whitelistType、faceImageUrl、sourceType、validStartTime、validEndTime、status、remark</td><td>新增ID（id）</td><td>robot_ops_whitelist</td></tr>
-      <tr><td>/robot-ops/visitor/whitelist</td><td>PUT</td><td>编辑白名单</td><td>id、name、mobile、idCardNo、whitelistType、faceImageUrl、sourceType、validStartTime、validEndTime、status、remark</td><td>无</td><td>robot_ops_whitelist</td></tr>
+      <tr><td>/robot-ops/visitor/whitelist</td><td>POST</td><td>新增白名单</td><td>name、mobile、idCardNo、whitelistType、faceImageUrl、sourceType、validStartTime、validEndTime、status、remark；运维后台新增时 sourceType 默认传 1，表示本地录入</td><td>新增ID（id）</td><td>robot_ops_whitelist</td></tr>
+      <tr><td>/robot-ops/visitor/whitelist</td><td>PUT</td><td>编辑白名单</td><td>id、name、mobile、idCardNo、whitelistType、faceImageUrl、sourceType、validStartTime、validEndTime、status、remark；sourceType 由系统自动维护，前端只读展示，不允许用户手动修改</td><td>无</td><td>robot_ops_whitelist</td></tr>
 <tr><td>/robot-ops/visitor/whitelist/{id}/status</td><td>PUT</td><td>启用/停用白名单</td><td>白名单ID（id）、启用状态（status）</td><td>无</td><td>robot_ops_whitelist</td></tr>
       <tr><td>/robot-ops/visitor/whitelist/{id}</td><td>DELETE</td><td>删除白名单</td><td>白名单ID（id）</td><td>无</td><td>robot_ops_whitelist</td></tr>
-      <tr><td>/robot-ops/visitor/whitelist/import</td><td>POST</td><td>导入白名单</td><td>Excel文件（file）；导入字段包括姓名、人员类型、手机号、身份证号、人脸照片地址、来源类型、有效开始时间、有效结束时间、启用状态、备注</td><td>导入总数、成功数、失败数、失败明细；导入时需校验 mobile、idCardNo、faceImageUrl 三者至少填写一种</td><td>robot_ops_whitelist</td></tr>
+      <tr><td>/robot-ops/visitor/whitelist/import</td><td>POST</td><td>导入白名单</td><td>Excel文件（file）；导入字段包括姓名、人员类型、手机号、身份证号、人脸照片地址、有效开始时间、有效结束时间、启用状态、备注；运维后台导入的数据 sourceType 默认写入 1，表示本地录入</td><td>导入总数、成功数、失败数、失败明细；导入时需校验 mobile、idCardNo、faceImageUrl 三者至少填写一种；手机号和身份证号需校验格式</td><td>robot_ops_whitelist</td></tr>
       <tr><td>/robot-ops/visitor/whitelist/export</td><td>GET</td><td>导出白名单</td><td>同分页查询条件</td><td>Excel文件；导出字段包括姓名、手机号、身份证号、人员类型、人脸照片地址、来源类型、有效开始时间、有效结束时间、启用状态、更新时间、备注</td><td>robot_ops_whitelist</td></tr>
     </tbody></table>
     <div class="note">白名单中的 whitelistType 字段在页面上显示为"人员类型"，用于表示人员身份，如内部人员、访客、VIP、其他。人脸识别不作为人员类型，而是白名单匹配方式之一。</div>
     <div class="note">白名单不单独设置识别方式字段。机器人侧可根据当前采集到的身份信息匹配白名单：人脸识别时通过 faceImageUrl 对应的人脸照片进行比对；刷身份证或输入身份证时匹配 idCardNo；输入手机号时匹配 mobile。任一方式匹配到启用且在有效期内的白名单人员，即视为白名单命中。</div>
-    <div class="note">新增或编辑白名单时，mobile、idCardNo、faceImageUrl 三者至少填写一种；一期不保存人脸特征ID。</div>
+    <div class="note">新增或编辑白名单时，mobile、idCardNo、faceImageUrl 三者至少填写一种；手机号填写时需符合大陆手机号格式，身份证号填写时需符合 18 位身份证基础格式；一期不保存人脸特征ID。</div>
+    <div class="note">来源类型 sourceType 使用 RuoYi 字典 source_type，当前字典值为：1=本地录入，2=平台同步，3=机器人采集。sourceType 由系统自动赋值，运维后台新增和导入默认写入 1；主控平台同步写入 2；机器人采集写入 3。前端新增/编辑弹窗中只读展示来源类型，不允许人工选择。</div>
+    <div class="note">有效期状态由前端根据 validStartTime、validEndTime 和当前时间动态展示，不作为一期分页查询参数。</div>
 
     <h3>7.6 监控管理接口</h3>
     <table><thead><tr><th>接口</th><th>方法</th><th>说明</th><th>请求参数</th><th>返回/处理字段</th><th>数据库表</th></tr></thead><tbody>
@@ -704,7 +707,7 @@
   `id_card_no` VARCHAR(50) DEFAULT NULL COMMENT '身份证号',
   `whitelist_type` VARCHAR(50) DEFAULT NULL COMMENT '人员类型字典值，如internal内部人员、visitor访客、vip VIP、other其他',
   `face_image_url` VARCHAR(255) DEFAULT NULL COMMENT '人脸照片地址，用于机器人侧照片比对',
-  `source_type` VARCHAR(50) DEFAULT NULL COMMENT '来源类型：local本地录入，platform平台同步，robot机器人采集',
+  `source_type` VARCHAR(50) DEFAULT NULL COMMENT '来源类型字典值：1本地录入，2平台同步，3机器人采集',
   `valid_start_time` DATETIME DEFAULT NULL COMMENT '有效开始时间，不填表示立即生效',
   `valid_end_time` DATETIME DEFAULT NULL COMMENT '有效结束时间，不填表示长期有效',
   `status` CHAR(1) NOT NULL DEFAULT '1' COMMENT '启用状态：0停用，1启用',
@@ -722,6 +725,7 @@
     <div class="note">说明：whitelist_type 当前页面显示为"人员类型"，用于描述人员身份，不表示识别方式。建议字典项为 internal=内部人员、visitor=访客、vip=VIP、other=其他。</div>
     <div class="note">说明：白名单不设置 recognition_type / auth_type 字段，因为同一人员可同时支持人脸照片、身份证号、手机号多种匹配方式。机器人侧根据实际采集到的信息选择对应字段进行匹配。</div>
     <div class="note">说明：一期不建设 face_feature_id 字段。当前人脸白名单采用照片比对方式，仅保存 face_image_url。</div>
+    <div class="note">说明：source_type 使用 RuoYi 字典 source_type，当前字典项为 1=本地录入、2=平台同步、3=机器人采集。运维后台新增和导入的数据默认写入 1，平台同步和机器人采集数据由对应接口写入。</div>
 
     <h3>8.4 监控与日志表</h3>
     <h4>8.4.1 远程喊话记录表 robot_ops_shout_record</h4>