# AGENTS.md — SmsMessage (notiMessage)

Android 应用，监听通知栏消息并通过 **双通道**（通知监听 + Xposed Hook）抓取内容，支持 PC 本地调试台转发。

> **Hook 架构与扩展指南**：详见 [docs/Hook指南.md](docs/Hook指南.md)（含 **Xposed / LSPosed**、Telegram、接入新 App）  
> **手机部署与银行 bypass 操作**：详见 [docs/手机操作手册.md](docs/手机操作手册.md)  
> **MariBank 风控与 register 载荷**：[docs/MariBank风控与载荷说明.md](docs/MariBank风控与载荷说明.md)

## 项目结构

```
notiMessage/
├── app/                    # 主应用模块 (com.miraclegarden.smsmessage)
│   ├── src/main/java/.../
│   │   ├── Activity/       # Activity 类 (MainActivity, NotificationActivity, SettingActivity, AppListActivity)
│   │   ├── service/        # Service 类 (NotificationService — 通知监听核心)
│   │   ├── network/        # ApiService, DebugForwarder, TokenManager
│   │   ├── comm/           # 通用组件 (CommonAdapter, ViewHolder)
│   │   ├── App.java        # Application 类，管理通知列表持久化
│   │   ├── AppConfig.java  # 调试转发 / 正式上传开关
│   │   ├── MessageLogStore.java  # 监听日志持久化
│   │   ├── MessageInfo.java, AppInfo.java  # 数据模型
│   │   └── GsonUtils.java  # JSON 工具类
│   └── src/main/res/       # 资源文件
├── xposed-module/          # Xposed Hook 模块 (com.miraclegarden.smsmessage.xposed)
│   └── src/main/java/.../hook/
│       ├── TelegramMessageHook.java   # Telegram 专用
│       ├── WeChatMessageHook.java     # 微信专用
│       └── SqliteMessageHook.java     # 通用 SQLite 兜底
├── debug-server/           # PC 本地调试台 (server.py, 端口 8765)
├── scripts/                # build-debug.ps1, install-full.ps1, start-debug-server.ps1
├── library/                # 基础库模块 (com.miraclegarden.library)
│   └── MiracleGardenActivity<T> # ViewBinding 基类
├── docs/Hook指南.md           # Hook 架构、Xposed/LSPosed、扩展
├── docs/手机操作手册.md       # Root 机部署与日常操作
├── docs/MariBank风控与载荷说明.md  # register 字段与风控说明
├── build.gradle            # 根构建文件
├── settings.gradle         # 模块: app, library, xposed-module
└── gradle.properties       # Gradle 配置
```

## 构建命令

```bash
# 构建（主 App + Xposed 双 APK）
./gradlew :app:assembleDebug :xposed-module:assembleDebug

# Windows 一键完整安装（推荐）
powershell -ExecutionPolicy Bypass -File scripts/install-full.ps1

# PC 调试台
powershell -ExecutionPolicy Bypass -File scripts/start-debug-server.ps1

# 构建 release（仅主 App）
./gradlew assembleRelease
./gradlew build                      # 完整构建（编译 + lint + 测试）

# Lint
./gradlew lint                       # 运行所有模块 lint
./gradlew :app:lint                  # 仅 app 模块 lint
./gradlew :library:lint              # 仅 library 模块 lint

# 单元测试
./gradlew test                       # 运行所有模块单元测试
./gradlew :app:testDebugUnitTest     # 仅 app 模块 debug 单元测试
./gradlew :app:testDebugUnitTest --tests "com.miraclegarden.smsmessage.ExampleUnitTest"  # 运行单个测试类
./gradlew :app:testDebugUnitTest --tests "*.ExampleUnitTest.addition_isCorrect"          # 运行单个测试方法

# Android 测试（需要设备/模拟器）
./gradlew connectedAndroidTest       # 运行所有模块 instrumented 测试
./gradlew :app:connectedDebugAndroidTest  # 仅 app 模块

# 清理
./gradlew clean
```

## SDK 与依赖版本

| 配置项 | app 模块 | library 模块 | xposed-module |
|--------|---------|-------------|---------------|
| compileSdk | 34 | 32 | 34 |
| minSdk | 24 | 21 | 24 |
| targetSdk | 34 | 32 | 34 |
| Java | 17 | 17 | 17 |

**关键依赖**: OkHttp 5.0.0-alpha.10 (网络), Gson 2.9.0 (JSON), ViewBinding (UI绑定), Material 1.6.1
**测试框架**: JUnit 4.13.2, Espresso 3.4.0, AndroidX Test JUnit 1.1.3
**Gradle**: 7.5.1, AGP 7.3.0

## 语言与代码规范

### 语言

纯 Java 项目，无 Kotlin。所有源文件均为 `.java`。

### 导入顺序

遵循 Android 标准导入顺序：
1. `android.*` — Android 框架
2. `androidx.*` — AndroidX 兼容库
3. 项目内部包 (`com.miraclegarden.*`)
4. 第三方库 (`org.json.*`, `okhttp3.*`, `com.google.gson.*`)
5. `java.*` — Java 标准库

导入之间按组用空行分隔。不使用通配符导入（`*`）。

### 命名规范

| 类型 | 规范 | 示例 |
|------|------|------|
| 类名 | PascalCase | `NotificationService`, `MessageInfo`, `CommonAdapter` |
| 方法名 | camelCase | `initData()`, `initView()`, `getSbnByNotificatinList()` |
| 变量 | camelCase | `messageInfo`, `sharedPreferences`, `appName` |
| 常量 | UPPER_SNAKE_CASE | `private static final String TAG = "..."` |
| 成员变量前缀 | 通用组件用 `m` 前缀 | `mContext`, `mDatas`, `mLayoutId` |
| 布局文件 | activity_xxx / item_xxx | `activity_main.xml`, `activity_notification.xml` |
| Activity 包名 | 大写开头子包 | `com.miraclegarden.smsmessage.Activity` |

### 类结构模式

Activity 类遵循统一初始化模式：
```java
public class XxxActivity extends MiracleGardenActivity<ActivityXxxBinding> {
    private static final String TAG = "XxxActivity";

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        initData();
        initView();
    }

    private void initData() { /* 数据初始化 */ }
    private void initView() { /* UI 绑定与事件监听 */ }
}
```

### ViewBinding

- 所有 Activity 继承 `MiracleGardenActivity<T extends ViewBinding>`
- 通过泛型参数自动反射创建 binding 实例
- 直接使用 `binding.xxx` 访问视图，**不使用** `findViewById`

### 数据模型

- POJO 风格：private 字段 + getter/setter
- 提供无参和全参构造函数
- 静态工厂方法用于类型转换（如 `MessageInfo.AppInfoToMessageInfo()`）
- 行内注释说明字段用途（`// 应用名`, `// 包名`）

### 网络请求

- 使用 OkHttp，异步调用 (`enqueue`)
- JSON 请求体使用 `org.json.JSONObject` 手动构建
- MediaType 常量: `public static final MediaType JSON = MediaType.parse("application/json; charset=utf-8")`
- 回调中通过 `NotificationActivity.sendMessage()` 反馈 UI

### 错误处理

- try/catch 包裹关键操作，catch 中使用 `e.printStackTrace()` 或 `Log.e(TAG, msg, e)`
- 部分场景直接抛出 `RuntimeException`（如 JSONException）
- null 检查使用 `TextUtils.isEmpty()` 或直接 `== null` 判断
- lint 配置: `abortOnError false`（lint 错误不阻塞构建）

### 注解使用

| 注解 | 用途 |
|------|------|
| `@Override` | 方法重写（必须标注） |
| `@Nullable` / `@NonNull` | 参数和返回值空安全 |
| `@SuppressLint` | 抑制特定 lint 警告（如 `"StaticFieldLeak"`, `"SimpleDateFormat"`） |
| `@RequiresApi` | API 版本要求标注 |

### 注释风格

- 类级别使用 Javadoc `/** */` 风格，含 `@Author`、创建时间、用途
- 方法级别使用 `/** */` 或单行 `//` 注释
- 行内注释使用中文（项目主要面向中文开发者）
- 代码注释中保留被注释掉的调试代码（`//LogUtils.i(...)`, `//notifyItemRangeChanged`）

### 数据持久化

- 使用 `SharedPreferences`，统一名称为 `"server"`
- 通过 `App` 类的静态方法管理通知列表（`saveNotiList`, `getNotiList`, `saveNotiBean`, `deleteNotiBean`）
- 列表数据序列化为 JSON 字符串存储

## 注意事项

- **无 CI/CD 配置** — 无自动化构建流程
- **无代码格式化工具** — 无 .editorconfig、checkstyle、spotless 等配置
- **测试覆盖极低** — 仅有默认生成的示例测试，无业务逻辑测试
- **签名信息硬编码** — keystore 密码直接写在 build.gradle 中
- **ProGuard 未启用** — release 构建 `minifyEnabled false`
- **仓库包含阿里云/华为镜像** — 构建时需要网络访问这些 Maven 仓库
- 修改代码时保持现有风格一致，即使风格不够规范
- 中文注释和 UI 字符串是项目惯例，新增代码保持一致
