工程结构与文档布局

Flutter-JL_Home（杰理之家 Demo）是珠海市杰理科技股份有限公司基于 RCSP 协议（远程控制系统协议） 打造的蓝牙控制开发平台。本文档讲解该仓库的顶层目录组织、code/ 参考工程、doc/ 文档中心与 libs/ 核心接口的布局方式，以及 README 文档体系的导航约定。

Purpose and Scope

本页面向首次接触该仓库的开发者，回答三个问题：

1. 仓库里有什么 —— 根目录、code/、doc/、libs/ 各目录的职责边界；
2. 工程内部如何组织 —— JieLi_Home_Demo Flutter 工程与 Android 原生层、AAR 依赖库的摆放方式；
3. 文档如何布局 —— README 九个章节的导航结构、中英文文档对应关系、文档中心的定位。

以下内容不属于本页范围，由其他目录页或官方文档中心覆盖：

• RCSP 发送/接收接口的协议细节 —— 见 doc/ 目录中的《Jieli Home Demo (Flutter) - Send/Receive Interface Introduction》及 libs/ 目录；
• 具体功能（音乐控制、EQ、ANC、OTA 等）的实现 —— 见功能模块对应页面；
• 环境搭建与调试操作 —— 见「快速开始」与「调试技巧」相关页面。

Overview

仓库定位

Flutter-JL_Home 是一个 Flutter 应用示例 + SDK 集成参考 混合形态的仓库，而不是一个纯库工程。它面向三类场景：

来源：README.md

Demo 覆盖的功能接口包括音乐控制、设备设置、文件浏览、闹钟管理、FM 控制、灯光控制、音效调节、按键设置、查找设备、ANC 设置、彩屏仓控制、AI 翻译与自定义命令（详见 README.md 功能表）。

仓库形态的关键设计意图

• 示例与参考分离：code/ 是可直接导入 Android Studio 的完整 Flutter 工程；libs/ 与 doc/ 是配套的接口说明与收发接口描述，避免把协议文档塞进代码工程，降低示例工程的耦合度。
• 中英双语文档并行：根目录同时维护 README.md（中文）与 README_EN.md（英文），doc/ 内同样有中英文双份接口文档，保证国内外开发者看到的信息一致。
• 原生依赖收敛：Android 端以预编译 .aar 形式集中存放在 code/JieLi_Home_Demo/android/libs/，通过 Gradle 直接引用，开发者无需自行编译 SDK。

Architecture

下图展示仓库顶层目录的角色划分与依赖关系（基于 README.md 工程结构章节 与仓库实际文件列表）：

flowchart TD
    subgraph sg_Root["仓库根目录 Flutter-JL_Home"]
        README["README.md<br/>中文总览与导航"]
        README_EN["README_EN.md<br/>英文总览与导航"]
        LICENSE["LICENSE<br/>Apache 2.0"]
    end

    subgraph sg_Code["code/ 参考源码工程"]
        DEMO["JieLi_Home_Demo<br/>杰理之家 Demo (Flutter)"]
        subgraph sg_Demo["Flutter 工程内部"]
            PUBSPEC["pubspec.yaml / pubspec.lock<br/>Flutter 依赖清单"]
            ANALYSIS["analysis_options.yaml<br/>Lint 规则"]
            ANDROID["android/<br/>原生层 + AAR 依赖"]
            DOCR["README.md<br/>工程级说明"]
        end
    end

    subgraph sg_Doc["doc/ 文档中心"]
        DOC_ZH["接口说明（中文）"]
        DOC_EN["接口说明（英文）"]
        DOC_TXT["ReadMe.txt 说明"]
    end

    subgraph sg_Libs["libs/ 核心收发接口"]
        RX["Receive Interface"]
        TX["Send Interface"]
    end

    README -->|"入口导航"| README_EN
    README -->|"指向"| DEMO
    README -->|"指向"| DOC_ZH
    README -->|"指向"| RX
    README -->|"指向"| TX
    DEMO --> PUBSPEC
    DEMO --> ANALYSIS
    DEMO --> ANDROID
    DEMO --> DOCR
    DOC_ZH <-->|"中英对照"| DOC_EN

各目录职责

说明：doc/ 与 libs/ 目录的内容以 README 工程结构章节描述为准；当前仓库快照中可直接确认的文件实体集中在 code/ 下。若在 Git 客户端中未见 doc/、libs/ 实体，请以 README.md 的目录树为准并结合 Tag 版本核对。

主内容：code/JieLi_Home_Demo 工程内部布局

code/ 目录下只有一个工程 JieLi_Home_Demo，它是仓库的核心可运行示例。从仓库文件列表可以确认其顶层组件：

Flutter 工程元文件

Android 原生层

android/ 子目录承载原生构建配置与资源：

• build.gradle / settings.gradle：Gradle 构建脚本；
• proguard-rules.pro：混淆规则；
• src/main/AndroidManifest.xml：Android 清单文件；
• src/main/assets/charging_case/...：彩屏仓相关资源（如 320x172/boot/ANI1.gif、screen/anim/lock/ANI2.gif），用于充电仓屏幕保护与开机动画；
• schemas/com.jieli.bt.sdk.tool.room.AppDatabase/5.json：Room 数据库 Schema，版本 5，说明 SDK 内部使用 Room 持久化数据；
• libs/：预编译 SDK 依赖（AAR）。

AAR 依赖库清单

android/libs/ 集中存放杰理各功能模块的预编译库，是理解 Demo 能力边界的重要依据：

依据：仓库 code/JieLi_Home_Demo/android/libs/ 文件列表。版本号随 SDK 迭代更新，集成时以本仓库 Tag 为准。

这种「核心协议 AAR + 能力模块 AAR + 组件 AAR」的分层方式，使 Demo 可以按需裁剪：只需要基础控制的客户可以只引入 jl_bluetooth_rcsp，需要音效的再叠加 jl_eq。

主内容：doc/ 与 libs/ 布局

doc/ —— 文档中心

按 README 描述，doc/ 包含：

• 《Jieli Home Demo (Flutter) - Send/Receive Interface Introduction.md》（中文）：发送/接收接口介绍；
• 《Jieli Home Demo (Flutter) - Send/Receive Interface Introduction_en.md》（英文）：同上内容的英文版；
• ReadMe.txt：说明文件。

设计意图：发送/接收接口是 RCSP 协议面向业务的关键抽象，单独成文便于在 Demo 代码之外维护协议级说明，也便于与 libs/ 目录的接口源码对照阅读。

libs/ —— 核心收发接口

• Receive Interface：杰理之家 Demo 的接收接口（设备 → App 方向）；
• Send Interface：杰理之家 Demo 的发送接口（App → 设备方向）。

收发分离的目录命名与协议文档一一对应，开发者按「发送什么指令 / 接收什么回调」两条路径检索代码，降低理解成本。

主内容：文档导航约定（README 九章结构）

根目录 README 是仓库的「地图」，其章节顺序即推荐的阅读路径：

来源：README.md 目录

中英文 README 章节完全对齐（英文版为 1. Overview 至 9. License），因此跨语言协作时可按章节号互指。

核心流程：从克隆到接入的导航路径

仓库的文档布局设计了一条明确的「上手流水线」。新开发者按以下顺序前进即可完成从了解仓库到跑通 Demo 的闭环：

sequenceDiagram
    participant Dev as 开发者
    participant Repo as 仓库根目录
    participant Doc as doc/ 文档中心
    participant Demo as code/JieLi_Home_Demo
    participant Libs as libs/ 接口目录

    Dev->>Repo: 阅读 README.md（一、概述）
    Repo-->>Dev: 确认产品/功能适用性
    Dev->>Repo: 二、运行环境 + 三、快速开始
    Repo-->>Dev: 环境要求与克隆/导入步骤
    Dev->>Demo: 导入 code/JieLi_Home_Demo
    Demo-->>Dev: 运行示例 App
    Dev->>Doc: 查阅收发接口文档（doc/）
    Doc-->>Dev: 协议级接口说明
    Dev->>Libs: 对照 libs/ 收发接口源码
    Libs-->>Dev: 具体调用示例
    Dev->>Repo: 六、调试技巧（日志排查）
    Repo-->>Dev: Logcat / Xcode Console

各步骤要点：

1. 读概述：通过功能表判断 Demo 是否覆盖目标产品（音箱/耳机/音频设备）；
2. 查环境：确认 Android 6.0+ / iOS 13.0+，硬件需支持 RCSP 的 SDK（AC701N、AC707N、AC697N、AC696N、AC695N 等，见 README.md 运行环境）；
3. 导入工程：Android Studio 打开 code/JieLi_Home_Demo；
4. 看文档：协议层疑问进入 doc/ 的中英文接口文档；
5. 对源码：收发细节对照 libs/ 目录；
6. 查日志：Android 用 Logcat、iOS 用 Xcode Console（README.md 调试技巧）。

使用示例

以下示例均从仓库实际文件中提取。

示例 1：克隆仓库与目录定位

git clone https://github.com/Jieli-Tech/Flutter-JL_Home.git
cd Flutter-JL_Home

Source: README.md

克隆后按 README「四、工程结构」的目录树定位三类内容：

Flutter-JL_Home/
├── code/                                    # 参考源码工程文件夹
│   └── JieLi_Home_Demo                      # 杰理之家Demo(Flutter)项目源码
├── doc/                                     # 文档文件夹
│   ├── Jieli Home Demo (Flutter) - Send/Receive Interface Introduction_en.md   # 英文文档
│   ├── Jieli Home Demo (Flutter) - Send/Receive Interface Introduction.md      # 中文文档
│   └── ReadMe.txt                           # 说明文件
└── libs/                                    # 核心收发接口文件夹
    ├── Receive Interface                    # 杰理之家Demo(Flutter)的接收接口
    └── Send Interface                       # 杰理之家Demo(Flutter)的发送接口

Source: README.md

示例 2：插件引用（接入方集成方式）

接入方工程通过以下 pubspec.yaml 片段声明杰理蓝牙插件：

  plugin:
    platforms:
      android:
        package: com.jieli.bt.sdk
        pluginClass: JlHomePlugin
      ios:
        pluginClass: JlHomePlugin

Source: README.md

该片段揭示了两条工程组织信息：Android 端插件包名为 com.jieli.bt.sdk（与 Room 数据库 Schema 路径 com.jieli.bt.sdk.tool.room.AppDatabase 一致），插件类为 JlHomePlugin，iOS 端使用同一插件类名，即 Flutter 层 API 跨平台统一。

示例 3：版本与许可证信息定位

| 版本 | 日期 | 修改记录 |
|------|------|----------|
| 1.0.0 | 2026/07/02 | 初始版本|

Source: README.md

版本历史位于 README 第八章，许可证（Apache License 2.0）位于第九章并附完整协议文本（README.md L197-L215）。

配置要点（仓库与工程层面）

仓库本身不提供运行时配置，但文档布局中明确定义了环境与工程级配置项，汇总如下（依据 README.md）：

边界情况与注意事项

以下事项基于仓库实际文件状态与 README 描述整理：

1. 目录实体与文档描述的差异：根目录可直接确认的文件实体为 README.md、README_EN.md、LICENSE 与 code/ 下的工程文件；doc/、libs/ 的目录树以 README「四、工程结构」为准。若在某一提交/Tag 中未见这些目录，请核对当前 Tag 版本，避免误判仓库缺失内容。
2. 版本号依赖：android/libs/ 中各 AAR 版本号（如 jl_bluetooth_rcsp_V4.2.0、jl_bt_ota_V1.10.0）与 SDK 发版节奏绑定，集成方应跟随仓库 Tag 升级，勿混用不同版本的 AAR。
3. 中英文文档一致性：README.md 与 README_EN.md、doc/ 中中英文接口文档按章节一一对应，但翻译内容可能存在滞后；以中文版为准时请留意英文版更新时间。
4. 资源体积：code/JieLi_Home_Demo/android/src/main/assets/charging_case/ 内含 GIF 动画资源（如 ANI1.gif、ANI2.gif），会增大 APK 体积；仅做基础音箱控制的客户可按需裁剪彩屏仓相关资源。

扩展点

仓库的工程结构为二次开发预留了清晰的位置：

• 新增业务功能：在 code/JieLi_Home_Demo 的 Flutter 层新增页面/逻辑，通过 JlHomePlugin 调用原生能力；
• 接入新硬件能力：以 android/libs/ 的 AAR 分层为参照，新增对应能力模块（如新的编解码、传输协议库）；
• 自定义命令：README 概述中明确支持「自定义命令」客户拓展功能，相关收发接口在 libs/ 的 Send/Receive Interface 中扩展；
• 文档贡献：新增协议说明时遵循 doc/ 的中英文双文档约定，并在根目录 README 目录树中同步登记。

Related Links

• README.md（中文总览）
• README_EN.md（英文总览）
• LICENSE（Apache 2.0）
• JieLi_Home_Demo 工程 README
• JieLi_Home_Demo pubspec.yaml
• 相关目录页：快速开始 / 配置说明 / 调试技巧 / 收发接口说明（Send/Receive Interface）