安卓故障排除指南{ #capture_app_troubleshooting_guide }¶
目的{ #capture_app_troubleshooting_guide_purpose }¶
本指南介绍 DHIS2 Android 用户和实施者从设置到实地数据收集、同步和持续维护的整个过程。每个阶段都会解释一些问题可能是如何出现的、可能的原因以及使用 DHIS2 的安卓生态系统工具进行修复的方法。
设置和配置{ #capture_app_troubleshooting_guide_setup }¶
在采集任何数据之前，设置将决定同步的方式。这一阶段的重点是安装、配置和首次同步。
关于 Rooted 设备的重要说明{ #capture_app_troubleshooting_guide_rooted_device }¶
DHIS2 Android 捕捉应用程序的生产版本无法在已 root 的设备上运行。
这是一项安全措施，旨在防止从本地数据库中提取敏感信息。如果用户尝试在已 root 的手机上运行生产版应用程序，设备会显示如下信息：*出于安全原因，此版本的应用程序不允许在 root 设备上使用。请使用培训版本。
**培训版本**的应用程序**可以**在root设备上运行，建议仅用于测试、调试或培训，不用于生产。
同步机制{ #capture_app_troubleshooting_guide_sync }¶
Android Capture 应用项目同步两个不同的数据流：
元数据/配置 元数据包括从 DHIS2 服务器下载的所有结构和配置信息（项目、数据集、类别、类别选项、组织单位、选项集、项目规则......）。安卓应用项目将这些信息存储在本地数据库中，这样用户即使在离线状态下也能继续操作。
元数据同步可确保设备拥有来自服务器的最新配置。管理员可使用 Android 设置网络应用项目定义设备检查更新的频率。元数据同步可以每 1 天、1 周或手动进行（默认设置为每天）。
在即将推出的 DHIS2 版本中，将提供更短的时间段（如 6 小时和 12 小时），以便管理员进行更精细的控制。
在推出或更改配置时，频繁同步元数据非常有用，而在稳定部署时，每周同步可减少带宽使用。
数据 数据是指用户通过 Android Capture 应用项目捕获的所有内容（跟踪的实体实例、注册、事件和数据值）。应用项目会将这些数据保存在本地，直到成功上传。数据同步可以按 30 分钟、1 小时、6 小时、12 小时、1 天的时间间隔安排，也可以手动完成。最佳设置取决于网络质量：连接稳定的地区可频繁同步，偏远地区可每日同步。
DHIS2 Android 的离线优先设计意味着用户可以随时在没有连接的情况下工作。恢复网络连接后，将根据配置自动或手动发送队列数据。
因此，保持新的元数据和适当的同步范围对于避免设备和服务器之间的冲突至关重要。
同步范围和文件大小管理{ #capture_app_troubleshooting_guide_syncscope }¶
管理员可为跟踪实体项目 (Tracker) 和事件项目定义单独的下载参数。应用项目在应用全局默认值之前，总是优先考虑特定项目的配置。例如，如果设备设置为全局下载 1000 个跟踪实体，但特定项目限制为 200 个，则应用项目会首先计算这 200 个，然后从全局总限制中减去。
事件设置只适用于事件类型的项目，跟踪项目受跟踪实体下载限制的制约。这可确保设备不会超出其容量，并确保关键项目始终优先接收数据。
该应用还可以限制最大下载文件大小（在 Android 设置中设置）。应用项目不会下载大于此限制的文件。这样可以防止内存不足或连接不畅的设备下载超大文件。
保留值{ #capture_app_troubleshooting_guide_reserved_values }¶
保留值是预先生成的唯一标识符，用于标记为自动生成的跟踪实体属性（例如患者或病例 ID）。当用户注册一个新的跟踪实体时，应用项目会在本地分配其中一个保留 ID，以确保即使是离线注册也有全局唯一的标识符。
流程是这样的
-
服务器会为每个自动生成的属性预先生成一个唯一 ID 池（可在 ASWA 中配置，默认为 500）。
-
在元数据/配置同步期间，设备会下载此池。
-
每注册一个新的跟踪实体，就会消耗一个保留值。
-
当池使用到一定程度时，就会在下一次成功同步时申请新的批次。用户也可以在应用设置菜单中手动进行补充。
跟踪器导入器和导出器 - 对同步的影响{ #capture_app_troubleshooting_guide_tracker_importer }¶
跟踪器导入器和跟踪器导出器是 DHIS2 生态系统中的关键后端服务，直接影响 Android 采集应用项目上传数据的方式和下载数据的数量。
DHIS2 **跟踪器导入器**会根据服务器元数据（强制属性、项目规则、所有权和共享以及组织单位捕获）验证被跟踪实体实例、注册、事件和关系的上传。当设备重新连接并同步时，其有效载荷将提交给导入器；如果验证成功，数据将被提交；如果不成功，导入器将返回一份详细摘要，显示在设备上和同步故障排除应用项目 中。
跟踪器导出器***会根据用户的组织单位、分配的程序和 Android 同步范围，确定设备在同步期间可以下载哪些跟踪实体、注册和事件。如果导出器返回的结果过大，第一次同步就会变得缓慢，并可能触及设备限制；如果导出器返回的结果过小，第一次同步就会变得缓慢，并可能触及设备限制。
Android Capture 应用项目会逐步启用这些服务。将设备与服务器对齐时，请使用此矩阵：
| 服务 | 安卓支持状态 |
|---|---|
| 跟踪器导入器 | 自 DHIS2 2.38+ 起可用 自 2.40+ 起默认 自 v43+ 起必须使用 |
| 跟踪器出口商 | 自 2.40+ 起可用 自 2.40+ 起默认 自 v43+ 起必须使用 |
在早期的服务器版本（2.36-2.37）中，端点是存在的，但安卓应用项目默认情况下不使用它。这是在端点成熟时特意做出的安全选择。从 2.40 开始，导入器和导出器都是安卓同步的标准路径，从 v43+ 版本开始则必须使用。如果您的实例低于这些阈值，请在大规模推广前测试暂存中的行为。
何时使用 "新 "Tracker Importer 端点{ #when-to-use-the-new-tracker-importer-endpoint }¶
在以下情况下使用新的导入器：
*您的 DHIS2 服务器版本为 2.36 或更高。 * 您正在处理大型移动设备上传或离线优先方案。 * 您需要的是更高的性能、更好的错误汇总和面向未来的架构。
如果出现以下情况，您可能会遇到问题：
- 设备上的元数据已过期（因此客户端有效载荷未通过验证）。
- 导出/下载查询会返回较大的有效载荷，导致移动同步延迟或超时。
使用配置故障排除功能（仅限培训应用项目）{ #capture_app_troubleshooting_guide_config_feature }¶
配置故障排除功能是一种诊断工具，仅适用于 DHIS2 Android 培训应用项目，不适用于生产采集应用项目。它专为管理员和实施人员设计，用于在向现场推广之前，在设置或培训期间测试和验证项目规则和翻译等配置元素。该工具不需要特殊的用户角色或权限。
目的和用例{ #purpose-and-use-cases }¶
配置故障排除功能有助于及早发现元数据的不一致，防止在生产中出现验证或同步错误。它允许管理员
-
验证项目规则： 应用项目会运行一个规则验证器，检查本地存储在设备上的所有项目规则，突出显示配置不一致的地方（无效引用、字段缺失或循环依赖）。
-
测试翻译： 应用项目包含一个语言切换器，允许用户在可用界面语言之间即时切换。这有助于在推出前识别未翻译或标注错误的字段、按钮和选项集。
将此验证步骤作为配置工作流程的一部分，可确保采集应用项目的生产部署稳定一致，最大限度地减少因配置不匹配而导致的字段级数据录入错误。
管理 APK 分发和版本对齐{ #capture_app_troubleshooting_guide_APK_distribution }¶
同步可靠性还取决于在所有设备上保持一致的 Android Capture 版本。网络应用项目中的 APK Distribution 功能允许管理员将特定应用项目版本分配给用户组。
管理员上传新的 Android Capture 版本时，会定义版本号，可选择设置最低或推荐的 Android 操作系统版本，并为特定用户组分配访问权限。每个用户组可以访问多个版本，但每个用户只能看到分配给其组的最新版本。如果没有为任何版本分配用户组，系统会默认实例中的所有用户使用最新版本。
新版本上传后，安卓用户下次登录或在应用中检查更新时就会看到更新通知。消息会提示他们直接从实例中下载最新的 APK，但更新并不是强制性的。用户可以选择忽略该消息，继续使用当前版本。这种设计可确保逐步引入更新，而不会在关键活动期间中断现场工作或强制安装。
重要的是要了解 APK Distribution 不会强制更新或控制设备。它的作用仅限于显示更新信息和促进直接从 DHIS2 服务器下载版本。管理员仍负责协调更新并确保用户最终迁移到推荐版本。
初始设置期间的常见问题{ #capture_app_troubleshooting_guide_common_issues_setup }¶
在初始设置期间，大多数同步和配置问题都源于用户权限不匹配或元数据共享不完整。在用户开始输入数据之前确保正确的配置对于稳定的同步和准确的所有权验证至关重要。
下表总结了最常见的设置问题、原因以及如何使用 DHIS2 工具解决这些问题。在用户开始采集数据之前，请确保这些配置检查已得到验证。大多数同步或可见性问题都源于其中一个或多个设置问题。
| 症状 | 根本原因 | 如何修复 | 工具/检查 |
|---|---|---|---|
| 登录后看不到**项目/数据集** | 用户可以捕获组织单位，但无法访问项目/数据集或 TET。 | 检查用户组是否对 "项目 "和 "跟踪实体类型 "都有 "可捕获和查看 "权限。更改共享后重新同步配置。 | 维护应用项目 → 项目共享/ OU 访问 → TET 共享 |
| 缺失阶段 | 计划阶段的共享不一致。 | 再次检查 "项目阶段 "是否继承了与父项目相同的共享。 | 维护应用项目 |
| 无法注册新的被跟踪实体（未生成 ID） | 保留值已用完或未下载。 | 增加保留值计数。触发配置同步。 | Android 设置 Web App → 保留值 |
| 无法创建新阶段或数据集时期/类别组合中缺少选项 | 类别组合或其类别选项未与用户共享、已过期或被期限或机关单位过滤掉。 | 检查与计划或数据集相关联的所有类别选项的共享情况。确保选项对选定的组织单位和时期有效。 | 维护应用项目 → 类别 |
同步和故障排除：数据无法上传时{ #capture_app_troubleshooting_guide_sync_errors }¶
同步是出现最多支持问题的地方。设备重新连接后，离线采集的数据将通过 Tracker Importer 上传，Tracker Importer 会根据服务器的配置和权限验证每条记录。当这一过程遇到问题时，Android Capture 应用项目现在提供了一种改进的、用户友好的导航和解决问题的方法。
安卓应用项目中的同步错误导航{ #capture_app_troubleshooting_guide_error_navigation }¶
每次尝试同步后，Android Capture 应用项目都会在同步对话框中直接显示同步错误。错误按项目或数据集分组，并显示清晰的信息，说明出错的原因。导航经过重新设计，用户只需轻点任何列出的错误，应用项目就会自动打开相应的事件、注册或数据集。有问题的字段会高亮显示，以便快速更正。
数据修复后，用户点击 "刷新 "按钮即可立即重试同步。这种行为允许现场工作人员更正数据，而无需通过多个表单或阶段进行搜索。
一些复杂的后台错误代码会被翻译成清晰的句子，以帮助用户了解问题是否与权限、配置或数据录入有关。
同步故障排除应用项目（在服务器上）¶
对于管理员来说，DHIS2 中的同步故障排除应用项目 可补充用户在设备上看到的内容。它提供服务器端验证结果，显示哪些有效载荷被拒绝、何时被拒绝以及拒绝的原因。通过按消息类型过滤，管理员可以快速将设备错误与相应的导入摘要进行匹配。这种可追溯性对于诊断问题是否源于元数据、所有权或项目规则至关重要。
目前，"同步故障排除应用项目 "只存储过去 24 小时内的错误（为节省磁盘空间，这些错误已被清理）。这对识别和纠正正在发生的同步问题很有用，但无法检查过去的错误。
此清理期在系统设置中定义，适用于所有单次运行作业（如数据导入）。可以通过 API 更改该值，但不建议这样做，因为延长该周期会延长错误的保留时间，但也会增加数据库存储空间。
导出和导入本地数据库进行分析{ #capture_app_troubleshooting_guide_export_app }¶
Android Capture 应用项目包含强大的诊断功能，允许实施人员从设备中提取或恢复整个本地数据库。该功能适用于无法通过常规同步或配置步骤解决数据不一致或同步故障的情况。
当用户遇到持续的同步问题时，管理员可以申请一份本地数据库副本来检查其内容。从应用项目的 "设置 "菜单中选择 "导出数据库"。应用项目会生成一个加密文件，其中包含所有本地存储的元数据、配置和捕获数据。该文件可以安全地与系统管理员或支持团队共享。
要导入数据库进行审查，请在其他设备或测试手机上打开 Android Capture 应用项目。在登录屏幕上，点击右上角的三点菜单，然后选择导入数据库。选择先前导出的文件。
导入后，管理员必须使用与原始所有者相同的用户凭据才能查看存储在该数据库中的数据、项目和配置。通过这一过程，支持团队可以完全按照用户的体验重现环境，并找出同步或验证失败的地方。
导出和导入本地数据库为调试难以远程跟踪的问题提供了一种安全而现实的方法，尤其是在大规模部署中设备长时间离线运行的情况下。
解释和解决常见错误{ #capture_app_troubleshooting_guide_common_issues_sync }¶
安卓应用项目将 DHIS2 Tracker Importer 错误模式映射为可读信息。下面参考了最常见的错误、应用项目目前如何解释这些错误、它们的含义以及下一步的实际步骤。
| 码 | 应用项目中显示的信息 | 为什么会出现这个错误？ | 如何解决 |
|---|---|---|---|
| E1000 | 您不能访问%s | 您在一个没有数据捕获权限的组织单位中创建/更新数据（或在离线捕获数据后权限被删除）。 | 如果不需要同步这些数据：在设备上，删除本地记录或删除本地数据 → 同步配置，以便应用项目刷新权限并将该 OU 从范围中删除。 如果确实需要同步暂时恢复用户的捕获 OU 和项目写共享 → 让用户成功同步 → 同步配置并应用新的受限权限。 |
| E1001 | 您不能访问类型%s | 项目使用的跟踪实体类型没有写入权限。(或在离线捕获数据后这些权限被删除） | 不需要数据：使用 TET → 同步配置删除待处理的注册。 需要数据：授予 TET（和项目）的写入权限，或让有权限的用户执行上传→同步数据→然后还原设备上的权限和同步配置。 |
| E1002 | %s 已经存在。(%s:%s) | 重复跟踪实体（相同 UID）或唯一属性碰撞（已使用国家 ID）。 | 不需要数据：删除设备上的重复内容 → 刷新。 需要数据：搜索服务器上的 TEI → 更新现有 TEI（如果是唯一属性冲突，将值更改为正确的唯一属性） → 重新同步数据。 |
| E1003 | %s 不在搜索范围内 | 试图访问用户搜索范围之外的 OU 中的 TEI 或事件。 | 当 TEI 从搜索范围之外的 OU 转移时，可能会出现这种情况 |
| E1005 | %s 类型无法找到 | 设备引用的跟踪实体类型已不存在 | 如果记录是一次性的：删除它 → 同步配置。 如果必须保留：在设备上同步配置 → 确保 TET 存在并分配给项目 → 重试数据同步。 |
| E1006 | 属性%s 不存在 | 有效负载包含服务器上没有的属性 UID（元数据在捕获后已更改）。 | 丢弃数据：删除/编辑属性数据 → 刷新 → 同步配置。 保留数据：确认属性仍是项目/TET 的一部分 → 如果属性被替换，重新输入有效属性 → 同步配置 → 重新同步数据。 |
| E1007 | 属性与值类型不匹配%s. （错误：%s) | 输入值与属性值类型不匹配（数字与文本、日期格式等）。 | 不保留数据：删除/清除无效值→刷新。 保留数据：删除值 → 同步配置 → 更正值以符合预期类型 → 重新同步数据。 |
| E1008 | 项目阶段%s 没有引用项目。 | 元数据已损坏："节目阶段 "丢失了其父节目链接。 | 修复服务器上的阶段项目链接（API、导入/导出应用项目）→同步配置。 |
| E1009 | 文件已分配。 | 同一文件资源被链接两次或重复使用不当。 | |
| E1031 | 缺少事件 "coccurredAt "日期。 | 当您尝试导入或创建事件时，如果未指定所需的 occurredAt（事件日期）字段，则会出现此问题。 | - 如果在导入（例如通过 CSV 或 JSON）过程中遇到此错误，则必须确保每个事件行或对象都包含有效的 occurredAt 值。如果字段缺失或为空，导入将失败。 - 如果需要修复数据库中的现有数据，可以使用 SQL 脚本 指定默认日期或删除不一致的记录。 |
| E1032 | 服务器中找不到%s 事件。 | 本地记录引用了服务器上已删除或从未存在的事件。 | 手动删除事件 |
| E1063 | 服务器中找不到%s 。 | 本地记录引用的 TEI 不在服务器上（已删除或从未上传）。 | 手动删除 TEI |
| E1064 | 属性值%s 不唯一。 | 唯一属性值已被另一个 TEI 使用。 | |
| E1069 | 未找到与注册相关的计划。 | 注册引用了服务器没有的项目（UID 已更改/删除）。 | |
| E1081 | 服务器中找不到注册信息。 | 本地注册已在服务器上删除或从未导入。 | |
| E1084 | 未找到文件引用。 | 服务器上不存在文件资源 UID（过期、已删除或由于离线捕获而从未上传）。 | |
| E1100 | 您无权删除%s 。 | 您试图在没有必要授权的情况下删除 TEI（级联删除）。 | 删除记录临时授予执行删除的权限（如 F_TEI_CASCADE_DELETE）→同步数据→同步元数据。 保留记录：使用粒度同步来同步其余记录 → 删除本地数据 → 同步配置 → 同步数据以恢复本地 DB。 |
| E1103 | 您无权删除注册。 | 您试图在没有必要授权的情况下删除注册。 | 删除记录临时授权执行删除 → 同步元数据 → 同步数据 → 恢复更改 → 同步元数据。 要保留记录：使用粒度同步来同步其余记录 → 删除本地数据 → 同步配置 → 同步数据以恢复本地 DB。 |
| 码 | 服务器信息 | 可能的原因 | 纠正行动 |
|---|---|---|---|
| ** E1010-E1013** | 找不到与事件关联的节目/OU/舞台 | 删除或错误配置项目元数据。 | 核实链接的项目和 OU；重新分配。 |
| ** E1014-E1016** | 注册非注册计划或重复注册。 | 试图多次注册一个单一注册计划。 | 检查项目类型；关闭以前的注册。 |
| E1050-E1057 | 活动日期、类别选项无效或缺失。 | 日期超出允许范围或类别组合无效。 | 调整活动日期或类别选项。 |
| E1068-E1070 | 缺少用于注册的链接实体。 | 注册时提及不存在的 TEI、计划或 OU。 | 同步元数据；恢复丢失的实体。 |
| E1076-E1077 | 缺少必填数据元素或文本超出长度。 | 违反属性限制。 | 补全缺失字段或缩短文本值。 |
| E1082-E1083 | 事件已删除或用户无权编辑。 | 试图修改已删除或已完成的事件。 | 取消标记为已完成或重新创建事件。 |
| E1085 | 属性值类型不匹配。 | 输入的数据类型错误。 | 匹配预期值类型。 |
| E1086-E1089 | 计划阶段不匹配或缺失。 | 计划与阶段的关系不一致。 | 重建项目规则并同步元数据。 |
| E1090 | TEI 类型中未声明的强制属性。 | 元数据不一致。 | 为 TEI 类型添加属性。 |
| E1096-E1099 | 缺少对项目或类别选项的数据读/写访问。 | 权限或共享问题。 | 调整共享；验证角色配置。 |
| E1301-E1312 | 由项目规则生成 - 缺少必填字段或关系。 | 规则隐藏必填字段或缺失的关系。 | 更新规则或数据；重新运行同步。 |
| E4000-E4018 | 关系约束或重复错误。 | 无效或循环关系定义。 | 审查关系；确保 TEI 正确连接。 |
| E5000-E5001 | 持久性或删除依赖性错误。 | 由于引用完整性，对象无法删除。 | 清理依赖关系；重试。 |
| E9999 | 不适用 - 占位符。 | 未定义的导入错误。 | 详情请查看日志或 DHIS2 API。 |
用于故障排除和测试的实用外部工具¶
本节简要概述了在测试、调试、支持用户或演示 DHIS2 Android 捕捉应用项目时仍然有用的外部工具。
Scrcpy{ #scrcpy }¶
scrcpy 是一款轻便、快速的工具，可让您
- 在电脑上镜像安卓设备屏幕
- 通过键盘和鼠标控制设备
- 记录屏幕（用于报告错误）
- 通过拖放安装 APK
- 同时使用 USB 和无线连接
它适用于**Windows、macOS 和 Linux**，无需 root。
更多信息： https://github.com/Genymobile/scrcpy
其他屏幕克隆替代方案{ #other-screen-cloning-alternatives }¶
如果没有 scrcpy，以下工具也很常用：
- Vysor - 界面简单，提供 Chrome 浏览器扩展。
https://vysor.io - AirDroid - 无线镜像，无需在电脑上安装任何设备即可使用。
https://www.airdroid.com
这些工具在远程支持、培训课程或演示过程中非常有用。
使用安卓模拟器{ #using-android-emulators }¶
安卓模拟器可以复制各种设备配置，使实施人员能够
- 测试不同的安卓操作系统版本
- 模拟手机和平板电脑
- 比较多个 DHIS2 安卓应用项目版本
- 重现配置问题
最常见的选项是**Android Studio Emulator**：
- 打开安卓工作室
- 转到**工具 → 设备管理器**
- 下载所需的安卓系统镜像
- 创建符合所需规格的虚拟设备
更多信息： https://developer.android.com/studio/run/managing-avds
模拟器非常适合早期测试，但仍建议使用物理设备进行最终验证和报告错误。