From 1fd9836881f9db67b2e3d3433e15038a145a9e83 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=AD=99=E5=B0=8F=E4=BA=91?= <sunpengchina85@gmail.com>
Date: Thu, 4 Dec 2025 14:24:49 +0800
Subject: [PATCH] Initial commit: main project structure

---
 .gitignore                                    |  24 ++
 pom.xml                                       |  14 +
 reademe/submodule/reademe.md                  | 358 ++++++++++++++++++
 .../在主仓库中更新子模块引用.md   |  48 +++
 .../子模块修改后的冲突处理.md      |  71 ++++
 5 files changed, 515 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 pom.xml
 create mode 100644 reademe/submodule/reademe.md
 create mode 100644 reademe/submodule/在主仓库中更新子模块引用.md
 create mode 100644 reademe/submodule/子模块修改后的冲突处理.md

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..468658a
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,24 @@
+# IntelliJ IDEA (root project only)
+.idea/
+*.iml
+*.iws
+*.ipr
+
+# macOS
+.DS_Store
+.AppleDouble
+.LSOverride
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# Linux
+*~
+
+# Temporary files
+*.tmp
+*.bak
+*.swp
+*~.nib
diff --git a/pom.xml b/pom.xml
new file mode 100644
index 0000000..25e0268
--- /dev/null
+++ b/pom.xml
@@ -0,0 +1,14 @@
+<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+  <modelVersion>4.0.0</modelVersion>
+  <groupId>com.tuoheng</groupId>
+  <artifactId>hyf</artifactId>
+  <version>1.0-SNAPSHOT</version>
+  <packaging>pom</packaging>
+  <name>Archetype - hyf</name>
+  <url>http://maven.apache.org</url>
+  <modules>
+    <module>thingsboard-client-demo</module>
+    <module>thingsboard-gateway-ws-demo</module>
+  </modules>
+</project>
diff --git a/reademe/submodule/reademe.md b/reademe/submodule/reademe.md
new file mode 100644
index 0000000..9f62ef7
--- /dev/null
+++ b/reademe/submodule/reademe.md
@@ -0,0 +1,358 @@
+# HYF 项目
+
+这是一个使用 Git Submodules 管理的 Maven 多模块项目。
+
+## 项目结构
+
+```
+hyf/
+├── pom.xml                           # 父项目 POM
+├── thingsboard-client-demo/          # 子模块1（Git Submodule）
+└── thingsboard-gateway-ws-demo/      # 子模块2（Git Submodule）
+```
+
+---
+
+## 一、如何添加一个新的 Module
+
+### 1.1 创建并初始化新模块的 Git 仓库
+
+```bash
+# 在本地创建新模块目录和代码
+cd /Users/sunpeng/workspace/hyf
+mkdir new-module
+cd new-module
+
+# 初始化 Git 仓库
+git init
+git add .
+git commit -m "Initial commit: new module"
+
+# 关联远程仓库并推送
+git remote add origin <新模块的远程仓库URL>
+git branch -M main
+git push -u origin main
+```
+
+### 1.2 将新模块添加为 Submodule
+
+```bash
+# 回到根目录
+cd /Users/sunpeng/workspace/hyf
+
+# 删除本地的新模块目录
+rm -rf new-module
+
+# 添加为 Git Submodule
+git submodule add <新模块的远程仓库URL> new-module
+
+# 提交 submodule 配置
+git add .
+git commit -m "Add new-module as submodule"
+git push
+```
+
+### 1.3 更新父项目 pom.xml
+
+编辑根目录的 `pom.xml`，在 `<modules>` 标签中添加新模块：
+
+```xml
+<modules>
+  <module>thingsboard-client-demo</module>
+  <module>thingsboard-gateway-ws-demo</module>
+  <module>new-module</module>
+</modules>
+```
+
+提交修改：
+
+```bash
+git add pom.xml
+git commit -m "Add new-module to parent pom"
+git push
+```
+
+---
+
+## 二、如何更新 Module（子模块）
+
+### 2.1 修改子模块代码
+
+```bash
+# 进入子模块目录
+cd thingsboard-client-demo
+
+# 修改代码后提交
+git add .
+git commit -m "描述你的修改内容"
+git push
+```
+
+### 2.2 在主仓库中更新子模块引用
+
+**重要**：修改子模块后，主仓库需要更新对子模块 commit 的引用。
+
+```bash
+# 回到根目录
+cd /Users/sunpeng/workspace/hyf
+
+# 查看子模块状态（会显示子模块有新的 commit）
+git status
+
+# 提交子模块引用的更新
+git add thingsboard-client-demo
+git commit -m "Update thingsboard-client-demo submodule"
+git push
+```
+
+### 2.3 同时修改多个子模块
+
+```bash
+# 1. 提交第一个子模块
+cd thingsboard-client-demo
+git add .
+git commit -m "修改客户端代码"
+git push
+
+# 2. 提交第二个子模块
+cd ../thingsboard-gateway-ws-demo
+git add .
+git commit -m "修改网关代码"
+git push
+
+# 3. 回到根目录，更新所有子模块引用
+cd ..
+git add .
+git commit -m "Update submodules"
+git push
+```
+
+---
+
+## 三、如何拉代码并更新各个子模块
+
+### 3.1 首次克隆项目（推荐方式）
+
+```bash
+# 一次性克隆主仓库和所有子模块
+git clone --recursive <主仓库URL>
+```
+
+### 3.2 首次克隆项目（分步方式）
+
+```bash
+# 先克隆主仓库
+git clone <主仓库URL>
+cd hyf
+
+# 初始化并拉取所有子模块
+git submodule init
+git submodule update
+```
+
+### 3.3 已有项目，拉取最新代码
+
+```bash
+cd /Users/sunpeng/workspace/hyf
+
+# 拉取主仓库最新代码
+git pull
+
+# 更新所有子模块到主仓库记录的版本
+git submodule update
+
+# 或者：更新所有子模块到各自远程仓库的最新版本
+git submodule update --remote
+```
+
+### 3.4 拉取特定子模块的最新代码
+
+```bash
+# 进入子模块目录
+cd thingsboard-client-demo
+
+# 拉取该子模块的最新代码
+git pull origin main
+
+# 回到根目录，提交子模块引用的更新
+cd ..
+git add thingsboard-client-demo
+git commit -m "Update thingsboard-client-demo to latest"
+git push
+```
+
+---
+
+## 四、如何更新主模块和子模块
+
+### 4.1 只修改了主模块（根目录文件）
+
+```bash
+cd /Users/sunpeng/workspace/hyf
+
+# 修改了 pom.xml、.gitignore 等根目录文件
+git add .
+git commit -m "描述主模块的修改内容"
+git push
+```
+
+### 4.2 同时修改了主模块和子模块
+
+```bash
+# 1. 先提交所有子模块的修改
+cd thingsboard-client-demo
+git add .
+git commit -m "修改客户端代码"
+git push
+
+cd ../thingsboard-gateway-ws-demo
+git add .
+git commit -m "修改网关代码"
+git push
+
+# 2. 回到根目录，提交主模块和子模块引用的更新
+cd ..
+git add .
+git commit -m "Update main module and submodules"
+git push
+```
+
+### 4.3 团队协作：同步他人的修改
+
+当其他人修改了主模块或子模块后，你需要同步：
+
+```bash
+cd /Users/sunpeng/workspace/hyf
+
+# 拉取主仓库最新代码
+git pull
+
+# 更新所有子模块到主仓库记录的版本
+git submodule update --init --recursive
+```
+
+**注意**：`--init` 参数会自动初始化新添加的子模块。
+
+---
+
+## 常用命令速查
+
+### 查看状态
+
+```bash
+# 查看主仓库状态
+git status
+
+# 查看所有子模块状态
+git submodule foreach git status
+
+# 查看子模块的详细信息
+git submodule status
+```
+
+### 批量操作子模块
+
+```bash
+# 在所有子模块中执行命令
+git submodule foreach <command>
+
+# 例如：在所有子模块中拉取最新代码
+git submodule foreach git pull origin main
+
+# 例如：在所有子模块中查看当前分支
+git submodule foreach git branch
+```
+
+### 子模块更新
+
+```bash
+# 更新子模块到主仓库记录的版本
+git submodule update
+
+# 更新子模块到远程最新版本
+git submodule update --remote
+
+# 初始化并更新所有子模块（包括新添加的）
+git submodule update --init --recursive
+```
+
+---
+
+## Maven 构建
+
+```bash
+# 在根目录构建所有模块
+mvn clean install
+
+# 只构建特定模块
+mvn clean install -pl thingsboard-client-demo
+
+# 构建特定模块及其依赖
+mvn clean install -pl thingsboard-client-demo -am
+```
+
+---
+
+## 重要注意事项
+
+1. **子模块修改流程**：先在子模块目录提交并推送，再回到主仓库更新子模块引用
+2. **主仓库记录的是子模块的特定 commit**，不是分支名
+3. **克隆项目时务必使用 `--recursive`**，或手动执行 `git submodule update --init`
+4. **拉取代码后记得执行 `git submodule update`**，确保子模块版本正确
+5. **团队协作时**，确保所有成员理解 submodule 的工作方式，避免子模块版本混乱
+
+---
+
+## 工作流程示例
+
+### 日常开发流程
+
+```bash
+# 1. 早上开始工作，拉取最新代码
+cd /Users/sunpeng/workspace/hyf
+git pull
+git submodule update --init --recursive
+
+# 2. 修改子模块代码
+cd thingsboard-client-demo
+# ... 编写代码 ...
+git add .
+git commit -m "实现新功能"
+git push
+
+# 3. 更新主仓库的子模块引用
+cd ..
+git add thingsboard-client-demo
+git commit -m "Update thingsboard-client-demo"
+git push
+
+# 4. 如果修改了主模块配置
+git add pom.xml
+git commit -m "更新依赖版本"
+git push
+```
+
+### 添加新功能模块流程
+
+```bash
+# 1. 创建新模块仓库并推送
+mkdir new-feature
+cd new-feature
+git init
+# ... 创建代码 ...
+git add .
+git commit -m "Initial commit"
+git remote add origin <新模块URL>
+git push -u origin main
+
+# 2. 添加为 submodule
+cd /Users/sunpeng/workspace/hyf
+rm -rf new-feature
+git submodule add <新模块URL> new-feature
+
+# 3. 更新 pom.xml
+# 编辑 pom.xml，添加 <module>new-feature</module>
+git add .
+git commit -m "Add new-feature module"
+git push
+```
diff --git a/reademe/submodule/在主仓库中更新子模块引用.md b/reademe/submodule/在主仓库中更新子模块引用.md
new file mode 100644
index 0000000..14d8cc9
--- /dev/null
+++ b/reademe/submodule/在主仓库中更新子模块引用.md
@@ -0,0 +1,48 @@
+主仓库和子仓库确实是独立的 Git 仓库，各自有自己的提交历史。但关键在于： 主仓库需要记录"使用子模块的哪个版本"
+
+工作原理
+当你在主仓库中添加 submodule 时，主仓库实际上存储的是：
+子模块的远程仓库 URL（存在 .gitmodules 文件中）
+子模块的特定 commit SHA（这是关键！）
+你可以理解为主仓库中有一个"指针"，指向子模块的某个具体 commit。
+为什么需要更新引用？
+看这个场景：
+# 子模块当前在 commit abc123
+# 主仓库记录：thingsboard-client-demo -> abc123
+
+# 你修改了子模块代码
+cd thingsboard-client-demo
+git commit -m "新功能"  # 产生新 commit def456
+git push
+
+# 此时：
+# - 子模块远程仓库：最新是 def456
+# - 主仓库记录：仍然是 abc123 ❌
+如果不更新主仓库的引用，会发生什么？
+其他团队成员克隆主仓库后，执行 git submodule update
+他们会得到 abc123 版本的子模块
+他们看不到你的新功能（def456）！
+更新引用的作用
+cd /Users/sunpeng/workspace/hyf
+git add thingsboard-client-demo  # 更新指针：abc123 -> def456
+git commit -m "Update submodule"
+git push
+这一步是在告诉主仓库："现在请使用子模块的 def456 版本"。
+类比理解
+可以把它想象成：
+子仓库 = 一个独立的软件包（比如 npm 包）
+主仓库 = package.json 文件
+当你更新了软件包的代码并发布新版本后，你还需要在 package.json 中更新版本号，告诉项目"请使用新版本"。
+// 类似于
+{
+  "dependencies": {
+    "thingsboard-client-demo": "1.0.0"  // 旧版本
+    "thingsboard-client-demo": "1.1.0"  // 需要手动更新到新版本
+  }
+}
+总结
+主仓库和子仓库是独立的，但主仓库需要明确记录使用子仓库的哪个版本。这样可以：
+保证团队成员获得一致的代码版本
+支持版本回退（可以回到使用旧版本子模块的状态）
+避免子模块"自动更新"导致的不可预期问题
+这就是为什么修改子模块后，需要在主仓库中更新引用的原因。
\ No newline at end of file
diff --git a/reademe/submodule/子模块修改后的冲突处理.md b/reademe/submodule/子模块修改后的冲突处理.md
new file mode 100644
index 0000000..3106da4
--- /dev/null
+++ b/reademe/submodule/子模块修改后的冲突处理.md
@@ -0,0 +1,71 @@
+实际行为
+当你在子模块有未提交的修改时执行 git submodule update：
+cd thingsboard-client-demo
+# 修改了一些文件，但没有 commit
+
+cd ..
+git submodule update
+Git 会：
+检测到子模块有未提交的修改
+拒绝更新，并给出类似这样的错误：
+error: Your local changes to the following files would be overwritten by checkout:
+    src/main/java/SomeFile.java
+Please commit your changes or stash them before you switch branches.
+Unable to checkout 'abc123' in submodule path 'thingsboard-client-demo'
+为什么会这样？
+git submodule update 本质上是在子模块中执行 git checkout <commit>。Git 的保护机制会阻止 checkout 覆盖未提交的修改。
+不同场景
+场景 1：未暂存的修改（modified）
+cd thingsboard-client-demo
+echo "test" >> file.txt  # 修改文件，未 git add
+
+cd ..
+git submodule update
+# ❌ 会报错，拒绝更新
+场景 2：已暂存但未提交（staged）
+cd thingsboard-client-demo
+echo "test" >> file.txt
+git add file.txt  # 已暂存，但未 commit
+
+cd ..
+git submodule update
+# ❌ 仍然会报错，拒绝更新
+场景 3：新增的未跟踪文件（untracked）
+cd thingsboard-client-demo
+echo "test" > new-file.txt  # 新文件，未 git add
+
+cd ..
+git submodule update
+# ✅ 可以更新！因为新文件不会被覆盖
+如何处理未提交的修改？
+如果你确实需要更新子模块，有几个选择：
+选项 1：提交修改
+cd thingsboard-client-demo
+git add .
+git commit -m "临时修改"
+git push  # 如果需要保存到远程
+
+cd ..
+git submodule update
+选项 2：暂存修改（stash）
+cd thingsboard-client-demo
+git stash  # 暂存修改
+
+cd ..
+git submodule update
+
+cd thingsboard-client-demo
+git stash pop  # 恢复修改
+选项 3：放弃修改
+cd thingsboard-client-demo
+git checkout .  # 放弃所有修改
+git clean -fd   # 删除未跟踪的文件
+
+cd ..
+git submodule update
+总结
+你的修改是安全的，Git 会保护你的工作：
+有未提交修改时，git submodule update 会拒绝执行
+你的修改不会丢失
+你需要先处理这些修改（提交、暂存或放弃）才能更新子模块
+这是 Git 的安全机制，防止意外覆盖你的工作成果。
\ No newline at end of file