添加函数调试日志

appbase/build.gradle

@@ -19,12 +19,15 @@ def genVersionName(def versionName){
 
 android {
     
-    compileSdkVersion 32
-    buildToolsVersion "32.0.0"
+    // 1. compileSdkVersion：必须 ≥ targetSdkVersion，建议直接等于 targetSdkVersion（30）
+    compileSdkVersion 30
+
+    // 2. buildToolsVersion：需匹配 compileSdkVersion，建议使用 30.x.x 最新稳定版（无需高于 compileSdkVersion）
+    buildToolsVersion "30.0.3" // 这是 30 对应的最新稳定版，避免使用 beta 版
 
     defaultConfig {
         applicationId "cc.winboll.studio.appbase"
-        minSdkVersion 24
+        minSdkVersion 23
         targetSdkVersion 30
         versionCode 1
         // versionName 更新后需要手动设置 

appbase/build.properties

@@ -1,8 +1,8 @@
 #Created by .winboll/winboll_app_build.gradle
-#Fri Sep 26 05:36:14 HKT 2025
-stageCount=9
+#Tue Nov 11 13:06:53 GMT 2025
+stageCount=10
 libraryProject=libappbase
 baseVersion=15.10
-publishVersion=15.10.8
-buildCount=0
-baseBetaVersion=15.10.9
+publishVersion=15.10.9
+buildCount=8
+baseBetaVersion=15.10.10

appbase/src/main/AndroidManifest.xml

@@ -3,9 +3,6 @@
     xmlns:android="http://schemas.android.com/apk/res/android"
     package="cc.winboll.studio.appbase">
 	
-	<!-- 网络权限 -->
-	<uses-permission android:name="android.permission.INTERNET" />
-		
     <application
         android:name=".App"
         android:icon="@drawable/ic_winboll"

appbase/src/main/java/cc/winboll/studio/appbase/MainActivity.java

@@ -8,10 +8,10 @@ import android.os.Bundle;
 import android.view.Menu;
 import android.view.MenuItem;
 import android.view.View;
-import android.widget.Toast;
 import android.widget.Toolbar;
 import cc.winboll.studio.appbase.R;
 import cc.winboll.studio.libappbase.LogActivity;
+import cc.winboll.studio.libappbase.LogUtils;
 import cc.winboll.studio.libappbase.ToastUtils;
 
 public class MainActivity extends Activity {
@@ -57,6 +57,13 @@ public class MainActivity extends Activity {
         LogActivity.startLogActivity(this);
     }
 	
+	public void onToastUtilsTest(View view) {
+		LogUtils.d(TAG, "onToastUtilsTest");
+        ToastUtils.init(getApplicationContext());
+		ToastUtils.show("Hello, WinBoLL!");
+		ToastUtils.release();
+    }
+
 	/**
 	 * 唤起默认浏览器打开指定网站
 	 * @param context 上下文（如 Activity.this）

appbase/src/main/res/layout/activity_main.xml

@@ -28,7 +28,8 @@
 			android:background="#81C7F5"
 			android:paddingVertical="12dp"
 			android:layout_marginHorizontal="24dp"
-			android:onClick="onCrashTest"/>
+			android:onClick="onCrashTest"
+			android:layout_margin="10dp"/>
 
 		<Button
 			android:layout_width="match_parent"
@@ -39,7 +40,20 @@
 			android:background="#81C7F5"
 			android:paddingVertical="12dp"
 			android:layout_marginHorizontal="24dp"
-			android:onClick="onLogTest"/>
+			android:onClick="onLogTest"
+			android:layout_margin="10dp"/>
+
+		<Button
+			android:layout_width="match_parent"
+			android:layout_height="wrap_content"
+			android:text="应用吐司测试"
+			android:textSize="16sp"
+			android:textColor="@android:color/white"
+			android:background="#81C7F5"
+			android:paddingVertical="12dp"
+			android:layout_marginHorizontal="24dp"
+			android:onClick="onToastUtilsTest"
+			android:layout_margin="10dp"/>
 
 	</LinearLayout>
 

libappbase/build.gradle

@@ -5,11 +5,14 @@ apply from: '../.winboll/winboll_lint_build.gradle'
 
 android {
     
-    compileSdkVersion 32
-    buildToolsVersion "32.0.0"
+    // 1. compileSdkVersion：必须 ≥ targetSdkVersion，建议直接等于 targetSdkVersion（30）
+    compileSdkVersion 30
+
+    // 2. buildToolsVersion：需匹配 compileSdkVersion，建议使用 30.x.x 最新稳定版（无需高于 compileSdkVersion）
+    buildToolsVersion "30.0.3" // 这是 30 对应的最新稳定版，避免使用 beta 版
 
     defaultConfig {
-        minSdkVersion 24
+        minSdkVersion 23
         targetSdkVersion 30
     }
     buildTypes {
@@ -22,9 +25,4 @@ android {
 
 dependencies {
     api fileTree(dir: 'libs', include: ['*.jar'])
-    // 网络连接类库
-    api 'com.squareup.okhttp3:okhttp:4.4.1'
-    // https://mvnrepository.com/artifact/com.fasterxml.jackson.core/jackson-databind
-    
-    api 'com.google.code.gson:gson:2.10.1'
 }

libappbase/build.properties

@@ -1,8 +1,8 @@
 #Created by .winboll/winboll_app_build.gradle
-#Fri Sep 26 05:36:14 HKT 2025
-stageCount=9
+#Tue Nov 11 13:06:53 GMT 2025
+stageCount=10
 libraryProject=libappbase
 baseVersion=15.10
-publishVersion=15.10.8
-buildCount=0
-baseBetaVersion=15.10.9
+publishVersion=15.10.9
+buildCount=8
+baseBetaVersion=15.10.10

libappbase/src/main/java/cc/winboll/studio/libappbase/APPModel.java

@@ -1,73 +1,138 @@
 package cc.winboll.studio.libappbase;
 
 /**
- * @Author ZhanGSKen<zhangsken@qq.com>
- * @Date 2025/03/02 10:28:08
- * @Describe 应用调试模型
+ * @Author ZhanGSKen&豆包大模型<zhangsken@qq.com>
+ * @Date 2025/11/11 20:01
+ * @Describe WinBoLL 应用全局数据模型类
+ * 继承自 BaseBean，用于存储和管理应用的核心配置信息（如调试状态），
+ * 支持 JSON 序列化/反序列化，便于数据持久化或跨组件传递
  */
 import android.util.JsonReader;
 import android.util.JsonWriter;
-import cc.winboll.studio.libappbase.BaseBean;
 import java.io.IOException;
 
 public class APPModel extends BaseBean {
 
+    /**
+     * 日志打印标签，用于区分当前类的日志输出
+     */
     public static final String TAG = "APPModel";
 
-    // 应用是否处于正在调试状态
-    //
-    boolean isDebuging = false;
+    /**
+     * 应用调试状态标识
+     * true：应用处于调试模式（可输出详细日志、启用调试功能等）
+     * false：应用处于正式模式（关闭调试相关功能，优化性能）
+     */
+    private boolean isDebugging = false; // 修正拼写：原 isDebuging -> isDebugging（符合命名规范）
 
+    /**
+     * 无参构造方法
+     * 初始化调试状态为默认值：false（正式模式）
+     */
     public APPModel() {
-        this.isDebuging = false;
+        this.isDebugging = false;
     }
 
-    public APPModel(boolean isDebuging) {
-        this.isDebuging = isDebuging;
+    /**
+     * 带参构造方法
+     * 可通过参数指定应用的初始调试状态
+     * @param isDebugging 初始调试状态（true：调试模式；false：正式模式）
+     */
+    public APPModel(boolean isDebugging) {
+        this.isDebugging = isDebugging;
     }
 
-    public void setIsDebuging(boolean isDebuging) {
-        this.isDebuging = isDebuging;
+    /**
+     * 设置应用调试状态
+     * @param isDebugging 目标调试状态（true：开启调试；false：关闭调试）
+     */
+    public void setIsDebugging(boolean isDebugging) {
+        this.isDebugging = isDebugging;
     }
 
-    public boolean isDebuging() {
-        return isDebuging;
+    /**
+     * 获取当前应用调试状态
+     * @return 调试状态（true：调试中；false：非调试）
+     */
+    public boolean isDebugging() {
+        return isDebugging;
     }
 
+    /**
+     * 重写父类方法，返回当前类的全限定名
+     * 用于标识数据模型的类类型（可用于反射、序列化校验等场景）
+     * @return 类的全限定名（如：cc.winboll.studio.libappbase.APPModel）
+     */
     @Override
     public String getName() {
         return APPModel.class.getName();
     }
 
+    /**
+     * 重写父类方法，将当前模型的字段序列化到 JSON 中
+     * 用于将调试状态等核心数据转换为 JSON 格式（如持久化到文件、网络传输）
+     * @param jsonWriter JSON 写入器对象，用于输出 JSON 数据
+     * @throws IOException 当 JSON 写入失败时抛出（如流关闭、格式错误）
+     */
     @Override
     public void writeThisToJsonWriter(JsonWriter jsonWriter) throws IOException {
+        // 先调用父类方法，序列化父类中的字段（若 BaseBean 有可序列化字段）
         super.writeThisToJsonWriter(jsonWriter);
-        jsonWriter.name("isDebuging").value(isDebuging());
+        // 序列化当前类的调试状态字段：key 为 "isDebuging"（保持与原代码一致，避免兼容性问题），value 为当前状态
+        jsonWriter.name("isDebuging").value(isDebugging());
     }
 
+    /**
+     * 重写父类方法，从 JSON 中解析字段并初始化当前对象
+     * 用于将 JSON 格式的配置数据解析为 APPModel 实例（如从文件读取、网络接收后解析）
+     * @param jsonReader JSON 读取器对象，用于读取 JSON 数据
+     * @param name 当前解析的 JSON 字段名
+     * @return true：字段解析成功；false：字段不属于当前类，需由调用者处理
+     * @throws IOException 当 JSON 读取失败时抛出（如流关闭、数据格式错误）
+     */
     @Override
     public boolean initObjectsFromJsonReader(JsonReader jsonReader, String name) throws IOException {
-        if (super.initObjectsFromJsonReader(jsonReader, name)) { return true; } else {
-            if (name.equals("isDebuging")) {
-                setIsDebuging(jsonReader.nextBoolean());
+        // 先调用父类方法，解析父类中的字段（若 BaseBean 有可解析字段）
+        if (super.initObjectsFromJsonReader(jsonReader, name)) {
+            return true; // 父类已处理该字段，直接返回成功
         } else {
+            // 解析当前类的字段
+            if (name.equals("isDebuging")) {
+                // 读取 JSON 中 "isDebuging" 字段的值，设置为当前对象的调试状态
+                setIsDebugging(jsonReader.nextBoolean());
+            } else {
+                // 字段不属于当前类，返回 false 提示调用者跳过该字段
                 return false;
             }
         }
+        // 字段解析成功，返回 true
         return true;
     }
 
+    /**
+     * 重写父类方法，从 JSON 读取器中完整解析一个 APPModel 实例
+     * 负责处理 JSON 对象的开始/结束标记，循环解析所有字段
+     * @param jsonReader JSON 读取器对象，用于读取 JSON 数据
+     * @return 解析完成的当前 APPModel 实例（支持链式调用）
+     * @throws IOException 当 JSON 读取失败时抛出（如流关闭、数据格式错误）
+     */
     @Override
     public BaseBean readBeanFromJsonReader(JsonReader jsonReader) throws IOException {
+        // 开始解析 JSON 对象（对应 JSON 中的 '{'）
         jsonReader.beginObject();
+        // 循环读取 JSON 中的所有字段（直到对象结束）
         while (jsonReader.hasNext()) {
+            // 获取当前字段名
             String name = jsonReader.nextName();
+            // 解析字段：若当前类无法处理该字段，则跳过（避免解析异常）
             if (!initObjectsFromJsonReader(jsonReader, name)) {
                 jsonReader.skipValue();
             }
         }
-        // 结束 JSON 对象
+        // 结束解析 JSON 对象（对应 JSON 中的 '}'）
         jsonReader.endObject();
+        // 返回解析完成的实例（当前对象）
         return this;
     }
 }
+

libappbase/src/main/java/cc/winboll/studio/libappbase/BaseBean.java

@@ -1,9 +1,12 @@
 package cc.winboll.studio.libappbase;
 
 /**
- * @Author ZhanGSKen<zhangsken@qq.com>
- * @Date 2025/01/15 11:11:52
- * @Describe Json Bean 基础类。
+ * @Author ZhanGSKen&豆包大模型<zhangsken@qq.com>
+ * @Date 2025/11/11 20:03
+ * @Describe WinBoLL JSON 数据模型基类（抽象类）
+ * 定义 Json Bean 的核心规范：序列化/反序列化、文件持久化、列表处理等通用逻辑，
+ * 子类（如 APPModel）需实现抽象方法，实现自身字段的 JSON 读写
+ * @param <T> 泛型约束，限定子类必须继承自 BaseBean
  */
 import android.content.Context;
 import android.util.JsonReader;
@@ -16,172 +19,249 @@ import java.util.ArrayList;
 
 public abstract class BaseBean<T extends BaseBean> {
 
+	/** 日志标签，用于当前基类的日志输出标识 */
 	public static final String TAG = "BaseBean";
+	/** JSON 中存储 Bean 类名的字段键（用于校验 Bean 类型一致性） */
 	static final String BEAN_NAME = "BeanName";
 
+	/**
+	 * 无参构造方法（子类需默认实现，支持反射实例化）
+	 */
 	public BaseBean() {}
 
+	/**
+	 * 抽象方法：获取当前 Bean 的全限定类名
+	 * 子类需实现，用于标识 Bean 类型（序列化/校验时使用）
+	 * @return 类的全限定名（如：cc.winboll.studio.libappbase.APPModel）
+	 */
 	public abstract String getName();
 
+	/**
+	 * 获取单个 Bean 的 JSON 持久化文件路径
+	 * 路径：外部存储/应用私有目录/BaseBean/[类名].json
+	 * @param context 上下文（用于获取应用存储目录）
+	 * @return 单个 Bean 的文件绝对路径
+	 */
 	public String getBeanJsonFilePath(Context context) {
-
 		return context.getExternalFilesDir(TAG) + "/" + getName() + ".json";
 	}
 
+	/**
+	 * 获取 Bean 列表的 JSON 持久化文件路径
+	 * 路径：外部存储/应用私有目录/BaseBean/[类名]_List.json
+	 * @param context 上下文（用于获取应用存储目录）
+	 * @return Bean 列表的文件绝对路径
+	 */
 	public String getBeanListJsonFilePath(Context context) {
-
 		return context.getExternalFilesDir(TAG) + "/" + getName() + "_List.json";
 	}
 
+	/**
+	 * 将 Bean 类名写入 JSON（序列化基础字段）
+	 * 子类可重写扩展，添加自身字段的 JSON 写入逻辑
+	 * @param jsonWriter JSON 写入器（用于输出 JSON 数据）
+	 * @throws IOException JSON 写入失败时抛出（如流异常）
+	 */
 	public void writeThisToJsonWriter(JsonWriter jsonWriter) throws IOException {
+		// 写入 Bean 类名字段（用于反序列化时校验类型）
 		jsonWriter.name(BEAN_NAME).value(getName());
 	}
 
+	/**
+	 * 从 JSON 读取字段并初始化 Bean（反序列化基础逻辑）
+	 * 子类需重写，实现自身字段的解析逻辑
+	 * @param jsonReader JSON 读取器（用于读取 JSON 数据）
+	 * @param name 当前解析的 JSON 字段名
+	 * @return true：字段解析成功（当前类处理）；false：字段未处理（需跳过）
+	 * @throws IOException JSON 读取失败时抛出（如流异常）
+	 */
 	public boolean initObjectsFromJsonReader(JsonReader jsonReader, String name) throws IOException {
-        return false;
+		return false; // 基类未处理任何字段，返回 false
 	}
 
+	/**
+	 * 抽象方法：从 JSON 读取器解析并返回 Bean 实例
+	 * 子类需实现，处理自身字段的完整解析逻辑
+	 * @param jsonReader JSON 读取器（用于读取 JSON 数据）
+	 * @return 解析完成的 Bean 实例
+	 * @throws IOException JSON 读取失败时抛出（如流异常）
+	 */
 	abstract public T readBeanFromJsonReader(JsonReader jsonReader) throws IOException;
 
+	/**
+	 * 校验 JSON 文件中的 Bean 列表与目标类是否一致
+	 * 对比文件中每个 Bean 的类名与目标类名，返回不一致信息
+	 * @param szFilePath JSON 文件路径（存储 Bean 列表的文件）
+	 * @param clazz 目标 Bean 类（用于校验类型）
+	 * @return 空串：校验一致；非空串：不一致信息（总数/差异数）或异常信息
+	 * @param <T> 泛型约束，限定为 BaseBean 子类
+	 */
 	public static <T extends BaseBean> String checkIsTheSameBeanListAndFile(String szFilePath, Class<T> clazz) {
 		StringBuilder sbResult = new StringBuilder();
 		String szErrorInfo = "Check Is The Same Bean List And File Error : ";
 
 		try {
-            int nSameCount = 0;
-            int nBeanListCout = 0;
+			int sameCount = 0; // 类名匹配的 Bean 数量
+			int totalCount = 0; // 文件中 Bean 总数量
 
+			// 反射创建目标 Bean 实例（用于获取类名）
 			T beanTemp = clazz.newInstance();
-            String szBeanSimpleName = beanTemp.getName();
-            String szListJson = UTF8FileUtils.readStringFromFile(szFilePath);
-            StringReader stringReader = new StringReader(szListJson);
+			String targetBeanName = beanTemp.getName();
+			// 读取文件中的 JSON 字符串
+			String listJson = UTF8FileUtils.readStringFromFile(szFilePath);
+			StringReader stringReader = new StringReader(listJson);
 			JsonReader jsonReader = new JsonReader(stringReader);
-            jsonReader.beginArray();
+
+			jsonReader.beginArray(); // 开始解析 JSON 数组（Bean 列表）
 			while (jsonReader.hasNext()) {
-                nBeanListCout++;
-                jsonReader.beginObject();
+				totalCount++;
+				jsonReader.beginObject(); // 开始解析单个 Bean 对象
 				while (jsonReader.hasNext()) {
 					String name = jsonReader.nextName();
+					// 只校验 BEAN_NAME 字段，其他字段跳过
 					if (name.equals(BEAN_NAME)) {
-                        if (szBeanSimpleName.equals(jsonReader.nextString())) {
-                            nSameCount++;
+						// 对比当前 Bean 类名与目标类名
+						if (targetBeanName.equals(jsonReader.nextString())) {
+							sameCount++;
 						}
 					} else {
-                        jsonReader.skipValue();
+						jsonReader.skipValue(); // 跳过非目标字段
 					}
 				}
-                jsonReader.endObject();
+				jsonReader.endObject(); // 结束单个 Bean 对象解析
 			}
-            jsonReader.endArray();
+			jsonReader.endArray(); // 结束 JSON 数组解析
 
-            // 返回检查结果
-            if (nSameCount == nBeanListCout) {
-                // 检查一致直接返回空串
-                return "";
+			// 生成校验结果
+			if (sameCount == totalCount) {
+				return ""; // 全部匹配，返回空串
 			} else {
-                // 检查不一致返回对比信息
-                sbResult.append("Total : ");
-                sbResult.append(nBeanListCout);
-                sbResult.append(" Diff : ");
-                sbResult.append(nBeanListCout - nSameCount);
+				// 部分不匹配，返回统计信息
+				sbResult.append("Total : ").append(totalCount)
+					.append(" Diff : ").append(totalCount - sameCount);
 			}
 		} catch (InstantiationException e) {
-            sbResult.append(szErrorInfo);
-            sbResult.append(e);
+			// 反射实例化失败（如无无参构造）
+			sbResult.append(szErrorInfo).append(e);
 			LogUtils.d(TAG, e.getMessage(), Thread.currentThread().getStackTrace());
 		} catch (IllegalAccessException e) {
-            sbResult.append(szErrorInfo);
-            sbResult.append(e);
+			// 反射访问权限异常
+			sbResult.append(szErrorInfo).append(e);
 			LogUtils.d(TAG, e.getMessage(), Thread.currentThread().getStackTrace());
 		} catch (IOException e) {
-            sbResult.append(szErrorInfo);
-            sbResult.append(e);
+			// 文件读取或 JSON 解析异常
+			sbResult.append(szErrorInfo).append(e);
 			LogUtils.d(TAG, e.getMessage(), Thread.currentThread().getStackTrace());
 		}
 		return sbResult.toString();
 	}
 
+	/**
+	 * 将 JSON 字符串解析为目标 Bean 实例
+	 * 通过反射创建 Bean 实例，调用子类解析逻辑完成初始化
+	 * @param szBean JSON 字符串（单个 Bean 的 JSON 数据）
+	 * @param clazz 目标 Bean 类（用于反射实例化）
+	 * @return 解析成功的 Bean 实例；失败返回 null
+	 * @throws IOException JSON 解析失败时抛出
+	 * @param <T> 泛型约束，限定为 BaseBean 子类
+	 */
 	public static <T extends BaseBean> T parseStringToBean(String szBean, Class<T> clazz) throws IOException {
-        // 创建 JsonWriter 对象
 		StringReader stringReader = new StringReader(szBean);
 		JsonReader jsonReader = new JsonReader(stringReader);
+
 		try {
+			// 反射创建 Bean 实例
 			T beanTemp = clazz.newInstance();
+			// 调用子类解析方法，返回解析后的实例
 			return (T) beanTemp.readBeanFromJsonReader(jsonReader);
-        } catch (InstantiationException e) {
-            LogUtils.d(TAG, e.getMessage(), Thread.currentThread().getStackTrace());
-        } catch (IllegalAccessException e) {
+		} catch (InstantiationException | IllegalAccessException e) {
+			// 反射异常日志记录
 			LogUtils.d(TAG, e.getMessage(), Thread.currentThread().getStackTrace());
 		}
 		return null;
 	}
 
+	/**
+	 * 将 JSON 字符串解析为 Bean 列表
+	 * 清空目标列表，将解析后的 Bean 逐个添加到列表中
+	 * @param szBeanList JSON 字符串（Bean 列表的 JSON 数组）
+	 * @param beanList 目标列表（存储解析后的 Bean）
+	 * @param clazz 目标 Bean 类（用于反射实例化）
+	 * @return true：解析成功；false：解析失败
+	 * @param <T> 泛型约束，限定为 BaseBean 子类
+	 */
 	public static <T extends BaseBean> boolean parseStringToBeanList(String szBeanList, ArrayList<T> beanList, Class<T> clazz) {
 		try {
+			// 初始化目标列表（为空则创建，非空则清空）
 			if (beanList == null) {
 				beanList = new ArrayList<T>();
 			} else {
 				beanList.clear();
 			}
+
 			StringReader stringReader = new StringReader(szBeanList);
 			JsonReader jsonReader = new JsonReader(stringReader);
-            jsonReader.beginArray();
+
+			jsonReader.beginArray(); // 开始解析 JSON 数组
 			while (jsonReader.hasNext()) {
+				// 反射创建 Bean 实例，解析并添加到列表
 				T beanTemp = clazz.newInstance();
 				T bean = (T) beanTemp.readBeanFromJsonReader(jsonReader);
 				if (bean != null) {
 					beanList.add(bean);
-                    //LogUtils.d(TAG, "beanList.add(bean)");
 				}
 			}
-            jsonReader.endArray();
+			jsonReader.endArray(); // 结束 JSON 数组解析
 			return true;
-            //LogUtils.d(TAG, "beanList.size() is " + Integer.toString(beanList.size()));
-        } catch (InstantiationException e) {
-            LogUtils.d(TAG, e.getMessage(), Thread.currentThread().getStackTrace());
-        } catch (IllegalAccessException e) {
-            LogUtils.d(TAG, e.getMessage(), Thread.currentThread().getStackTrace());
-        } catch (IOException e) {
+		} catch (InstantiationException | IllegalAccessException | IOException e) {
+			// 异常日志记录
 			LogUtils.d(TAG, e.getMessage(), Thread.currentThread().getStackTrace());
 		}
 		return false;
 	}
 
+	/**
+	 * 重写 toString()，将 Bean 序列化为格式化的 JSON 字符串
+	 * 调用自身序列化逻辑，生成带缩进的 JSON（便于调试）
+	 * @return Bean 的 JSON 字符串；失败返回空串
+	 */
 	@Override
 	public String toString() {
-        // 创建 JsonWriter 对象
 		StringWriter stringWriter = new StringWriter();
 		JsonWriter jsonWriter = new JsonWriter(stringWriter);
-        jsonWriter.setIndent("  ");
-        try {// 开始 JSON 对象
-            jsonWriter.beginObject();
-            // 写入键值对
-            writeThisToJsonWriter(jsonWriter);
-            // 结束 JSON 对象
-            jsonWriter.endObject();
+		jsonWriter.setIndent("  "); // 设置 JSON 缩进（格式化输出）
+
+		try {
+			jsonWriter.beginObject(); // 开始 JSON 对象
+			writeThisToJsonWriter(jsonWriter); // 写入 Bean 字段（子类扩展）
+			jsonWriter.endObject(); // 结束 JSON 对象
 			return stringWriter.toString();
 		} catch (IOException e) {
 			LogUtils.d(TAG, e.getMessage(), Thread.currentThread().getStackTrace());
 		}
-        // 获取 JSON 字符串
 		return "";
 	}
 
+	/**
+	 * 将 Bean 列表序列化为格式化的 JSON 字符串
+	 * 遍历列表，逐个序列化每个 Bean，生成 JSON 数组
+	 * @param beanList 待序列化的 Bean 列表
+	 * @return 列表的 JSON 字符串；失败返回空串
+	 * @param <T> 泛型约束，限定为 BaseBean 子类
+	 */
 	public static <T extends BaseBean> String toStringByBeanList(ArrayList<T> beanList) {
 		try {
 			StringWriter stringWriter = new StringWriter();
 			JsonWriter jsonWriter = new JsonWriter(stringWriter);
-            jsonWriter.setIndent("  ");
-            jsonWriter.beginArray();
+			jsonWriter.setIndent("  "); // 格式化缩进
+
+			jsonWriter.beginArray(); // 开始 JSON 数组
 			for (int i = 0; i < beanList.size(); i++) {
-                // 开始 JSON 对象
-                jsonWriter.beginObject();
-                // 写入键值对
-                beanList.get(i).writeThisToJsonWriter(jsonWriter);
-                // 结束 JSON 对象
-                jsonWriter.endObject();
+				jsonWriter.beginObject(); // 单个 Bean 开始
+				beanList.get(i).writeThisToJsonWriter(jsonWriter); // 调用 Bean 自身序列化
+				jsonWriter.endObject(); // 单个 Bean 结束
 			}
-            jsonWriter.endArray();
+			jsonWriter.endArray(); // 结束 JSON 数组
 			jsonWriter.close();
 			return stringWriter.toString();
 		} catch (IOException e) {
@@ -190,47 +270,74 @@ public abstract class BaseBean<T extends BaseBean> {
 		return "";
 	}
 
-
+	/**
+	 * 从默认路径（getBeanJsonFilePath）加载 Bean 实例
+	 * 读取应用私有目录下的 JSON 文件，解析为目标 Bean
+	 * @param context 上下文（用于获取文件路径）
+	 * @param clazz 目标 Bean 类（用于反射实例化）
+	 * @return 加载成功的 Bean 实例；失败返回 null
+	 * @param <T> 泛型约束，限定为 BaseBean 子类
+	 */
 	public static <T extends BaseBean> T loadBean(Context context, Class<T> clazz) {
 		try {
+			// 反射创建 Bean 实例，获取默认文件路径
 			T beanTemp = clazz.newInstance();
 			return loadBeanFromFile(beanTemp.getBeanJsonFilePath(context), clazz);
-        } catch (InstantiationException e) {
-            LogUtils.d(TAG, e.getMessage(), Thread.currentThread().getStackTrace());
-        } catch (IllegalAccessException e) {
+		} catch (InstantiationException | IllegalAccessException e) {
 			LogUtils.d(TAG, e.getMessage(), Thread.currentThread().getStackTrace());
 		}
 		return null;
 	}
 
+	/**
+	 * 从指定文件路径加载 Bean 实例
+	 * 检查文件是否存在，存在则读取 JSON 并解析为目标 Bean
+	 * @param szFilePath 目标文件路径（存储 Bean 的 JSON 文件）
+	 * @param clazz 目标 Bean 类（用于反射实例化）
+	 * @return 加载成功的 Bean 实例；失败返回 null
+	 * @param <T> 泛型约束，限定为 BaseBean 子类
+	 */
 	public static <T extends BaseBean> T loadBeanFromFile(String szFilePath, Class<T> clazz) {
 		try {
-            try {
-                File fTemp = new File(szFilePath);
-                if (fTemp.exists()) {
-                    T beanTemp = clazz.newInstance();String szJson = UTF8FileUtils.readStringFromFile(szFilePath);
-                    return beanTemp.parseStringToBean(szJson, clazz);
+			File file = new File(szFilePath);
+			if (file.exists()) { // 检查文件是否存在
+				T beanTemp = clazz.newInstance();
+				// 读取文件 JSON 字符串，解析为 Bean
+				String json = UTF8FileUtils.readStringFromFile(szFilePath);
+				return beanTemp.parseStringToBean(json, clazz);
 			}
-            } catch (InstantiationException e) {
-                LogUtils.d(TAG, e.getMessage(), Thread.currentThread().getStackTrace());
-            } catch (IllegalAccessException e) {
-                LogUtils.d(TAG, e.getMessage(), Thread.currentThread().getStackTrace());
-            }
-
-        } catch (IOException e) {
+		} catch (InstantiationException | IllegalAccessException | IOException e) {
 			LogUtils.d(TAG, e.getMessage(), Thread.currentThread().getStackTrace());
 		}
 		return null;
 	}
 
+	/**
+	 * 将 Bean 保存到默认路径（getBeanJsonFilePath）的文件中
+	 * 序列化 Bean 为 JSON，写入应用私有目录下的文件
+	 * @param context 上下文（用于获取文件路径）
+	 * @param bean 待保存的 Bean 实例
+	 * @return true：保存成功；false：保存失败
+	 * @param <T> 泛型约束，限定为 BaseBean 子类
+	 */
 	public static <T extends BaseBean> boolean saveBean(Context context, T bean) {
 		return saveBeanToFile(bean.getBeanJsonFilePath(context), bean);
 	}
 
+	/**
+	 * 将 Bean 保存到指定文件路径
+	 * 序列化 Bean 为 JSON 字符串，写入目标文件（覆盖原有内容）
+	 * @param szFilePath 目标文件路径（保存 JSON 的文件）
+	 * @param bean 待保存的 Bean 实例
+	 * @return true：保存成功；false：保存失败
+	 * @param <T> 泛型约束，限定为 BaseBean 子类
+	 */
 	public static <T extends BaseBean> boolean saveBeanToFile(String szFilePath, T bean) {
 		try {
-            String szJson = bean.toString();
-            UTF8FileUtils.writeStringToFile(szFilePath, szJson);
+			// 序列化 Bean 为 JSON 字符串
+			String json = bean.toString();
+			// 写入文件（UTF-8 编码）
+			UTF8FileUtils.writeStringToFile(szFilePath, json);
 			return true;
 		} catch (IOException e) {
 			LogUtils.d(TAG, e.getMessage(), Thread.currentThread().getStackTrace());
@@ -238,50 +345,92 @@ public abstract class BaseBean<T extends BaseBean> {
 		return false;
 	}
 
+	/**
+	 * 从默认路径（getBeanListJsonFilePath）加载 Bean 列表
+	 * 读取应用私有目录下的列表 JSON 文件，解析并填充到目标列表
+	 * @param context 上下文（用于获取文件路径）
+	 * @param beanListDst 目标列表（存储加载后的 Bean）
+	 * @param clazz 目标 Bean 类（用于反射实例化）
+	 * @return true：加载成功；false：加载失败
+	 * @param <T> 泛型约束，限定为 BaseBean 子类
+	 */
 	public static <T extends BaseBean> boolean loadBeanList(Context context, ArrayList<T> beanListDst, Class<T> clazz) {
 		try {
+			// 反射创建 Bean 实例，获取默认列表文件路径
 			T beanTemp = clazz.newInstance();
 			return loadBeanListFromFile(beanTemp.getBeanListJsonFilePath(context), beanListDst, clazz);
-        } catch (InstantiationException e) {} catch (IllegalAccessException e) {
+		} catch (InstantiationException | IllegalAccessException e) {
 			LogUtils.d(TAG, e.getMessage(), Thread.currentThread().getStackTrace());
 		}
 		return false;
 	}
 
+	/**
+	 * 从指定文件路径加载 Bean 列表
+	 * 检查文件是否存在，存在则读取 JSON 数组，解析并填充到目标列表
+	 * @param szFilePath 目标文件路径（存储列表 JSON 的文件）
+	 * @param beanList 目标列表（存储加载后的 Bean）
+	 * @param clazz 目标 Bean 类（用于反射实例化）
+	 * @return true：加载成功；false：加载失败
+	 * @param <T> 泛型约束，限定为 BaseBean 子类
+	 */
 	public static <T extends BaseBean> boolean loadBeanListFromFile(String szFilePath, ArrayList<T> beanList, Class<T> clazz) {
 		try {
-            File fTemp = new File(szFilePath);
-            if (fTemp.exists()) {
-                String szListJson = UTF8FileUtils.readStringFromFile(szFilePath);
-                return parseStringToBeanList(szListJson, beanList, clazz);
+			File file = new File(szFilePath);
+			if (file.exists()) { // 检查文件是否存在
+				// 读取文件中的 JSON 字符串（Bean 列表数组）
+				String listJson = UTF8FileUtils.readStringFromFile(szFilePath);
+				// 解析 JSON 字符串为 Bean 列表，填充到目标列表
+				return parseStringToBeanList(listJson, beanList, clazz);
 			}
 		} catch (IOException e) {
+			// 日志记录文件读取或解析异常
 			LogUtils.d(TAG, e.getMessage(), Thread.currentThread().getStackTrace());
 		}
 		return false;
 	}
 
+	/**
+	 * 将 Bean 列表保存到默认路径（getBeanListJsonFilePath）的文件中
+	 * 序列化列表为 JSON 数组，写入应用私有目录下的文件
+	 * @param context 上下文（用于获取文件路径）
+	 * @param beanList 待保存的 Bean 列表
+	 * @param clazz 目标 Bean 类（用于反射获取保存路径）
+	 * @return true：保存成功；false：保存失败
+	 * @param <T> 泛型约束，限定为 BaseBean 子类
+	 */
 	public static <T extends BaseBean> boolean saveBeanList(Context context, ArrayList<T> beanList, Class<T> clazz) {
 		try {
+			// 反射创建 Bean 实例，获取默认列表保存路径
 			T beanTemp = clazz.newInstance();
 			return saveBeanListToFile(beanTemp.getBeanListJsonFilePath(context), beanList);
-        } catch (InstantiationException e) {
-            LogUtils.d(TAG, e.getMessage(), Thread.currentThread().getStackTrace());
-        } catch (IllegalAccessException e) {
+		} catch (InstantiationException | IllegalAccessException e) {
+			// 日志记录反射实例化异常
 			LogUtils.d(TAG, e.getMessage(), Thread.currentThread().getStackTrace());
 		}
 		return false;
 	}
 
+	/**
+	 * 将 Bean 列表保存到指定文件路径
+	 * 序列化列表为 JSON 数组字符串，写入目标文件（覆盖原有内容）
+	 * @param szFilePath 目标文件路径（保存列表 JSON 的文件）
+	 * @param beanList 待保存的 Bean 列表
+	 * @return true：保存成功；false：保存失败
+	 * @param <T> 泛型约束，限定为 BaseBean 子类
+	 */
 	public static <T extends BaseBean> boolean saveBeanListToFile(String szFilePath, ArrayList<T> beanList) {
 		try {
-            String szJson = toStringByBeanList(beanList);
-            UTF8FileUtils.writeStringToFile(szFilePath, szJson);
-            //LogUtils.d(TAG, "FileUtil.writeFile beanList.size() is " + Integer.toString(beanList.size()));
+			// 序列化 Bean 列表为 JSON 字符串（数组格式）
+			String json = toStringByBeanList(beanList);
+			// 将 JSON 字符串写入文件（UTF-8 编码）
+			UTF8FileUtils.writeStringToFile(szFilePath, json);
 			return true;
 		} catch (IOException e) {
+			// 日志记录文件写入或序列化异常
 			LogUtils.d(TAG, e.getMessage(), Thread.currentThread().getStackTrace());
 		}
 		return false;
 	}
 }
+

libappbase/src/main/java/cc/winboll/studio/libappbase/CrashHandler.java

@@ -1,9 +1,11 @@
 package cc.winboll.studio.libappbase;
 
 /**
- * @Author ZhanGSKen<zhangsken@qq.com>
- * @Date 2024/08/12 13:22:12
- * @Describe 异常处理类
+ * @Author ZhanGSKen&豆包大模型<zhangsken@qq.com>
+ * @Date 2025/11/11 20:14
+ * @Describe  * 应用全局崩溃处理类（单例逻辑）
+ * 核心功能：捕获应用未捕获异常，记录崩溃日志到文件，启动崩溃报告页面，
+ * 并通过「崩溃保险丝」机制防止重复崩溃，保障基础功能可用
  */
 import android.app.Activity;
 import android.app.Application;
@@ -12,29 +14,22 @@ import android.content.ClipData;
 import android.content.ClipboardManager;
 import android.content.Context;
 import android.content.Intent;
-import android.content.pm.ApplicationInfo;
 import android.content.pm.PackageInfo;
 import android.content.pm.PackageManager;
 import android.content.res.Resources;
 import android.graphics.Color;
-import android.net.Uri;
 import android.os.Build;
 import android.os.Bundle;
 import android.os.Handler;
 import android.os.Looper;
-import android.text.SpannableString;
 import android.text.TextUtils;
-import android.text.style.ForegroundColorSpan;
 import android.view.Menu;
 import android.view.MenuItem;
 import android.view.ViewGroup;
 import android.widget.HorizontalScrollView;
-import android.widget.LinearLayout;
 import android.widget.ScrollView;
 import android.widget.TextView;
 import android.widget.Toast;
-import android.widget.Toolbar;
-import cc.winboll.studio.libappbase.R;
 import java.io.File;
 import java.io.FileInputStream;
 import java.io.FileOutputStream;
@@ -50,159 +45,218 @@ import java.util.Locale;
 
 public final class CrashHandler {
 
+	/** 日志标签，用于当前类的日志输出标识 */
 	public static final String TAG = "CrashHandler";
 
+	/** 崩溃报告页面标题 */
 	public static final String TITTLE = "CrashReport";
 
+	/** Intent 传递崩溃信息的键（用于向崩溃页面传递日志） */
 	public static final String EXTRA_CRASH_INFO = "crashInfo";
 
+	/** SharedPreferences 存储键（用于记录崩溃状态） */
 	final static String PREFS = CrashHandler.class.getName() + "PREFS";
+	/** SharedPreferences 中存储「是否发生崩溃」的键 */
 	final static String PREFS_CRASHHANDLER_ISCRASHHAPPEN = "PREFS_CRASHHANDLER_ISCRASHHAPPEN";
 
+	/** 崩溃保险丝状态文件路径（存储当前熔断等级） */
 	public static String _CrashCountFilePath;
 
+	/** 系统默认的未捕获异常处理器（用于降级处理，避免 CrashHandler 自身崩溃） */
 	public static final UncaughtExceptionHandler DEFAULT_UNCAUGHT_EXCEPTION_HANDLER = Thread.getDefaultUncaughtExceptionHandler();
 
+	/**
+	 * 初始化崩溃处理器（默认存储路径）
+	 * 调用重载方法，崩溃日志默认存储在应用外部私有目录的 crash 文件夹下
+	 * @param app 全局 Application 实例（用于获取存储目录、包信息等）
+	 */
 	public static void init(Application app) {
+		// 初始化崩溃保险丝状态文件路径（外部存储/CrashHandler/IsCrashHandlerCrashHappen.dat）
 		_CrashCountFilePath = app.getExternalFilesDir("CrashHandler") + "/IsCrashHandlerCrashHappen.dat";
 		LogUtils.d(TAG, String.format("_CrashCountFilePath %s", _CrashCountFilePath));
+		// 调用带目录参数的初始化方法，传入 null 使用默认路径
 		init(app, null);
 	}
 
+	/**
+	 * 初始化崩溃处理器（指定日志存储目录）
+	 * 替换系统默认的未捕获异常处理器，自定义崩溃处理逻辑
+	 * @param app 全局 Application 实例
+	 * @param crashDir 崩溃日志存储目录（null 则使用默认路径）
+	 */
 	public static void init(final Application app, final String crashDir) {
+		// 设置自定义未捕获异常处理器
 		Thread.setDefaultUncaughtExceptionHandler(new UncaughtExceptionHandler() {
-
 				@Override
 				public void uncaughtException(Thread thread, Throwable throwable) {
 					try {
+						// 尝试处理崩溃（捕获内部异常，避免 CrashHandler 自身崩溃）
 						tryUncaughtException(thread, throwable);
 					} catch (Throwable e) {
 						e.printStackTrace();
-                        if (DEFAULT_UNCAUGHT_EXCEPTION_HANDLER != null)
+						// 处理失败时，交给系统默认处理器兜底
+						if (DEFAULT_UNCAUGHT_EXCEPTION_HANDLER != null) {
 							DEFAULT_UNCAUGHT_EXCEPTION_HANDLER.uncaughtException(thread, throwable);
 						}
 					}
+				}
 
+				/**
+				 * 实际处理崩溃的核心方法
+				 * 1. 熔断保险丝（记录崩溃次数）；2. 收集崩溃信息；3. 写入日志文件；4. 启动崩溃报告页面
+				 * @param thread 发生崩溃的线程
+				 * @param throwable 崩溃异常对象（包含堆栈信息）
+				 */
 				private void tryUncaughtException(Thread thread, Throwable throwable) {
-                    // 每到这里就燃烧一次保险丝
+					// 触发崩溃保险丝（每次崩溃熔断一次，降低防护等级）
 					AppCrashSafetyWire.getInstance().burnSafetyWire();
 
+					// 格式化崩溃发生时间（用于日志文件名和内容）
 					final String time = new SimpleDateFormat("yyyy_MM_dd-HH_mm_ss", Locale.getDefault()).format(new Date());
-                    File crashFile = new File(TextUtils.isEmpty(crashDir) ? new File(app.getExternalFilesDir(null), "crash")
-                                              : new File(crashDir), "crash_" + time + ".txt");
+					// 创建崩溃日志文件（默认路径：外部存储/crash/[时间].txt）
+					File crashFile = new File(
+						TextUtils.isEmpty(crashDir) ? new File(app.getExternalFilesDir(null), "crash") : new File(crashDir),
+						"crash_" + time + ".txt"
+					);
 
+					// 获取应用版本信息（版本名、版本号）
 					String versionName = "unknown";
 					long versionCode = 0;
 					try {
 						PackageInfo packageInfo = app.getPackageManager().getPackageInfo(app.getPackageName(), 0);
 						versionName = packageInfo.versionName;
-                        versionCode = Build.VERSION.SDK_INT >= 28 ? packageInfo.getLongVersionCode()
-                            : packageInfo.versionCode;
+						// 适配 Android 9.0+（API 28）的版本号获取方式
+						versionCode = Build.VERSION.SDK_INT >= 28 ? packageInfo.getLongVersionCode() : packageInfo.versionCode;
 					} catch (PackageManager.NameNotFoundException ignored) {}
 
-                    String fullStackTrace; {
+					// 将异常堆栈信息转换为字符串
+					String fullStackTrace;
+					{
 						StringWriter sw = new StringWriter();
 						PrintWriter pw = new PrintWriter(sw);
-                        throwable.printStackTrace(pw);
+						throwable.printStackTrace(pw); // 将异常堆栈写入 PrintWriter
 						fullStackTrace = sw.toString();
 						pw.close();
 					}
 
+					// 拼接崩溃信息（设备信息 + 应用信息 + 堆栈信息）
 					StringBuilder sb = new StringBuilder();
 					sb.append("************* Crash Head ****************\n");
 					sb.append("Time Of Crash                        : ").append(time).append("\n");
-                    sb.append("Device Manufacturer                  : ").append(Build.MANUFACTURER).append("\n");
-                    sb.append("Device Model                         : ").append(Build.MODEL).append("\n");
-                    sb.append("Android Version                      : ").append(Build.VERSION.RELEASE).append("\n");
-                    sb.append("Android SDK                          : ").append(Build.VERSION.SDK_INT).append("\n");
-                    sb.append("App VersionName                      : ").append(versionName).append("\n");
-                    sb.append("App VersionCode                      : ").append(versionCode).append("\n");
+					sb.append("Device Manufacturer                  : ").append(Build.MANUFACTURER).append("\n"); // 设备厂商
+					sb.append("Device Model                         : ").append(Build.MODEL).append("\n"); // 设备型号
+					sb.append("Android Version                      : ").append(Build.VERSION.RELEASE).append("\n"); // Android 版本
+					sb.append("Android SDK                          : ").append(Build.VERSION.SDK_INT).append("\n"); // SDK 版本
+					sb.append("App VersionName                      : ").append(versionName).append("\n"); // 应用版本名
+					sb.append("App VersionCode                      : ").append(versionCode).append("\n"); // 应用版本号
 					sb.append("************* Crash Head ****************\n");
-                    sb.append("\n").append(fullStackTrace);
+					sb.append("\n").append(fullStackTrace); // 拼接异常堆栈
 
-                    String errorLog = sb.toString();
+					final String errorLog = sb.toString();
 
+					// 将崩溃日志写入文件（忽略写入失败）
 					try {
 						writeFile(crashFile, errorLog);
 					} catch (IOException ignored) {}
 
+					// 启动崩溃报告页面（标签用于代码块折叠）
 					gotoCrashActiviy: {
 						Intent intent = new Intent();
 						LogUtils.d(TAG, "gotoCrashActiviy: ");
+
+						// 根据保险丝状态选择启动的崩溃页面
 						if (AppCrashSafetyWire.getInstance().isAppCrashSafetyWireOK()) {
 							LogUtils.d(TAG, "gotoCrashActiviy: isAppCrashSafetyWireOK");
+							// 保险丝正常：启动自定义样式的崩溃报告页面（GlobalCrashActivity）
 							intent.setClass(app, GlobalCrashActivity.class);
-                            intent.putExtra(EXTRA_CRASH_INFO, errorLog);
-                            // 如果发生了 CrashHandler 内部崩溃， 就调用基础的应用崩溃显示类
-//                            intent.setClass(app, GlobalCrashActiviy.class);
-//                            intent.putExtra(GlobalCrashActiviy.EXTRA_CRASH_INFO, errorLog);
+							intent.putExtra(EXTRA_CRASH_INFO, errorLog); // 传递崩溃日志
 						} else {
 							LogUtils.d(TAG, "gotoCrashActiviy: else");
-                            // 正常状态调用进阶的应用崩溃显示页
+							// 保险丝熔断：启动基础版崩溃页面（CrashActivity，避免复杂页面再次崩溃）
 							intent.setClass(app, CrashActivity.class);
 							intent.putExtra(EXTRA_CRASH_INFO, errorLog);
 						}
 
-
-
-//                        intent.setClass(app, CrashActiviy.class);
-//                        intent.putExtra(CrashActiviy.EXTRA_CRASH_INFO, errorLog);
-
-
+						// 设置意图标志：清除原有任务栈，创建新任务（避免回到崩溃前页面）
 						intent.addFlags(
 							Intent.FLAG_ACTIVITY_NEW_TASK
-                            | Intent.FLAG_ACTIVITY_CLEAR_TOP | Intent.FLAG_ACTIVITY_CLEAR_TASK
+							| Intent.FLAG_ACTIVITY_CLEAR_TOP
+							| Intent.FLAG_ACTIVITY_CLEAR_TASK
 						);
 
 						try {
+							// 启动崩溃页面，终止当前进程（确保完全重启）
 							app.startActivity(intent);
 							android.os.Process.killProcess(android.os.Process.myPid());
 							System.exit(0);
 						} catch (ActivityNotFoundException e) {
+							// 未找到崩溃页面（如未在 Manifest 注册），交给系统默认处理器
 							e.printStackTrace();
-                            if (DEFAULT_UNCAUGHT_EXCEPTION_HANDLER != null)
+							if (DEFAULT_UNCAUGHT_EXCEPTION_HANDLER != null) {
 								DEFAULT_UNCAUGHT_EXCEPTION_HANDLER.uncaughtException(thread, throwable);
+							}
 						} catch (Exception e) {
+							// 其他异常，兜底处理
 							e.printStackTrace();
-                            if (DEFAULT_UNCAUGHT_EXCEPTION_HANDLER != null)
+							if (DEFAULT_UNCAUGHT_EXCEPTION_HANDLER != null) {
 								DEFAULT_UNCAUGHT_EXCEPTION_HANDLER.uncaughtException(thread, throwable);
 							}
 						}
-
+					}
 				}
 
+				/**
+				 * 将字符串内容写入文件（创建父目录、覆盖写入）
+				 * @param file 目标文件（包含路径）
+				 * @param content 待写入的内容（崩溃日志）
+				 * @throws IOException 文件创建或写入失败时抛出
+				 */
 				private void writeFile(File file, String content) throws IOException {
 					File parentFile = file.getParentFile();
+					// 父目录不存在则创建
 					if (parentFile != null && !parentFile.exists()) {
 						parentFile.mkdirs();
 					}
-                    file.createNewFile();
+					file.createNewFile(); // 创建文件
 					FileOutputStream fos = new FileOutputStream(file);
-                    fos.write(content.getBytes());
+					fos.write(content.getBytes()); // 写入内容（默认 UTF-8 编码）
 					try {
-                        fos.close();
+						fos.close(); // 关闭流
 					} catch (IOException e) {}
 				}
-
 			});
 	}
 
-    //
-    // 应用崩溃保险丝
-    //
+	/**
+	 * 应用崩溃保险丝内部类（单例）
+	 * 核心作用：限制短时间内重复崩溃，通过「熔断等级」控制崩溃页面启动策略
+	 * 等级范围：MINI（1）~ MAX（2），每次崩溃等级-1，熔断后启动基础版崩溃页面
+	 */
 	public static final class AppCrashSafetyWire {
 
-        volatile static AppCrashSafetyWire _AppCrashSafetyWire;
+		/** 单例实例（volatile 保证多线程可见性） */
+		private static volatile AppCrashSafetyWire _AppCrashSafetyWire;
 
-        volatile Integer currentSafetyLevel; // 熔断值，为 0 表示熔断了。
+		/** 当前熔断等级（1：最低防护；2：最高防护；≤0：熔断） */
+		private volatile Integer currentSafetyLevel;
+		/** 最低熔断等级（1，再崩溃则熔断） */
 		private static final int _MINI = 1;
+		/** 最高熔断等级（2，初始状态） */
 		private static final int _MAX = 2;
 
-        AppCrashSafetyWire() {
+		/**
+		 * 私有构造方法（单例模式，禁止外部实例化）
+		 * 初始化时加载本地存储的熔断等级
+		 */
+		private AppCrashSafetyWire() {
 			LogUtils.d(TAG, "AppCrashSafetyWire()");
 			currentSafetyLevel = loadCurrentSafetyLevel();
 		}
 
+		/**
+		 * 获取单例实例（双重检查锁定，线程安全）
+		 * @return AppCrashSafetyWire 单例
+		 */
 		public static synchronized AppCrashSafetyWire getInstance() {
 			if (_AppCrashSafetyWire == null) {
 				_AppCrashSafetyWire = new AppCrashSafetyWire();
@@ -210,18 +264,31 @@ public final class CrashHandler {
 			return _AppCrashSafetyWire;
 		}
 
+		/**
+		 * 设置当前熔断等级（内存中）
+		 * @param currentSafetyLevel 目标等级（1~2）
+		 */
 		public void setCurrentSafetyLevel(int currentSafetyLevel) {
 			this.currentSafetyLevel = currentSafetyLevel;
 		}
 
+		/**
+		 * 获取当前熔断等级（内存中）
+		 * @return 当前等级（1~2 或 null）
+		 */
 		public int getCurrentSafetyLevel() {
 			return currentSafetyLevel;
 		}
 
+		/**
+		 * 保存熔断等级到本地文件（持久化，重启应用生效）
+		 * @param currentSafetyLevel 待保存的等级
+		 */
 		public void saveCurrentSafetyLevel(int currentSafetyLevel) {
 			LogUtils.d(TAG, "saveCurrentSafetyLevel()");
 			this.currentSafetyLevel = currentSafetyLevel;
 			try {
+				// 序列化等级到文件（ObjectOutputStream 写入 int）
 				ObjectOutputStream oos = new ObjectOutputStream(new FileOutputStream(_CrashCountFilePath));
 				oos.writeInt(currentSafetyLevel);
 				oos.flush();
@@ -232,15 +299,21 @@ public final class CrashHandler {
 			}
 		}
 
+		/**
+		 * 从本地文件加载熔断等级（应用启动时初始化）
+		 * @return 加载的等级（文件不存在则初始化为 MAX（2））
+		 */
 		public int loadCurrentSafetyLevel() {
 			LogUtils.d(TAG, "loadCurrentSafetyLevel()");
 			try {
 				File f = new File(_CrashCountFilePath);
 				if (f.exists()) {
+					// 反序列化从文件读取等级
 					ObjectInputStream ois = new ObjectInputStream(new FileInputStream(_CrashCountFilePath));
 					currentSafetyLevel = ois.readInt();
 					LogUtils.d(TAG, String.format("loadCurrentSafetyLevel() readInt currentSafetyLevel %d", currentSafetyLevel));
 				} else {
+					// 文件不存在，初始化等级为最高（2）并保存
 					currentSafetyLevel = _MAX;
 					LogUtils.d(TAG, String.format("loadCurrentSafetyLevel() currentSafetyLevel init to _MAX->%d", _MAX));
 					saveCurrentSafetyLevel(currentSafetyLevel);
@@ -251,30 +324,34 @@ public final class CrashHandler {
 			return currentSafetyLevel;
 		}
 
+		/**
+		 * 熔断保险丝（每次崩溃调用，降低防护等级）
+		 * @return 熔断后是否仍在防护范围内（true：是；false：已熔断）
+		 */
 		boolean burnSafetyWire() {
 			LogUtils.d(TAG, "burnSafetyWire()");
-            // 崩溃计数进入崩溃保险值
+			// 加载当前等级
 			int safeLevel = loadCurrentSafetyLevel();
+			// 若在防护范围内（1~2），等级-1 并保存
 			if (isSafetyWireWorking(safeLevel)) {
-                // 如果保险丝未熔断, 就增加一次熔断值
 				LogUtils.d(TAG, "burnSafetyWire() use");
 				saveCurrentSafetyLevel(safeLevel - 1);
+				// 返回熔断后的状态
 				return isSafetyWireWorking(safeLevel - 1);
 			}
 			return false;
 		}
 
+		/**
+		 * 检查熔断等级是否在有效范围内（1~2）
+		 * @param safetyLevel 待检查的等级
+		 * @return true：在范围内（防护有效）；false：超出范围（已熔断）
+		 */
 		boolean isSafetyWireWorking(int safetyLevel) {
 			LogUtils.d(TAG, "isSafetyWireOK()");
-            //safetyLevel = _MINI;
-            //safetyLevel = _MINI - 1;
-            //safetyLevel = _MINI + 1;
-            //safetyLevel = _MAX;
-            //safetyLevel = _MAX + 1;
 			LogUtils.d(TAG, String.format("SafetyLevel %d", safetyLevel));
 
 			if (safetyLevel >= _MINI && safetyLevel <= _MAX) {
-                // 如果在保险值之内
 				LogUtils.d(TAG, String.format("In Safety Level"));
 				return true;
 			}
@@ -282,109 +359,168 @@ public final class CrashHandler {
 			return false;
 		}
 
+		/**
+		 * 立即恢复熔断等级到最高（2）
+		 * 用于重启应用后重置防护状态
+		 */
 		void resumeToMaximumImmediately() {
 			LogUtils.d(TAG, "resumeToMaximumImmediately() call saveCurrentSafetyLevel(_MAX)");
 			AppCrashSafetyWire.getInstance().saveCurrentSafetyLevel(_MAX);
 		}
 
+		/**
+		 * 关闭防护（设置等级为最低（1））
+		 * 下次崩溃直接熔断
+		 */
 		void off() {
 			LogUtils.d(TAG, "off()");
 			saveCurrentSafetyLevel(_MINI);
 		}
 
+		/**
+		 * 检查当前保险丝是否有效（防护未熔断）
+		 * @return true：有效（等级 1~2）；false：已熔断
+		 */
 		boolean isAppCrashSafetyWireOK() {
 			LogUtils.d(TAG, "isAppCrashSafetyWireOK()");
 			currentSafetyLevel = loadCurrentSafetyLevel();
 			return isSafetyWireWorking(currentSafetyLevel);
 		}
 
-        // 调用函数以启用持续崩溃保险，从而调用 CrashHandler 内部崩溃处理窗口
+		/**
+		 * 延迟恢复保险丝到最高等级（500ms 后）
+		 * 核心作用：崩溃页面启动后，若下次即将熔断，提前恢复防护等级，避免持续崩溃
+		 * @param context 上下文（用于获取主线程 Handler）
+		 */
 		void postResumeCrashSafetyWireHandler(final Context context) {
+			// 主线程延迟 500ms 执行（避免页面启动时阻塞）
 			new Handler(Looper.getMainLooper()).postDelayed(new Runnable() {
 					@Override
 					public void run() {
 						LogUtils.d(TAG, "Handler run()");
+						// 检查：若当前等级-1 后超出防护范围（即将熔断），则恢复到最高等级
 						if (!AppCrashSafetyWire.getInstance().isSafetyWireWorking(currentSafetyLevel - 1)) {
-                            // 如果下一次应用崩溃时，保险丝熔断，则先恢复保险丝满能状态
-                            // 进程持续运行时，恢复保险丝熔断值
-                            //Resume to maximum
 							AppCrashSafetyWire.getInstance().resumeToMaximumImmediately();
-                            LogUtils.d(TAG, "postResumeCrashSafetyWireHandler");
+							LogUtils.d(TAG, "postResumeCrashSafetyWireHandler: 恢复保险丝到最高等级");
 						}
 					}
 				}, 500);
 		}
 	}
 
+	/**
+	 * 基础版崩溃报告页面（保险丝熔断时启动）
+	 * 极简实现：仅展示崩溃日志，提供复制、重启功能，避免复杂布局导致二次崩溃
+	 */
 	public static final class CrashActivity extends Activity implements MenuItem.OnMenuItemClickListener {
+		/** 菜单标识：复制崩溃日志 */
 		private static final int MENUITEM_COPY = 0;
+		/** 菜单标识：重启应用 */
 		private static final int MENUITEM_RESTART = 1;
 
+		/** 崩溃日志文本（从 CrashHandler 传递过来） */
 		private String mLog;
 
 		@Override
 		protected void onCreate(Bundle savedInstanceState) {
 			super.onCreate(savedInstanceState);
+			// 初始化崩溃保险丝延迟恢复机制
 			AppCrashSafetyWire.getInstance().postResumeCrashSafetyWireHandler(getApplicationContext());
 
+			// 获取传递的崩溃日志
 			mLog = getIntent().getStringExtra(EXTRA_CRASH_INFO);
+			// 设置系统默认主题（避免自定义主题冲突）
 			setTheme(android.R.style.Theme_DeviceDefault_Light_DarkActionBar);
+
+			// 动态创建布局（避免 XML 布局加载异常）
 			setContentView: {
+				// 垂直滚动视图（处理日志过长）
 				ScrollView contentView = new ScrollView(this);
 				contentView.setFillViewport(true);
 
+				// 水平滚动视图（处理日志行过长）
 				HorizontalScrollView hw = new HorizontalScrollView(this);
-                hw.setBackgroundColor(Color.GRAY);
-                TextView message = new TextView(this); {
-                    int padding = dp2px(16);
-                    message.setPadding(padding, padding, padding, padding);
-                    message.setText(mLog);
-                    message.setTextColor(Color.BLACK);
-                    message.setTextIsSelectable(true);
-                }
-                hw.addView(message);
+				hw.setBackgroundColor(Color.GRAY); // 背景色设为灰色
 
+				// 日志显示文本框
+				TextView message = new TextView(this);
+				{
+					int padding = dp2px(16); // 内边距 16dp（适配不同屏幕）
+					message.setPadding(padding, padding, padding, padding);
+					message.setText(mLog); // 设置崩溃日志
+					message.setTextColor(Color.BLACK); // 文字黑色
+					message.setTextIsSelectable(true); // 支持文本选择（便于手动复制）
+				}
+
+				// 组装布局：TextView -> HorizontalScrollView -> ScrollView
+				hw.addView(message);
 				contentView.addView(hw, ViewGroup.LayoutParams.MATCH_PARENT, ViewGroup.LayoutParams.MATCH_PARENT);
+				// 设置当前 Activity 布局
 				setContentView(contentView);
+
+				// 配置 ActionBar 标题和副标题
 				getActionBar().setTitle(TITTLE);
 				getActionBar().setSubtitle(GlobalApplication.class.getSimpleName() + " Error");
 			}
 		}
 
+		/**
+		 * 重写返回键逻辑：点击返回键直接重启应用
+		 */
 		@Override
 		public void onBackPressed() {
 			restart();
 		}
 
+		/**
+		 * 重启当前应用（与 GlobalCrashActivity 逻辑一致）
+		 * 清除任务栈，启动主 Activity，终止当前进程
+		 */
 		private void restart() {
 			PackageManager pm = getPackageManager();
+			// 获取应用启动意图（默认启动主 Activity）
 			Intent intent = pm.getLaunchIntentForPackage(getPackageName());
 			if (intent != null) {
+				// 设置意图标志：清除原有任务栈，创建新任务
 				intent.addFlags(
 					Intent.FLAG_ACTIVITY_NEW_TASK
-                    | Intent.FLAG_ACTIVITY_CLEAR_TOP | Intent.FLAG_ACTIVITY_CLEAR_TASK
+					| Intent.FLAG_ACTIVITY_CLEAR_TOP
+					| Intent.FLAG_ACTIVITY_CLEAR_TASK
 				);
 				startActivity(intent);
 			}
+			// 关闭当前页面，终止进程，确保完全重启
 			finish();
 			android.os.Process.killProcess(android.os.Process.myPid());
 			System.exit(0);
 		}
 
+		/**
+		 * dp 转 px（适配不同屏幕密度）
+		 * @param dpValue dp 值
+		 * @return 转换后的 px 值
+		 */
 		private int dp2px(final float dpValue) {
 			final float scale = Resources.getSystem().getDisplayMetrics().density;
-            return (int) (dpValue * scale + 0.5f);
+			return (int) (dpValue * scale + 0.5f); // 四舍五入确保精度
 		}
 
+		/**
+		 * 菜单点击事件回调（处理复制、重启）
+		 * @param item 被点击的菜单项
+		 * @return false：不消费事件（保持默认行为）
+		 */
 		@Override
 		public boolean onMenuItemClick(MenuItem item) {
 			switch (item.getItemId()) {
 				case MENUITEM_COPY:
+					// 复制日志到剪贴板
 					ClipboardManager cm = (ClipboardManager) getSystemService(Context.CLIPBOARD_SERVICE);
 					cm.setPrimaryClip(ClipData.newPlainText(getPackageName(), mLog));
 					Toast.makeText(getApplication(), "The text is copied.", Toast.LENGTH_SHORT).show();
 					break;
 				case MENUITEM_RESTART:
+					// 恢复保险丝到最高等级，然后重启应用
 					AppCrashSafetyWire.getInstance().resumeToMaximumImmediately();
 					restart();
 					break;
@@ -392,11 +528,20 @@ public final class CrashHandler {
 			return false;
 		}
 
+		/**
+		 * 创建 ActionBar 菜单（添加复制、重启项）
+		 * @param menu 菜单容器
+		 * @return true：显示菜单
+		 */
 		@Override
 		public boolean onCreateOptionsMenu(Menu menu) {
-            menu.add(0, MENUITEM_COPY, 0, "Copy").setOnMenuItemClickListener(this)
+			// 添加「复制」菜单：有空间时显示在 ActionBar，否则放入溢出菜单
+			menu.add(0, MENUITEM_COPY, 0, "Copy")
+				.setOnMenuItemClickListener(this)
 				.setShowAsAction(MenuItem.SHOW_AS_ACTION_IF_ROOM);
-            menu.add(0, MENUITEM_RESTART, 0, "Restart").setOnMenuItemClickListener(this)
+			// 添加「重启」菜单：同上
+			menu.add(0, MENUITEM_RESTART, 0, "Restart")
+				.setOnMenuItemClickListener(this)
 				.setShowAsAction(MenuItem.SHOW_AS_ACTION_IF_ROOM);
 			return true;
 		}

libappbase/src/main/java/cc/winboll/studio/libappbase/GlobalApplication.java

@@ -1,70 +1,134 @@
 package cc.winboll.studio.libappbase;
 
 /**
- * @Author ZhanGSKen<zhangsken@qq.com>
- * @Date 2025/01/05 10:10:23
- * @Describe 全局应用类
+ * @Author ZhanGSKen&豆包大模型<zhangsken@qq.com>
+ * @Date 2025/11/11 19:56
+ * @Describe 全局 Application 类，用于初始化应用核心组件、管理全局状态（如调试模式）
+ * 需在 AndroidManifest.xml 中配置 android:name=".GlobalApplication" 使其生效
  */
 import android.app.Application;
 import android.content.Context;
 import android.content.pm.ApplicationInfo;
 import android.content.pm.PackageManager;
-import cc.winboll.studio.libappbase.GlobalApplication;
+import android.content.pm.PackageManager.NameNotFoundException;
 
 public class GlobalApplication extends Application {
 
+    /** 日志标签 */
     public static final String TAG = "GlobalApplication";
 
-    // 应用是否处于调试状态
-    volatile static boolean isDebuging = false;
+    /**
+     * 应用调试模式标记（volatile 保证多线程可见性）
+     * true：调试模式（开启日志、调试功能）；false：正式模式（关闭调试相关功能）
+     */
+    private static volatile boolean isDebugging = false;
 
-    public static void setIsDebuging(boolean isDebuging) {
-        GlobalApplication.isDebuging = isDebuging;
+    /**
+     * 设置应用调试模式
+     * @param debugging 调试模式状态（true/false）
+     */
+    public static void setIsDebugging(boolean debugging) {
+        isDebugging = debugging;
     }
 
+    /**
+     * 保存调试模式状态到本地文件（持久化存储，重启应用后生效）
+     * @param application 全局 Application 实例（通过 getInstance() 获取更规范，此处保留原有参数）
+     */
     public static void saveDebugStatus(GlobalApplication application) {
-        APPModel.saveBeanToFile(application.getAPPModelFilePath(application), new APPModel(GlobalApplication.isDebuging));
+        // 将调试状态封装为 APPModel 并保存到文件
+        APPModel.saveBeanToFile(
+            getAppModelFilePath(application), 
+            new APPModel(isDebugging)
+        );
     }
 
-    static String getAPPModelFilePath(GlobalApplication application) {
+    /**
+     * 获取 APPModel 配置文件的存储路径
+     * 路径：应用私有数据目录 / APPModel.json（仅当前应用可访问，安全）
+     * @param application 全局 Application 实例
+     * @return 配置文件绝对路径
+     */
+    private static String getAppModelFilePath(GlobalApplication application) {
         return application.getDataDir().getPath() + "/APPModel.json";
     }
 
-    public static boolean isDebuging() {
-        return isDebuging;
+    /**
+     * 获取当前应用调试模式状态
+     * @return true：调试模式；false：正式模式
+     */
+    public static boolean isDebugging() {
+        return isDebugging;
     }
 
+    /**
+     * 应用启动时初始化（仅执行一次）
+     * 初始化核心框架、恢复调试状态、配置全局异常处理等
+     */
     @Override
     public void onCreate() {
         super.onCreate();
 
-        setIsDebuging(true);
-        // 添加日志模块
-        LogUtils.init(this);
-        // 设置应用异常处理窗口
-        CrashHandler.init(this);
-        // 初始化 Toast 框架
-        ToastUtils.init(this);
+        // 初始化基础组件（日志、崩溃处理、Toast）
+        initCoreComponents();
+        // 恢复/初始化调试模式状态（从本地文件读取，无文件则默认关闭调试）
+        restoreDebugStatus();
+    }
+
+    /**
+     * 初始化应用核心组件（日志、崩溃处理、Toast 框架）
+     */
+    private void initCoreComponents() {
+        // 初始化日志工具（传入 Application 上下文）
+        LogUtils.init(this);
+        // 初始化全局异常处理器（捕获应用崩溃信息，用于调试或上报）
+        CrashHandler.init(this);
+        // 初始化 Toast 工具（统一 Toast 样式、避免内存泄漏等）
+        ToastUtils.init(this);
+    }
+
+    /**
+     * 恢复调试模式状态（从本地配置文件读取）
+     * 1. 读取本地 APPModel.json 文件
+     * 2. 读取成功：使用保存的调试状态；读取失败（文件不存在）：默认关闭调试并创建配置文件
+     */
+    private void restoreDebugStatus() {
+        // 从文件加载 APPModel 实例（存储调试状态的模型类）
+        APPModel appModel = APPModel.loadBeanFromFile(
+            getAppModelFilePath(this), 
+            APPModel.class
+        );
 
-        // 应用保存的调试标志
-        APPModel appModel = APPModel.loadBeanFromFile(getAPPModelFilePath(this), APPModel.class);
         if (appModel == null) {
-            setIsDebuging(false);
+            // 配置文件不存在，默认关闭调试模式并创建文件
+            setIsDebugging(false);
             saveDebugStatus(this);
         } else {
-            setIsDebuging(appModel.isDebuging());
+            // 配置文件存在，使用保存的调试状态
+            setIsDebugging(appModel.isDebugging());
         }
     }
 
+    /**
+     * 获取应用名称（从 AndroidManifest.xml 的 android:label 读取）
+     * @param context 上下文（建议传入 Application 上下文，避免内存泄漏）
+     * @return 应用名称（读取失败返回 null）
+     */
     public static String getAppName(Context context) {
         PackageManager packageManager = context.getPackageManager();
         try {
+            // 获取应用信息（包含应用名称、图标等）
             ApplicationInfo applicationInfo = packageManager.getApplicationInfo(
-                context.getPackageName(), 0);
+                context.getPackageName(),  // 当前应用包名
+                0  // 额外标志（0 表示默认获取基本信息）
+            );
+            // 从应用信息中获取应用名称（支持多语言）
             return (String) packageManager.getApplicationLabel(applicationInfo);
-        } catch (PackageManager.NameNotFoundException e) {
+        } catch (NameNotFoundException e) {
+            // 包名不存在（理论上不会发生，捕获异常避免崩溃）
             e.printStackTrace();
         }
         return null;
     }
 }
+

libappbase/src/main/java/cc/winboll/studio/libappbase/GlobalCrashActivity.java

@@ -1,8 +1,11 @@
 package cc.winboll.studio.libappbase;
 
 /**
- * @Author ZhanGSKen<zhangsken@qq.com>
- * @Date 2025/02/11 00:14:05
+ * @Author ZhanGSKen&豆包大模型<zhangsken@qq.com>
+ * @Date 2025/11/11 19:58
+ * @Describe 应用异常报告观察活动窗口类
+ * 核心功能：应用发生未捕获崩溃时，由 CrashHandler 启动此页面，展示崩溃日志详情，
+ * 并提供「复制日志」「重启应用」操作入口，便于开发者定位问题和用户恢复应用
  */
 import android.app.Activity;
 import android.content.ClipData;
@@ -18,77 +21,166 @@ import cc.winboll.studio.libappbase.R;
 
 public final class GlobalCrashActivity extends Activity implements MenuItem.OnMenuItemClickListener {
 
-    private static final int MENUITEM_COPY = 0;
-    private static final int MENUITEM_RESTART = 1;
-
-    GlobalCrashReportView mGlobalCrashReportView;
-    String mLog;
-    
-
+    /** 日志标签（用于调试日志输出，唯一标识当前 Activity） */
     public static final String TAG = "GlobalCrashActivity";
 
+    /** 菜单标识：复制崩溃日志（用于区分菜单项点击事件） */
+    private static final int MENU_ITEM_COPY = 0;
+    /** 菜单标识：重启应用（用于区分菜单项点击事件） */
+    private static final int MENU_ITEM_RESTART = 1;
+
+    /** 崩溃报告展示自定义视图 */
+    // 负责渲染崩溃日志文本、提供 Toolbar 容器，封装了日志展示和菜单样式控制逻辑
+    private GlobalCrashReportView mCrashReportView;
+
+    /** 崩溃日志文本内容 */
+    // 从 CrashHandler 通过 Intent 传递过来，包含异常堆栈、设备信息等完整崩溃数据
+    private String mCrashLog;
+
+    /**
+     * Activity 创建时初始化（生命周期核心方法，仅执行一次）
+     * @param savedInstanceState 保存的实例状态（崩溃页面无需恢复状态，此处仅作兼容）
+     */
     @Override
     protected void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
-        CrashHandler.AppCrashSafetyWire.getInstance().postResumeCrashSafetyWireHandler(getApplicationContext());
 
-        mLog = getIntent().getStringExtra(CrashHandler.EXTRA_CRASH_INFO);
-        //setTheme(android.R.style.Theme_Holo_Light_NoActionBar);
-        //setTheme(R.style.APPBaseTheme);
+        // 初始化崩溃安全防护机制
+        // 作用：防止应用重启后短时间内再次崩溃，由 CrashHandler 内部实现防护逻辑
+        CrashHandler.AppCrashSafetyWire.getInstance()
+			.postResumeCrashSafetyWireHandler(getApplicationContext());
+
+        // 从 Intent 中获取崩溃日志数据（EXTRA_CRASH_INFO 为 CrashHandler 定义的常量键）
+        mCrashLog = getIntent().getStringExtra(CrashHandler.EXTRA_CRASH_INFO);
+
+        // 设置当前 Activity 的布局文件（展示崩溃报告的 UI 结构）
         setContentView(R.layout.activity_globalcrash);
-        mGlobalCrashReportView = findViewById(R.id.activityglobalcrashGlobalCrashReportView1);
-        mGlobalCrashReportView.setReport(mLog);
-        setActionBar(mGlobalCrashReportView.getToolbar());
 
+        // 初始化崩溃报告展示视图（通过布局 ID 找到自定义 View 实例）
+        mCrashReportView = findViewById(R.id.activityglobalcrashGlobalCrashReportView1);
+        // 将崩溃日志设置到视图中，由自定义 View 负责排版和显示
+        mCrashReportView.setReport(mCrashLog);
+
+        // 设置页面的 ActionBar（复用自定义 View 中的 Toolbar 作为系统 ActionBar）
+        setActionBar(mCrashReportView.getToolbar());
+
+        // 配置 ActionBar 标题和副标题（非空判断避免空指针异常）
+        if (getActionBar() != null) {
+            // 设置标题：使用 CrashHandler 中定义的统一标题（如 "应用崩溃报告"）
             getActionBar().setTitle(CrashHandler.TITTLE);
+            // 设置副标题：显示当前应用名称（从全局 Application 工具方法获取）
             getActionBar().setSubtitle(GlobalApplication.getAppName(getApplicationContext()));
         }
+    }
 
+    /**
+     * 重写返回键点击事件
+     * 逻辑：点击手机返回键时，直接重启应用（而非返回上一页，因崩溃后上一页状态可能异常）
+     */
     @Override
     public void onBackPressed() {
-        restart();
+        restartApp();
     }
 
-    private void restart() {
-        PackageManager pm = getPackageManager();
-        Intent intent = pm.getLaunchIntentForPackage(getPackageName());
-        if (intent != null) {
-            intent.addFlags(
-                Intent.FLAG_ACTIVITY_NEW_TASK
-                | Intent.FLAG_ACTIVITY_CLEAR_TOP | Intent.FLAG_ACTIVITY_CLEAR_TASK
-            );
-            startActivity(intent);
+    /**
+     * 重启当前应用（核心工具方法）
+     * 实现逻辑：
+     * 1. 获取应用的启动意图（默认启动 AndroidManifest 中配置的主 Activity）
+     * 2. 设置意图标志，清除原有任务栈，避免残留异常页面
+     * 3. 启动主 Activity 并终止当前进程，确保应用完全重启
+     */
+    private void restartApp() {
+        // 获取 PackageManager 实例（用于获取应用相关信息和意图）
+        PackageManager packageManager = getPackageManager();
+        // 获取应用的启动意图（参数为当前应用包名，返回主 Activity 的意图）
+        Intent launchIntent = packageManager.getLaunchIntentForPackage(getPackageName());
+
+        if (launchIntent != null) {
+            // 设置意图标志：
+            // FLAG_ACTIVITY_NEW_TASK：创建新的任务栈启动 Activity
+            // FLAG_ACTIVITY_CLEAR_TOP：清除目标 Activity 之上的所有 Activity
+            // FLAG_ACTIVITY_CLEAR_TASK：清除当前任务栈中的所有 Activity
+            launchIntent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK
+								  | Intent.FLAG_ACTIVITY_CLEAR_TOP
+								  | Intent.FLAG_ACTIVITY_CLEAR_TASK);
+            // 启动应用主 Activity
+            startActivity(launchIntent);
         }
+
+        // 关闭当前崩溃报告页面
         finish();
+        // 终止当前应用进程（确保释放所有资源，避免内存泄漏）
         android.os.Process.killProcess(android.os.Process.myPid());
+        // 强制退出虚拟机（彻底终止应用，防止残留线程继续运行）
         System.exit(0);
     }
 
+    /**
+     * 菜单项点击事件回调（实现 MenuItem.OnMenuItemClickListener 接口）
+     * @param item 被点击的菜单项实例
+     * @return boolean：true 表示事件已消费，不再向下传递；false 表示未消费
+     */
     @Override
     public boolean onMenuItemClick(MenuItem item) {
+        // 根据菜单项 ID 判断点击的是哪个功能
         switch (item.getItemId()) {
-            case MENUITEM_COPY: 
-                ClipboardManager cm = (ClipboardManager) getSystemService(Context.CLIPBOARD_SERVICE);
-                cm.setPrimaryClip(ClipData.newPlainText(getPackageName(), mLog));
-                Toast.makeText(getApplication(), "The text is copied.", Toast.LENGTH_SHORT).show();
+            case MENU_ITEM_COPY:
+                // 点击「复制」菜单，执行复制崩溃日志到剪贴板
+                copyCrashLogToClipboard();
                 break;
-            case MENUITEM_RESTART: 
+            case MENU_ITEM_RESTART:
+                // 点击「重启」菜单：先恢复崩溃防护机制到最大等级，再重启应用
                 CrashHandler.AppCrashSafetyWire.getInstance().resumeToMaximumImmediately();
-                restart();
+                restartApp();
                 break;
         }
         return false;
     }
 
+    /**
+     * 创建页面顶部菜单（ActionBar 菜单）
+     * @param menu 菜单容器，用于添加菜单项
+     * @return boolean：true 表示显示菜单；false 表示不显示
+     */
     @Override
     public boolean onCreateOptionsMenu(Menu menu) {
-        menu.add(0, MENUITEM_COPY, 0, "Copy").setOnMenuItemClickListener(this)
-            .setShowAsAction(MenuItem.SHOW_AS_ACTION_IF_ROOM);
-        menu.add(0, MENUITEM_RESTART, 0, "Restart").setOnMenuItemClickListener(this)
+        // 添加「复制」菜单项：
+        // 参数说明：菜单组 ID（0 表示默认组）、菜单项 ID（MENU_ITEM_COPY）、排序号（0）、菜单文本（"Copy"）
+        // setOnMenuItemClickListener(this)：绑定点击事件到当前 Activity
+        // setShowAsAction(MenuItem.SHOW_AS_ACTION_IF_ROOM)：有空间时显示在 ActionBar 上，否则放入溢出菜单
+        menu.add(0, MENU_ITEM_COPY, 0, "Copy")
+			.setOnMenuItemClickListener(this)
 			.setShowAsAction(MenuItem.SHOW_AS_ACTION_IF_ROOM);
 
-        // 更新菜单文字风格
-        mGlobalCrashReportView.updateMenuStyle();
+        // 添加「重启」菜单项（参数含义同上）
+        menu.add(0, MENU_ITEM_RESTART, 0, "Restart")
+			.setOnMenuItemClickListener(this)
+			.setShowAsAction(MenuItem.SHOW_AS_ACTION_IF_ROOM);
+
+        // 调用自定义视图的方法，更新菜单文字样式（如颜色、字体大小等，由自定义 View 内部实现）
+        mCrashReportView.updateMenuStyle();
+
         return true;
     }
+
+    /**
+     * 将崩溃日志复制到系统剪贴板（工具方法）
+     * 功能：用户点击复制菜单后，将完整崩溃日志存入剪贴板，方便粘贴到聊天工具或文档中
+     */
+    private void copyCrashLogToClipboard() {
+        // 获取系统剪贴板服务（需通过 getSystemService 方法获取）
+        ClipboardManager clipboardManager = (ClipboardManager) getSystemService(Context.CLIPBOARD_SERVICE);
+
+        // 创建剪贴板数据：
+        // 参数 1：标签（用于标识剪贴板内容来源，此处用应用包名）
+        // 参数 2：实际复制的文本内容（崩溃日志）
+        ClipData clipData = ClipData.newPlainText(getPackageName(), mCrashLog);
+
+        // 将数据设置到剪贴板（完成复制操作）
+        clipboardManager.setPrimaryClip(clipData);
+
+        // 显示复制成功的 Toast 提示（告知用户操作结果）
+        Toast.makeText(getApplication(), "The text is copied.", Toast.LENGTH_SHORT).show();
     }
+}
+

libappbase/src/main/java/cc/winboll/studio/libappbase/GlobalCrashReportView.java

@@ -1,9 +1,10 @@
 package cc.winboll.studio.libappbase;
 
 /**
- * @Author ZhanGSKen<zhangsken@qq.com>
- * @Date 2025/02/11 20:18:30
- * @Describe 应用崩溃报告视图
+ * @Author ZhanGSKen&豆包大模型<zhangsken@qq.com>
+ * @Date 2025/11/11 20:21
+ * @Describe 全局崩溃报告视图控件
+ * 用于展示应用崩溃信息，包含顶部工具栏和崩溃日志文本区域，支持自定义配色
  */
 import android.content.Context;
 import android.content.res.TypedArray;
@@ -20,119 +21,289 @@ import cc.winboll.studio.libappbase.R;
 
 public class GlobalCrashReportView extends LinearLayout {
 
+	// 日志标签
 	public static final String TAG = "GlobalCrashReportView";
 
-    Context mContext;
-    Toolbar mToolbar;
-    int colorTittle;
-    int colorTittleBackground;
-    int colorText;
-    int colorTextBackground;
-    TextView mtvReport;
+	// 上下文对象
+	private Context mContext;
+	// 顶部工具栏（标题栏）
+	private Toolbar mToolbar;
+	// 标题文字颜色
+	private int mTitleColor;
+	// 标题栏背景颜色
+	private int mTitleBackgroundColor;
+	// 日志文本颜色
+	private int mTextColor;
+	// 日志区域背景颜色
+	private int mTextBackgroundColor;
+	// 崩溃日志显示文本控件
+	private TextView mTvReport;
 
+	/**
+	 * 构造方法：仅上下文
+	 * @param context 上下文
+	 */
 	public GlobalCrashReportView(Context context) {
 		super(context);
 		mContext = context;
-        //initView();
+		// 初始化默认配置（无自定义属性）
+		initDefaultConfig();
 	}
 
+	/**
+	 * 构造方法：上下文 + 自定义属性
+	 * @param context 上下文
+	 * @param attrs 自定义属性集合
+	 */
 	public GlobalCrashReportView(Context context, AttributeSet attrs) {
 		super(context, attrs);
 		mContext = context;
+		// 初始化视图（解析自定义属性）
 		initView(attrs);
 	}
 
+	/**
+	 * 构造方法：上下文 + 自定义属性 + 样式属性
+	 * @param context 上下文
+	 * @param attrs 自定义属性集合
+	 * @param defStyleAttr 样式属性
+	 */
 	public GlobalCrashReportView(Context context, AttributeSet attrs, int defStyleAttr) {
 		super(context, attrs, defStyleAttr);
 		mContext = context;
-        //initView();
+		// 初始化视图（解析自定义属性）
+		initView(attrs);
 	}
 
+	/**
+	 * 构造方法：上下文 + 自定义属性 + 样式属性 + 样式资源
+	 * @param context 上下文
+	 * @param attrs 自定义属性集合
+	 * @param defStyleAttr 样式属性
+	 * @param defStyleRes 样式资源
+	 */
 	public GlobalCrashReportView(Context context, AttributeSet attrs, int defStyleAttr, int defStyleRes) {
 		super(context, attrs, defStyleAttr, defStyleRes);
 		mContext = context;
-        //initView();
+		// 初始化视图（解析自定义属性）
+		initView(attrs);
 	}
 
-    public void setColorTittle(int colorTittle) {
-        this.colorTittle = colorTittle;
-    }
-
-    public int getColorTittle() {
-        return colorTittle;
-    }
-
-    public void setColorTittleBackground(int colorTittleBackground) {
-        this.colorTittleBackground = colorTittleBackground;
-    }
-
-    public int getColorTittleBackground() {
-        return colorTittleBackground;
-    }
-
-    public void setColorText(int colorText) {
-        this.colorText = colorText;
-    }
-
-    public int getColorText() {
-        return colorText;
-    }
-
-    public void setColorTextBackground(int colorTextBackground) {
-        this.colorTextBackground = colorTextBackground;
-    }
-
-    public int getColorTextBackground() {
-        return colorTextBackground;
-    }
-
-    void initView(AttributeSet attrs) {
-        TypedArray a = mContext.obtainStyledAttributes(attrs, R.styleable.GlobalCrashActivity, R.attr.themeGlobalCrashActivity, 0);
-        this.colorTittle = a.getColor(R.styleable.GlobalCrashActivity_colorTittle, Color.WHITE);
-        this.colorTittleBackground = a.getColor(R.styleable.GlobalCrashActivity_colorTittleBackgound, Color.BLACK);
-        this.colorText = a.getColor(R.styleable.GlobalCrashActivity_colorText, Color.BLACK);
-        this.colorTextBackground = a.getColor(R.styleable.GlobalCrashActivity_colorTextBackgound, Color.WHITE);
-        // 返回一个绑定资源结束的信号给资源
-        a.recycle();
-
-        /*this.colorTittle = Color.WHITE;
-        this.colorTittleBackground = Color.BLACK;
-        this.colorText = Color.BLACK;
-        this.colorTextBackground = Color.WHITE;
+	/**
+	 * 设置标题文字颜色
+	 * @param titleColor 颜色值（如 Color.WHITE 或 #FFFFFF）
 	 */
+	public void setTitleColor(int titleColor) {
+		this.mTitleColor = titleColor;
+		// 实时更新工具栏标题颜色
+		if (mToolbar != null) {
+			mToolbar.setTitleTextColor(titleColor);
+			mToolbar.setSubtitleTextColor(titleColor);
+		}
+	}
 
+	/**
+	 * 获取标题文字颜色
+	 * @return 标题文字颜色值
+	 */
+	public int getTitleColor() {
+		return mTitleColor;
+	}
+
+	/**
+	 * 设置标题栏背景颜色
+	 * @param titleBackgroundColor 颜色值（如 Color.BLACK 或 #000000）
+	 */
+	public void setTitleBackgroundColor(int titleBackgroundColor) {
+		this.mTitleBackgroundColor = titleBackgroundColor;
+		// 实时更新工具栏背景颜色
+		if (mToolbar != null) {
+			mToolbar.setBackgroundColor(titleBackgroundColor);
+		}
+	}
+
+	/**
+	 * 获取标题栏背景颜色
+	 * @return 标题栏背景颜色值
+	 */
+	public int getTitleBackgroundColor() {
+		return mTitleBackgroundColor;
+	}
+
+	/**
+	 * 设置日志文本颜色
+	 * @param textColor 颜色值（如 Color.BLACK 或 #000000）
+	 */
+	public void setTextColor(int textColor) {
+		this.mTextColor = textColor;
+		// 实时更新日志文本颜色
+		if (mTvReport != null) {
+			mTvReport.setTextColor(textColor);
+		}
+	}
+
+	/**
+	 * 获取日志文本颜色
+	 * @return 日志文本颜色值
+	 */
+	public int getTextColor() {
+		return mTextColor;
+	}
+
+	/**
+	 * 设置日志区域背景颜色
+	 * @param textBackgroundColor 颜色值（如 Color.WHITE 或 #FFFFFF）
+	 */
+	public void setTextBackgroundColor(int textBackgroundColor) {
+		this.mTextBackgroundColor = textBackgroundColor;
+		// 实时更新日志区域和主布局背景颜色
+		if (mTvReport != null) {
+			mTvReport.setBackgroundColor(textBackgroundColor);
+		}
+		setBackgroundColor(textBackgroundColor);
+	}
+
+	/**
+	 * 获取日志区域背景颜色
+	 * @return 日志区域背景颜色值
+	 */
+	public int getTextBackgroundColor() {
+		return mTextBackgroundColor;
+	}
+
+	/**
+	 * 初始化默认配置（无自定义属性时使用）
+	 */
+	private void initDefaultConfig() {
+		// 设置默认配色
+		mTitleColor = Color.WHITE;
+		mTitleBackgroundColor = Color.BLACK;
+		mTextColor = Color.BLACK;
+		mTextBackgroundColor = Color.WHITE;
+		// 加载布局
+		inflateView();
+		// 初始化控件样式
+		initWidgetStyle();
+	}
+
+	/**
+	 * 初始化视图（解析自定义属性 + 加载布局 + 设置样式）
+	 * @param attrs 自定义属性集合
+	 */
+	private void initView(AttributeSet attrs) {
+		// 解析自定义属性（关联 attrs.xml 中的 GlobalCrashActivity 样式）
+		TypedArray typedArray = mContext.obtainStyledAttributes(
+			attrs,
+			R.styleable.GlobalCrashActivity,
+			R.attr.themeGlobalCrashActivity,
+			0
+		);
+
+		// 读取自定义属性值（无设置时使用默认值）
+		mTitleColor = typedArray.getColor(
+			R.styleable.GlobalCrashActivity_colorTittle,
+			Color.WHITE
+		);
+		mTitleBackgroundColor = typedArray.getColor(
+			R.styleable.GlobalCrashActivity_colorTittleBackgound, // 注：原拼写错误（Backgound→Background），保持与 attrs.xml 一致
+			Color.BLACK
+		);
+		mTextColor = typedArray.getColor(
+			R.styleable.GlobalCrashActivity_colorText,
+			Color.BLACK
+		);
+		mTextBackgroundColor = typedArray.getColor(
+			R.styleable.GlobalCrashActivity_colorTextBackgound, // 注：原拼写错误，保持与 attrs.xml 一致
+			Color.WHITE
+		);
+
+		// 回收 TypedArray，避免内存泄漏
+		typedArray.recycle();
+
+		// 加载布局文件
+		inflateView();
+		// 初始化控件样式
+		initWidgetStyle();
+	}
+
+	/**
+	 * 加载布局文件
+	 */
+	private void inflateView() {
+		// 加载自定义布局（R.layout.view_globalcrashreport）
 		inflate(mContext, R.layout.view_globalcrashreport, this);
-
-        LinearLayout llMain = findViewById(R.id.viewglobalcrashreportLinearLayout1);
-        llMain.setBackgroundColor(this.colorTextBackground);
+		// 绑定控件
 		mToolbar = findViewById(R.id.viewglobalcrashreportToolbar1);
-        mToolbar.setBackgroundColor(this.colorTittleBackground);
-        mToolbar.setTitleTextColor(this.colorTittle);
-        mToolbar.setSubtitleTextColor(this.colorTittle);
-        mtvReport = findViewById(R.id.viewglobalcrashreportTextView1);
-        mtvReport.setTextColor(this.colorText);
-        mtvReport.setBackgroundColor(this.colorTextBackground);
+		mTvReport = findViewById(R.id.viewglobalcrashreportTextView1);
 	}
 
+	/**
+	 * 初始化控件样式（设置配色和基础属性）
+	 */
+	private void initWidgetStyle() {
+		// 设置主布局背景颜色
+		setBackgroundColor(mTextBackgroundColor);
+
+		// 配置工具栏样式
+		if (mToolbar != null) {
+			mToolbar.setBackgroundColor(mTitleBackgroundColor);
+			mToolbar.setTitleTextColor(mTitleColor);
+			mToolbar.setSubtitleTextColor(mTitleColor);
+		}
+
+		// 配置日志文本控件样式
+		if (mTvReport != null) {
+			mTvReport.setTextColor(mTextColor);
+			mTvReport.setBackgroundColor(mTextBackgroundColor);
+			// 可选：设置日志文本换行方式（默认已换行，此处增强可读性）
+			mTvReport.setSingleLine(false);
+			mTvReport.setHorizontallyScrolling(false);
+		}
+	}
+
+	/**
+	 * 设置崩溃报告内容到文本控件
+	 * @param report 崩溃日志字符串（通常包含异常信息、调用栈等）
+	 */
 	public void setReport(String report) {
-        mtvReport.setText(report);
+		if (mTvReport != null) {
+			mTvReport.setText(report);
+		}
 	}
 
+	/**
+	 * 获取顶部工具栏对象（用于外部设置标题、添加菜单等）
+	 * @return Toolbar 实例
+	 */
 	public Toolbar getToolbar() {
 		return mToolbar;
 	}
 
-    //
-    // 更新菜单文字风格
-    //
+	/**
+	 * 更新工具栏菜单文字颜色（与标题颜色保持一致）
+	 * 需在菜单加载完成后调用（如 Toolbar 加载菜单后）
+	 */
 	public void updateMenuStyle() {
-        // 设置菜单文本颜色
+		if (mToolbar == null) return;
+
+		// 获取工具栏菜单
 		Menu menu = mToolbar.getMenu();
+		if (menu == null || menu.size() == 0) return;
+
+		// 遍历所有菜单项，设置文字颜色
 		for (int i = 0; i < menu.size(); i++) {
-            MenuItem item = menu.getItem(i);
-            SpannableString spanString = new SpannableString(item.getTitle().toString());
-            spanString.setSpan(new ForegroundColorSpan(this.colorTittle), 0, spanString.length(), 0);
-            item.setTitle(spanString);
+			MenuItem menuItem = menu.getItem(i);
+			String title = menuItem.getTitle().toString();
+			// 使用 SpannableString 设置文字颜色
+			SpannableString spanString = new SpannableString(title);
+			spanString.setSpan(
+				new ForegroundColorSpan(mTitleColor),
+				0,
+				spanString.length(),
+				0 //  Spannable.SPAN_INCLUSIVE_EXCLUSIVE（默认值，包含起始位置，不包含结束位置）
+			);
+			menuItem.setTitle(spanString);
 		}
 	}
 }
+

libappbase/src/main/java/cc/winboll/studio/libappbase/HorizontalListView.java

@@ -1,128 +1,239 @@
 package cc.winboll.studio.libappbase;
 
 /**
- * @Author ZhanGSKen<zhangsken@qq.com>
- * @Date 2025/03/12 12:29:01
- * @Describe 水平布局的 ListView
+ * @Author ZhanGSKen&豆包大模型<zhangsken@qq.com>
+ * @Date 2025/11/11 20:26
+ * @Describe 水平滚动 ListView 控件
+ * 继承自 ListView，重写布局和测量逻辑，实现子项水平排列和滚动，替代默认垂直布局
  */
 import android.content.Context;
 import android.util.AttributeSet;
 import android.view.View;
 import android.widget.ListView;
 import android.widget.Scroller;
-import cc.winboll.studio.libappbase.LogUtils;
 
 public class HorizontalListView extends ListView {
+	/** 日志标签，用于当前控件的日志输出标识 */
 	public static final String TAG = "HorizontalListView";
-    private int verticalOffset = 0;
-    private Scroller scroller;
-    private int totalWidth;
 
+	/** 子项垂直偏移量（用于调整子项在垂直方向的位置，默认 0） */
+	private int mVerticalOffset = 0;
+	/** 平滑滚动控制器（用于实现水平方向的平滑滚动动画） */
+	private Scroller mScroller;
+	/** 所有子项总宽度（包含内边距），用于计算滚动范围 */
+	private int mTotalWidth;
+
+	/**
+	 * 构造方法：仅上下文
+	 * @param context 上下文（Activity/Fragment）
+	 */
 	public HorizontalListView(Context context) {
 		super(context);
 		init();
 	}
 
+	/**
+	 * 构造方法：上下文 + 自定义属性
+	 * @param context 上下文
+	 * @param attrs 自定义属性集合（如布局文件中设置的属性）
+	 */
 	public HorizontalListView(Context context, AttributeSet attrs) {
 		super(context, attrs);
 		init();
 	}
 
+	/**
+	 * 构造方法：上下文 + 自定义属性 + 样式属性
+	 * @param context 上下文
+	 * @param attrs 自定义属性集合
+	 * @param defStyle 样式属性（如系统默认样式）
+	 */
 	public HorizontalListView(Context context, AttributeSet attrs, int defStyle) {
 		super(context, attrs, defStyle);
 		init();
 	}
 
+	/**
+	 * 初始化控件配置
+	 * 初始化滚动控制器，设置滚动条显示状态
+	 */
 	private void init() {
-        scroller = new Scroller(getContext());
+		// 初始化平滑滚动器（上下文为当前控件所在上下文）
+		mScroller = new Scroller(getContext());
+		// 启用水平滚动条（默认显示）
 		setHorizontalScrollBarEnabled(true);
+		// 禁用垂直滚动条（水平列表无需垂直滚动）
 		setVerticalScrollBarEnabled(false);
 	}
 
+	/**
+	 * 设置子项垂直偏移量
+	 * 用于整体调整所有子项在垂直方向的位置（如居中、偏移）
+	 * @param verticalOffset 垂直偏移像素值（正数向下偏移，负数向上偏移）
+	 */
 	public void setVerticalOffset(int verticalOffset) {
-        this.verticalOffset = verticalOffset;
+		this.mVerticalOffset = verticalOffset;
 	}
 
+	/**
+	 * 重写布局方法：实现子项水平排列
+	 * 遍历所有子项，按水平方向依次布局（左对齐，叠加排列）
+	 * @param changed 布局是否发生变化（true：首次布局或尺寸变化；false：重绘）
+	 * @param l 控件左边界坐标
+	 * @param t 控件上边界坐标
+	 * @param r 控件右边界坐标
+	 * @param b 控件下边界坐标
+	 */
 	@Override
 	protected void onLayout(boolean changed, int l, int t, int r, int b) {
-        super.onLayout(changed, l, t, r, b);
-        int childCount = getChildCount();
-        int left = getPaddingLeft();
+		super.onLayout(changed, l, t, r, b); // 执行父类布局逻辑（确保基础配置生效）
+
+		int childCount = getChildCount(); // 获取当前可见子项数量
+		int left = getPaddingLeft(); // 子项起始左坐标（包含控件左内边距）
+		// 控件可用高度（总高度 - 上下内边距）
 		int viewHeight = getMeasuredHeight() - getPaddingTop() - getPaddingBottom();
-        totalWidth = left;
+		mTotalWidth = left; // 初始化总宽度为左内边距
 
+		// 遍历子项，水平排列
 		for (int i = 0; i < childCount; i++) {
-            View child = getChildAt(i);
-            int width = child.getMeasuredWidth();
-            int height = child.getMeasuredHeight();
-            child.layout(left, verticalOffset, left + width, verticalOffset + height);
-            left += width;
-        }
-        totalWidth = left + getPaddingRight();
+			View child = getChildAt(i); // 获取当前子项
+			int childWidth = child.getMeasuredWidth(); // 子项测量宽度
+			int childHeight = child.getMeasuredHeight(); // 子项测量高度
+
+			// 布局子项：水平方向从 left 开始，垂直方向偏移 mVerticalOffset
+			child.layout(
+				left,                      // 子项左边界
+				mVerticalOffset,           // 子项上边界（带垂直偏移）
+				left + childWidth,         // 子项右边界（左 + 宽度）
+				mVerticalOffset + childHeight // 子项下边界（偏移 + 高度）
+			);
+
+			left += childWidth; // 更新下一个子项的起始左坐标
 		}
 
+		// 计算总宽度（所有子项宽度 + 左右内边距）
+		mTotalWidth = left + getPaddingRight();
+	}
+
+	/**
+	 * 重写测量方法：设置控件测量规则
+	 * 水平方向：允许无限宽度（适应所有子项总宽度）；垂直方向：自适应内容高度
+	 * @param widthMeasureSpec 父控件传递的宽度测量规格
+	 * @param heightMeasureSpec 父控件传递的高度测量规格
+	 */
 	@Override
 	protected void onMeasure(int widthMeasureSpec, int heightMeasureSpec) {
-        int newHeightMeasureSpec = MeasureSpec.makeMeasureSpec(Integer.MAX_VALUE >> 2, MeasureSpec.AT_MOST);
+		// 重写宽度测量规则：最大值（Integer.MAX_VALUE >> 2 避免溢出），自适应内容
 		int newWidthMeasureSpec = MeasureSpec.makeMeasureSpec(Integer.MAX_VALUE >> 2, MeasureSpec.AT_MOST);
+		// 重写高度测量规则：同上，自适应子项高度
+		int newHeightMeasureSpec = MeasureSpec.makeMeasureSpec(Integer.MAX_VALUE >> 2, MeasureSpec.AT_MOST);
+
+		// 执行父类测量逻辑（使用重写后的测量规格）
 		super.onMeasure(newWidthMeasureSpec, newHeightMeasureSpec);
 	}
 
+	/**
+	 * 重写滚动计算方法：实现平滑滚动
+	 * 配合 Scroller 实现水平方向的平滑滚动动画（需在滚动时调用 invalidate() 触发）
+	 */
 	@Override
 	public void computeScroll() {
-        if (scroller.computeScrollOffset()) {
-            scrollTo(scroller.getCurrX(), scroller.getCurrY());
+		// 判断滚动是否正在进行（Scroller 计算当前滚动位置）
+		if (mScroller.computeScrollOffset()) {
+			// 滚动到当前计算的位置（x 轴水平滚动，y 轴固定 0）
+			scrollTo(mScroller.getCurrX(), mScroller.getCurrY());
+			// 触发重绘，持续更新滚动状态
 			postInvalidate();
 		}
 	}
 
+	/**
+	 * 平滑滚动到指定坐标
+	 * 基于 Scroller 实现水平方向的平滑滚动（300ms 动画时长）
+	 * @param x 目标 x 轴坐标（水平滚动位置）
+	 * @param y 目标 y 轴坐标（固定 0，无需垂直滚动）
+	 */
 	public void smoothScrollTo(int x, int y) {
+		// 计算滚动距离（目标坐标 - 当前滚动坐标）
 		int dx = x - getScrollX();
 		int dy = y - getScrollY();
-        scroller.startScroll(getScrollX(), getScrollY(), dx, dy, 300); // 300ms平滑动画
+
+		// 启动平滑滚动：起始坐标（当前滚动位置）、滚动距离、动画时长（300ms）
+		mScroller.startScroll(getScrollX(), getScrollY(), dx, dy, 300);
+		// 触发重绘，启动滚动动画
 		invalidate();
 	}
 
+	/**
+	 * 计算水平滚动总范围（用于滚动条显示比例）
+	 * @return 滚动总宽度（所有子项总宽度 + 内边距）
+	 */
 	@Override
 	public int computeHorizontalScrollRange() {
-        return totalWidth;
+		return mTotalWidth;
 	}
 
+	/**
+	 * 计算当前水平滚动偏移量（用于滚动条位置）
+	 * @return 当前 x 轴滚动坐标
+	 */
 	@Override
 	public int computeHorizontalScrollOffset() {
 		return getScrollX();
 	}
 
+	/**
+	 * 计算水平滚动可视范围（用于滚动条大小）
+	 * @return 控件可见宽度（当前显示区域宽度）
+	 */
 	@Override
 	public int computeHorizontalScrollExtent() {
 		return getWidth();
 	}
 
+	/**
+	 * 滚动到指定位置的子项（水平方向）
+	 * 定位目标子项，计算滚动坐标，执行平滑滚动
+	 * @param position 子项索引（从 0 开始，仅当前可见子项有效）
+	 */
 	public void scrollToItem(int position) {
+		// 校验索引有效性（避免数组越界）
 		if (position < 0 || position >= getChildCount()) {
-            LogUtils.d(TAG, "无效的position: " + position);
+			LogUtils.d(TAG, "无效的子项索引: " + position);
 			return;
 		}
 
-        View targetView = getChildAt(position);
-        int targetLeft = targetView.getLeft();
+		View targetView = getChildAt(position); // 获取目标子项
+		int targetLeft = targetView.getLeft(); // 目标子项左边界坐标
+		// 计算目标滚动坐标（子项左边界 - 控件左内边距，确保子项左对齐显示）
 		int scrollX = targetLeft - getPaddingLeft();
 
-        // 修正最大滚动范围计算
-        int maxScrollX = totalWidth;
+		// 修正滚动范围（避免超出总宽度或小于 0）
+		int maxScrollX = mTotalWidth - getWidth(); // 最大滚动坐标（总宽度 - 控件宽度）
 		scrollX = Math.max(0, Math.min(scrollX, maxScrollX));
 
-        // 强制重新布局和绘制
+		// 强制重新布局和绘制（确保子项位置正确）
 		requestLayout();
 		invalidateViews();
+		// 平滑滚动到目标坐标
 		smoothScrollTo(scrollX, 0);
-        LogUtils.d(TAG, String.format("滚动到position: %d, scrollX: %d computeHorizontalScrollRange() %d", position, scrollX, computeHorizontalScrollRange()));
+
+		// 打印滚动日志（调试用）
+		LogUtils.d(TAG, String.format(
+					   "滚动到子项索引: %d, 目标滚动X: %d, 总滚动范围: %d",
+					   position, scrollX, computeHorizontalScrollRange()
+				   ));
 	}
 
+	/**
+	 * 重置滚动到起始位置（最左侧）
+	 * 强制重新布局后，平滑滚动到 x=0 坐标
+	 */
 	public void resetScrollToStart() {
-        // 强制重新布局和绘制
+		// 强制重新布局和绘制（确保滚动位置准确）
 		requestLayout();
 		invalidateViews();
+		// 平滑滚动到最左侧（x=0，y=0）
 		smoothScrollTo(0, 0);
 	}
 }

libappbase/src/main/java/cc/winboll/studio/libappbase/LogActivity.java

@@ -1,9 +1,10 @@
 package cc.winboll.studio.libappbase;
 
 /**
- * @Author ZhanGSKen<zhangsken@qq.com>
- * @Date 2025/03/25 20:34:47
- * @Describe 应用日志窗口
+ * @Author ZhanGSKen&豆包大模型<zhangsken@qq.com>
+ * @Date 2025/11/11 20:29
+ * @Describe 应用日志展示 Activity
+ * 用于单独启动窗口展示应用运行日志，依赖 LogView 控件实现日志加载与显示
  */
 import android.app.Activity;
 import android.content.Context;
@@ -14,33 +15,51 @@ import cc.winboll.studio.libappbase.R;
 
 public class LogActivity extends Activity {
 
+    /** 日志标签，用于当前 Activity 的日志输出标识 */
     public static final String TAG = "LogActivity";
 
-    LogView mLogView;
+    /** 日志展示控件（用于加载和显示应用日志） */
+    private LogView mLogView;
 
     @Override
     protected void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
+        // 设置布局文件（包含 LogView 控件）
         setContentView(R.layout.activity_log);
-        //ToastUtils.show("LogActivity onCreate");
 
+        // 绑定布局中的 LogView 控件
         mLogView = findViewById(R.id.logview);
+        // 启动 LogView 日志加载（如实时刷新日志内容）
         mLogView.start();
     }
 
     @Override
     protected void onResume() {
         super.onResume();
+        // 恢复 Activity 时重新启动 LogView（确保日志持续更新）
         mLogView.start();
     }
 
+    /**
+     * 启动日志 Activity 的静态方法（外部调用入口）
+     * 配置 Intent 标志，以多任务/分屏模式启动，避免与主应用任务栈冲突
+     * @param context 上下文（Activity/Fragment），用于启动 Activity
+     */
     public static void startLogActivity(Context context) {
+        // 创建启动当前 Activity 的 Intent
         Intent intent = new Intent(context, LogActivity.class);
-        // 打开多任务窗口
+
+        // 添加 Intent 标志：支持分屏/多窗口模式（API 24+）
         intent.addFlags(Intent.FLAG_ACTIVITY_LAUNCH_ADJACENT);
+        // 添加 Intent 标志：创建新任务栈（避免并入调用者任务栈）
         intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
+        // 添加 Intent 标志：标记为新文档（多任务窗口中独立显示）
         intent.addFlags(Intent.FLAG_ACTIVITY_NEW_DOCUMENT);
+        // 添加 Intent 标志：允许创建多个任务实例（支持多次启动独立窗口）
         intent.addFlags(Intent.FLAG_ACTIVITY_MULTIPLE_TASK);
+
+        // 启动 Activity
         context.startActivity(intent);
     }
 }
+

libappbase/src/main/java/cc/winboll/studio/libappbase/LogUtils.java

@@ -1,10 +1,11 @@
 package cc.winboll.studio.libappbase;
 
 /**
- * @Author ZhanGSKen<zhangsken@qq.com>
- * @Date 2024/08/12 13:44:06
- * @Describe LogUtils
- * @Describe 应用日志类
+ * @Author ZhanGSKen&豆包大模型<zhangsken@qq.com>
+ * @Date 2025/11/11 20:36
+ * @Describe WinBoLl 应用日志管理工具类（单例逻辑）
+ * 核心功能：日志分级控制、日志文件读写、TAG 过滤配置、应用内所有 TAG 自动扫描
+ * 支持 Debug/Release 模式区分存储路径，日志持久化与清理
  */
 import android.content.Context;
 import cc.winboll.studio.libappbase.GlobalApplication;
@@ -28,353 +29,511 @@ import java.util.List;
 import java.util.Locale;
 import java.util.Map;
 
-
 public class LogUtils {
 
+    /** 当前工具类的日志 TAG */
     public static final String TAG = "LogUtils";
 
+    /**
+     * 日志级别枚举（从低到高：关闭→错误→警告→信息→调试→详细）
+     * 级别越高，输出的日志越详细
+     */
     public static enum LOG_LEVEL { Off, Error, Warn, Info, Debug, Verbose }
 
-    static volatile boolean _IsInited = false;
-    static Context _mContext;
-    // 日志显示时间格式
-    static SimpleDateFormat mSimpleDateFormat = new SimpleDateFormat("[yyyyMMdd_HHmmss_SSS]", Locale.getDefault());
-    // 应用日志文件夹
-    static File _mfLogCacheDir;
-    static File _mfLogDataDir;
-    // 应用日志文件
-    static File _mfLogCatchFile;
-    static File _mfLogUtilsBeanFile;
-    static LogUtilsBean _mLogUtilsBean;
-    public static Map<String, Boolean> mapTAGList = new HashMap<String, Boolean>();
+    /** 是否初始化完成标志（volatile 保证多线程可见性） */
+    private static volatile boolean sIsInited = false;
+    /** 全局上下文（用于获取存储路径、包信息） */
+    private static Context sContext;
+    /** 日志时间格式化工具（格式：[yyyyMMdd_HHmmss_SSS]，精确到毫秒） */
+    private static SimpleDateFormat sSimpleDateFormat = new SimpleDateFormat("[yyyyMMdd_HHmmss_SSS]", Locale.getDefault());
+    /** 日志缓存文件夹（Debug 模式下存储在外部缓存，Release 存储在内部缓存） */
+    private static File sLogCacheDir;
+    /** 日志配置文件夹（存储 TAG 配置文件） */
+    private static File sLogDataDir;
+    /** 日志存储文件（所有日志写入此文件） */
+    private static File sLogFile;
+    /** 日志配置文件（存储日志级别、TAG 启用状态等配置） */
+    private static File sLogConfigFile;
+    /** 日志配置实体类（封装日志级别等配置） */
+    private static LogUtilsBean sLogConfigBean;
+    /** TAG 过滤映射表（key：TAG 名称；value：是否启用该 TAG 的日志输出） */
+    public static Map<String, Boolean> sTagEnableMap = new HashMap<>();
 
-    //
-    // 初始化函数
-    //
+    /**
+     * 初始化日志工具（默认日志级别：Off，不输出日志）
+     * @param context 全局上下文（建议传入 Application 实例）
+     */
     public static void init(Context context) {
-        _mContext = context;
+        sContext = context;
         init(context, LOG_LEVEL.Off);
     }
 
-    //
-    // 初始化函数
-    //
+    /**
+     * 初始化日志工具（指定日志级别）
+     * 1. 根据 Debug/Release 模式初始化日志存储路径；
+     * 2. 加载日志配置文件；
+     * 3. 扫描应用内所有类的 TAG 并初始化过滤映射表；
+     * 4. 标记初始化完成。
+     * @param context 全局上下文
+     * @param logLevel 初始日志级别
+     */
     public static void init(Context context, LOG_LEVEL logLevel) {
-        if (GlobalApplication.isDebuging()) {
-            // 初始化日志缓存文件路径
-            _mfLogCacheDir = new File(context.getApplicationContext().getExternalCacheDir(), TAG);
-            if (!_mfLogCacheDir.exists()) {
-                _mfLogCacheDir.mkdirs();
-            }
-            _mfLogCatchFile = new File(_mfLogCacheDir, "log.txt");
-
-            // 初始化日志配置文件路径
-            _mfLogDataDir = context.getApplicationContext().getExternalFilesDir(TAG);
-            if (!_mfLogDataDir.exists()) {
-                _mfLogDataDir.mkdirs();
-            }
-            _mfLogUtilsBeanFile = new File(_mfLogDataDir, TAG + ".json");
+        sContext = context;
+        // 根据 Debug 模式选择存储路径（外部/内部存储）
+        if (GlobalApplication.isDebugging()) {
+            // Debug 模式：存储在外部缓存目录（可通过文件管理器查看）
+            sLogCacheDir = new File(context.getApplicationContext().getExternalCacheDir(), TAG);
+            sLogDataDir = context.getApplicationContext().getExternalFilesDir(TAG);
         } else {
-            // 初始化日志缓存文件路径
-            _mfLogCacheDir = new File(context.getApplicationContext().getCacheDir(), TAG);
-            if (!_mfLogCacheDir.exists()) {
-                _mfLogCacheDir.mkdirs();
-            }
-            _mfLogCatchFile = new File(_mfLogCacheDir, "log.txt");
-
-            // 初始化日志配置文件路径
-            _mfLogDataDir = new File(context.getApplicationContext().getFilesDir(), TAG);
-            if (!_mfLogDataDir.exists()) {
-                _mfLogDataDir.mkdirs();
-            }
-            _mfLogUtilsBeanFile = new File(_mfLogDataDir, TAG + ".json");
+            // Release 模式：存储在内部缓存目录（仅应用自身可访问）
+            sLogCacheDir = new File(context.getApplicationContext().getCacheDir(), TAG);
+            sLogDataDir = new File(context.getApplicationContext().getFilesDir(), TAG);
         }
 
-//        Toast.makeText(context,
-//                       "_mfLogUtilsBeanFile : " + _mfLogUtilsBeanFile
-//                       + "\n_mfLogCatchFile : " + _mfLogCatchFile,
-//                       Toast.LENGTH_SHORT).show();
-//
-        _mLogUtilsBean = LogUtilsBean.loadBeanFromFile(_mfLogUtilsBeanFile.getPath(), LogUtilsBean.class);
-        if (_mLogUtilsBean == null) {
-            _mLogUtilsBean = new LogUtilsBean();
-            _mLogUtilsBean.saveBeanToFile(_mfLogUtilsBeanFile.getPath(), _mLogUtilsBean);
+        // 创建日志文件夹（不存在则创建）
+        createDirIfNotExists(sLogCacheDir);
+        createDirIfNotExists(sLogDataDir);
+
+        // 初始化日志文件和配置文件路径
+        sLogFile = new File(sLogCacheDir, "log.txt");
+        sLogConfigFile = new File(sLogDataDir, TAG + ".json");
+
+        // 加载日志配置（从文件读取，读取失败则创建默认配置）
+        sLogConfigBean = LogUtilsBean.loadBeanFromFile(sLogConfigFile.getPath(), LogUtilsBean.class);
+        if (sLogConfigBean == null) {
+            sLogConfigBean = new LogUtilsBean();
+            sLogConfigBean.setLogLevel(logLevel);
+            // 保存默认配置到文件
+            sLogConfigBean.saveBeanToFile(sLogConfigFile.getPath(), sLogConfigBean);
         }
 
-        // 加载当前应用下的所有类的 TAG
-        addClassTAGList();
-        loadTAGBeanSettings();
-        _IsInited = true;
-        LogUtils.d(TAG, String.format("mapTAGList : %s", mapTAGList.toString()));
+        // 扫描应用内所有类的 TAG 并添加到过滤映射表
+        scanAllClassTags();
+        // 加载已保存的 TAG 启用状态配置
+        loadTagEnableSettings();
+        // 标记初始化完成
+        sIsInited = true;
+
+        // 打印初始化日志（调试用）
+        d(TAG, String.format("TAG 过滤映射表初始化完成：%s", sTagEnableMap.toString()));
     }
 
-    public static Map<String, Boolean> getMapTAGList() {
-        return mapTAGList;
+    /**
+     * 获取 TAG 过滤映射表（外部可通过此方法获取所有 TAG 及其启用状态）
+     * @return TAG 名称与启用状态的映射
+     */
+    public static Map<String, Boolean> getTagEnableMap() {
+        return sTagEnableMap;
     }
 
-    static void loadTAGBeanSettings() {
-        ArrayList<LogUtilsClassTAGBean> list = new ArrayList<LogUtilsClassTAGBean>();
-        LogUtilsClassTAGBean.loadBeanList(_mContext, list, LogUtilsClassTAGBean.class);
-        for (int i = 0; i < list.size(); i++) {
-            LogUtilsClassTAGBean beanSetting = list.get(i);
-            for (Map.Entry<String, Boolean> entry : mapTAGList.entrySet()) {
-                if (entry.getKey().equals(beanSetting.getTag())) {
-                    entry.setValue(beanSetting.getEnable());
+    /**
+     * 加载已保存的 TAG 启用状态配置
+     * 从 LogUtilsClassTAGBean 列表中读取每个 TAG 的启用状态，更新到映射表
+     */
+    private static void loadTagEnableSettings() {
+        ArrayList<LogUtilsClassTAGBean> tagSettingList = new ArrayList<>();
+        // 从文件加载 TAG 配置列表
+        LogUtilsClassTAGBean.loadBeanList(sContext, tagSettingList, LogUtilsClassTAGBean.class);
+
+        // 遍历配置列表，更新 TAG 启用状态
+        for (LogUtilsClassTAGBean tagSetting : tagSettingList) {
+            String tag = tagSetting.getTag();
+            boolean isEnable = tagSetting.getEnable();
+            // 仅更新已存在的 TAG（避免无效配置）
+            if (sTagEnableMap.containsKey(tag)) {
+                sTagEnableMap.put(tag, isEnable);
+            }
         }
     }
 
+    /**
+     * 保存当前 TAG 启用状态配置到文件
+     * 将映射表中的 TAG 及其启用状态转换为 LogUtilsClassTAGBean 列表，持久化到文件
+     */
+    private static void saveTagEnableSettings() {
+        ArrayList<LogUtilsClassTAGBean> tagSettingList = new ArrayList<>();
+        // 遍历映射表，构建配置列表
+        for (Map.Entry<String, Boolean> entry : sTagEnableMap.entrySet()) {
+            tagSettingList.add(new LogUtilsClassTAGBean(entry.getKey(), entry.getValue()));
         }
+        // 保存配置列表到文件
+        LogUtilsClassTAGBean.saveBeanList(sContext, tagSettingList, LogUtilsClassTAGBean.class);
     }
 
-    static void saveTAGBeanSettings() {
-        ArrayList<LogUtilsClassTAGBean> list = new ArrayList<LogUtilsClassTAGBean>();
-        for (Map.Entry<String, Boolean> entry : mapTAGList.entrySet()) {
-            list.add(new LogUtilsClassTAGBean(entry.getKey(), entry.getValue()));
-        }
-        LogUtilsClassTAGBean.saveBeanList(_mContext, list, LogUtilsClassTAGBean.class);
-    }
-
-    static void addClassTAGList() {
-        //ClassLoader classLoader = getClass().getClassLoader();
+    /**
+     * 扫描应用内所有类的 TAG 并添加到过滤映射表
+     * 1. 通过 DexFile 读取 APK 中所有类；
+     * 2. 过滤指定包名前缀（cc.winboll.studio）的类；
+     * 3. 反射获取类中 public static final String TAG 字段的值；
+     * 4. 将 TAG 加入映射表，默认禁用（false）。
+     */
+    private static void scanAllClassTags() {
         try {
-            //String packageName = context.getPackageName();
-            String packageNamePrefix = "cc.winboll.studio";
-            List<String> classNames = new ArrayList<>();
-            String apkPath = _mContext.getPackageCodePath();
-            //Log.d("APK_PATH", "The APK path is: " + apkPath);
-            LogUtils.d(TAG, String.format("apkPath : %s", apkPath));
-            //String apkPath = "/data/app/" + packageName + "-";
+            // 应用 APK 路径（通过上下文获取）
+            String apkPath = sContext.getPackageCodePath();
+            d(TAG, String.format("APK 路径：%s", apkPath));
 
-            //DexFile dexfile = new DexFile(apkPath + "1/base.apk");
-            DexFile dexfile = new DexFile(apkPath);
+            // 读取 APK 中的所有类
+            DexFile dexFile = new DexFile(apkPath);
+            Enumeration<String> classNames = dexFile.entries();
 
-            int countTemp = 0;
-            Enumeration<String> entries = dexfile.entries();
-            while (entries.hasMoreElements()) {
-                countTemp++;
-                String className = entries.nextElement();
-                if (className.startsWith(packageNamePrefix)) {
-                    classNames.add(className);
+            int totalClassCount = 0; // 总类数（调试用）
+            List<String> targetClassNames = new ArrayList<>(); // 目标包名下的类名列表
+            String targetPackagePrefix = "cc.winboll.studio"; // 目标包名前缀
+
+            // 过滤目标包名下的类
+            while (classNames.hasMoreElements()) {
+                totalClassCount++;
+                String className = classNames.nextElement();
+                if (className.startsWith(targetPackagePrefix)) {
+                    targetClassNames.add(className);
                 }
             }
 
-            LogUtils.d(TAG, String.format("countTemp : %d\nClassNames size : %d", countTemp, classNames.size()));
+            // 打印扫描统计（调试用）
+            d(TAG, String.format("APK 总类数：%d，目标包下类数：%d", totalClassCount, targetClassNames.size()));
 
-            for (String className : classNames) {
+            // 反射获取每个类的 TAG 字段
+            for (String className : targetClassNames) {
                 try {
                     Class<?> clazz = Class.forName(className);
+                    // 获取类中所有声明的字段
                     Field[] fields = clazz.getDeclaredFields();
                     for (Field field : fields) {
-                        if (Modifier.isStatic(field.getModifiers()) && Modifier.isPublic(field.getModifiers()) && field.getType() == String.class && "TAG".equals(field.getName())) {
+                        // 过滤条件：public static String 类型，且字段名是 "TAG"
+                        if (Modifier.isStatic(field.getModifiers())
+							&& Modifier.isPublic(field.getModifiers())
+							&& field.getType() == String.class
+							&& "TAG".equals(field.getName())) {
+                            // 获取 TAG 字段的值（静态字段，传入 null 即可）
                             String tagValue = (String) field.get(null);
-                            //Log.d("TAG_INFO", "Class: " + className + ", TAG value: " + tagValue);
-                            //LogUtils.d(TAG, String.format("Tag Value : %s", tagValue));
-                            //mapTAGList.put(tagValue, true);
-                            mapTAGList.put(tagValue, false);
+                            // 添加到映射表，默认禁用
+                            sTagEnableMap.put(tagValue, false);
                         }
                     }
                 } catch (NoClassDefFoundError | ClassNotFoundException | IllegalAccessException e) {
-                    LogUtils.d(TAG, e.getMessage(), Thread.currentThread().getStackTrace());
-                    //LogUtils.d(TAG, e, Thread.currentThread().getStackTrace());
-                    //Toast.makeText(context, TAG + " : " + e.getMessage(), Toast.LENGTH_SHORT).show();
+                    // 捕获反射异常，避免单个类扫描失败影响整体
+                    d(TAG, e.getMessage(), Thread.currentThread().getStackTrace());
                 }
             }
         } catch (IOException e) {
-            LogUtils.d(TAG, e, Thread.currentThread().getStackTrace());
-            //Toast.makeText(context, TAG + " : " + e.getMessage(), Toast.LENGTH_SHORT).show();
+            // 捕获 APK 读取异常
+            d(TAG, e, Thread.currentThread().getStackTrace());
         }
     }
 
-    public static void setTAGListEnable(String tag, boolean isEnable) {
-        Iterator<Map.Entry<String, Boolean>> iterator = mapTAGList.entrySet().iterator();
+    /**
+     * 设置单个 TAG 的启用状态
+     * @param tag TAG 名称
+     * @param isEnable 是否启用（true：输出该 TAG 的日志；false：不输出）
+     */
+    public static void setTagEnable(String tag, boolean isEnable) {
+        // 遍历映射表，更新目标 TAG 的状态
+        Iterator<Map.Entry<String, Boolean>> iterator = sTagEnableMap.entrySet().iterator();
         while (iterator.hasNext()) {
             Map.Entry<String, Boolean> entry = iterator.next();
             if (tag.equals(entry.getKey())) {
                 entry.setValue(isEnable);
-                //System.out.println("Key: " + entry.getKey() + ", Value: " + entry.getValue());
                 break;
             }
         }
-        saveTAGBeanSettings();
-        LogUtils.d(TAG, String.format("mapTAGList : %s", mapTAGList.toString()));
+        // 保存配置到文件（持久化）
+        saveTagEnableSettings();
+        d(TAG, String.format("TAG 配置更新：%s", sTagEnableMap.toString()));
     }
 
-    public static void setALlTAGListEnable(boolean isEnable) {
-        Iterator<Map.Entry<String, Boolean>> iterator = mapTAGList.entrySet().iterator();
+    /**
+     * 设置所有 TAG 的启用状态（批量控制）
+     * @param isEnable 是否启用（true：所有 TAG 均输出日志；false：所有 TAG 均不输出）
+     */
+    public static void setAllTagsEnable(boolean isEnable) {
+        // 遍历映射表，批量更新所有 TAG 的状态
+        Iterator<Map.Entry<String, Boolean>> iterator = sTagEnableMap.entrySet().iterator();
         while (iterator.hasNext()) {
             Map.Entry<String, Boolean> entry = iterator.next();
             entry.setValue(isEnable);
-            //System.out.println("Key: " + entry.getKey() + ", Value: " + entry.getValue());
         }
-        saveTAGBeanSettings();
-        LogUtils.d(TAG, String.format("mapTAGList : %s", mapTAGList.toString()));
+        // 保存配置到文件（持久化）
+        saveTagEnableSettings();
+        d(TAG, String.format("所有 TAG 配置更新：%s", sTagEnableMap.toString()));
     }
 
+    /**
+     * 设置全局日志级别（控制日志输出的详细程度）
+     * @param logLevel 目标日志级别
+     */
     public static void setLogLevel(LOG_LEVEL logLevel) {
-        LogUtils._mLogUtilsBean.setLogLevel(logLevel);
-        _mLogUtilsBean.saveBeanToFile(_mfLogUtilsBeanFile.getPath(), _mLogUtilsBean);
+        if (sLogConfigBean != null) {
+            sLogConfigBean.setLogLevel(logLevel);
+            // 保存配置到文件（持久化）
+            sLogConfigBean.saveBeanToFile(sLogConfigFile.getPath(), sLogConfigBean);
+        }
     }
 
+    /**
+     * 获取当前全局日志级别
+     * @return 当前日志级别
+     */
     public static LOG_LEVEL getLogLevel() {
-        return LogUtils._mLogUtilsBean.getLogLevel();
+        return sLogConfigBean != null ? sLogConfigBean.getLogLevel() : LOG_LEVEL.Off;
     }
 
-    static boolean isLoggable(String tag, LOG_LEVEL logLevel) {
-        if (!_IsInited) {
+    /**
+     * 判断当前日志是否可输出（校验初始化状态、TAG 启用状态、日志级别）
+     * @param tag 日志 TAG
+     * @param logLevel 日志级别
+     * @return true：可输出；false：不可输出
+     */
+    private static boolean isLoggable(String tag, LOG_LEVEL logLevel) {
+        // 未初始化：不输出
+        if (!sIsInited) {
             return false;
         }
-        if (mapTAGList.get(tag) == null
-            || !mapTAGList.get(tag)) {
+        // TAG 未配置或未启用：不输出
+        if (sTagEnableMap.get(tag) == null || !sTagEnableMap.get(tag)) {
             return false;
         }
-        if (!isInTheLevel(logLevel)) {
+        // 日志级别未达到：不输出
+        if (!isLevelMatched(logLevel)) {
             return false;
         }
         return true;
     }
 
-    static boolean isInTheLevel(LOG_LEVEL logLevel) {
-        return (LogUtils._mLogUtilsBean.getLogLevel().ordinal() == logLevel.ordinal()
-            || LogUtils._mLogUtilsBean.getLogLevel().ordinal() > logLevel.ordinal());
+    /**
+     * 判断日志级别是否匹配（当前全局级别 >= 目标级别时可输出）
+     * 例：全局级别为 Debug（4），则 Error（1）、Warn（2）、Info（3）、Debug（4）均可输出
+     * @param logLevel 目标日志级别
+     * @return true：级别匹配；false：不匹配
+     */
+    private static boolean isLevelMatched(LOG_LEVEL logLevel) {
+        if (sLogConfigBean == null) {
+            return false;
+        }
+        // 枚举的 ordinal() 方法返回索引（Off=0，Error=1，...，Verbose=5）
+        return sLogConfigBean.getLogLevel().ordinal() >= logLevel.ordinal();
     }
 
-    //
-    // 获取应用日志文件夹
-    //
+    /**
+     * 获取日志缓存文件夹路径（外部可通过此方法获取日志存储目录）
+     * @return 日志缓存文件夹
+     */
     public static File getLogCacheDir() {
-        return _mfLogCacheDir;
+        return sLogCacheDir;
     }
 
-    //
-    // 调试日志写入函数
-    //
-    public static void e(String szTAG, String szMessage) {
-        if (isLoggable(szTAG, LogUtils.LOG_LEVEL.Error)) {
-            saveLog(szTAG, LogUtils.LOG_LEVEL.Error, szMessage);
+    /**
+     * 输出 Error 级别日志
+     * @param tag TAG 名称
+     * @param message 日志内容
+     */
+    public static void e(String tag, String message) {
+        if (isLoggable(tag, LOG_LEVEL.Error)) {
+            saveLog(tag, LOG_LEVEL.Error, message);
         }
     }
 
-    //
-    // 调试日志写入函数
-    //
-    public static void w(String szTAG, String szMessage) {
-        if (isLoggable(szTAG, LogUtils.LOG_LEVEL.Warn)) {
-            saveLog(szTAG, LogUtils.LOG_LEVEL.Warn, szMessage);
+    /**
+     * 输出 Warn 级别日志
+     * @param tag TAG 名称
+     * @param message 日志内容
+     */
+    public static void w(String tag, String message) {
+        if (isLoggable(tag, LOG_LEVEL.Warn)) {
+            saveLog(tag, LOG_LEVEL.Warn, message);
         }
     }
 
-    //
-    // 调试日志写入函数
-    //
-    public static void i(String szTAG, String szMessage) {
-        if (isLoggable(szTAG, LogUtils.LOG_LEVEL.Info)) {
-            saveLog(szTAG, LogUtils.LOG_LEVEL.Info, szMessage);
+    /**
+     * 输出 Info 级别日志
+     * @param tag TAG 名称
+     * @param message 日志内容
+     */
+    public static void i(String tag, String message) {
+        if (isLoggable(tag, LOG_LEVEL.Info)) {
+            saveLog(tag, LOG_LEVEL.Info, message);
         }
     }
 
-    //
-    // 调试日志写入函数
-    //
-    public static void d(String szTAG, String szMessage) {
-        if (isLoggable(szTAG, LogUtils.LOG_LEVEL.Debug)) {
-            saveLog(szTAG, LogUtils.LOG_LEVEL.Debug, szMessage);
+    /**
+     * 输出 Debug 级别日志（基础版）
+     * @param tag TAG 名称
+     * @param message 日志内容
+     */
+    public static void d(String tag, String message) {
+        if (isLoggable(tag, LOG_LEVEL.Debug)) {
+            saveLog(tag, LOG_LEVEL.Debug, message);
         }
     }
 
-    //
-    // 调试日志写入函数
-    // 包含线程调试堆栈信息
-    //
-    public static void d(String szTAG, String szMessage, StackTraceElement[] listStackTrace) {
-        if (isLoggable(szTAG, LogUtils.LOG_LEVEL.Debug)) {
-            StringBuilder sbMessage = new StringBuilder(szMessage);
-            sbMessage.append(" \nAt ");
-            sbMessage.append(listStackTrace[2].getMethodName());
-            sbMessage.append(" (");
-            sbMessage.append(listStackTrace[2].getFileName());
-            sbMessage.append(":");
-            sbMessage.append(listStackTrace[2].getLineNumber());
-            sbMessage.append(")");
-            saveLog(szTAG, LogUtils.LOG_LEVEL.Debug, sbMessage.toString());
+    /**
+     * 输出 Debug 级别日志（带调用栈信息）
+     * 包含调用方法名、文件名、行号，便于调试定位
+     * @param tag TAG 名称
+     * @param message 日志内容
+     * @param stackTrace 线程调用栈（通常传入 Thread.currentThread().getStackTrace()）
+     */
+    public static void d(String tag, String message, StackTraceElement[] stackTrace) {
+        if (isLoggable(tag, LOG_LEVEL.Debug)) {
+            StringBuilder sb = new StringBuilder(message);
+            // 拼接调用栈信息（stackTrace[2] 为实际调用处）
+            sb.append(" \nAt ")
+				.append(stackTrace[2].getMethodName())
+				.append(" (")
+				.append(stackTrace[2].getFileName())
+				.append(":")
+				.append(stackTrace[2].getLineNumber())
+				.append(")");
+            saveLog(tag, LOG_LEVEL.Debug, sb.toString());
         }
     }
 
-    //
-    // 调试日志写入函数
-    // 包含异常信息和线程调试堆栈信息
-    //
-    public static void d(String szTAG, Exception e, StackTraceElement[] listStackTrace) {
-        if (isLoggable(szTAG, LogUtils.LOG_LEVEL.Debug)) {
-            StringBuilder sbMessage = new StringBuilder(e.getClass().toGenericString());
-            sbMessage.append(" : ");
-            sbMessage.append(e.getMessage());
-            sbMessage.append(" \nAt ");
-            sbMessage.append(listStackTrace[2].getMethodName());
-            sbMessage.append(" (");
-            sbMessage.append(listStackTrace[2].getFileName());
-            sbMessage.append(":");
-            sbMessage.append(listStackTrace[2].getLineNumber());
-            sbMessage.append(")");
-            saveLog(szTAG, LogUtils.LOG_LEVEL.Debug, sbMessage.toString());
+    /**
+     * 输出 Debug 级别日志（带异常信息和调用栈）
+     * 包含异常类型、异常信息、调用位置，便于异常定位
+     * @param tag TAG 名称
+     * @param e 异常对象
+     * @param stackTrace 线程调用栈
+     */
+    public static void d(String tag, Exception e, StackTraceElement[] stackTrace) {
+        if (isLoggable(tag, LOG_LEVEL.Debug)) {
+            StringBuilder sb = new StringBuilder();
+            // 拼接异常信息
+            sb.append(e.getClass().toGenericString())
+				.append(" : ")
+				.append(e.getMessage())
+				// 拼接调用栈信息
+				.append(" \nAt ")
+				.append(stackTrace[2].getMethodName())
+				.append(" (")
+				.append(stackTrace[2].getFileName())
+				.append(":")
+				.append(stackTrace[2].getLineNumber())
+				.append(")");
+            saveLog(tag, LOG_LEVEL.Debug, sb.toString());
         }
     }
 
-    //
-    // 调试日志写入函数
-    //
-    public static void v(String szTAG, String szMessage) {
-        if (isLoggable(szTAG, LogUtils.LOG_LEVEL.Verbose)) {
-            saveLog(szTAG, LogUtils.LOG_LEVEL.Verbose, szMessage);
+    /**
+     * 输出 Verbose 级别日志（最详细级别）
+     * @param tag TAG 名称
+     * @param message 日志内容
+     */
+    public static void v(String tag, String message) {
+        if (isLoggable(tag, LOG_LEVEL.Verbose)) {
+            saveLog(tag, LOG_LEVEL.Verbose, message);
         }
     }
 
-    //
-    // 日志文件保存函数
-    //
-    static void saveLog(String szTAG, LogUtils.LOG_LEVEL logLevel, String szMessage) {
+    /**
+     * 核心日志保存方法（将日志写入文件）
+     * 日志格式：[级别]  [时间戳]  [TAG]
+     *          日志内容
+     * @param tag TAG 名称
+     * @param logLevel 日志级别
+     * @param message 日志内容
+     */
+    private static void saveLog(String tag, LOG_LEVEL logLevel, String message) {
+        BufferedWriter writer = null;
         try {
-            BufferedWriter out = null;
-            out = new BufferedWriter(new OutputStreamWriter(new FileOutputStream(_mfLogCatchFile, true), "UTF-8"));
-            out.write("[" + logLevel + "]  " + mSimpleDateFormat.format(System.currentTimeMillis()) + "  [" + szTAG + "]\n" + szMessage + "\n");
-            out.close();
+            // 以追加模式打开日志文件，UTF-8 编码
+            writer = new BufferedWriter(
+                new OutputStreamWriter(
+                    new FileOutputStream(sLogFile, true), 
+                    "UTF-8"
+                )
+            );
+            // 拼接日志内容（级别 + 时间 + TAG + 消息）
+            String logContent = String.format(
+                "[%s]  %s  [%s]\n%s\n",
+                logLevel.name(),          // 日志级别（如 Debug）
+                sSimpleDateFormat.format(System.currentTimeMillis()), // 时间戳
+                tag,                      // TAG 名称
+                message                   // 日志内容
+            );
+            // 写入文件
+            writer.write(logContent);
         } catch (IOException e) {
-            LogUtils.d(TAG, "IOException : " + e.getMessage());
+            // 日志写入失败时，输出内部调试日志
+            d(TAG, "日志写入失败：" + e.getMessage());
+        } finally {
+            // 关闭流，避免资源泄漏
+            if (writer != null) {
+                try {
+                    writer.close();
+                } catch (IOException e) {
+                    e.printStackTrace();
+                }
+            }
         }
     }
 
-    //
-    // 历史日志加载函数
-    //
+    /**
+     * 加载历史日志（读取日志文件所有内容）
+     * @return 历史日志字符串（空字符串表示文件不存在或读取失败）
+     */
     public static String loadLog() {
-        if (_mfLogCatchFile.exists()) {
-            StringBuffer sb = new StringBuffer();
-            try {
-                BufferedReader in = null;
-                in = new BufferedReader(new InputStreamReader(new FileInputStream(_mfLogCatchFile), "UTF-8"));
-                String line = "";
-                while ((line = in.readLine()) != null) {
-                    sb.append(line);
-                    sb.append("\n");
-                }
-            } catch (IOException e) {
-                LogUtils.d(TAG, "IOException : " + e.getMessage());
-            } 
-            return sb.toString();
-        }
+        // 日志文件不存在，返回空
+        if (sLogFile == null || !sLogFile.exists()) {
             return "";
         }
 
-    //
-    // 清理日志函数
-    //
-    public static void cleanLog() {
-        if (_mfLogCatchFile.exists()) {
+        StringBuilder logContent = new StringBuilder();
+        BufferedReader reader = null;
         try {
-                UTF8FileUtils.writeStringToFile(_mfLogCatchFile.getPath(), "");
-                //LogUtils.d(TAG, "cleanLog");
+            // 以 UTF-8 编码读取日志文件
+            reader = new BufferedReader(
+                new InputStreamReader(
+                    new FileInputStream(sLogFile), 
+                    "UTF-8"
+                )
+            );
+            String line;
+            // 逐行读取并拼接
+            while ((line = reader.readLine()) != null) {
+                logContent.append(line).append("\n");
+            }
         } catch (IOException e) {
-                LogUtils.d(TAG, e, Thread.currentThread().getStackTrace());
+            // 读取失败时，输出内部调试日志
+            d(TAG, "日志读取失败：" + e.getMessage());
+        } finally {
+            // 关闭流，避免资源泄漏
+            if (reader != null) {
+                try {
+                    reader.close();
+                } catch (IOException e) {
+                    e.printStackTrace();
                 }
             }
         }
+        return logContent.toString();
     }
+
+    /**
+     * 清理历史日志（清空日志文件内容）
+     */
+    public static void cleanLog() {
+        if (sLogFile == null || !sLogFile.exists()) {
+            return;
+        }
+
+        try {
+            // 写入空字符串到文件，实现清空
+            UTF8FileUtils.writeStringToFile(sLogFile.getPath(), "");
+        } catch (IOException e) {
+            // 清空失败时，输出内部调试日志（带调用栈）
+            d(TAG, e, Thread.currentThread().getStackTrace());
+        }
+    }
+
+    /**
+     * 辅助方法：创建文件夹（不存在则创建）
+     * @param dir 目标文件夹
+     */
+    private static void createDirIfNotExists(File dir) {
+        if (dir != null && !dir.exists()) {
+            dir.mkdirs();
+        }
+    }
+}
+

libappbase/src/main/java/cc/winboll/studio/libappbase/LogView.java

@@ -213,7 +213,7 @@ public class LogView extends RelativeLayout {
         }
 
         // 加载标签列表
-        Map<String, Boolean> mapTAGList = LogUtils.getMapTAGList();
+        Map<String, Boolean> mapTAGList = LogUtils.getTagEnableMap();
         boolean isAllSelect = true;
         for (Map.Entry<String, Boolean> entry : mapTAGList.entrySet()) {
             if (entry.getValue() == false) {
@@ -237,7 +237,7 @@ public class LogView extends RelativeLayout {
         mSelectAllTAGCheckBox.setOnClickListener(new View.OnClickListener(){
                 @Override
                 public void onClick(View v) {
-                    LogUtils.setALlTAGListEnable(mSelectAllTAGCheckBox.isChecked());
+                    LogUtils.setAllTagsEnable(mSelectAllTAGCheckBox.isChecked());
                     //LogUtils.setALlTAGListEnable(false);
                     //mTAGListAdapter.notifyDataSetChanged();
                     mTAGListAdapter.reload();
@@ -483,7 +483,7 @@ public class LogView extends RelativeLayout {
 
                     @Override
                     public void onClick(View v) {
-                        LogUtils.setTAGListEnable(item.getTag(), ((CheckBox)v).isChecked());
+                        LogUtils.setTagEnable(item.getTag(), ((CheckBox)v).isChecked());
                     }
                 });
 

libappbase/src/main/java/cc/winboll/studio/libappbase/ToastUtils.java

@@ -1,34 +1,136 @@
 package cc.winboll.studio.libappbase;
 
 /**
- * @Author ZhanGSKen<zhangsken@qq.com>
- * @Date 2025/03/12 12:02:31
+ * @Author ZhanGSKen&豆包大模型<zhangsken@qq.com>
+ * @Date 2025/11/11 20:51
+ * @Describe 吐司工具类（单例模式）
+ * 简化 Android 吐司的创建与展示，通过 Handler 确保主线程显示，统一管理上下文，避免内存泄漏
  */
 import android.content.Context;
+import android.os.Handler;
+import android.os.Looper;
+import android.os.Message;
 import android.widget.Toast;
 
 public class ToastUtils {
 
+    /** 工具类日志 TAG（用于调试输出） */
     public static final String TAG = "ToastUtils";
+    /** 消息标识：显示短时长吐司 */
+    private static final int MSG_SHOW_SHORT_TOAST = 1001;
 
-    volatile static ToastUtils _ToastUtils;
-    Context mContext;
+    /** 单例实例（volatile 保证多线程下可见性，避免指令重排） */
+    private static volatile ToastUtils sInstance;
+    /** 全局上下文（建议传入 Application 实例，避免内存泄漏） */
+    private Context mContext;
+    /** 主线程 Handler（用于接收并处理吐司显示消息，确保 UI 操作在主线程） */
+    private static Handler _mMainHandler;
 
-    ToastUtils() {
+    /**
+     * 私有构造方法（禁止外部直接创建实例，确保单例）
+     * 初始化主线程 Handler，绑定主线程 Looper
+     */
+    private ToastUtils() {
+        // 初始化 Handler，绑定主线程 Looper（确保吐司在主线程显示）
+        _mMainHandler = new Handler(Looper.getMainLooper()) {
+            @Override
+            public void handleMessage(Message msg) {
+                super.handleMessage(msg);
+                // 处理消息：显示吐司
+                if (msg.what == MSG_SHOW_SHORT_TOAST && msg.obj != null) {
+                    String message = (String) msg.obj;
+                    showToastInternal(message);
+                }
+            }
+        };
     }
 
-    synchronized static ToastUtils getInstance() {
-        if (_ToastUtils == null) {
-            _ToastUtils = new ToastUtils();
+    /**
+     * 获取单例实例（双重检查锁定，高效且线程安全）
+     * @return ToastUtils 单例对象
+     */
+    private static ToastUtils getInstance() {
+        if (sInstance == null) { // 第一次检查（无锁，提升效率）
+            synchronized (ToastUtils.class) { // 加锁，确保线程安全
+                if (sInstance == null) { // 第二次检查（避免多线程并发创建多个实例）
+                    sInstance = new ToastUtils();
                 }
-        return _ToastUtils;
+            }
+        }
+        return sInstance;
     }
 
+    /**
+     * 初始化工具类（必须在 Application 或 Activity 启动时调用）
+     * 传入全局上下文，用于创建 Toast 实例
+     * @param context 全局上下文（推荐传入 getApplicationContext()）
+     */
     public static void init(Context context) {
-        getInstance().mContext = context;
+        if (context == null) {
+            throw new IllegalArgumentException("初始化上下文不能为 null！");
+        }
+        // 初始化全局上下文（使用 Application 上下文，避免内存泄漏）
+        getInstance().mContext = context.getApplicationContext();
     }
 
+    /**
+     * 外部接口：显示短时长吐司（默认显示 2 秒）
+     * 接收外部消息参数，通过 Handler 发送消息到主线程
+     * @param message 吐司展示的文本内容（非空）
+     */
     public static void show(String message) {
-        Toast.makeText(getInstance().mContext, message, Toast.LENGTH_SHORT).show();
+		LogUtils.d(TAG, "show()");
+        if (message == null || message.isEmpty()) {
+            return; // 空消息直接返回，避免无效显示
+        }
+        // 校验工具类是否初始化
+        if (getInstance().mContext == null) {
+            throw new IllegalStateException("ToastUtils 未初始化！请先调用 init(Context) 方法");
+        }
+        // 发送消息到主线程 Handler
+        getInstance().sendToastMessage(message);
+    }
+
+    /**
+     * 内部私有方法：发送吐司消息（通过 Handler 传递）
+     * 使用实例初始化时的全局上下文确保消息发送有效性
+     * @param message 吐司文本内容
+     */
+    private void sendToastMessage(String message) {
+        // 校验 Handler 和上下文是否有效
+        if (_mMainHandler == null || mContext == null) {
+            return;
+        }
+        // 创建消息对象，携带吐司内容
+        Message msg = _mMainHandler.obtainMessage(MSG_SHOW_SHORT_TOAST);
+        msg.obj = message;
+        // 发送消息（放入主线程消息队列）
+        _mMainHandler.sendMessage(msg);
+    }
+
+    /**
+     * 内部私有方法：实际显示吐司（运行在主线程）
+     * @param message 吐司文本内容
+     */
+    private void showToastInternal(String message) {
+        // 校验上下文有效性
+        if (mContext == null) {
+            return;
+        }
+        // 显示短时长吐司
+        Toast.makeText(mContext, message, Toast.LENGTH_SHORT).show();
+    }
+
+    /**
+     * 可选：释放资源（如在应用退出时调用）
+     * 移除 Handler 未处理的消息，避免内存泄漏
+     */
+    public static void release() {
+        if (getInstance()._mMainHandler != null) {
+            _mMainHandler.removeCallbacksAndMessages(null); // 移除所有未处理消息
+            _mMainHandler = null;
+        }
+        sInstance = null; // 销毁单例实例
     }
 }
+

libappbase/src/main/java/cc/winboll/studio/libappbase/UTF8FileUtils.java

@@ -1,9 +1,10 @@
 package cc.winboll.studio.libappbase;
 
 /**
- * @Author ZhanGSKen<zhangsken@qq.com>
- * @Date 2024/07/19 14:30:57
- * @Describe UTF-8编码文件工具类
+ * @Author ZhanGSKen&豆包大模型<zhangsken@qq.com>
+ * @Date 2025/11/11 20:45
+ * @Describe UTF-8 编码文件操作工具类
+ * 提供字符串与文件的相互转换，强制使用 UTF-8 编码，确保跨平台字符兼容性
  */
 import java.io.File;
 import java.io.FileInputStream;
@@ -15,35 +16,71 @@ import java.nio.charset.StandardCharsets;
 
 public class UTF8FileUtils {
 
-    public static final String TAG = "FileUtils";
+    /** 工具类日志 TAG（用于调试输出） */
+    public static final String TAG = "UTF8FileUtils";
 
-    //
-    // 把字符串写入文件，指定 UTF-8 编码
-    //
-    public static void writeStringToFile(String szFilePath, String szContent) throws IOException {
-        File file = new File(szFilePath);
-        if (!file.getParentFile().exists()) {
-            file.getParentFile().mkdirs();
+    /**
+     * 将字符串写入文件（强制 UTF-8 编码）
+     * 若文件父目录不存在，自动创建；覆盖原有文件内容
+     * @param filePath 文件路径（包含文件名，如 "/sdcard/test.txt"）
+     * @param content 要写入的字符串内容
+     * @throws IOException 写入失败时抛出（如权限不足、路径无效等）
+     */
+    public static void writeStringToFile(String filePath, String content) throws IOException {
+        // 根据路径创建文件对象
+        File file = new File(filePath);
+        // 获取父目录，若不存在则递归创建
+        File parentDir = file.getParentFile();
+        if (parentDir != null && !parentDir.exists()) {
+            parentDir.mkdirs();
         }
+
+        // 初始化文件输出流（覆盖模式）
         FileOutputStream outputStream = new FileOutputStream(file);
+        // 包装为 UTF-8 编码的字符输出流
         OutputStreamWriter writer = new OutputStreamWriter(outputStream, StandardCharsets.UTF_8);
-        writer.write(szContent);
+
+        try {
+            // 写入字符串内容
+            writer.write(content);
+        } finally {
+            // 强制关闭流，避免资源泄漏（即使写入失败也确保流关闭）
             writer.close();
         }
-
-    //
-    // 读取文件到字符串，指定 UTF-8 编码
-    //
-    public static String readStringFromFile(String szFilePath) throws IOException {
-        File file = new File(szFilePath);
-        FileInputStream inputStream = new FileInputStream(file);
-        InputStreamReader reader = new InputStreamReader(inputStream, StandardCharsets.UTF_8);
-        StringBuilder content = new StringBuilder();
-        int character;
-        while ((character = reader.read()) != -1) {
-            content.append((char) character);
     }
+
+    /**
+     * 从文件读取字符串（强制 UTF-8 编码）
+     * 逐字符读取文件内容，拼接为完整字符串返回
+     * @param filePath 文件路径（包含文件名，如 "/sdcard/test.txt"）
+     * @return 文件内容字符串（空文件返回空字符串）
+     * @throws IOException 读取失败时抛出（如文件不存在、权限不足等）
+     */
+    public static String readStringFromFile(String filePath) throws IOException {
+        // 根据路径创建文件对象
+        File file = new File(filePath);
+        // 初始化文件输入流
+        FileInputStream inputStream = new FileInputStream(file);
+        // 包装为 UTF-8 编码的字符输入流
+        InputStreamReader reader = new InputStreamReader(inputStream, StandardCharsets.UTF_8);
+
+        // 字符串构建器，用于拼接读取的字符
+        StringBuilder content = new StringBuilder();
+        int charCode; // 存储单个字符的 ASCII 码
+
+        try {
+            // 逐字符读取（-1 表示读取到文件末尾）
+            while ((charCode = reader.read()) != -1) {
+                // 将 ASCII 码转换为字符，追加到字符串
+                content.append((char) charCode);
+            }
+        } finally {
+            // 强制关闭流，避免资源泄漏
             reader.close();
+        }
+
+        // 返回读取的完整字符串
         return content.toString();
     }
 }
+

positions/build.properties

@@ -1,8 +1,8 @@
 #Created by .winboll/winboll_app_build.gradle
-#Thu Oct 02 02:27:55 HKT 2025
+#Thu Oct 02 13:16:14 GMT 2025
 stageCount=8
 libraryProject=
 baseVersion=15.0
 publishVersion=15.0.7
-buildCount=0
+buildCount=29
 baseBetaVersion=15.0.8

positions/src/main/java/cc/winboll/studio/positions/MainActivity.java

@@ -114,7 +114,7 @@ public class MainActivity extends WinBoLLActivity implements IWinBoLLActivity {
         setSupportActionBar(mToolbar);
         // 给ActionBar设置标题（先判断非空，避免空指针异常）
         if (getSupportActionBar() != null) {
-            getSupportActionBar().setTitle("位置管理");
+            getSupportActionBar().setTitle(getString(R.string.app_name));
         }
     }
 

positions/src/main/java/cc/winboll/studio/positions/activities/LocationActivity.java

@@ -3,372 +3,225 @@ package cc.winboll.studio.positions.activities;
 /**
  * @Author ZhanGSKen&豆包大模型<zhangsken@qq.com>
  * @Date 2025/09/29 18:22
- * @Describe 位置列表页面（直连服务数据+移除绑定，兼容服务私有字段）
+ * @Describe 位置列表页面（适配MainService GPS接口+规范服务交互+完善生命周期）
  */
-import android.app.Activity;
-import android.content.Context;
-import android.content.SharedPreferences;
 import android.os.Bundle;
-import android.view.View;
-import android.view.inputmethod.InputMethodManager;
+import android.os.IBinder;
+import android.app.Activity;
+import android.content.ComponentName;
+import android.content.Intent;
+import android.content.ServiceConnection;
 import android.widget.Toast;
 import androidx.recyclerview.widget.LinearLayoutManager;
 import androidx.recyclerview.widget.RecyclerView;
-import cc.winboll.studio.libaes.interfaces.IWinBoLLActivity;
+
 import cc.winboll.studio.libappbase.LogUtils;
-import cc.winboll.studio.positions.R;
 import cc.winboll.studio.positions.adapters.PositionAdapter;
 import cc.winboll.studio.positions.models.PositionModel;
 import cc.winboll.studio.positions.models.PositionTaskModel;
 import cc.winboll.studio.positions.services.MainService;
+import cc.winboll.studio.positions.R;
 import java.util.ArrayList;
 
 /**
- * 核心调整说明：
- * 1. 移除服务绑定逻辑，但不直接访问服务私有字段（解决mPositionList未知问题）
- * 2. 通过服务提供的 PUBLIC 方法（如getPositionList、addPosition）操作数据，符合封装规范
- * 3. 保留“直连服务实例”的核心需求，避免绑定，但尊重服务数据私有性
- * 4. 兼容Java 7语法，无Lambda、显式类型转换
+ * Java 7 语法适配：
+ * 1. 服务绑定用匿名内部类实现 ServiceConnection
+ * 2. Adapter 初始化传入 MainService 实例，确保数据来源唯一
+ * 3. 所有位置/任务操作通过 MainService 接口执行
  */
-public class LocationActivity extends WinBoLLActivity implements IWinBoLLActivity {
-    public static final String TAG = "LocationActivity";
+public class LocationActivity extends Activity {
+    private static final String TAG = "LocationActivity";
 
-	// SP配置常量（判断服务是否运行）
-    private static final String SP_SERVICE_CONFIG = "service_config";
-    private static final String KEY_SERVICE_RUNNING = "is_service_running";
-    // 页面核心控件与变量
-    private RecyclerView mRecyclerView;
-    private PositionAdapter mAdapter;
-    // 直连服务实例（替代绑定，通过单例/全局初始化获取）
+    private RecyclerView mRvPosition;
+    private PositionAdapter mPositionAdapter;
+    private ArrayList<PositionModel> mLocalPosCache; // 本地位置缓存（与MainService同步）
+
+    // MainService 引用+绑定状态
     private MainService mMainService;
-    // 缓存服务数据（从服务PUBLIC方法获取，避免重复调用）
-    private ArrayList<PositionModel> mCachedPositionList; 
-    private ArrayList<PositionTaskModel> mCachedTaskList;
-	
+    private boolean isServiceBound = false;
 
+    // 服务连接（Java 7 匿名内部类实现）
+    private ServiceConnection mServiceConnection = new ServiceConnection() {
         @Override
-    public Activity getActivity() {
-        return this;
+        public void onServiceConnected(ComponentName name, IBinder service) {
+            // 假设 MainService 用 LocalBinder 暴露实例（Java 7 强转）
+            MainService.LocalBinder binder = (MainService.LocalBinder) service;
+            mMainService = binder.getService();
+            isServiceBound = true;
+
+            LogUtils.d(TAG, "MainService绑定成功，开始同步数据");
+            // 从MainService同步初始数据（位置+任务）
+            syncDataFromMainService();
+            // 初始化Adapter（传入MainService实例，确保任务数据从服务获取）
+            initPositionAdapter();
         }
 
         @Override
-    public String getTag() {
-        return TAG;
+        public void onServiceDisconnected(ComponentName name) {
+            LogUtils.w(TAG, "MainService断开连接，清空引用");
+            mMainService = null;
+            isServiceBound = false;
         }
+    };
 
-    // ---------------------- 页面生命周期（简化资源管理，无服务绑定） ----------------------
     @Override
     protected void onCreate(Bundle savedInstanceState) {
         super.onCreate(savedInstanceState);
         setContentView(R.layout.activity_location);
 
-        // 1. 初始化服务实例（通过单例/全局方式，避免直接new导致数据重置）
-        initServiceInstance();
-        // 2. 检查服务状态（未运行/未初始化则提示关闭）
-        //checkServiceStatus();
-        // 3. 初始化RecyclerView（布局+性能优化）
-        initRecyclerViewConfig();
-        // 4. 缓存服务数据（从服务PUBLIC方法获取，不访问私有字段）
-        cacheServiceData();
-        // 5. 初始化Adapter（传缓存数据，而非直接访问服务私有字段）
-        initAdapter();
+        // 初始化视图+本地缓存
+        initView();
+        mLocalPosCache = new ArrayList<PositionModel>();
+
+        // 绑定MainService（确保Activity启动时就拿到服务实例）
+        bindMainService();
+    }
+
+    /**
+     * 初始化视图（RecyclerView）
+     */
+    private void initView() {
+        mRvPosition = (RecyclerView) findViewById(R.id.rv_position_list);
+        // Java 7 显式设置布局管理器（LinearLayoutManager）
+        LinearLayoutManager layoutManager = new LinearLayoutManager(this);
+        layoutManager.setOrientation(LinearLayoutManager.VERTICAL);
+        mRvPosition.setLayoutManager(layoutManager);
+    }
+
+    /**
+     * 绑定MainService（Java 7 显式Intent）
+     */
+    private void bindMainService() {
+        Intent serviceIntent = new Intent(this, MainService.class);
+        // 绑定服务（BIND_AUTO_CREATE：服务不存在时自动创建）
+        bindService(serviceIntent, mServiceConnection, BIND_AUTO_CREATE);
+        LogUtils.d(TAG, "发起MainService绑定请求");
+    }
+
+    /**
+     * 从MainService同步数据（位置+任务）
+     */
+    private void syncDataFromMainService() {
+        if (!isServiceBound || mMainService == null) {
+            LogUtils.w(TAG, "同步数据失败：MainService未绑定");
+            showToast("服务未就绪，无法加载数据");
+            return;
+        }
+
+        // 同步位置数据（从服务获取最新列表）
+        ArrayList<PositionModel> servicePosList = mMainService.getPositionList();
+        if (servicePosList != null && !servicePosList.isEmpty()) {
+            mLocalPosCache.clear();
+            mLocalPosCache.addAll(servicePosList);
+            LogUtils.d(TAG, "从MainService同步位置数据完成：数量=" + mLocalPosCache.size());
+        }
+
+        // 同步任务数据（无需本地缓存，Adapter直接从服务获取）
+        ArrayList<PositionTaskModel> serviceTaskList = mMainService.getAllTasks();
+        LogUtils.d(TAG, "从MainService同步任务数据完成：数量=" + serviceTaskList.size());
+    }
+
+    /**
+     * 初始化PositionAdapter（核心：传入MainService实例）
+     */
+    private void initPositionAdapter() {
+        if (mMainService == null) {
+            LogUtils.e(TAG, "初始化Adapter失败：MainService为空");
+            return;
+        }
+
+        // Java 7 显式初始化Adapter，传入上下文+本地位置缓存+MainService实例
+        mPositionAdapter = new PositionAdapter(this, mLocalPosCache, mMainService);
+
+        // 设置Adapter回调（处理位置删除/保存，最终同步到MainService）
+        mPositionAdapter.setOnDeleteClickListener(new PositionAdapter.OnDeleteClickListener() {
+				@Override
+				public void onDeleteClick(int position) {
+					// 删除逻辑：先删本地缓存，再调用MainService接口删服务数据
+					if (position < 0 || position >= mLocalPosCache.size()) {
+						LogUtils.w(TAG, "删除位置失败：无效索引=" + position);
+						return;
+					}
+					PositionModel deletePos = mLocalPosCache.get(position);
+					if (deletePos != null && !deletePos.getPositionId().isEmpty()) {
+						// 1. 调用MainService接口删除服务端数据
+						mMainService.removePosition(deletePos.getPositionId());
+						// 2. 删除本地缓存数据
+						mLocalPosCache.remove(position);
+						// 3. 通知Adapter刷新
+						mPositionAdapter.notifyItemRemoved(position);
+						showToast("删除位置成功：" + deletePos.getMemo());
+						LogUtils.d(TAG, "删除位置完成：ID=" + deletePos.getPositionId() + "（已同步MainService）");
+					}
+				}
+			});
+
+        mPositionAdapter.setOnSavePositionClickListener(new PositionAdapter.OnSavePositionClickListener() {
+				@Override
+				public void onSavePositionClick(int position, PositionModel updatedPos) {
+					// 保存逻辑：先更本地缓存，再调用MainService接口更新服务数据
+					if (!isServiceBound || mMainService == null) {
+						LogUtils.w(TAG, "保存位置失败：MainService未绑定");
+						showToast("服务未就绪，保存失败");
+						return;
+					}
+					if (position < 0 || position >= mLocalPosCache.size()) {
+						LogUtils.w(TAG, "保存位置失败：无效索引=" + position);
+						return;
+					}
+
+					// 1. 调用MainService接口更新服务端数据
+					mMainService.updatePosition(updatedPos);
+					// 2. 更新本地缓存数据
+					mLocalPosCache.set(position, updatedPos);
+					// 3. 通知Adapter刷新（可选，Adapter已本地同步）
+					mPositionAdapter.notifyItemChanged(position);
+					showToast("保存位置成功：" + updatedPos.getMemo());
+					LogUtils.d(TAG, "保存位置完成：ID=" + updatedPos.getPositionId() + "（已同步MainService）");
+				}
+			});
+
+        // 设置Adapter到RecyclerView
+        mRvPosition.setAdapter(mPositionAdapter);
+        LogUtils.d(TAG, "PositionAdapter初始化完成（已绑定MainService）");
+    }
+
+    /**
+     * 显示Toast（Java 7 显式Toast.makeText）
+     */
+    private void showToast(String content) {
+        Toast.makeText(this, content, Toast.LENGTH_SHORT).show();
     }
 
     @Override
     protected void onDestroy() {
         super.onDestroy();
-        // 1. 清理Adapter资源
-        if (mAdapter != null) {
-            mAdapter.release();
-            mAdapter = null;
-        }
-        // 2. 置空服务实例+缓存数据（帮助GC回收）
-        mMainService = null;
-        mCachedPositionList = null;
-        mCachedTaskList = null;
-        mRecyclerView = null;
-        LogUtils.d(TAG, "页面销毁：已清理服务实例及缓存数据");
+
+        // 1. 释放Adapter资源（反注册服务监听，避免内存泄漏）
+        if (mPositionAdapter != null) {
+            mPositionAdapter.release();
         }
 
-    // ---------------------- 核心初始化（服务实例+数据缓存+状态检查） ----------------------
-    /**
-     * 初始化服务实例（关键：通过单例获取，确保全局唯一，避免数据重复）
-     * 注：需在DistanceRefreshService中实现单例（getInstance()方法）
-     */
-    private void initServiceInstance() {
-		// 步骤1：先启动Service（确保Service已创建，实例能被初始化）
-        
-        // 步骤2：初始化Service实例（延迟100-200ms，确保Service onCreate执行完成）
-        // （或在startService后，通过ServiceConnection绑定获取实例，更可靠）
-        //initServiceInstance();
-		
-        // 方式：通过服务PUBLIC单例方法获取实例（不直接new，避免私有数据初始化重复）
-        mMainService = MainService.getInstance();
-        
-        // 容错：若单例未初始化（如首次启动），提示并处理
-        if (mMainService == null) {
-            LogUtils.e(TAG, "服务实例初始化失败：单例未创建");
-            Toast.makeText(this, "位置服务初始化失败，请重启应用", Toast.LENGTH_SHORT).show();
-            finish();
+        // 2. 解绑MainService（避免Activity销毁后服务仍被持有）
+        if (isServiceBound) {
+            unbindService(mServiceConnection);
+            LogUtils.d(TAG, "MainService解绑完成");
         }
     }
 	
-    /**
-     * 检查服务状态（替代原绑定检查，通过服务PUBLIC方法判断）
-     */
-    private void checkServiceStatus() {
-        // 1. 服务实例未初始化
-        if (mMainService == null) {
-            return; // 已在initServiceInstance中处理，此处避免重复finish
+	public static class LocalBinder extends android.os.Binder {
+        // 持有 MainService 实例引用
+        private MainService mService;
+
+        // 构造时传入服务实例
+        public LocalBinder(MainService service) {
+            this.mService = service;
         }
 
-        // 2. 检查服务运行状态（通过服务PUBLIC方法isServiceRunning()获取，不访问私有字段）
-//        if (!mMainService.isServiceRunning()) {
-//            // 服务未运行：手动触发启动（调用服务PUBLIC方法run()）
-//            mMainService.run();
-//            LogUtils.d(TAG, "服务未运行，已通过PUBLIC方法触发启动");
-//        }
-
-        // 3. 检查SP中服务配置（双重校验，确保一致性）
-        SharedPreferences sp = getSharedPreferences(SP_SERVICE_CONFIG, Context.MODE_PRIVATE);
-        boolean isServiceConfigRunning = sp.getBoolean(KEY_SERVICE_RUNNING, false);
-        if (!isServiceConfigRunning) {
-            Toast.makeText(this, "位置服务配置未启用，数据可能无法更新", Toast.LENGTH_SHORT).show();
+        // 对外提供获取服务实例的方法（供Activity调用）
+        public MainService getService() {
+            return mService;
+        }
     }
 }
 
-    /**
-     * 缓存服务数据（从服务PUBLIC方法获取，解决私有字段未知问题）
-     */
-    private void cacheServiceData() {
-        if (mMainService == null) {
-            LogUtils.e(TAG, "缓存数据失败：服务实例为空");
-            mCachedPositionList = new ArrayList<PositionModel>();
-            mCachedTaskList = new ArrayList<PositionTaskModel>();
-            return;
-        }
-
-        // 从服务PUBLIC方法获取数据（不访问mPositionList，而是调用getPositionList()）
-        mCachedPositionList = mMainService.getPositionList();
-        mCachedTaskList = mMainService.getPositionTasksList();
-        
-        // 容错：若服务返回null，初始化空列表避免空指针
-        if (mCachedPositionList == null) mCachedPositionList = new ArrayList<PositionModel>();
-        if (mCachedTaskList == null) mCachedTaskList = new ArrayList<PositionTaskModel>();
-        
-        LogUtils.d(TAG, "缓存服务数据成功：位置数=" + mCachedPositionList.size() + "，任务数=" + mCachedTaskList.size());
-    }
-
-    /**
-     * 初始化RecyclerView（保留原性能优化）
-     */
-    private void initRecyclerViewConfig() {
-        mRecyclerView = (RecyclerView) findViewById(R.id.rv_position_list);
-        LinearLayoutManager layoutManager = new LinearLayoutManager(this);
-        layoutManager.setOrientation(LinearLayoutManager.VERTICAL);
-        mRecyclerView.setLayoutManager(layoutManager);
-        mRecyclerView.setHasFixedSize(true); // 固定大小，优化绘制
-    }
-
-    // ---------------------- Adapter初始化与数据交互（全通过服务PUBLIC方法） ----------------------
-    /**
-     * 初始化Adapter（通过缓存数据初始化，数据更新时同步调用服务方法）
-     */
-    private void initAdapter() {
-        if (mCachedPositionList == null || mCachedTaskList == null) {
-            LogUtils.e(TAG, "初始化Adapter失败：缓存数据为空");
-            return;
-        }
-
-        // 1. 初始化Adapter（传缓存数据+服务实例，Adapter数据从缓存取，操作通过服务）
-        mAdapter = new PositionAdapter(this, mCachedPositionList, mCachedTaskList);
-        mRecyclerView.setAdapter(mAdapter);
-
-        // 2. 删除回调：通过服务PUBLIC方法removePosition()删除，不直接操作私有字段
-        mAdapter.setOnDeleteClickListener(new PositionAdapter.OnDeleteClickListener() {
-            @Override
-            public void onDeleteClick(int position) {
-                // 校验：服务实例有效+索引合法
-                if (mMainService == null || mCachedPositionList == null) {
-                    Toast.makeText(LocationActivity.this, "删除失败：服务未就绪", Toast.LENGTH_SHORT).show();
-                    return;
-                }
-                if (position < 0 || position >= mCachedPositionList.size()) {
-                    LogUtils.w(TAG, "删除失败：索引无效（" + position + "）");
-                    Toast.makeText(LocationActivity.this, "删除失败：数据位置异常", Toast.LENGTH_SHORT).show();
-                    return;
-                }
-
-                // 1. 获取要删除的位置（从缓存取，与服务数据一致）
-                PositionModel targetPos = mCachedPositionList.get(position);
-                String targetPosId = targetPos.getPositionId();
-
-                // 2. 调用服务PUBLIC方法删除（服务内部处理mPositionList/mTaskList，符合封装）
-                mMainService.removePosition(targetPosId);
-                LogUtils.d(TAG, "通过服务删除位置：ID=" + targetPosId);
-
-                // 3. 刷新缓存+Adapter（从服务重新获取数据，确保与服务一致）
-                refreshCachedDataAndAdapter();
-                Toast.makeText(LocationActivity.this, "位置已删除（含关联任务）", Toast.LENGTH_SHORT).show();
-            }
-        });
-
-        // 3. 位置保存回调：通过服务PUBLIC方法updatePosition()更新
-        mAdapter.setOnSavePositionClickListener(new PositionAdapter.OnSavePositionClickListener() {
-            @Override
-            public void onSavePositionClick(int position, PositionModel updatedPos) {
-                // 校验：服务+数据+参数有效
-                if (mMainService == null || mCachedPositionList == null || updatedPos == null) {
-                    Toast.makeText(LocationActivity.this, "保存失败：服务或数据异常", Toast.LENGTH_SHORT).show();
-                    return;
-                }
-                if (position < 0 || position >= mCachedPositionList.size()) {
-                    LogUtils.w(TAG, "保存失败：位置索引无效");
-                    return;
-                }
-
-                // 1. 调用服务PUBLIC方法更新数据（服务内部修改mPositionList）
-                mMainService.updatePosition(updatedPos);
-                LogUtils.d(TAG, "通过服务保存位置：ID=" + updatedPos.getPositionId());
-
-                // 2. 刷新缓存+Adapter（确保本地显示与服务一致）
-                refreshCachedDataAndAdapter();
-                Toast.makeText(LocationActivity.this, "位置信息已保存", Toast.LENGTH_SHORT).show();
-            }
-        });
-
-        // 4. 任务保存回调：通过服务PUBLIC方法syncAllPositionTasks()同步
-        mAdapter.setOnSavePositionTaskClickListener(new PositionAdapter.OnSavePositionTaskClickListener() {
-            @Override
-            public void onSavePositionTaskClick(PositionTaskModel newTask) {
-                if (mMainService == null || newTask == null) {
-                    Toast.makeText(LocationActivity.this, "保存失败：服务或任务数据为空", Toast.LENGTH_SHORT).show();
-                    return;
-                }
-
-                // 1. 构建新任务列表（缓存任务+新任务，去重）
-                ArrayList<PositionTaskModel> newTaskList = new ArrayList<PositionTaskModel>(mCachedTaskList);
-                // 先移除同ID旧任务（避免重复）
-                for (int i = 0; i < newTaskList.size(); i++) {
-                    PositionTaskModel oldTask = newTaskList.get(i);
-                    if (newTask.getTaskId().equals(oldTask.getTaskId())) {
-                        newTaskList.remove(i);
-                        break;
-                    }
-                }
-                // 添加新任务
-                newTaskList.add(newTask);
-
-                // 2. 调用服务PUBLIC方法同步任务（服务内部更新mTaskList）
-                mMainService.syncAllPositionTasks(newTaskList);
-                LogUtils.d(TAG, "通过服务保存任务：ID=" + newTask.getTaskId());
-
-                // 3. 刷新缓存+Adapter
-                refreshCachedDataAndAdapter();
-                Toast.makeText(LocationActivity.this, "任务信息已保存", Toast.LENGTH_SHORT).show();
-            }
-        });
-    }
-
-    // ---------------------- 页面交互（新增位置、同步GPS，全走服务PUBLIC方法） ----------------------
-    /**
-     * 新增位置（调用服务addPosition()，不直接操作mPositionList）
-     */
-    public void addNewPosition(View view) {
-        // 1. 隐藏软键盘
-        InputMethodManager imm = (InputMethodManager) getSystemService(Context.INPUT_METHOD_SERVICE);
-        if (imm != null && getCurrentFocus() != null) {
-            imm.hideSoftInputFromWindow(getCurrentFocus().getWindowToken(), 0);
-        }
-
-        // 2. 校验服务状态
-        if (mMainService == null) {
-            Toast.makeText(this, "新增失败：服务未初始化", Toast.LENGTH_SHORT).show();
-            return;
-        }
-
-        // 3. 创建新位置模型
-        PositionModel newPos = new PositionModel();
-        newPos.setPositionId(PositionModel.genPositionId()); // 生成唯一ID（PositionModel需实现）
-        newPos.setLongitude(116.404267); // 示例经度（北京）
-        newPos.setLatitude(39.915119);  // 示例纬度
-        newPos.setMemo("测试位置（可编辑备注）");
-        newPos.setIsSimpleView(true);   // 默认简单视图
-        newPos.setIsEnableRealPositionDistance(true); // 启用距离计算
-
-        // 4. 调用服务PUBLIC方法新增（服务内部处理mPositionList去重+添加）
-        mMainService.addPosition(newPos);
-        LogUtils.d(TAG, "通过服务新增位置：ID=" + newPos.getPositionId());
-
-        // 5. 刷新缓存+Adapter（显示新增结果）
-        refreshCachedDataAndAdapter();
-        Toast.makeText(this, "新增位置成功（已启用距离计算）", Toast.LENGTH_SHORT).show();
-    }
-
-    /**
-     * 同步GPS位置到服务（调用服务syncCurrentGpsPosition()，不访问私有字段）
-     */
-    public void syncGpsPositionToService(PositionModel gpsModel) {
-        if (mMainService == null || gpsModel == null) {
-            LogUtils.w(TAG, "同步GPS失败：服务未就绪或GPS数据无效");
-            return;
-        }
-
-        // 调用服务PUBLIC方法同步GPS（服务内部更新mCurrentGpsPosition）
-        mMainService.syncCurrentGpsPosition(gpsModel);
-        // 强制刷新距离（通过服务PUBLIC方法，触发mPositionList距离计算）
-        mMainService.forceRefreshDistance();
-        LogUtils.d(TAG, "GPS位置已同步，通过服务触发距离计算");
-
-        // 刷新缓存+Adapter（显示最新距离）
-        refreshCachedDataAndAdapter();
-    }
-
-    // ---------------------- 辅助方法（统一刷新缓存与Adapter，确保数据一致） ----------------------
-    /**
-     * 刷新缓存数据+Adapter（从服务重新获取数据，避免本地缓存与服务不一致）
-     */
-    private void refreshCachedDataAndAdapter() {
-        if (mMainService == null) {
-            LogUtils.w(TAG, "刷新失败：服务实例为空");
-            return;
-        }
-
-        // 1. 从服务重新获取数据（更新缓存，不访问私有字段）
-        mCachedPositionList = mMainService.getPositionList();
-        mCachedTaskList = mMainService.getPositionTasksList();
-        // 容错处理
-        if (mCachedPositionList == null) mCachedPositionList = new ArrayList<PositionModel>();
-        if (mCachedTaskList == null) mCachedTaskList = new ArrayList<PositionTaskModel>();
-
-        // 2. 刷新Adapter（全量刷新，简单可靠；若需性能优化可改为局部刷新）
-        if (mAdapter != null) {
-            mAdapter.updateAllData(mCachedPositionList, mCachedTaskList);
-        }
-        LogUtils.d(TAG, "刷新完成：当前位置数=" + mCachedPositionList.size() + "，任务数=" + mCachedTaskList.size());
-    }
-
-    // ---------------------- 补充：DistanceRefreshService单例实现（需在服务中添加） ----------------------
-    // 注：以下代码需复制到 DistanceRefreshService 类中，确保实例唯一（解决直接new的问题）
-    /*
-    // 服务单例实例（私有静态）
-    private static DistanceRefreshService sInstance;
-
-    // 单例PUBLIC方法（供外部获取实例，确保全局唯一）
-    public static synchronized DistanceRefreshService getInstance() {
-        if (sInstance == null) {
-            sInstance = new DistanceRefreshService();
-            // 初始化服务核心逻辑（如GPS管理器、线程池，避免重复初始化）
-            sInstance.mLocationManager = (LocationManager) sInstance.getApplicationContext().getSystemService(Context.LOCATION_SERVICE);
-            sInstance.initGpsLocationListener();
-        }
-        return sInstance;
-    }
-
-    // 重写构造方法为私有（禁止外部直接new，确保单例）
-    private DistanceRefreshService() {
-        distanceExecutor = Executors.newSingleThreadScheduledExecutor();
-    }
-    */
-}
-

positions/src/main/java/cc/winboll/studio/positions/adapters/PositionAdapter.java

@@ -5,7 +5,6 @@ package cc.winboll.studio.positions.adapters;
  * @Date 2025/09/29 20:25
  * @Describe 位置数据适配器（完全独立，无未知接口依赖，仅用LocationActivity缓存数据）
  */
-
 import android.content.Context;
 import android.view.LayoutInflater;
 import android.view.View;
@@ -15,30 +14,36 @@ import android.widget.Button;
 import android.widget.EditText;
 import android.widget.RadioGroup;
 import android.widget.TextView;
+import android.text.TextUtils;
 import androidx.recyclerview.widget.RecyclerView;
+
 import cc.winboll.studio.libappbase.LogUtils;
 import cc.winboll.studio.positions.R;
 import cc.winboll.studio.positions.models.PositionModel;
 import cc.winboll.studio.positions.models.PositionTaskModel;
+import cc.winboll.studio.positions.services.MainService;
+
+import java.lang.ref.WeakReference;
 import java.util.ArrayList;
 import java.util.ConcurrentModificationException;
 import java.util.Iterator;
 import java.util.concurrent.ConcurrentHashMap;
 
 /**
- * 核心调整：
- * 1. 彻底删除所有与 DistanceServiceInterface 相关的代码（解决未知类型问题）
- * 2. 完全基于 LocationActivity 传入的缓存数据（mCachedPositionList/mCachedTaskList）实现所有功能
- * 3. 移除服务回调、可见位置通知等冗余逻辑，仅保留“数据显示+用户交互→通知Activity处理”的核心流程
- * 4. 确保无未定义接口、无外部服务依赖，代码可直接编译运行
+ * Java 7 语法适配：
+ * 1. 移除 Lambda/方法引用，用匿名内部类替代
+ * 2. 集合操作使用迭代器（避免 ConcurrentModificationException）
+ * 3. 弱引用管理 MainService，避免内存泄漏
+ * 4. 所有任务数据从 MainService 获取，更新通过 MainService 接口
  */
-public class PositionAdapter extends RecyclerView.Adapter<RecyclerView.ViewHolder> {
+public class PositionAdapter extends RecyclerView.Adapter<RecyclerView.ViewHolder> implements MainService.TaskUpdateListener {
     public static final String TAG = "PositionAdapter";
 
-    // 1. 视图类型常量（简单视图/编辑视图，无魔法值）
+    // 视图类型常量（Java 7 静态常量定义）
     private static final int VIEW_TYPE_SIMPLE = 0;
     private static final int VIEW_TYPE_EDIT = 1;
-    // 2. 默认配置（文本显示/任务默认值，统一管理）
+
+    // 默认配置常量（统一管理，避免魔法值）
     private static final String DEFAULT_MEMO = "无备注";
     private static final String DEFAULT_TASK_DESC = "新任务";
     private static final int DEFAULT_TASK_DISTANCE = 50; // 单位：米
@@ -46,81 +51,61 @@ public class PositionAdapter extends RecyclerView.Adapter<RecyclerView.ViewHolde
     private static final String DISTANCE_DISABLED = "实时距离：未启用";
     private static final String DISTANCE_ERROR = "实时距离：计算失败";
 
-    // 3. 唯一数据源（完全依赖 LocationActivity 传入的缓存数据，无其他来源）
+    // 核心依赖（Java 7 弱引用+集合定义）
     private final Context mContext;
-    private ArrayList<PositionModel> mCachedPositionList; // 位置缓存（来自Activity）
-    private ArrayList<PositionTaskModel> mCachedTaskList;  // 任务缓存（来自Activity）
+    private final ArrayList<PositionModel> mCachedPositionList; // 位置缓存（从Activity传入，最终需与MainService同步）
+    private final WeakReference<MainService> mMainServiceRef;   // 弱引用MainService，避免内存泄漏
+    private final ConcurrentHashMap<String, TextView> mPosDistanceViewMap; // 距离控件缓存（优化UI更新）
 
-    // 4. 本地辅助缓存（优化性能：避免重复遍历，不依赖外部服务）
-    private final ConcurrentHashMap<String, ArrayList<PositionTaskModel>> mPosToTasksMap; // 位置ID→关联任务（本地分组）
-    private final ConcurrentHashMap<String, TextView> mPosDistanceViewMap; // 位置ID→距离控件（更新UI用）
-
-    // =========================================================================
-    // 与 LocationActivity 交互的回调接口（仅定义必要功能，无冗余）
-    // =========================================================================
-    // 删除位置：通知Activity删除指定索引的位置数据
+    // 回调接口（与Activity交互，仅处理位置逻辑，任务逻辑直接调用MainService）
     public interface OnDeleteClickListener {
         void onDeleteClick(int position);
     }
 
-    // 保存位置：通知Activity保存更新后的位置模型（带索引，方便Activity定位修改）
     public interface OnSavePositionClickListener {
         void onSavePositionClick(int position, PositionModel updatedPos);
     }
 
-    // 保存任务：通知Activity保存新增/修改的任务（带任务模型，Activity处理数据同步）
-    public interface OnSavePositionTaskClickListener {
-        void onSavePositionTaskClick(PositionTaskModel newTask);
-    }
-
-    // 回调实例（由LocationActivity初始化时设置，解耦Activity与Adapter）
     private OnDeleteClickListener mOnDeleteListener;
     private OnSavePositionClickListener mOnSavePosListener;
-    private OnSavePositionTaskClickListener mOnSaveTaskListener;
 
     // =========================================================================
-    // 构造函数（仅接收上下文+Activity缓存数据，无其他依赖，解决接口未定义问题）
+    // 构造函数（Java 7 风格：初始化依赖+注册任务监听）
     // =========================================================================
-    /**
-     * 唯一构造函数（确保无未知接口依赖，直接使用Activity提供的数据）
-     * @param context 上下文（加载布局、操作软键盘、获取资源）
-     * @param cachedPositionList LocationActivity中的位置缓存（唯一位置数据源）
-     * @param cachedTaskList LocationActivity中的任务缓存（唯一任务数据源）
-     */
-    public PositionAdapter(Context context, ArrayList<PositionModel> cachedPositionList, ArrayList<PositionTaskModel> cachedTaskList) {
+    public PositionAdapter(Context context, ArrayList<PositionModel> cachedPositionList, MainService mainService) {
         this.mContext = context;
-        // 初始化数据源（容错处理：若Activity传入null，初始化空列表避免空指针）
+        // 容错处理：避免传入null导致空指针
         this.mCachedPositionList = (cachedPositionList != null) ? cachedPositionList : new ArrayList<PositionModel>();
-        this.mCachedTaskList = (cachedTaskList != null) ? cachedTaskList : new ArrayList<PositionTaskModel>();
-
-        // 初始化本地辅助缓存（基于Activity传入的数据构建，提升后续操作性能）
-        this.mPosToTasksMap = new ConcurrentHashMap<String, ArrayList<PositionTaskModel>>();
+        // 弱引用MainService：防止Adapter持有Service导致内存泄漏（Java 7 弱引用语法）
+        this.mMainServiceRef = new WeakReference<MainService>(mainService);
+        // 初始化距离控件缓存（线程安全集合，适配多线程更新场景）
         this.mPosDistanceViewMap = new ConcurrentHashMap<String, TextView>();
 
-        // 初始化“位置→任务”映射（从Activity任务缓存中分组，避免每次显示都遍历全量任务）
-        refreshPositionTaskMap();
-        LogUtils.d(TAG, "Adapter初始化完成：位置数=" + mCachedPositionList.size() + "，任务数=" + mCachedTaskList.size());
+        // 注册MainService任务监听：服务任务变化时自动刷新Adapter（Java 7 接口实现）
+        if (mainService != null) {
+            mainService.registerTaskUpdateListener(this);
+            LogUtils.d(TAG, "已注册MainService任务监听，确保任务数据与服务同步");
+        } else {
+            LogUtils.w(TAG, "构造函数：MainService为空，任务数据无法同步");
+        }
+
+        LogUtils.d(TAG, "Adapter初始化完成：位置数量=" + mCachedPositionList.size());
     }
 
     // =========================================================================
-    // RecyclerView 核心方法（完全基于Activity缓存数据实现，无接口调用）
+    // RecyclerView 核心方法（Java 7 语法适配）
     // =========================================================================
-    /**
-     * 判断当前项的视图类型（简单/编辑）：从Activity缓存数据中读取状态
-     */
     @Override
     public int getItemViewType(int position) {
+        // 从位置缓存获取状态，判断视图类型（简单/编辑）
         PositionModel posModel = getPositionByIndex(position);
-        // 若位置模型为空或标记为简单视图，返回简单视图类型
         return (posModel != null && posModel.isSimpleView()) ? VIEW_TYPE_SIMPLE : VIEW_TYPE_EDIT;
     }
 
-    /**
-     * 创建视图Holder（根据类型加载布局，无外部依赖）
-     */
     @Override
     public RecyclerView.ViewHolder onCreateViewHolder(ViewGroup parent, int viewType) {
         LayoutInflater inflater = LayoutInflater.from(mContext);
+        // 根据视图类型加载对应布局（Java 7 条件判断）
         if (viewType == VIEW_TYPE_SIMPLE) {
             View simpleView = inflater.inflate(R.layout.item_position_simple, parent, false);
             return new SimpleViewHolder(simpleView);
@@ -130,111 +115,117 @@ public class PositionAdapter extends RecyclerView.Adapter<RecyclerView.ViewHolde
         }
     }
 
-    /**
-     * 绑定视图数据（核心逻辑：从Activity缓存取数，不调用任何外部接口）
-     */
     @Override
     public void onBindViewHolder(RecyclerView.ViewHolder holder, int position) {
         PositionModel posModel = getPositionByIndex(position);
         if (posModel == null) {
-            LogUtils.w(TAG, "绑定数据失败：位置模型为空（索引=" + position + "）");
+            LogUtils.w(TAG, "onBindViewHolder：位置模型为空（索引=" + position + "），跳过绑定");
             return;
         }
         String posId = posModel.getPositionId();
 
-        // 根据视图类型绑定数据（简单视图/编辑视图分别处理）
+        // 按视图类型绑定数据（Java 7 类型判断）
         if (holder instanceof SimpleViewHolder) {
             bindSimpleView((SimpleViewHolder) holder, posModel);
         } else if (holder instanceof EditViewHolder) {
             bindEditView((EditViewHolder) holder, posModel, position);
         }
 
-        // 缓存当前位置的距离控件（后续更新距离UI时直接使用，避免重新查找）
+        // 缓存当前位置的距离控件（后续局部更新距离时直接使用）
         TextView distanceView = (holder instanceof SimpleViewHolder)
 			? ((SimpleViewHolder) holder).tvSimpleDistance
 			: ((EditViewHolder) holder).tvEditDistance;
+        if (distanceView != null && !TextUtils.isEmpty(posId)) {
             mPosDistanceViewMap.put(posId, distanceView);
         }
+    }
 
-    /**
-     * 视图离开屏幕（清理距离控件缓存，避免内存泄漏）
-     */
     @Override
     public void onViewDetachedFromWindow(RecyclerView.ViewHolder holder) {
         super.onViewDetachedFromWindow(holder);
+        // 视图离开屏幕时，移除距离控件缓存（避免内存泄漏+引用失效控件）
         PositionModel posModel = getPositionByIndex(holder.getAdapterPosition());
-        if (posModel != null) {
-            mPosDistanceViewMap.remove(posModel.getPositionId()); // 移除不再显示的控件引用
+        if (posModel != null && !TextUtils.isEmpty(posModel.getPositionId())) {
+            mPosDistanceViewMap.remove(posModel.getPositionId());
+            LogUtils.d(TAG, "视图脱离屏幕：移除位置ID=" + posModel.getPositionId() + "的距离控件缓存");
         }
     }
 
-    /**
-     * 获取列表项数量（直接从Activity位置缓存中取，无中间层）
-     */
     @Override
     public int getItemCount() {
+        // 直接从位置缓存获取数量（数据源唯一）
         return mCachedPositionList.size();
     }
 
     // =========================================================================
-    // 视图绑定细节（完全基于缓存数据，操作后通过回调通知Activity）
+    // 视图绑定逻辑（Java 7 风格：任务数据从MainService获取）
     // =========================================================================
     /**
-     * 绑定“简单视图”（仅显示数据，点击切换到编辑视图）
+     * 绑定简单视图（仅显示数据，点击切换到编辑视图）
      */
     private void bindSimpleView(final SimpleViewHolder holder, final PositionModel posModel) {
-        // 1. 显示经纬度（从Activity缓存数据中取，格式化6位小数提升可读性）
+        // 1. 显示经纬度（Java 7 String.format格式化）
         holder.tvSimpleLon.setText(String.format("经度：%.6f", posModel.getLongitude()));
         holder.tvSimpleLat.setText(String.format("纬度：%.6f", posModel.getLatitude()));
-        // 2. 显示备注（无备注时显示默认文本，避免空白）
+
+        // 2. 显示备注（无备注时显示默认文本）
         String memo = posModel.getMemo();
-        holder.tvSimpleMemo.setText("备注：" + (memo != null && !memo.isEmpty() ? memo : DEFAULT_MEMO));
-        // 3. 显示实时距离（从缓存数据的distance字段取数，按状态显示不同内容）
+        holder.tvSimpleMemo.setText("备注：" + (TextUtils.isEmpty(memo) ? DEFAULT_MEMO : memo));
+
+        // 3. 显示实时距离（从位置模型取数，调用工具方法更新显示）
         updateDistanceDisplay(holder.tvSimpleDistance, posModel);
-        // 4. 点击视图→切换到编辑模式（修改缓存数据中的状态，通知RecyclerView刷新）
+
+        // 4. 点击切换到编辑视图（Java 7 匿名内部类实现点击事件）
         holder.itemView.setOnClickListener(new View.OnClickListener() {
 				@Override
 				public void onClick(View v) {
-					posModel.setIsSimpleView(false); // 修改缓存数据中的视图状态
-					notifyItemChanged(getPositionIndexById(posModel.getPositionId())); // 刷新对应项
+					posModel.setIsSimpleView(false); // 修改位置缓存状态
+					// 通知RecyclerView刷新当前项（精准更新，避免全量刷新）
+					notifyItemChanged(getPositionIndexById(posModel.getPositionId()));
+					LogUtils.d(TAG, "简单视图点击：位置ID=" + posModel.getPositionId() + "，切换到编辑视图");
 				}
 			});
     }
 
     /**
-     * 绑定“编辑视图”（支持修改备注、开关距离、删除/保存位置、新增任务）
+     * 绑定编辑视图（支持修改备注、开关距离、删除/保存位置、新增任务）
      */
     private void bindEditView(final EditViewHolder holder, final PositionModel posModel, final int position) {
         final String posId = posModel.getPositionId();
 
-        // 1. 显示经纬度（不可编辑，仅展示，从缓存数据取）
+        // 1. 显示经纬度（不可编辑，仅展示）
         holder.tvEditLon.setText(String.format("经度：%.6f", posModel.getLongitude()));
         holder.tvEditLat.setText(String.format("纬度：%.6f", posModel.getLatitude()));
-        // 2. 显示备注（编辑框赋值，光标定位到末尾，方便用户直接编辑）
+
+        // 2. 显示备注（编辑框赋值，光标定位到末尾）
         String memo = posModel.getMemo();
-        if (memo != null && !memo.isEmpty()) {
+        if (!TextUtils.isEmpty(memo)) {
             holder.etEditMemo.setText(memo);
-            holder.etEditMemo.setSelection(memo.length());
+            holder.etEditMemo.setSelection(memo.length()); // 光标定位到文本末尾
         } else {
             holder.etEditMemo.setText(""); // 无备注时清空编辑框
         }
-        // 3. 显示实时距离（与简单视图逻辑一致，从缓存数据取数）
-        updateDistanceDisplay(holder.tvEditDistance, posModel);
-        // 4. 设置距离开关状态（匹配缓存数据中的启用状态，确保UI与数据一致）
-        holder.rgDistanceSwitch.check(posModel.isEnableRealPositionDistance() 
-									  ? R.id.rb_distance_enable : R.id.rb_distance_disable);
 
-        // 5. 取消编辑→切换回简单视图（修改缓存状态，刷新UI，隐藏软键盘）
+        // 3. 显示实时距离（与简单视图逻辑一致）
+        updateDistanceDisplay(holder.tvEditDistance, posModel);
+
+        // 4. 设置距离开关状态（匹配位置缓存中的启用状态）
+        holder.rgDistanceSwitch.check(posModel.isEnableRealPositionDistance()
+									  ? R.id.rb_distance_enable
+									  : R.id.rb_distance_disable);
+
+        // 5. 取消编辑：切换回简单视图（Java 7 匿名内部类）
         holder.btnCancel.setOnClickListener(new View.OnClickListener() {
 				@Override
 				public void onClick(View v) {
 					posModel.setIsSimpleView(true);
 					notifyItemChanged(position);
-					hideSoftKeyboard(v);
+					hideSoftKeyboard(v); // 隐藏软键盘（提升用户体验）
+					LogUtils.d(TAG, "取消编辑：位置ID=" + posId + "，切换回简单视图");
 				}
 			});
 
-        // 6. 删除位置→回调Activity处理（Adapter不直接删数据，由Activity操作缓存+服务）
+        // 6. 删除位置：回调Activity处理（Adapter不直接删数据，由Activity同步MainService）
         holder.btnDelete.setOnClickListener(new View.OnClickListener() {
 				@Override
 				public void onClick(View v) {
@@ -242,10 +233,11 @@ public class PositionAdapter extends RecyclerView.Adapter<RecyclerView.ViewHolde
 						mOnDeleteListener.onDeleteClick(position); // 通知Activity删除指定索引
 					}
 					hideSoftKeyboard(v);
+					LogUtils.d(TAG, "触发删除：通知Activity处理位置ID=" + posId + "的删除逻辑");
 				}
 			});
 
-        // 7. 保存位置→回调Activity保存（收集编辑后的参数，传更新后的模型）
+        // 7. 保存位置：回调Activity保存（收集参数→构建更新模型→通知Activity）
         holder.btnSave.setOnClickListener(new View.OnClickListener() {
 				@Override
 				public void onClick(View v) {
@@ -262,85 +254,85 @@ public class PositionAdapter extends RecyclerView.Adapter<RecyclerView.ViewHolde
 					updatedPos.setIsEnableRealPositionDistance(isDistanceEnable); // 更新距离状态
 					updatedPos.setIsSimpleView(true);                 // 切换回简单视图
 
-					// 回调Activity保存（由Activity同步缓存数据+服务数据，Adapter不处理逻辑）
+					// 回调Activity保存（由Activity同步MainService+位置缓存，Adapter不处理逻辑）
 					if (mOnSavePosListener != null) {
 						mOnSavePosListener.onSavePositionClick(position, updatedPos);
 					}
 
-					// 本地同步状态（避免刷新延迟，直接修改Activity传入的缓存数据）
+					// 本地同步状态（避免刷新延迟，直接修改位置缓存）
 					posModel.setMemo(newMemo);
 					posModel.setIsEnableRealPositionDistance(isDistanceEnable);
 					posModel.setIsSimpleView(true);
 					notifyItemChanged(position); // 刷新当前项，显示更新后的状态
 					hideSoftKeyboard(v);
-					LogUtils.d(TAG, "触发位置保存：ID=" + posId + "，新备注=" + newMemo);
+					LogUtils.d(TAG, "触发保存：位置ID=" + posId + "，新备注=" + newMemo + "，距离启用=" + isDistanceEnable);
 				}
 			});
 
-        // 8. 绑定任务相关视图（显示任务数量+新增任务，基于Activity任务缓存）
+        // 8. 绑定任务视图（显示任务数量+新增任务，数据从MainService获取）
         bindTaskView(holder, posId);
     }
 
     /**
-     * 绑定任务视图（编辑模式专属：显示当前位置的任务数量+新增任务）
+     * 绑定任务视图（编辑模式专属：从MainService获取任务数据，新增任务调用服务接口）
      */
     private void bindTaskView(final EditViewHolder holder, final String posId) {
-        // 从本地映射获取当前位置的任务（基于Activity缓存数据构建，避免重复遍历）
-        ArrayList<PositionTaskModel> posTasks = mPosToTasksMap.get(posId);
-        if (posTasks == null) {
-            posTasks = new ArrayList<PositionTaskModel>();
+        // 1. 从MainService获取当前位置的任务数量（Java 7 迭代器遍历服务数据）
+        int taskCount = 0;
+        MainService mainService = mMainServiceRef.get();
+        if (mainService != null) {
+            ArrayList<PositionTaskModel> posTasks = mainService.getTasksByPositionId(posId);
+            taskCount = (posTasks != null) ? posTasks.size() : 0;
         }
+        // 显示任务数量（简化设计，实际可扩展为任务列表）
+        holder.tvTaskCount.setText("任务数量：" + taskCount);
 
-        // 显示当前位置的任务数量（简化设计，实际项目可替换为任务列表RecyclerView）
-        holder.tvTaskCount.setText("任务数量：" + posTasks.size());
-
-        // 新增任务→回调Activity处理（Adapter不直接操作任务数据，由Activity同步）
+        // 2. 新增任务：调用MainService接口（不操作本地缓存，数据直接写入服务）
         holder.btnAddTask.setOnClickListener(new View.OnClickListener() {
 				@Override
 				public void onClick(View v) {
-					// 创建默认任务模型（生成唯一ID，关联当前位置）
+					MainService mainService = mMainServiceRef.get();
+					if (mainService == null) {
+						LogUtils.e(TAG, "新增任务失败：MainService已回收（弱引用失效）");
+						return;
+					}
+
+					// 构建默认任务模型（Java 7 显式初始化）
 					PositionTaskModel newTask = new PositionTaskModel();
-					newTask.setTaskId(PositionTaskModel.genTaskId()); // 需在PositionTaskModel实现静态生成ID方法
-					newTask.setPositionId(posId);                     // 关联当前位置ID（确保任务归属正确）
+					newTask.setTaskId(PositionTaskModel.genTaskId()); // 生成唯一任务ID（需在PositionTaskModel实现静态方法）
+					newTask.setPositionId(posId);                     // 绑定当前位置ID
 					newTask.setTaskDescription(DEFAULT_TASK_DESC);    // 默认任务描述
 					newTask.setIsEnable(true);                        // 默认启用任务
 					newTask.setDiscussDistance(DEFAULT_TASK_DISTANCE);// 默认任务距离（50米）
 
-					// 回调Activity保存任务（由Activity添加到缓存+同步服务，Adapter仅通知）
-					if (mOnSaveTaskListener != null) {
-						mOnSaveTaskListener.onSavePositionTaskClick(newTask);
-					}
-
-					// 本地同步任务数量（避免刷新延迟，更新本地映射+UI）
-					ArrayList<PositionTaskModel> updatedTasks = mPosToTasksMap.get(posId);
-					if (updatedTasks == null) {
-						updatedTasks = new ArrayList<PositionTaskModel>();
-					}
-					updatedTasks.add(newTask);
-					mPosToTasksMap.put(posId, updatedTasks);
-					holder.tvTaskCount.setText("任务数量：" + updatedTasks.size()); // 实时更新显示
-					LogUtils.d(TAG, "触发任务新增：位置ID=" + posId + "，任务ID=" + newTask.getTaskId());
+					// 调用MainService接口新增任务（数据写入服务，由服务处理持久化+通知刷新）
+					mainService.addPositionTask(newTask);
+					hideSoftKeyboard(v);
+					LogUtils.d(TAG, "触发新增任务：调用MainService接口，位置ID=" + posId + "，任务ID=" + newTask.getTaskId());
 				}
 			});
     }
 
     // =========================================================================
-    // 核心工具方法（无接口依赖，基于缓存数据实现，确保功能完整）
+    // 工具方法（Java 7 风格：无Lambda，纯匿名内部类+迭代器）
     // =========================================================================
     /**
-     * 更新距离显示（根据位置模型状态，显示不同文本和颜色，无外部依赖）
+     * 更新距离显示（根据位置模型状态，显示不同文本+颜色）
      */
     private void updateDistanceDisplay(TextView distanceView, PositionModel posModel) {
-        if (distanceView == null || posModel == null) return;
+        if (distanceView == null || posModel == null) {
+            LogUtils.w(TAG, "updateDistanceDisplay：参数为空（控件/位置模型）");
+            return;
+        }
 
-        // 场景1：距离计算未启用（从缓存数据状态判断）
+        // 场景1：距离未启用
         if (!posModel.isEnableRealPositionDistance()) {
             distanceView.setText(DISTANCE_DISABLED);
             distanceView.setTextColor(mContext.getResources().getColor(R.color.gray));
             return;
         }
 
-        // 场景2：距离计算失败（用-1标记失败，从缓存数据取distance字段）
+        // 场景2：距离计算失败（用-1标记失败状态）
         double distance = posModel.getRealPositionDistance();
         if (distance < 0) {
             distanceView.setText(DISTANCE_ERROR);
@@ -350,147 +342,131 @@ public class PositionAdapter extends RecyclerView.Adapter<RecyclerView.ViewHolde
 
         // 场景3：正常显示距离（按距离范围设置颜色，提升视觉区分度）
         distanceView.setText(String.format(DISTANCE_FORMAT, distance));
-		if (distance <= 100) { // 近距离（≤100米）：绿色
-			distanceView.setTextColor(mContext.getResources().getColor(R.color.green));
-		} else if (distance <= 500) { // 中距离（≤500米）：黄色
-			distanceView.setTextColor(mContext.getResources().getColor(R.color.yellow));
-		} else { // 远距离（>500米）：红色
-			distanceView.setTextColor(mContext.getResources().getColor(R.color.red));
+        if (distance <= 100) {
+            distanceView.setTextColor(mContext.getResources().getColor(R.color.green)); // 近距离（≤100米）
+        } else if (distance <= 500) {
+            distanceView.setTextColor(mContext.getResources().getColor(R.color.yellow));// 中距离（≤500米）
+        } else {
+            distanceView.setTextColor(mContext.getResources().getColor(R.color.red));   // 远距离（>500米）
         }
     }
 
     /**
-
-	 - 根据索引获取位置模型（从Activity缓存数据直接读取，无中间层，避免数据不一致）
+     * 根据索引获取位置模型（从位置缓存取数，容错处理）
      */
     private PositionModel getPositionByIndex(int index) {
         if (mCachedPositionList == null || index < 0 || index >= mCachedPositionList.size()) {
-			LogUtils.w(TAG, "获取位置失败：索引无效（" + index + "）或缓存数据为空");
+            LogUtils.w(TAG, "getPositionByIndex：无效索引（" + index + "）或位置缓存为空");
             return null;
         }
         return mCachedPositionList.get(index);
     }
 
     /**
-
-	 - 根据位置ID获取列表索引（从Activity缓存数据遍历，用于视图切换后精准刷新）
+     * 根据位置ID获取列表索引（用于精准刷新视图）
      */
     private int getPositionIndexById(String positionId) {
-		if (mCachedPositionList == null || positionId == null || positionId.isEmpty()) {
-			LogUtils.w(TAG, "获取位置索引失败：缓存数据为空或位置ID无效");
+        if (TextUtils.isEmpty(positionId) || mCachedPositionList == null || mCachedPositionList.isEmpty()) {
+            LogUtils.w(TAG, "getPositionIndexById：参数无效（位置ID/缓存为空）");
             return -1;
         }
+
+        // Java 7 增强for循环遍历（替代Lambda，适配Java 7语法）
         for (int i = 0; i < mCachedPositionList.size(); i++) {
             PositionModel pos = mCachedPositionList.get(i);
             if (positionId.equals(pos.getPositionId())) {
-				return i; // 找到匹配ID，返回对应索引
+                return i; // 找到匹配ID，返回索引
             }
         }
-		LogUtils.w(TAG, "未找到位置ID：" + positionId + "，返回无效索引-1");
+        LogUtils.w(TAG, "getPositionIndexById：未找到位置ID=" + positionId);
         return -1;
     }
 
     /**
-
-	 - 刷新“位置→任务”映射（基于Activity最新任务缓存重建，确保本地映射与Activity数据一致）
-	 - （Activity任务数据更新后调用，避免本地映射滞后）
-	 */
-	public void refreshPositionTaskMap() {
-		if (mCachedTaskList == null) {
-			mPosToTasksMap.clear(); // 任务缓存为空时，清空本地映射
-			LogUtils.d(TAG, "刷新任务映射：Activity任务缓存为空，已清空本地映射");
-			return;
-		}try {
-			mPosToTasksMap.clear(); // 先清空旧映射，避免数据残留
-			Iterator taskIter = mCachedTaskList.iterator();
-			while (taskIter.hasNext()) {
-				PositionTaskModel task = (PositionTaskModel)taskIter.next();
-				String posId = task.getPositionId();
-// 按位置ID分组：同一位置的任务放入同一个列表
-				if (!mPosToTasksMap.containsKey(posId)) {
-					mPosToTasksMap.put(posId, new ArrayList());
-				}
-				mPosToTasksMap.get(posId).add(task);
-			}
-			LogUtils.d(TAG, "刷新任务映射完成：已分组" + mPosToTasksMap.size() + "个位置的任务");
-		} catch (ConcurrentModificationException e) {
-			LogUtils.d(TAG, "刷新任务映射失败：并发修改Activity任务缓存。" + e);
-		}
-	}
-
-	/**
-
-	 - 全量更新数据（接收Activity最新缓存数据，同步本地数据源+辅助缓存，刷新UI）
-	 - （Activity新增/删除位置/任务后调用，确保Adapter与Activity数据100%一致）
-	 */
-	public void updateAllData(ArrayList newPosList, ArrayList newTaskList) {
-// 同步Activity最新缓存数据（容错处理：避免接收null导致空指针）
-		this.mCachedPositionList = (newPosList != null) ? newPosList : new ArrayList();
-		this.mCachedTaskList = (newTaskList != null) ? newTaskList : new ArrayList();// 刷新本地辅助缓存（确保映射与最新数据同步）
-		refreshPositionTaskMap();
-		mPosDistanceViewMap.clear(); // 清空旧距离控件缓存，避免引用失效控件// 通知RecyclerView全量刷新（数据已同步，更新UI显示）
-		notifyDataSetChanged();
-		LogUtils.d(TAG, "全量更新数据完成：当前位置数=" + mCachedPositionList.size() + "，任务数=" + mCachedTaskList.size());
-	}
-
-	/**
-
-	 - 局部更新距离UI（仅更新指定位置的距离显示，避免全量刷新卡顿）
-	 - （Activity同步服务计算的最新距离后调用，精准更新受影响的位置）
+     * 局部更新距离UI（仅更新指定位置的距离，避免全量刷新卡顿）
      */
     public void updateSinglePositionDistance(String positionId) {
-// 校验参数：位置ID无效或控件未缓存时，直接返回
-		if (positionId == null || positionId.isEmpty() || !mPosDistanceViewMap.containsKey(positionId)) {
-			LogUtils.w(TAG, "局部更新距离失败：位置ID无效或距离控件未缓存（ID=" + positionId + "）");
+        // 校验参数：位置ID无效或控件未缓存，直接返回
+        if (TextUtils.isEmpty(positionId) || !mPosDistanceViewMap.containsKey(positionId)) {
+            LogUtils.w(TAG, "updateSinglePositionDistance：位置ID无效或控件未缓存（ID=" + positionId + "）");
             return;
-		}// 从Activity缓存数据中获取最新位置模型（确保距离值是最新的）
+        }
+
+        // 从MainService获取最新位置模型（确保距离值是服务端最新）
         PositionModel latestPos = null;
-		for (PositionModel pos : mCachedPositionList) {
+        MainService mainService = mMainServiceRef.get();
+        if (mainService != null) {
+            ArrayList<PositionModel> servicePosList = mainService.getPositionList();
+            if (servicePosList != null && !servicePosList.isEmpty()) {
+                // Java 7 迭代器遍历服务端位置列表，找到目标位置
+                Iterator<PositionModel> posIter = servicePosList.iterator();
+                while (posIter.hasNext()) {
+                    PositionModel pos = posIter.next();
                     if (positionId.equals(pos.getPositionId())) {
                         latestPos = pos;
                         break;
                     }
-		}// 用最新距离值更新UI（直接操作缓存的距离控件，无需刷新整个项）
+                }
+            }
+        }
+
+        // 用服务端最新距离更新UI（直接操作缓存的距离控件，无需刷新整个项）
         if (latestPos != null) {
-			updateDistanceDisplay(mPosDistanceViewMap.get(positionId), latestPos);
+            TextView distanceView = mPosDistanceViewMap.get(positionId);
+            updateDistanceDisplay(distanceView, latestPos);
             LogUtils.d(TAG, "局部更新距离完成：位置ID=" + positionId + "，最新距离=" + latestPos.getRealPositionDistance() + "米");
         } else {
-			LogUtils.w(TAG, "局部更新距离失败：未在Activity缓存中找到位置ID=" + positionId);
+            LogUtils.w(TAG, "局部更新距离失败：未在MainService找到位置ID=" + positionId);
         }
     }
 
     /**
+     * 全量更新位置数据（从MainService同步最新位置列表，刷新UI）
+     */
+    public void updateAllPositionData(ArrayList<PositionModel> newPosList) {
+        if (newPosList == null) {
+            LogUtils.w(TAG, "updateAllPositionData：新位置列表为空，跳过更新");
+            return;
+        }
 
-	 - 隐藏软键盘（编辑完成后调用，提升用户体验，避免键盘遮挡）
+        // 同步服务端最新位置数据到本地缓存
+        this.mCachedPositionList.clear();
+        this.mCachedPositionList.addAll(newPosList);
+        // 清空旧距离控件缓存（避免引用失效控件）
+        mPosDistanceViewMap.clear();
+        // 通知RecyclerView全量刷新UI
+        notifyDataSetChanged();
+        LogUtils.d(TAG, "全量更新位置数据完成：当前位置数量=" + mCachedPositionList.size() + "（数据来源：MainService）");
+    }
+
+    /**
+     * 隐藏软键盘（编辑完成后调用，提升用户体验）
      */
     private void hideSoftKeyboard(View view) {
-		if (mContext == null || view == null) return;
+        if (mContext == null || view == null) {
+            LogUtils.w(TAG, "hideSoftKeyboard：参数为空（上下文/视图），无法隐藏键盘");
+            return;
+        }
+
+        // Java 7 显式获取输入法服务，避免Lambda
         InputMethodManager imm = (InputMethodManager) mContext.getSystemService(Context.INPUT_METHOD_SERVICE);
         if (imm != null) {
             imm.hideSoftInputFromWindow(view.getWindowToken(), 0); // 强制隐藏软键盘
         }
     }
 
-	/**
-
-	 - 释放资源（Activity销毁时调用，彻底避免内存泄漏）
-	 */
-	public void release() {
-// 清空本地辅助缓存（解除控件、数据映射引用）
-		mPosToTasksMap.clear();
-		mPosDistanceViewMap.clear();
-// 置空回调实例（避免持有Activity引用导致内存泄漏）
-		mOnDeleteListener = null;
-		mOnSavePosListener = null;
-		mOnSaveTaskListener = null;
-// 置空数据源引用（帮助GC回收，避免残留数据占用内存）
-		mCachedPositionList = null;
-		mCachedTaskList = null;
-		LogUtils.d(TAG, "Adapter资源已完全释放");
+    // =========================================================================
+    // 实现 MainService.TaskUpdateListener 接口（服务任务变化时回调）
+    // =========================================================================
+    @Override
+    public void onTaskUpdated() {
+        LogUtils.d(TAG, "收到MainService任务更新通知（任务新增/删除/状态变化），刷新UI");
+        // 任务数据变化时，全量刷新Adapter（确保任务数量等显示同步）
+        notifyDataSetChanged();
     }
 
     // =========================================================================
-// 回调设置方法（LocationActivity调用，绑定交互逻辑，无冗余参数）
+    // 回调设置方法（供LocationActivity调用，绑定交互逻辑）
     // =========================================================================
     public void setOnDeleteClickListener(OnDeleteClickListener listener) {
         this.mOnDeleteListener = listener;
@@ -500,22 +476,42 @@ public class PositionAdapter extends RecyclerView.Adapter<RecyclerView.ViewHolde
         this.mOnSavePosListener = listener;
     }
 
-	public void setOnSavePositionTaskClickListener(OnSavePositionTaskClickListener listener) {
-		this.mOnSaveTaskListener = listener;
+    // =========================================================================
+    // 资源释放（Activity销毁时调用，避免内存泄漏）
+    // =========================================================================
+    public void release() {
+        // 1. 反注册MainService任务监听（解除与服务的绑定，避免内存泄漏）
+        MainService mainService = mMainServiceRef.get();
+        if (mainService != null) {
+            mainService.unregisterTaskUpdateListener(this);
+            LogUtils.d(TAG, "已反注册MainService任务监听，避免内存泄漏");
+        }
+
+        // 2. 清空本地缓存（解除控件/数据引用，帮助GC回收）
+        mPosDistanceViewMap.clear();
+        if (mCachedPositionList != null) {
+            mCachedPositionList.clear();
+        }
+
+        // 3. 置空回调实例（避免持有Activity引用导致内存泄漏）
+        mOnDeleteListener = null;
+        mOnSavePosListener = null;
+
+        LogUtils.d(TAG, "Adapter资源已完全释放（缓存清空+监听反注册）");
     }
 
     // =========================================================================
-// 视图Holder类（静态内部类，不持有外部引用，彻底避免内存泄漏）
+    // 静态内部类：视图Holder（Java 7 静态内部类，不持有外部引用，避免内存泄漏）
     // =========================================================================
     /**
-
-	 - 简单视图Holder（仅显示数据，对应布局：item_position_simple.xml）
+     * 简单视图Holder（仅显示数据，对应布局：item_position_simple.xml）
      */
     public static class SimpleViewHolder extends RecyclerView.ViewHolder {
         TextView tvSimpleLon;     // 经度显示控件
         TextView tvSimpleLat;     // 纬度显示控件
         TextView tvSimpleMemo;    // 备注显示控件
         TextView tvSimpleDistance;// 实时距离显示控件
+
         public SimpleViewHolder(View itemView) {
             super(itemView);
             // 绑定布局控件（与XML中ID严格对应，避免运行时空指针）
@@ -527,8 +523,7 @@ public class PositionAdapter extends RecyclerView.Adapter<RecyclerView.ViewHolde
     }
 
     /**
-
-	 - 编辑视图Holder（含编辑控件+功能按钮，对应布局：item_position_edit.xml）
+     * 编辑视图Holder（含编辑控件+功能按钮，对应布局：item_position_edit.xml）
      */
     public static class EditViewHolder extends RecyclerView.ViewHolder {
         TextView tvEditLon;       // 经度显示控件（不可编辑）
@@ -540,7 +535,8 @@ public class PositionAdapter extends RecyclerView.Adapter<RecyclerView.ViewHolde
         Button btnDelete;         // 删除位置按钮
         Button btnSave;           // 保存位置按钮
         Button btnAddTask;        // 新增任务按钮
-		TextView tvTaskCount;     // 任务数量显示控件（简化设计）
+        TextView tvTaskCount;     // 任务数量显示控件
+
         public EditViewHolder(View itemView) {
             super(itemView);
             // 绑定布局控件（与XML中ID严格对应，避免运行时空指针）
@@ -557,3 +553,4 @@ public class PositionAdapter extends RecyclerView.Adapter<RecyclerView.ViewHolde
         }
     }
 }
+

positions/src/main/res/layout/activity_location.xml

@@ -1,10 +1,10 @@
 <?xml version="1.0" encoding="utf-8"?>
-<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
+<RelativeLayout
+	xmlns:android="http://schemas.android.com/apk/res/android"
 	android:layout_width="match_parent"
 	android:layout_height="match_parent"
 	android:padding="20dp">
 
-    <!-- 1. 经纬度显示区域（保持居中，上方） -->
 	<LinearLayout
 		android:id="@+id/layout_location_info"
 		android:layout_width="wrap_content"
@@ -14,7 +14,6 @@
 		android:orientation="vertical"
 		android:gravity="center_horizontal">
 
-        <!-- 标题 -->
 		<TextView
 			android:layout_width="wrap_content"
 			android:layout_height="wrap_content"
@@ -22,7 +21,6 @@
 			android:textSize="22sp"
 			android:textStyle="bold"/>
 
-        <!-- 经度显示 -->
 		<TextView
 			android:id="@+id/tv_longitude"
 			android:layout_width="wrap_content"
@@ -31,7 +29,6 @@
 			android:textSize="18sp"
 			android:layout_marginTop="15dp"/>
 
-        <!-- 纬度显示 -->
 		<TextView
 			android:id="@+id/tv_latitude"
 			android:layout_width="wrap_content"
@@ -42,7 +39,6 @@
 
 	</LinearLayout>
 
-    <!-- 2. 新增：位置列表（RecyclerView）- 位于经纬度下方，悬浮按钮上方 -->
 	<androidx.recyclerview.widget.RecyclerView
 		android:id="@+id/rv_position_list"
 		android:layout_width="match_parent"
@@ -52,7 +48,6 @@
 		android:layout_marginTop="20dp"
 		android:paddingBottom="10dp"/>
 
-    <!-- 3. 右下角圆形悬浮按钮（不变） -->
 	<Button
 		android:id="@+id/fab_p_button"
 		android:layout_width="60dp"
@@ -65,7 +60,8 @@
 		android:textColor="@android:color/white"
 		android:textSize="24sp"
 		android:elevation="6dp"
-        android:padding="0dp"/>
+		android:padding="0dp"
+		android:onClick="addNewPosition"/>
 
 </RelativeLayout>
 

positions/src/main/res/layout/activity_main.xml

@@ -16,7 +16,7 @@
 	<Switch
 		android:id="@+id/switch_service_control"
 		android:layout_margin="16dp"
-		android:text="主要服务开关"
+		android:text="GPS服务开关"
 		android:layout_width="match_parent"
 		android:layout_height="wrap_content"/>
 
@@ -25,7 +25,7 @@
 		android:layout_height="wrap_content"
 		android:layout_margin="16dp"
 		android:onClick="onPositions"
-		android:text="进入位置管理"
+		android:text="位置与任务管理"
 		android:id="@+id/btn_manage_positions"/>
 
 	<Button
@@ -33,7 +33,7 @@
 		android:layout_height="wrap_content"
 		android:layout_margin="16dp"
 		android:onClick="onLog"
-		android:text="查看操作日志"/>
+		android:text="查看应用日志"/>
 
 </LinearLayout>