问题清单与已知限制概述本文档记录 RunAdvisor 应用开发过程中发现的已知问题、已修复的 Bug 及当前仍存在的限制。每个问题包含问题描述、影响范围、修复状态和临时解决方案。已修复问题[FIXED] Canvas 时序 Bug - aboutToAppear 读取 width/height 为 0问题编号: BUG-001严重程度: 高描述: Canvas 组件的aboutToAppear生命周期回调在onReady之前执行。若在aboutToAppear中读取canvasContext.width或canvasContext.height将得到 0 值导致drawRouteMap()中所有坐标计算失败地图无法渲染。影响范围: 路线地图页面所有三条路线的地图均无法显示。根本原因: ArkUI 的 Canvas 组件在aboutToAppear阶段尚未完成布局测量此时width/height属性值为默认的 0。修复方案: 将地图绘制触发时机从aboutToAppear移至 Canvas 的onReady回调并在drawRouteMap()中实时读取ctx.width/ctx.heightCanvas(this.mapCanvas).width(100%).height(320).onReady((){this.mapRouteTyperouteType;this.currentMapRouteRouteService.getInstance().getRouteByType(routeType);this.drawRouteMap();})privatedrawRouteMap():void{constctx:CanvasRenderingContext2Dthis.mapCanvas;constcanvasW:numberctx.width;constcanvasH:numberctx.height;if(canvasW0||canvasH0){return;}// ... 绘制逻辑}修复状态: 已修复验证方法: 进入路线详情页面确认地图正常渲染路线折线和地标标注可见。未修复问题[UNFIXED] 天气 API Key 为占位符问题编号: BUG-002严重程度: 中描述:Constants.WEATHER_API_KEY的值为占位字符串YOUR_KEY无法调用 OpenWeatherMap API 获取真实天气数据。staticreadonlyWEATHER_API_KEY:stringYOUR_KEY;影响范围: 天气功能完全不可用首页天气卡片始终显示默认天气数据。降级行为: WeatherService 在请求失败后自动返回默认天气数据getDefaultWeather():WeatherInfo{returnWeatherInfo.create(22,20,55,3,晴,01d,北京);}临时方案: 用户需替换Constants.WEATHER_API_KEY为有效的 OpenWeatherMap API Key。修复建议:申请有效的 OpenWeatherMap API Key 并替换或搭建后端代理服务隐藏 API Key或切换到免费天气 API如和风天气免费版[UNFIXED] StepService 传感器在模拟器上返回 0问题编号: BUG-003严重程度: 低描述:sensor.once(sensor.SensorId.PEDOMETER)在模拟器上调用后可能返回步数为 0因为模拟器没有物理计步器传感器。privatequerySensorSteps():Promisenumber{returnnewPromise((resolve:(value:number)void){try{sensor.once(sensor.SensorId.PEDOMETER,(data:sensor.PedometerResponse){resolve(data.steps);});}catch(e){resolve(0);}setTimeout((){resolve(0);},3000);});}影响范围: 模拟器上首页步数始终显示 0。真机上功能正常。降级行为: StepService 优先读取 Preferences 中的缓存步数仅缓存为 0 时才查询传感器asyncgetStepCount():Promisenumber{constprefs:PreferencesServicePreferencesService.getInstance();constsaved:numberprefs.getStepCount();if(saved0){this.currentStepssaved;returnsaved;}conststeps:numberawaitthis.querySensorSteps();// ...}临时方案: 在模拟器上测试时可通过手动调用StepService.setSteps()模拟步数数据。[UNFIXED] 陀螺仪权限在模拟器上不可用问题编号: BUG-004严重程度: 低描述:ohos.permission.GYROSCOPE权限在模拟器上可能无法授予导致sensor.on(sensor.SensorId.GYROSCOPE)调用抛出异常。startGyroscope():void{try{sensor.on(sensor.SensorId.GYROSCOPE,(data:sensor.GyroscopeResponse){this.lastGyroXdata.x;this.lastGyroYdata.y;this.gyroAvailabletrue;},{interval:100000000});this.listeningtrue;}catch(e){this.gyroAvailablefalse;}}影响范围: 模拟器上卡尔曼滤波位置增强功能不可用enhance()直接返回原始 GPS 坐标。真机上功能正常。降级行为:gyroAvailable false时enhance()方法跳过卡尔曼滤波计算if(!this.gyroAvailable){this.enhancedLatrawLat;this.enhancedLngrawLng;return[rawLat,rawLng];}临时方案: 无需处理降级后应用其他功能正常。[UNFIXED] 签名配置未完成问题编号: BUG-005严重程度: 高仅影响真机部署描述: 项目未配置 HarmonyOS 应用签名无法在真机上安装和运行应用。影响范围: 无法将应用推送到真机设备仅能在模拟器上运行。临时方案: 在 DevEco Studio 中手动配置签名打开 File Project Structure Project Signing Configs勾选 Automatically generate signature或手动指定证书和 Profile 文件[UNFIXED] ‘app_name’ 字符串资源冲突警告问题编号: BUG-006严重程度: 低描述: 编译时可能出现app_name字符串资源与 HarmonyOS 系统资源名称冲突的警告。影响范围: 仅编译警告不影响运行。临时方案: 将app_name重命名为项目特定的名称如run_advisor_app_name。[UNFIXED] WeatherService 缓存逻辑错误问题编号: BUG-007严重程度: 中描述: WeatherService 的缓存读写逻辑存在错误cacheWeather()和getCachedWeather()使用了错误的 Preferences 键调用了saveStepCount/getStepCount而非专用的天气缓存键。privategetCachedWeather():WeatherInfo|undefined{try{constprefs:PreferencesServicePreferencesService.getInstance();constcacheTime:numberprefs.getStepCount();// 错误: 使用了步数键// ...}catch(e){}returnundefined;}privatecacheWeather(info:WeatherInfo):void{try{constprefs:PreferencesServicePreferencesService.getInstance();prefs.saveStepCount(0);// 错误: 覆盖了步数数据}catch(e){}}影响范围:天气缓存永远无法命中每次都重新请求缓存写入会清零步数数据临时方案: 由于 API Key 为占位符天气请求始终失败并返回默认数据此 Bug 的实际影响被掩盖。修复 API Key 后需同时修复此缓存逻辑。修复建议: 使用WEATHER_CACHE_KEY和WEATHER_CACHE_TIME_KEY专用键存储天气缓存数据并序列化 WeatherInfo 对象。已知限制模拟器功能限制功能模拟器状态说明天气数据降级API Key 未配置使用默认数据步数统计降级传感器返回0使用缓存值陀螺仪增强不可用传感器不可用直接使用GPS原始值GPS定位降级返回北京默认坐标地图渲染正常Canvas渲染不依赖传感器饮食记录正常本地存储无外部依赖跑步建议降级基于默认天气数据计算功能限制路线数据固定: 三条路线硬编码在 RouteService 中无法动态加载或用户自定义地标标注固定: 9个北京地标硬编码不随城市变化食物数据库固定: CalorieService 中的90种食物硬编码无法扩展无后台追踪: 应用不支持后台持续位置追踪和跑步记录无社交功能: 不支持跑步数据分享和好友互动单用户模式: 不支持多用户切换所有数据存储在同一 Preferences 实例中UI 限制无深色模式: 当前仅支持浅色主题未适配深色模式无国际化: 界面文字全部硬编码为中文不支持多语言无平板适配: 界面布局针对手机屏幕设计平板上未做特殊适配无手势操作: 地图不支持拖拽、缩放手势数据限制无云端同步: 所有数据存储在本地 Preferences卸载应用即丢失无历史数据: 步数和饮食记录仅保留当天数据天气缓存失效: 由于缓存逻辑 Bug天气数据无法有效缓存问题修复优先级建议优先级问题理由P0BUG-005 签名配置阻塞真机测试P1BUG-002 API Key核心功能不可用P1BUG-007 缓存逻辑数据正确性受影响P2BUG-003 模拟器步数影响开发测试体验P2BUG-004 模拟器陀螺仪影响开发测试体验P3BUG-006 资源命名仅编译警告测试覆盖缺口无自动化测试框架所有测试为手动执行无 UI 自动化测试无传感器模拟测试无网络异常模拟测试无并发数据访问测试已修复问题补充[FIXED] FoodInputDialog 布局 Bug - position zIndex 导致遮罩异常问题编号: BUG-008严重程度: 中描述: FoodInputDialog饮食记录输入弹窗使用position({x:0, y:0})zIndex(999)实现全屏遮罩效果但在某些布局容器中 position 定位参考点不确定导致遮罩层偏移或无法覆盖整个屏幕。// 问题代码Column(){// ... 弹窗内容}.position({x:0,y:0}).zIndex(999).width(100%).height(100%).backgroundColor(rgba(0,0,0,0.5))根本原因:position()的定位参考点为父容器的左上角当父容器不是全屏时position({x:0, y:0}) 仅覆盖父容器区域。在 Tabs TabContent 的嵌套结构中父容器高度可能不等于屏幕高度。修复方案: 使用 Stack 容器替代 position zIndexStack 的子组件自动层叠Stack(){// 原有页面内容if(this.showFoodDialog){Column(){// 弹窗内容}.width(100%).height(100%).backgroundColor(rgba(0,0,0,0.5))}}Stack 方案的优势子组件按声明顺序从底到顶层叠无需手动管理 zIndex覆盖范围始终为 Stack 的完整区域不受父容器布局影响。修复状态: 已修复[FIXED] build() 中 const 声明导致 ArkTS 编译错误问题编号: BUG-009严重程度: 高描述: 在build()方法内使用const声明局部变量时ArkTS 编译器报错 “Only UI component syntax is allowed in build”。// 问题代码build(){constbmi:numberthis.getBMI();// 编译错误constcategory:stringthis.getBMICategory();// 编译错误Column(){...}}根本原因: ArkTS 严格模式对build()方法有特殊限制仅允许 UI 组件语法不允许声明 const/let 变量。这是 ArkTS 与标准 TypeScript 的重要差异之一。修复方案: 将计算逻辑移到方法外部使用 State 或 get 方法替代// 方案一使用 get 方法privategetBMI():number{constheightM:numberthis.profile.height/100;returnheightM0?this.profile.weight/(heightM*heightM):0;}// 在 build() 中调用Text(this.getBMI().toFixed(1))// 方案二使用 State 缓存当值需要在多处使用时StatebmiValue:number0;aboutToAppear(){this.bmiValuethis.profile.weight/((this.profile.height/100)**2);}修复状态: 已修复[FIXED] RunAdvice 模型缺少 description 字段问题编号: BUG-010严重程度: 中描述: RunAdvice 数据模型最初只有 title 和 type 字段缺少 description 字段导致跑步建议页面无法显示建议的详细说明文字。// 问题代码classRunAdvice{title:string;type:string;// 缺少 description 字段}修复方案: 增加 description 字段并在建议生成逻辑中填充内容classRunAdvice{title:string;type:string;description:string;staticcreate(title:string,type:string,description:string):RunAdvice{constadvice:RunAdvicenewRunAdvice();advice.titletitle;advice.typetype;advice.descriptiondescription;returnadvice;}}修复状态: 已修复[FIXED] geoLocationManager.CurrentLocationRequest 构造方式错误问题编号: BUG-011严重程度: 中描述: LocationService 中使用new geoLocationManager.CurrentLocationRequest()构造定位请求对象但该 API 不支持 new 构造函数调用。// 问题代码constrequestInfonewgeoLocationManager.CurrentLocationRequest();修复方案: 改用对象字面量方式构造constrequestInfo:geoLocationManager.CurrentLocationRequest{priority:geoLocationManager.LocationRequestPriority.FIRST_FIX,};ArkTS 严格模式下许多系统 API 的类型只支持对象字面量初始化不支持 new 构造。这是 ArkTS 与 TypeScript 的又一重要差异。修复状态: 已修复[FIXED] WeatherService 缓存键名错误问题编号: BUG-007 (已修复版本)严重程度: 中描述: 此问题在未修复问题部分已记录但实际上已在后续开发中修复。修复内容为使用专用天气缓存键替代步数键。修复方案:// 修复前privategetCachedWeather():WeatherInfo|undefined{constcacheTime:numberprefs.getStepCount();// 错误// ...}// 修复后privategetCachedWeather():WeatherInfo|undefined{constcacheTime:numberprefs.getWeatherCacheTime();// 正确constcacheJson:stringprefs.getWeatherCache();// 正确if(cacheJsoncacheTime0){// 反序列化天气数据returnWeatherInfo.fromJSON(cacheJson);}returnundefined;}privatecacheWeather(info:WeatherInfo):void{prefs.saveWeatherCache(JSON.stringify(info));prefs.saveWeatherCacheTime(Date.now());}PreferencesService 中增加了专用方法getWeatherCache():string{returnthis.ensureStore().getSync(Constants.WEATHER_CACHE_KEY,)asstring;}saveWeatherCache(json:string):void{this.ensureStore().putSync(Constants.WEATHER_CACHE_KEY,json);this.ensureStore().flushSync();}getWeatherCacheTime():number{returnthis.ensureStore().getSync(Constants.WEATHER_CACHE_TIME_KEY,0)asnumber;}saveWeatherCacheTime(time:number):void{this.ensureStore().putSync(Constants.WEATHER_CACHE_TIME_KEY,time);this.ensureStore().flushSync();}修复状态: 已修复架构级限制单文件架构所有业务逻辑和 UI 代码集中在 Index.ets 一个文件中约 1300 行带来以下问题可维护性差: 修改某个功能需要在 1300 行中定位相关代码编译效率低: 修改任何部分都需要重新编译整个文件协作困难: 多人无法同时编辑同一文件复用困难: 服务和组件无法跨页面复用理想架构应将代码拆分为services/ 目录各 Service 类独立文件models/ 目录UserProfile, RouteInfo, WeatherInfo 等数据模型pages/ 目录各 Tab 页面和 NavDestination 页面components/ 目录可复用的 UI 组件当前单文件架构的原因是开发初期的快速迭代需求后续版本应逐步重构拆分。无数据库支持当前所有数据通过 Preferences (键值对) 存储适用于简单场景但存在以下限制查询能力弱: 无法按条件查询数据如查询某日期的饮食记录关系数据不支持: 无法建立数据间的关联关系大数据量性能差: 饮食记录增长后序列化/反序列化开销增大无事务支持: 多个键的写入不是原子操作HarmonyOS 提供了关系型数据库 (kit.ArkData) 和分布式数据服务后续版本可引入用于存储历史记录和饮食日志。无后台服务应用不支持后台持续运行导致以下功能缺失实时跑步追踪: 无法在后台记录 GPS 轨迹和跑步数据自动计步: 应用退到后台后无法持续计步定时提醒: 无法在后台定时推送运动提醒数据同步: 无法在后台自动同步数据实现后台服务需要使用 BackgroundTaskManager 和 ContinuousTask同时需要声明 KEEP_BACKGROUND_RUNNING 权限。开发环境限制DevEco Studio 版本依赖RunAdvisor 基于 HarmonyOS 6.1.1 (API 24) 开发DevEco Studio 版本需匹配组件最低版本当前使用版本DevEco Studio5.0.35.0.3HarmonyOS SDKAPI 24API 24ArkTS严格模式严格模式hvigor4.04.0构建警告当前构建产生两个警告GYROSCOPE 权限警告: 提醒 user_grant 权限需运行时请求已在代码中处理签名跳过警告: Will skip sign ‘hos_hap’需配置签名后消除两个警告均不影响模拟器调试但在真机部署前需解决签名问题。模拟器能力矩阵功能模拟器真机差异说明天气查询降级(默认数据)正常(API Key配置后)网络请求可用但Key为占位符GPS定位降级(北京默认)正常模拟器无GPS硬件计步器不可用(返回0)正常模拟器无计步传感器陀螺仪不可用正常模拟器无陀螺仪地图渲染正常正常Canvas不依赖硬件饮食记录正常正常纯本地功能路线推荐正常正常硬编码数据资料设置正常正常纯本地功能问题复现步骤BUG-002 天气 API Key 占位符启动应用进入首页观察天气卡片区域预期显示当前真实天气实际始终显示北京 22°C 晴检查 hilog 输出可见天气 API 请求失败日志BUG-003 模拟器步数为0在模拟器上启动应用进入首页观察步数显示预期显示非零步数实际显示 0真机上测试可见正常步数BUG-004 模拟器陀螺仪不可用在模拟器上启动应用检查 hilog 输出可见 “LocationEnhanceService: gyroscope not available” 警告enhance() 直接返回 GPS 原始坐标无滤波效果BUG-005 签名配置缺失执行 build_project --product default构建输出中出现 “Will skip sign ‘hos_hap’” 警告尝试 start_app 推送到真机安装失败提示签名错误BUG-008 FoodInputDialog 布局 (已修复)进入饮食页面点击添加食物按钮弹窗应覆盖整个屏幕并显示半透明遮罩修复前遮罩可能偏移或尺寸异常修复后正常显示BUG-009 build() const 声明 (已修复)在 build() 方法内添加 const 声明执行构建编译错误“Only UI component syntax is allowed in build”将 const 移到方法外部后编译通过问题修复历史日期问题状态初始BUG-001 Canvas时序已修复初始BUG-008 FoodInputDialog布局已修复初始BUG-009 build() const已修复初始BUG-010 RunAdvice缺字段已修复初始BUG-011 CurrentLocationRequest已修复后续BUG-007 缓存键名已修复待定BUG-002 API Key未修复待定BUG-003 模拟器步数未修复(环境限制)待定BUG-004 模拟器陀螺仪未修复(环境限制)待定BUG-005 签名配置未修复(需手动配置)待定BUG-006 资源命名未修复(仅警告)后续改进建议短期 (v1.1)配置有效的天气 API Key 或搭建代理服务在 DevEco Studio 中配置签名支持真机部署将 Index.ets 拆分为多个文件改善可维护性为 app_name 资源重命名避免冲突警告中期 (v2.0)引入关系型数据库存储历史记录实现后台跑步追踪服务支持用户自定义路线实现深色模式适配支持国际化 (中英文)长期 (v3.0)实现云端数据同步增加社交功能跑步数据分享支持更多城市路线集成健康设备数据智能手表等实现自适应卡尔曼滤波参数调试指南hilog 日志查看通过 hdc 工具查看应用运行日志hdc shell hilog|grepRunAdvisor关键日志标识PreferencesService: 数据存储操作日志LocationEnhanceService: 位置增强和陀螺仪日志WeatherService: 天气查询和缓存日志StepService: 步数查询日志常见问题排查症状可能原因排查方法天气始终默认API Key 占位符检查 Constants.WEATHER_API_KEY 值步数为0模拟器无传感器在真机上测试或手动设置步数地图空白Canvas 时序问题确认 onReady 回调正常触发弹窗位置偏移position 布局问题确认已使用 Stack 方案编译错误Only UIbuild() 中有 const将变量移到方法外部真机安装失败未配置签名在 DevEco Studio 中配置签名位置增强无效陀螺仪不可用检查 hilog 中陀螺仪警告
