更新记录

1.0.0（2026-11-15）

首次发布

• 新增 bear-card-ocr：拍照或从相册选图，端侧离线识别 身份证（正/反）、驾驶证（主页/副页）、行驶证（主页/副页）、车牌号、车架号（VIN）、网约车驾驶员证、网约车运输证 共 7 类证件，回结构化字段、逐字段置信度、OCR 原文与证件四角点。
• 三端底层链路：Android 用 ML Kit 内置中英模型（text-recognition-chinese，离线）、iOS 用系统 Vision、HarmonyOS 用系统 Core Vision Kit；识别结果再走同一份三端共享的版面规则（card-rules.uts / card-fields.uts / card-parse.uts），关键字段带格式校验（身份证校验位、车牌格式、VIN 校验位）。
• scanCard 取景识别：Android（CameraX）与 iOS（AVFoundation）为扫描式取景，带实时边缘检测引导框、稳定后自动拍摄、裁剪摆正并回矫正图路径；HarmonyOS 拉系统相机拍一张，拍完即识别——插件按识别到的文字外接框把图轴对齐裁到内容再识别一遍，两遍结果取字段多的一份，产出的那张图落进应用沙盒作为 imagePath 返回，可直接再传 recognizeCard；该端没有透视矫正、没有实时边缘检测、没有「确认 / 保存」页，也没有扫描张数上限，captureBy 恒为 manual，liveEdgeSupported 回 false、correctSupported 回 true。
• recognizeCard 支持相册与本机图片路径，maxSide 可主动降采样提速；warmup / releaseEngine 管理引擎句柄；getEnvInfo 同步回本端引擎与能力位。
• 身份证号码解析容错：按 GB 11643 加权因子校验，兼容校验位缺失/单字符误识（O→0、I/L→1 等）、号码被空格或折行拆开的形态；姓名取值在标签与值挤行、下一行是「性别男」等污染场景下不再误取，仍可从邻近整行回收姓名。
• 版面锚点兼容 OCR 字间空格（「姓 名」「准 驾 车 型」「注 册 日 期」）与标签被拆成相邻两行；中文字段取值上限由 8 字放宽到 32 字，长单位名不再截断。
• 行驶证补齐车辆类型、品牌型号、发动机号码（放宽到 24 位）、注册日期与发证日期；驾驶证准驾车型兼容「C1, E」「A1 A2」与单字母 D/E/F/M/N/P；网约车驾驶员证补有效起始日期与有效期限，网约车运输证补座位、车辆尺寸与有效期至。
• 车牌号与车架号兼容逐字空格、圆点分隔与 O/I/Q 形近误识，车牌独立识别不再因排版空格回 9080006。
• 中英对照版式（驾驶证、行驶证）容错：OCR 把英文翻译标签和真值并到一处时（「姓名 Name 陈保」「准驾车型 Class」+ 下一行「C1 E」）会自动裁掉英文段，取值不再被 Name/Class/Address 占位；短锚点命中长标签时残留的标签尾巴（「准驾」命中「准驾车型」剩「车型」）也不再被当成值；准驾车型进一步兼容逐字插空格「C 1 E」与数字 1 误读成 I/L 的「CI」。
• 驾驶证发证机关（红色印章）补齐：印章名常被切成「广东省广州」「市公安局交」「通警察支队」这类多段短行，现在收齐所有机关名分段、按行政级别纠正倒置行序、按接缝重叠拼成完整机关名（「广东省广州市公安局交通警察支队」），不再只回其中一段；拼不出合法结尾（…支队/大队/局/厅）时不猜、不出该字段，工作区域/住址类行也不会被误拼进来。国籍只认带「国」的字样，避免姓名区失读的残片被当成国籍。
• 行驶证主页四列版式取值修正：标签行与值行纵向交错时（「使用性质」「品牌型号」同排、各自的值在下一行），按行框取同一排紧贴标签右边缘的值行，不再串到隔壁列；补齐所有人（标签被拆成「所有」+ 值）、住址（标签拆成「住」+「址：…」、去分隔符）、发动机号码、注册日期与新增的发证机关字段（红章分段拼装）。
• 车牌号在车牌与右邻英文标签被压掉空格粘成一段时也能取出（「浙G046321VEHICLETYPE」回「浙G046321」）。
• scanCard 对 plate / vin 不再按卡片处理：这两类没有卡片外形，三端都不画证件框、不做边缘检测与透视矫正。Android / iOS 取景界面只留预览、快门与相册入口；HarmonyOS 直接拉系统相机拍一张，快门落下就进识别（该端仍会按文字外接框裁到内容）。此时 captureBy 恒为 manual。
• Android 取景兼容性：部分机型/相机 HAL 拼不出「预览 + 拍照 + 分析」的 surface 组合时，不再直接以 init 失败——先降级为「预览 + 拍照」（保留快门与相册，按中央引导区矫正），只有降级后仍绑不上才失败；失败回包与控制台日志带上原生异常因果链、机型和系统版本，便于定位。targetRotation 在 Android 11 以下改走 windowManager.defaultDisplay（Activity.getDisplay() 是 API 30 才有），取景界面搭建中的异常也收口成 init 回包而不是闪退。
• Android 拍照取景的内存与线程收口：拍到的原图先按长边 2000 降采样再摆正/矫正（相机 24MP/48MP 原图原来要解 96–192MB，摆正再拷一份很容易把宿主打死）；解码、摆正、透视矫正、压缩全部移出主线程，主线程只做会话收口。检测框越界/无分析帧时退回中央引导区；透视矫正先裁到框的外接矩形再投影，并给矫正图长宽比设上限，避免歪框把变换后的位图边界拉飞。
• 识别完成后在控制台按 name=value(置信度) 逐项打印本次识别出的全部字段（[bear-card-ocr] 识别字段 …），并打印引擎回的全部 OCR 行及行框（[bear-card-ocr] OCR 行 …），三端口径一致。
• 行驶证「使用性质」按国标分类兜底：标签被反光/印章读歪、或四列版式里标签行与值行错位时，不再直接漏字段——先在全图找 预约出租客运 / 非营运 / 货运 等封闭分类词，命中即回标准写法；客远「营远」这类 远/运 形近误读统一归一为「客运」「营运」。
• 网约车运输证补齐三处实拍常见的缺口：证号（该版式不印「运输证号」标签，号码在标题下「浙交运管许可 义字 … 号」行里，按含「交运管 / 许可」的整行+同排续块取 9–22 位数字串）、座位（「座」与「位：5座」被拆成同一排两块，按行框拼回标签再取值）、有效期至与发证日期（红章压住「日」时引擎只读到「2029年06」，整日期取不到就退到 yyyy-MM）；「经营区域」文案按证件原文改为「经营范围」，证号字段名同步为「运输证号」。
• 车辆尺寸里的 4602mmX1825mmX1496mm 不再被滑窗当成车架号（同一段连读出现两次 mm 的整段判掉）。
• 网约车驾驶员证姓名的另一种失读形态：鸿蒙把「姓」与「名：张平」拆成两块、且「姓」整块没被识别出来时，锚点与同行拼接都落空，现在按「名」+分隔符+值的整行兜底取值（「名称」这类正文不会误取）。
• 网约车驾驶员证的有效起始日期与有效期限改用与运输证同一套日期降级：红章压住「日」时回 yyyy-MM（「有效起始日期:2026年08月」），连月也压掉只剩「2048年0」时回 yyyy，不再整条字段消失。
• 日期解析越界闪退修复：文本里只有「年 + 月」两段数字（红章压住日的常见形态）时，整日期解析会多读一位数字导致 IndexOutOfBoundsException 崩溃；越界判断改为按三段数字的实际长度收口，该输入现在安全降级为 yyyy-MM。
• 身份证性别的挤行失读：OCR 把「性别」「民族」压成「性男民族汉」时，按「性」后单字回收性别；证件横躺（照片里文字竖排）时住址按列邻接取值——同列下方是值、左/右相邻列是续行，「湖南省永兴县湘阴渡镇滩」+「头村江边组」不再只回前半段。
• 倒置拍摄（照片里证件上下颠倒）：装配时按「证件标题行落到图像下半区」判定并镜像回正行框；同时 Android / iOS 桥接层按 180° 朝向把同一张图再识别一遍（只改朝向、不拷贝位图，第二遍失败或为空时回第一遍），倒置字形的数字互串、标签读成乱码与长地址丢行明显减少。倒置驾驶证现在能取回姓名、证号、出生日期、住址、有效期与发证机关。
• 证号防误拼：身份证号码候选的「全图数字段串接」不再任意滑窗——真号码读坏后的碎片错位拼接也能凑出加权校验通过的 18 位，现在只从某个段的开头起拼，出生年份还限制在 1900–2100，不再吐出新造的假证号。
• 准驾车型补相邻行兜底：倾斜/倒置实拍里 C1 会被排到「准驾车型」标签正上方、横向间隔超出同行判定上限，现在锚点取空时补看紧邻的上下各一行。
• 住址只回单字残片（「组」「村」）时不出该字段，避免把折行残片当成完整住址。
• 行驶证安卓实拍防误判：英文标题不再被当成车架号（VIN 必须含数字，纯字母段不参与形近字纠正）；「所有人」下方若是隔壁列标签（「整备质量」被读成「整各质量」）不再回填；车牌省简称被读成形近字也能救回（「院AAP1866」→「皖AAP1866」），并兼容繁体「号牌号碼」标签；发动机号纯数字少于 6 位按截断残片丢弃。
• VIN 校验位修复与单字符纠错：ISO 3779 加权表原来对不上真实 VIN（字母对应值串错位、第 8 位权重 10 压不进字符串表），任何真车架号都过不了校验；现在按显式数组对齐，G↔6、S↔5、B↔8、Z↔2、D↔0 形近单字符误读按校验位找回唯一候选（校验位本身不参与替换），候选不唯一时不纠、按原读数低置信回。
• VIN 候选收集合并：锚点行段、全图行段、同一行内被空格拆开的两/三段拼接段（拉丁模型常把 17 位车架号读成「L6XCE6CB 3NO231743」两段）、去空格段一次性并进同一次检索，让校验位与形近纠错在全部候选上裁决，不再被第一条检索路径的兜底读数挡住；注册/发证日期行拼出的 18 位串不再被滑窗当成车架号兜底（滑窗候选只信校验位直判，整段恰好 17 位的读数才可兜底）。
• 使用性质吞字容错：红章/反光把「预约出租客运」读成「约出租客」时，按国标词表做「词内缺字」匹配回标准写法，不再把残片原样回出去。
• Android 行驶证双模型并行识别：中文模型之外同时跑 ML Kit 拉丁模型（同一张 InputImage 并行调用，拉丁模型创建失败时静默退回中文单模型），两路 OCR 行按行框坐标合并去重后再走同一份版面规则；倒置拍摄时两个模型一起按 180° 重跑。中文模型读不稳的车架号、注册日期、发证日期由拉丁模型补回（实拍样张 LGXCE6CB3NO231743 归一为 LGXCE6CB3N0231743，两个日期原样取回），其余证件仍只走中文模型。
• 行驶证注册日期/发证日期标签容错：标签被读成「建册期」「往册期」「发正日期」等形近形态时按同排的一对日期取值（注册在前、发证在后，只读到单个日期时不回，分不清归属宁缺勿错），不再整条字段消失；「一对日期」再放宽到「四位年 + 分隔符 + 4 位月日」（2022-0612）、中文年月日与「年 + 分隔 + 2 位月 + 分隔 + 2 位日」形态，同排另一个模型补读的断头日期也能配成对。
• 行驶证车牌跨行拼装：号牌号码标签行只剩省份简称或残片、完整车牌落在同排后续行时（拉丁模型读数与中文读数分行），先收齐同排行、再分两趟找省份简称与 7 位字母数字段拼装（行集按 y 排序后字母段可能排在省简称行之前），拼出的车牌过车牌格式校验且候选唯一才回，不再整条字段消失。
• 行驶证车辆类型按国标词表纠错：GA 802 常用车型词表内单字符误读（「小型餐车」→「小型轿车」）且修复候选唯一时回纠错值，词表外的读数原样透传不猜。
• Android / iOS 倒置判定不再依赖证件占满画面：先看版面是否整体颠倒（标题/顶部标签「姓名」「号牌号码」「档案编号」落在底部标签「有效期限」「注册日期」「公民身份号码」下方），判不出再退回原来的标题行位置口径；证件没铺满照片、带背景桌面与底部水印时也能按 180° 重跑第二遍，倒置驾驶证的证号、出生日期、住址与有效期不再整片丢失。
• 驾驶证实拍（倒置、点阵字体）补齐五处：住址锚点兼容「生址」「使址」形近误读，折行续行的单字「组」不再被丢弃；初次领证日期被读成「2815年」时按 0→6/8/9 纠回 2015 年后仍要通过 1900–2100 区间校验，不再回不可信年份；有效期限起点被读丢（「2073 # 2031-07-13」）时从断头日期后回收 2031-07-13 作为有效期至；发证机关行尾黏着「车型」标签、「交通」的「通」被读成「透」时，截到机关名结尾词并把「…交」后的「透」纠回「通」，仍回完整机关名；国籍接受繁体「中國」与 CHN，准驾车型兼容「Cl」，姓名锚点落空时不再把英文子标签「Sex」裁出的「ex」当成姓名。
• 网约车驾驶员证补齐出生日期、国籍、住址三个字段（字段追加，原有字段不变）：标签串被引擎挤成「姓性出国住」一行、真值行只剩「别:男」「籍:中国」「址:江西省…」这类单字标签尾巴时仍能取值；出生日期优先从校验通过的证号回推。有效期只读到「2054年0月08日」（月位被章压成 0）时仍按精度降级回 2054，不猜月份。
• 身份证号码单字符纠错：18 位里只有一位被引擎认成别的数字时（安卓实拍驾驶证「431023198302615112」应为「431023198302015112」），按 GB 11643 加权校验、出生日期合法、省级区划前缀三段约束找回唯一候选；候选不唯一或没有候选一律不出该字段，不猜号码。
• 性别由证号奇偶回推：身份证、驾驶证、网约车驾驶员证的「性别」被红章/反光遮住或读成残片时，改用校验通过的 18 位证号第 17 位奇偶回推男/女（奇为男、偶为女），以 0.6 置信度出字段；证号本身校验不过时不出，不猜性别。
• 年份单字符纠错：初次领证日期、有效期限的年份被读成「2616-11」这类 0↔6/8/9 单字符误读时，按唯一候选纠回 2016-11，纠完仍要过 1900–2100 区间校验；需要改两位以上（「2073」→「2016」）的读数不纠、按原值低置信回或直接不出。
• 准驾车型逐字歧义收口：拉丁模型把数字 1 读成小写 l / 大写 I 时（「ClD」），只在整串唯一可解的情况下按 I/l→1 归一，回 C1,D；歧义候选不唯一时原样透传，不猜车型组合。
• 车牌形近归一与假命中防护：按 GA 36（车牌字母表不含 I/O）把读数里的 O→0、I→1 归一，「粤ABYO388」回「粤ABY0388」；行驶证副页「检验有效期至…月豫」这类行尾的省份简称不再被当成车牌起点，不再产出「豫E20250」这种假车牌。
• 车牌序号字母数上限：7/8 位形态的序号最多容忍 2 个字母（实拍里「粤ABY0388」被读成「學ABYE388」，截短成「粤ABYE38」也是错的），3 个及以上一律不出该字段，不猜哪个字母其实是数字。
• 行驶证副页号牌也走跨行拼装，省份形近表补「学→粤」（繁体「學」先经归一表换成简体）：副页号牌被读成两路（「學ABYE388」+「ABYO388」）、任一路单独都不合法时，用同排的省简称拼另一路干净的 7 位段，回「粤ABY0388」；拼装结果同样要过格式校验且候选唯一。跨行拼装用的省简称必须紧跟发牌字母才算车牌上下文，「臺研以3835」里的「台」后面是汉字，不再被拼成「台GAT3835」。
• 行驶证副页补「检验有效期至」字段（checkValidity，按年月精度出值）：这一行常被印章压成「1024 年06 月」「205 年62 月」这类断字，读不出合法年月就不出字段，不补数字。
• 车牌形态表补全专用尾缀号牌（GA 36）：「省简称 + 发牌字母 + 4 位序号 + 警/学/挂/消/应急/港/澳」也是合法号牌，此前只有 7/8 位主体能过校验，「粤A1234挂」这类 6 位主体整条落空；尾缀字保留在输出值里（裁掉尾缀就是另一块牌），没有尾缀的 6 位主体仍判不合法。普通 7 位、新能源 8 位两种主体形态不变。
• 车牌号不再依赖「号牌号码」标签读到：改按 GA 36 形态在全图直出，三条路径由强到弱——逐行形态直读 → 全文拼串直读 → 同排省简称与序号段拼装。标签是小号印刷字，实拍里常被读成「農号码」「牌号码」「,曾号码,」「号牌码」，锚点一落空整块牌就丢了，而号牌本身是证件上最大的字；实拍主页「農号码苏AV593 车辆类型…」+「BBAV5903」两行现在拼回「苏BAV5903」。同一张图里出现多个不同号牌读数时按「被更多行支持 → 版面更靠上」取舍（号牌号码总在版面第一行，别的号牌读数只出现在更下面的检验记录/备注里），仍并列就不出；省简称读丢、序号读糊的仍然只交空值，一个字符都不补。行驶证主页/副页、车牌独立识别、网约车运输证四处共用这套取值。
• 网约车运输证座位回收：「座」与「位：5座」被引擎拆成同一排两块时（标签只剩「座经」），按值行自带的「位…座」后缀回收载人数，不再整条字段消失。
• 网约车驾驶员证有效期至按年龄上限出清：出生日期来自校验通过的证号时，「有效期至」年份超过出生年份 100 年以上的读数（红章把「20」压成「25」造出「2086」）直接不出该字段，不回不可信年份。
• 行驶证主页四列版式取值修正：标签行被 OCR 框得很矮时（「车辆类型」行高只有 35px），原来按两倍标签高设的横向间隔上限会连本列的值行一起拒掉、退到隔壁列取到省份简称（「车辆类型=粵」）；现在上限按「标签行高 + 值行高」给，值行回到自己那一列。
• 网约车驾驶员证「证号」标签被裁掉时按身份证号回收：这一证的证号就是持证人 18 位身份证号（实拍三张样本逐位相同），标签行读不到号码、但身份证行读得到且过 GB 11643 加权校验时用它补上「证号」；号码本身不猜，校验不过不出。
• 网约车驾驶员证 / 运输证的「核发机关」标签直读形态也过一遍机关名收口：压掉串内空白与拉丁/标点残片、再截到机关名结尾词，「惠州市 运输局如/」回「惠州市运输局」；结尾词后还有「交/通/公/警/车」这类没写完的机关词时不截，完整机关名原样保留，裁的都是已读到的字符、不补字。
• 行驶证「车辆类型」标签整块读糊时按国标词表直读：iOS 把小号标签读成「焦类想才」，锚点取不到值而「小型轿车」本身就在 OCR 行里，整条字段消失。现在取到的值先按 GA 802 词表校正（命中词表回标准写法），值为空才退全图逐行扫词表；词表外的读数（「瞭员為」）原样透传不猜，与「使用性质」同一兜底口径。
• 行驶证注册日期/发证日期同排两枚一起归位：末排两个标签全读歪时（「注册日期」→「照品N」、「发证日期」→「品N」）锚点和列分界都建不起来，现在自下而上找同一行里连着两枚日期的行，按左右顺序归位为注册/发证（含「至/到」的区间行跳过，认不出谁是谁就不回）。宽松扫描另修两处：年份的 6/8/9→0 纠错只在这行确实带日期分隔符时才做，一次没配上只前进一位（「2.2023-07-04」这类前缀粘杂数的读数不再整枚跳过）。
• uni 风格 API：options 入参 + success / fail / complete，返回 void；错误码段位 9080，序号 009 固定为「当前平台不支持」。
• 案例页只两块，上下排列：上面主操作区（选证件类型与面 + 一个「从相册选图识别」按钮），下面结果主视区；样式全部走行内 :style（鸿蒙不把页面级 css 打进包）；环境探测、首次识别前预热、onUnload 释放引擎均在代码里静默自动执行。
• 案例页结果区底下补一张「送入引擎的图」：相册选图选完就显示原图（识别失败也在），按 widthFix 宽度铺满、高度等比，整张图完整可见，逐项字段与图上的印刷值直接对照；路径原样列在图下，便于定位是哪张图。
• 案例页正 / 反面切换状态修复：面 chips 的高亮判定写成 chipStyle(side)，与类型 chips 共用「等于当前类型 或 等于当前面」一个条件，结果是「正面 / 主页」和「反面 / 副页」永远同时高亮，点哪个都看不出变化。现在改按 item.value == side 逐项判定；再点当前证件类型不再把面悄悄重置回正面、也不再清掉这一轮结果，换面或换类型才清空上一轮字段，并在结果区首行写明当前选的是哪一面。
• 相机权限由插件取景界面自查自申，宿主无需预授予；相册走系统选择器，不申请相册权限；鸿蒙端取景由系统相机进程持有相机与权限（cameraPicker），插件不申请相机权限。
• iOS 端解析层可编译性收口：版面规则四份共享文件（card-rules / card-fields / card-parse / core）此前只过了 Android 与鸿蒙的原生编译，iOS 侧 Swift 类型检查有 47 处不通过——单参 substring 的 NSNumber/Int 重载、number 上的一元负号、CardLine 字段隐式解包后进运算退化成可选、跨函数原地 push/赋值形参数组、超长字符串拼接表达式类型推断超时。现全部改成三端一致写法（tailFrom/tailChars/textLen/neg/absNum/maxNum/minNum 收口，行几何走 lineX/lineY/lineW/lineH/lineText 取值函数，候选记账表在函数内本地建后一次算完），iOS 与 Android 出同一批字段、同一套取值口径。云端另有本地复现不出的一处：倒置判定里 const frameHeight : number = payload.height 这种「带类型标注、由接口字段初始化」的中间变量再参与除法时，云端生成 frameHeight! / 2、变量本身已是非可选 NSNumber，报 cannot force unwrap value of non-optional type 'NSNumber'；改为直接对 payload.height 运算后不再有这一步。
• 证号/身份证号的单字符纠错改按原始字符位定位坏位：iOS 把数字 0 读成字母 O、1 读成 I/l 时，原来的纠错只在校验失败后把整段压成纯数字再逐位试，串里带字母就整条落空（实拍驾驶证证号「43O223I99002276534」两个坏位、只补回一个也过不了校验）。现在先在原始字符位上找「唯一的非数字位」，该位逐一代入 0–9 直到加权校验通过；纯数字的坏位只在「全图逐位试探有且只有一种解」时才补，多解说明猜不出是哪个字符，宁可不补。字母坏位能定位到具体字符位，因此不受「唯一解」限制；17 位段（缺校验位）按 GB 11643 补算校验位那一路不变。
• 身份证姓名的版面兜底：标签整列没读到时，锚点、同行拼接、邻近整行三条路全落空而姓名值本身就在 OCR 行里（iOS 实拍「吴汉钊 / 男 / 1990 年 11 月 20 日…」只剩值行、「姓客李家劲」标签第二字读糊）。现在补两条只在身份证正面生效的取值：① 行首是「姓」+ 一个非「名」的字、后面紧跟 2–4 个汉字，按这段汉字取值（停止词照旧截断，值里夹数字或标点就不取）；② 某行整行是 2–4 个汉字且紧邻下一行正好是单字「男」或「女」——版面里姓名永远压在性别之上，全图只允许出现一处这种候选，两处说明位置证据不唯一，宁缺勿错不出字段。置信度按 0.5 / 0.4 出，低于锚点命中，业务侧可当待确认值处理。驾驶证的姓名缺口是引擎把字形读坏（「鄧水雄」→「無間煲蛋」），不做同类兜底。
• iOS 端非正立拍摄的朝向重试与失败取证：VNImageRequestHandler 的 orientation 形参只影响 Vision 怎么摆正字形，横躺拍摄按 .up 认等于让它认竖排字，中文标签整列糊成乱码、版面锚点一条挂不上就整单 9080006（实拍行驶证主页/副页倒置两张、网约车两证横躺两张就是这个形态）。现在主遍读不出来时按行框与文本换朝向再认：过半行框是竖条（高 > 1.5 倍宽）判横躺，试 .right/.left；标签一个都没命中且版面上下关系也判不出倒置时，试 .down/.right/.left；取「标签命中行最多」的那遍，且要求不少于 2 行并严格多于主遍才采纳，换朝向把已有字段换掉不如不换。两道止损：短边不足 300px 的缩略图（糊的是分辨率不是朝向）不重试；剩余预算不够一遍 accurate 档（约 2.5s）就停手，免得把结果换成 9080007 超时。重试采纳横躺朝向时回传的宽高同步互换，行框与图尺寸保持同一口径。另外 9080006 失败路径现在也打「引擎图尺寸 + 全部 OCR 行及行框」，倒置/旋转样本失败后能离线回放版面原貌，不再只剩一句「识别出 N 行」。
• 网约车驾驶员证 / 运输证的「有效起始日期」不再被止期行顶掉：四字段锚点允许一个汉字错位，有效期起/有效期自 会容错命中「有效期限:2032年…」这行止期标签，而本类版式是「有效起始日期 / 有效期限」两行分开，于是把止期年份当成了 validFrom（实拍 Android 回 validFrom=2032、真值 2026-01-07）。现在起期取值多一道归属校验：命中的行里必须真印着起始标签，否则退回严格起始锚点重取；重取落空就按「有效期开始」原口径不出该字段（运输证仍按发证日期兜底），宁缺毋滥不猜日期。同图 validTo 走的是精确「有效期限」锚点，取值不变。
• 倒置判定升级为「版面上下关系优先」（共享解析层，三端同时生效）：旧口径只看标题行中心有没有越过画面中线，实拍常带桌面、水印与留白，证件只占画面一角时倒置的标题未必落到下半区。现在先比两行的纵向顺序——标题行（读不到就退到「姓名 / 号牌号码 / 档案编号 / 签发机关 / 运输证号」这类必然印在卡片首行的字段）与「有效期限 / 注册日期 / 公民身份号码 / 记录」这类必然印在下部的字段，上沿反而压在下沿之下就是转了 180°；两类锚点凑不齐一组才退回旧的标题启发式。回放两端真机行集：整体转 180° 后判出的张数 Android 6→14、iOS 8→16，且这些行集镜像回正后解析出的字段与正立那遍逐项一致（0 张出入）；正立行集新旧两版输出逐字节相同，无回归。共享层新增的三个顶层声明与 app-android/ocr.kt 里的同名判定错开命名——共享层顶层声明会被转译进同一个 Kotlin 包，与手写桥接文件撞名就是 conflicting declarations。
• 鸿蒙端补朝向重试与失败取证：textRecognition 没有朝向入参（Android 是 InputImage.fromBitmap(bitmap, 180)、iOS 是 VNImageRequestHandler 的 orientation），非正立拍摄在本端只能把图真转过来再认一遍。现在主遍之后按判据补认：版面判出倒置试 180°；过半行框是竖条（高 > 1.5 倍宽）判成横躺，试 90° / 270°；两个判据都不成立但一个字段都没解析出来，说明标签整列读糊了、朝向只剩试出来，三档都试（触发面同 iOS，Android 只有 180° 那一遍）。旋转走 DecodingOptions.rotate 从同一个 ImageSource 再解一张——PixelMap.rotateSync 改的是手里这张，而整图那张要留着兜底与出图。采纳门槛是字段数严格多于当前这遍，换平维持原结果；采信旋转这一遍之后 sourceWidth / sourceHeight、内容裁剪的 region 与落盘的 imagePath 一并换到旋转后的口径（90° / 270° 宽高互换），行框与图尺寸保持同一坐标系。两道止损：短边不足 300px 的缩略图不重试（糊的是分辨率不是朝向），剩余时间不够再认一遍（留 2.5s）就停手，宁可少试一档朝向也不把已读到的字段拖成 9080007。另外 9080006 失败路径现在也打「引擎图尺寸 + 全部 OCR 行及行框」，此前本端失败只剩一句「识别出 N 行」，倒置 / 横躺样张的版面原貌离线回放不出来。

平台兼容性

uni-app(4.75)

uni-app x(4.75)

其他

bear-card-ocr

拍照或从相册选一张证件图，端侧离线按指定的证件类型解析出结构化字段：身份证（正/反）、驾驶证（主页/副页）、行驶证（主页/副页）、车牌号、车架号（VIN）、网约车驾驶员证、网约车运输证。支持 Android、iOS、HarmonyOS，全程不联网、不上传图片。

相机权限由插件的取景界面自查自申，宿主无需预授予。收费插件，普通授权与源码授权两档，权利边界见 license.txt。

兼容性

三端都纯端侧执行、不发起网络请求，也不依赖任何在线 OCR 服务。uni-app 与 uni-app-x 共用同一份原生实现，最低版本一致。运行环境：HBuilderX 4.44+、uni-app / uni-app-x 4.75+。数值与 package.json 矩阵、各端 config.json 逐项一致。

验收口径：uni-app（vue2 与 vue3）与 uni-app-x 工程，在 Android / iOS / HarmonyOS 三端真机跑通案例页全部能力。

使用前提

1. 三端都要用自定义基座验收。UTS 插件不参与标准基座，直接「运行到手机或模拟器」跑标准基座会缺实现。Android 还多一层：config.json 声明了 ML Kit 的文字识别与 CameraX 的 Maven 依赖，本地标准基座不解析这类依赖，会在生成的 index.kt 报 找不到名称“androidx” / “com.google”；云端自定义基座与本地离线打包（HBuilderX 配好 SDK / Gradle）都能解析。iOS 与 HarmonyOS 走系统框架，无此症状。
2. 相机权限不需要宿主预授予：scanCard 的取景界面进入时自查自申；Android 的 CAMERA 与 iOS 的 NSCameraUsageDescription 随插件声明，文案与真实用途一致。相册选图由 uni.chooseImage 与系统选择器负责，插件不申请相册权限。HarmonyOS 端取景是系统相机（cameraPicker），由系统相机进程持有相机与权限，插件不申请 ohos.permission.CAMERA。
3. scanCard 三端形态不同：Android / iOS 是插件内置的取景界面，有实时证件框引导、稳定后自动拍摄（autoCapture: false 改为手动快门）、内置相册入口，成功后回裁剪摆正图路径 imagePath；captureBy 为 edge 或 manual。HarmonyOS 直接拉系统相机拍一张（恒为手动快门、没有引导框、也没有图库入口，autoCapture / enableAlbum 不生效），拍完即识别：插件按识别到的文字外接框把图轴对齐裁到内容，再识别一遍，两遍结果取字段多的一份，裁（或没裁）的那张图落进沙盒当 imagePath 回给业务；没有透视矫正、没有确认/保存页、也没有扫描张数上限。plate / vin 两类不按卡片处理：三端都不画证件框、不做边缘检测与透视矫正，拍照即识别。业务侧按 getEnvInfo().liveEdgeSupported / correctSupported 决定界面文案（鸿蒙为 false / true）。要相册识别请用 recognizeCard 配 uni.chooseImage。
4. 一次只跑一个识别或取景：上一次未结束（含取景界面打开中）再次调用返回 9080004，需要连续识别请等上一次回调。
5. cardType 必填且必须准确：指定后只按该证件的版面规则解析，不做「全类型自动判型」（7 类证件靠 OCR 文本判型容易误判）。图片与指定类型明显不符时，识别有文字但命中不了锚点，回 9080006。
6. path 只接受本机可读路径：支持 _doc/、_downloads/、_temp/、沙盒相对路径、file:// 前缀，以及 HarmonyOS 上 uni.chooseImage 直接回到的媒体库 URI（file://media/...，整条透传给系统文件接口，无需先 uni.saveFile）。网络地址不支持，读不到字节时回 9080003，errMsg 会给出展开后的本机绝对路径（HarmonyOS 还同时带出入参原文）。
7. HarmonyOS 的两条硬限制：该端引擎只在国内正规真机可用，模拟器与海外机型会在初始化阶段回 9080002；该端对送入图有接口级尺寸判定（短边 ≥ 100、宽 ≤ 10000、高 ≤ 15210），下限越界回 9080003 且无法放大，只能换更大的图或离近重拍；上限越界不会失败，插件在解码时按 sampleSize 自动降到限内，maxSide 只是业务主动提速的开关。
8. 非正立拍摄会自动换朝向重认：第一遍判出倒置 / 横躺、或一个字段都没读出来时，各端按自己的能力补跑一遍，取字段多的那一份，所以这类照片的单张耗时比正拍明显更长。档位差别要认：Android 只补 180°（倒置），横躺拍摄靠 EXIF 摆正与取景层矫正，画面里斜躺的证件换不回朝向；iOS 换 Vision 的朝向按候选档重认；HarmonyOS 重新解码一张旋转图后依次试 180° / 90° / 270°。iOS 与 HarmonyOS 另有两道闸：短边不足 300px 的缩略图不重试（糊的是分辨率不是朝向），本次剩余时间不够再认一遍时停止重试、回已经读到的字段。判据靠版面里的标签行，标签整列读糊时可能换不回朝向，仍建议把证件转正、占满画面再拍。
9. 字段宁缺毋滥：没解析出的字段不会出现在 fields 里，不猜测回填；一个字段都没解析出时回 9080006。confidence 只是 OCR 行置信度与格式校验的合成值，业务侧仍应对关键字段做人工确认（如身份证校验位、VIN 校验位已在插件内校验）。

快速开始

<script setup>
import { ref } from 'vue'
import { scanCard, recognizeCard, getEnvInfo } from '@/uni_modules/bear-card-ocr'

const fields = ref([])
const env = getEnvInfo()   // 同步返回：本端引擎、能力位与尺寸限制

// 取景识别：Android / iOS 拉插件取景界面；鸿蒙拉系统相机，拍完自动裁到内容再识别
function scanIdcard() {
  scanCard({
    cardType: 'idcard',
    side: 'front',
    success: (res) => {
      // res.data.fields 为结构化字段；res.captureBy 为 'edge' | 'manual'
      fields.value = res.data == null ? [] : res.data.fields
      console.log('矫正图', res.imagePath, '拍摄方式', res.captureBy)
    },
    fail: (err) => {
      console.log('识别失败', err.errCode, err.errMsg)
    }
  })
}

// 上图识别：页面上已有图片时用 recognizeCard
function recognizePicked(path) {
  recognizeCard({
    path: path,
    cardType: 'driver',
    side: 'front',
    maxSide: 1600,
    success: (res) => {
      fields.value = res.data == null ? [] : res.data.fields
    },
    fail: (err) => {
      console.log('识别失败', err.errCode, err.errMsg)
    }
  })
}

console.log(env.engine, env.scanSupported, env.liveEdgeSupported, env.correctSupported)
</script>

import 只允许写到插件根目录 @/uni_modules/bear-card-ocr，MUST NOT 指到 utssdk/ 下的文件。

API

getEnvInfo() : CardEnv

同步返回运行环境与本端真实能力，不需要权限、不会失败。

recognizeCard(options)

scanCard(options)

取景阶段不计入超时：用户对齐证件的时长不受插件控制；拿到照片 / 矫正图后再按默认超时跑识别这一跳。

plate / vin 不是卡片形态：三端都不做卡片框引导与透视矫正，拍照后直接拿整幅照片识别。Android / iOS 的取景界面只保留预览、快门与相册入口；HarmonyOS 走系统相机拍一张，识别后仍会按文字外接框裁到内容。

CardResult：

CardScanResult 在 CardResult 基础上多三个字段：

CardData：

CardField：name（英文稳定键，业务代码认这个）、label（中文显示名）、value（已归一的值：日期统一 yyyy-MM-dd，印章压住「日」只剩年月时退成 yyyy-MM、月也读不出时只回 yyyy，身份证去空格、车牌去分隔符）、confidence（0–1，格式校验通过的字段最低 0.8）。CardPoint：x、y。

七类证件的字段表

fields[].name 为下表第一列，label 为第二列；同一证件类型在不同端、不同版本里字段名不变，新增字段只会追加。

身份证 idcard（side: 'front' 人像面 / 'back' 国徽面）

驾驶证 driver（front 主页 / back 副页）

行驶证 vehicle（front 主页 / back 副页）

车牌号 plate（单面，side 恒为 front）

车牌号形态规则（GA 36）：plateNumber（含行驶证主页/副页的「号牌号码」、运输证的「车牌号」）按形态直出——图里读到的字符能拼成下面任一形态就出值，不要求「号牌号码」这个标签本身被识别到；标签读糊、读丢都不影响取牌，读不到的字符一律不补。

车牌字母表不含 I 与 O（就是为了不与 1/0 混淆），读数里的 I/O 一律按 1/0 归一；首字合法集是 31 个省级简称（含台、港、澳）再加使、领两类号牌字。省简称被读成形近字（院/睆/晥 → 皖、學 → 粤）时，只在能拼出完整合法形态的情况下才纠正。号牌被引擎切成两行读（省简称在中文行、序号在拉丁行）时按同一排的邻行拼装，拼装结果在整图里唯一才出值。

车架号 vin（单面）

网约车驾驶员证 rideDriver（单面）

网约车运输证 rideTransport（单面）

warmup(options?)

把引擎初始化耗时从首次识别里挪走：Android 创建并缓存 ML Kit 识别器，HarmonyOS 调 textRecognition.init()，iOS 的 Vision 没有常驻句柄、用一张空图预跑一次请求。建议进入识别场景时调一次，不要放循环里。

CardEngineState：ready（句柄是否就绪）、engine（引擎标识）、duration（本次调用耗时，ms）。重复预热的开销分端不同：Android 第二次起只是缓存命中（接近 0），HarmonyOS 直接回 0，iOS 没有常驻句柄、每次都会重跑一次空图请求（耗时不为 0）。引擎创建失败返回 9080002。

releaseEngine(options?)

释放引擎并复位 engineReady，下次识别会重新初始化。页面 onUnload 或退出识别场景时调用；没有可释放的句柄时返回 9080004（不算异常，按业务需要忽略即可）。参数与回调同 warmup，成功结果同样是 CardEngineState（ready 为 false）。

错误码

错误码以 90 开头，本插件占 9080 段位，序号 009 固定表示「当前平台不支持」。原生引擎与相机的原始码不占段位，会拼在 errMsg 末尾（native code= 或厂商码文案）。