create-dwy 0.12.1 → 0.13.0

package/templates/claude-global/rules/Android/dwy-android-core.md

@@ -1,44 +1,104 @@
 ---
-description: Android (Java + Kotlin + XML) 代码注释与基础风格规范
+description: Android (Java + Kotlin + XML + Gradle) 代码注释与基础风格规范
 paths:
   - "**/*.java"
   - "**/*.kt"
   - "**/*.kts"
+  - "**/*.gradle"
   - "**/AndroidManifest.xml"
   - "**/res/**/*.xml"
 ---
 
 # Android 代码注释与基础风格规范
 
-适用于 **Android 原生项目**(Java + Kotlin 混编,XML 布局)。本规范**重点是代码注释**,兼带最小必要的命名 / 简约 / 反模式约束。
+适用于 **Android 原生项目**(Java + Kotlin 混编,XML 布局,Gradle 构建脚本)。本规范**重点是代码注释**,兼带最小必要的命名 / 简约 / 反模式约束。
 
 不限制构建工具、UI 框架、架构模式、SDK 版本、依赖库选型 —— 与老项目兼容。
 
 ## 一、命名规范
 
-| 类型 | 风格 | 示例 |
-|---|---|---|
-| 包 | `lowercase` | `com.example.user` |
-| 类 / 接口 / 枚举 | `PascalCase` | `LoginActivity`、`UserAdapter` |
-| 方法 / 函数 | `camelCase` | `loadUserById()` |
-| 变量 / 参数 | `camelCase` | `userCount` |
-| 常量 (`static final` / `const val`) | `UPPER_SNAKE_CASE` | `MAX_RETRY_COUNT` |
-| Activity | `XxxActivity` | `LoginActivity` |
-| Fragment | `XxxFragment` | `HomeFragment` |
-| Adapter / ViewHolder | `XxxAdapter` / `XxxViewHolder` | `OrderAdapter` |
-| Dialog | `XxxDialog` | `ConfirmDialog` |
-| 布尔变量 / 方法 | `is*` / `has*` / `can*` / `should*` | `isLoading`、`hasNext` |
+
+| 类型                                | 风格                                  | 示例                            |
+| --------------------------------- | ----------------------------------- | ----------------------------- |
+| 包                                 | `lowercase`                         | `com.example.user`            |
+| 类 / 接口 / 枚举                       | `PascalCase`                        | `LoginActivity`、`UserAdapter` |
+| 方法 / 函数                           | `camelCase`                         | `loadUserById()`              |
+| 变量 / 参数                           | `camelCase`                         | `userCount`                   |
+| 常量 (`static final` / `const val`) | `UPPER_SNAKE_CASE`                  | `MAX_RETRY_COUNT`             |
+| Activity                          | `XxxActivity`                       | `LoginActivity`               |
+| Fragment                          | `XxxFragment`                       | `HomeFragment`                |
+| Adapter / ViewHolder              | `XxxAdapter` / `XxxViewHolder`      | `OrderAdapter`                |
+| Dialog                            | `XxxDialog`                         | `ConfirmDialog`               |
+| 布尔变量 / 方法                         | `is`* / `has*` / `can*` / `should*` | `isLoading`、`hasNext`         |
+
 
 ### 资源命名
 
-| 资源类型 | 规则 | 示例 |
-|---|---|---|
-| 布局文件 | `<类型>_<功能>.xml` 全小写下划线 | `activity_login.xml`、`fragment_home.xml`、`item_order.xml`、`dialog_confirm.xml` |
-| View id | `<控件类型>_<功能>` | `tv_username`、`et_password`、`btn_submit`、`rv_orders`、`iv_avatar` |
-| drawable | `<用途>_<状态>` | `bg_button_primary`、`ic_arrow_right`、`shape_card_corner` |
-| color | `<语义>` | `color_primary`、`color_text_secondary` |
-| string | `<场景>_<语义>` | `login_button_submit`、`home_title` |
-| dimen | `<语义>` | `padding_normal`、`text_size_title` |
+
+| 资源类型            | 规则                       | 示例                                                                             |
+| --------------- | ------------------------ | ------------------------------------------------------------------------------ |
+| 布局文件            | `<类型>_<功能>.xml` 全小写下划线   | `activity_login.xml`、`fragment_home.xml`、`item_order.xml`、`dialog_confirm.xml` |
+| View id         | `<控件类型>_<功能>`            | `tv_username`、`et_password`、`btn_submit`、`rv_orders`、`iv_avatar`               |
+| drawable        | `<用途>_<状态>`              | `bg_button_primary`、`ic_arrow_right`、`shape_card_corner`                       |
+| color           | `<语义>`                   | `color_primary`、`color_text_secondary`                                         |
+| string          | `<场景>_<语义>`              | `login_button_submit`、`home_title`                                             |
+| dimen           | `<语义>`                   | `padding_normal`、`text_size_title`                                             |
+| anim / animator | `<逻辑名>_<方向|序号>` 或通用动画名   | `fade_in.xml`、`push_bottom_in.xml`、`loading_001.xml`                           |
+| menu            | `menu_<场景>.xml`          | `menu_order_detail.xml`                                                        |
+| style / theme   | `PascalCase`,点号继承,从通用到特殊 | `Widget.App.Button`、`Theme.App.Dark`                                           |
+| mipmap          | 仅放启动图标 `ic_launcher*`    | `ic_launcher.webp`                                                             |
+| raw / xml       | `<语义>` 全小写下划线            | `network_security_config.xml`、`bgm_login.mp3`                                  |
+
+
+资源全部**小写 + 下划线**分词,**禁止**驼峰、大写、中划线(style / theme 除外,用 `PascalCase` + 点号继承)。
+
+#### 控件 id 缩写对照表
+
+View id 规则:`<控件缩写>_<逻辑名>`,如 `tv_username`、`btn_submit`。常用控件缩写:
+
+
+| 类别      | 控件 = 缩写                                                                                                    |
+| ------- | ---------------------------------------------------------------------------------------------------------- |
+| 布局      | LinearLayout=`ll`、RelativeLayout=`rl`、ConstraintLayout=`cl`、FrameLayout=`fl`、TableLayout=`tl`              |
+| 滚动 / 列表 | ScrollView=`sv`、NestedScrollView=`nsv`、ListView=`lv`、GridView=`gv`、RecyclerView=`rv`、ViewPager(2)=`vp`     |
+| 文本 / 输入 | TextView=`tv`、EditText=`et`、Button=`btn`、ImageButton=`ib`                                                  |
+| 展示      | ImageView=`iv`、WebView=`wv`、CardView=`cv`                                                                  |
+| 选择 / 开关 | CheckBox=`cb`、RadioButton=`rbtn`、RadioGroup=`rg`、ToggleButton=`tb`、Switch=`sw`、Spinner=`spn`               |
+| 进度      | ProgressBar=`pb`、SeekBar=`sb`、RatingBar=`rb`                                                               |
+| 容器 / 导航 | Toolbar=`toolbar`、TabLayout=`tab`、FloatingActionButton=`fab`、BottomNavigationView=`bnv`、AppBarLayout=`abl` |
+
+
+> 缩写冲突时取更长缩写消歧:`rbtn`(RadioButton) 区别于 `rb`(RatingBar)。表中无对应的控件,按"首字母 / 业务语义就近"自拟,组内保持一致。
+
+#### drawable / selector 状态后缀
+
+drawable 完整规则:`<模块_>业务功能_控件描述_状态`,如 `login_btn_pressed`、`tabs_icon_home_normal`。selector 多状态切换图统一用状态词后缀:
+
+
+| 状态后缀         | 含义      |
+| ------------ | ------- |
+| `_normal`    | 默认 / 常态 |
+| `_pressed`   | 按下      |
+| `_focused`   | 聚焦      |
+| `_selected`  | 选中      |
+| `_checked`   | 勾选      |
+| `_disabled`  | 禁用      |
+| `_activated` | 激活      |
+
+
+```text
+res/drawable/
+  selector_btn_login.xml       <!-- 状态选择器 -->
+  bg_btn_login_normal.xml      <!-- 常态背景 -->
+  bg_btn_login_pressed.xml     <!-- 按下背景 -->
+  bg_btn_login_disabled.xml    <!-- 禁用背景 -->
+```
+
+#### mipmap / 9-patch / 模块前缀
+
+- **mipmap 只放启动图标**(`ic_launcher` 系列),其余图片一律放 `drawable` —— mipmap 会跨密度保留资源,普通图放 mipmap 白白增大包体
+- **9-patch 图保留 `.9` 后缀**:`bg_chat_bubble.9.png`
+- **模块前缀(可选)**:多模块 / 大型项目推荐资源加业务模块前缀,便于检索、避免跨模块重名 —— `user_activity_login.xml`、id `user_tv_name`;单模块 / 老项目可省略,保持本规范其余示例的无前缀写法
 
 ### 禁止的写法
 
@@ -64,7 +124,7 @@ val isActive = true
 ### 禁止魔法字符串与硬编码
 
 - 同一字面量在文件内出现 **2 次及以上**必须提取为常量
-- **用户可见文案必须走 `strings.xml`**,便于国际化与统一审校
+- **所有用户可见文案必须走 `strings.xml`**,便于国际化与统一审校
 - 颜色走 `colors.xml`,尺寸走 `dimens.xml`
 
 ```kotlin
@@ -91,17 +151,19 @@ class UserActivity : AppCompatActivity() {
 <TextView android:text="@string/login_button_submit" android:textSize="@dimen/text_size_normal" />
 ```
 
-## 二、代码注释(本文件重点)
+## 二、代码注释
 
 ### 总则
+
 - 注释解释 **为什么(why)**,不复述 **做了什么(what)**
 - 全部使用**中文**,**禁止**中英混用
-- 公开 API 注释**必须**有,**禁止**简单的"获取 / 设置 / 处理"敷衍式注释
+- 类与方法注释**必须**有(不分可见性,一目了然的简单成员可省,见 §2.5 / §2.8),**禁止**简单的"获取 / 设置 / 处理"敷衍式注释
 - 代码改动后**必须**同步更新注释,留下过时注释 = 违规
 
 ### 2.1 文件 / 类级注释(强制)
 
-每个公开类必须有类级 Javadoc / KDoc,放在类声明上方,说明:
+每个类(**不分可见性**,含 `private` / `internal` / 嵌套类 / 内部类)都必须有类级 Javadoc / KDoc,放在类声明上方,说明:
+
 - 该类的**职责**
 - 与谁配合工作(被谁调用、依赖谁)
 - 关键的使用约束 / 生命周期 / 线程要求(如果有)
@@ -142,15 +204,18 @@ public final class AvatarLoader {
 }
 ```
 
-### 2.2 公开方法 / 函数注释(强制)
+### 2.2 方法 / 函数注释(强制)
+
+所有方法 / 函数(**不分可见性**,含 `private` / `internal` / 顶层函数)必须有 Javadoc / KDoc,包含:
 
-所有 `public` / Kotlin 默认可见性的方法 / 函数(含顶层函数)必须有 Javadoc / KDoc,包含:
 - 一句话功能描述
 - `@param` 每个参数的语义、取值范围、可空性
 - `@return` 返回值语义,空集合 / null 含义
 - `@throws` 可能抛出的异常 + 触发条件
 - 涉及线程 / 主线程要求时**必须**注明
 
+例外:一目了然的简单 getter / setter、测试方法可省(详见 §2.5 / §2.8)。私有方法注释重点写**为什么这样实现**,不复述代码。
+
 ```kotlin
 /**
  * 根据 ID 查询用户。
@@ -325,17 +390,20 @@ public final class Constants {
 
 ### 2.8 注释规范汇总
 
-| 场景 | 风格 | 必填 |
-|---|---|---|
-| 单行可描述清楚 | 单行 KDoc/Javadoc:`/** xxx。 */` | ✓ |
-| 有参数 / 返回值 / 异常 | 多行,含 `@param` / `@return` / `@throws` | ✓ |
-| Activity / Fragment | 必须注明入口、参数 key、返回结果 | ✓ |
-| 回调接口 | 必须注明触发线程 + 每个参数语义 | ✓ |
-| `data class` 字段 | Kotlin `@property`,Java 字段上 `/** */` | ✓ |
-| 复杂业务规则 | 行内注释解释 why + 关联 PRD / 需求号 | ✓ |
-| 重写方法 | `@inheritDoc` 或重新写明覆写差异 | ✓ |
-| 简单 getter / setter / 一目了然 | 可省 | — |
-| 测试方法 | 测试名本身就是描述,可省 | — |
+
+| 场景                        | 风格                                                 | 必填  |
+| ------------------------- | -------------------------------------------------- | --- |
+| 单行可描述清楚                   | 单行 KDoc/Javadoc:`/** xxx。 */`                      | ✓   |
+| 有参数 / 返回值 / 异常            | 多行,含 `@param` / `@return` / `@throws`              | ✓   |
+| Activity / Fragment       | 必须注明入口、参数 key、返回结果                                 | ✓   |
+| 回调接口                      | 必须注明触发线程 + 每个参数语义                                  | ✓   |
+| `data class` 字段           | Kotlin `@property`,Java 字段上 `/** */`               | ✓   |
+| 复杂业务规则                    | 行内注释解释 why + 关联 PRD / 需求号                          | ✓   |
+| 重写方法                      | `@inheritDoc` 或重新写明覆写差异                            | ✓   |
+| Gradle 脚本(Groovy)         | 解释 why:锁版本/exclude 原因、变体用途、自定义 task/方法语义(详见 §2.10) | ✓   |
+| 简单 getter / setter / 一目了然 | 可省                                                 | —   |
+| 测试方法                      | 测试名本身就是描述,可省                                       | —   |
+
 
 ### 2.9 行内注释禁止事项
 
@@ -356,9 +424,65 @@ val data = newService.fetch()
 // TODO(zhang, 2026-05-30): 兼容企业微信扫码,关联 issue #1234
 ```
 
+### 2.10 Gradle 脚本注释(Groovy)
+
+老项目的 `build.gradle` / `settings.gradle` 多用 **Groovy** 编写(新项目 Kotlin DSL `*.gradle.kts` 同理)。构建脚本是声明式配置,注释**只解释"为什么这样配",不复述配置项字面**。
+
+注释语法:`//` 单行、`/* */` 多行、`/** */` Groovydoc(自定义方法用),全部**中文**。
+
+**必须注释的场景**:
+
+- 依赖锁死/降级版本、`exclude` / `force` / `resolutionStrategy` —— 写明原因(冲突、漏洞、兼容)
+- 非常规依赖(为绕过某 bug、临时分支版本)—— 写明来源与可移除条件
+- `buildTypes` / `productFlavors` / `signingConfigs` —— 每个变体的用途、签名/密钥来源
+- 自定义 `task`、`ext` 变量、`def` 方法 —— 用途、单位、输入输出
+- 关键魔法值(`minSdk` / `targetSdk` 选定依据、超时、内存参数)
+
+```groovy
+android {
+    defaultConfig {
+        // minSdk 23:线上 92% 设备覆盖,低于 23 的指纹 API 需大量兼容代码,收益不抵成本
+        minSdk 23
+        targetSdk 34
+    }
+
+    buildTypes {
+        release {
+            // 走 CI 注入的正式签名,密钥在 Jenkins 凭据(credentialsId: android-release-key),禁止入库
+            signingConfig signingConfigs.release
+            minifyEnabled true
+        }
+    }
+}
+
+dependencies {
+    // 锁 4.9.3:4.10+ 要求 minSdk 24,与本项目 minSdk 23 冲突,升级需先抬 minSdk
+    implementation 'com.squareup.okhttp3:okhttp:4.9.3'
+
+    // 排除传递依赖的旧 support 库,避免与 androidx 冲突(报 Duplicate class)
+    implementation('com.legacy:sdk:2.1.0') {
+        exclude group: 'com.android.support'
+    }
+}
+
+/**
+ * 读取 local.properties 中的密钥,缺失时回退空串(本地开发无需打正式包)。
+ *
+ * @param key 属性名
+ * @return 属性值;不存在时返回空字符串
+ */
+def localProp(String key) {
+    def f = rootProject.file('local.properties')
+    return f.exists() ? new Properties().with { load(f.newReader()); getProperty(key, '') } : ''
+}
+```
+
+**禁止**(同 §2.9):复述配置字面(`// 设置 minSdk`)、注释掉的依赖/配置块、不带责任人的 TODO。
+
 ## 三、可空性
 
 ### Kotlin
+
 - 默认所有类型不可空,可空显式 `?`
 - **禁止** `!!` 出现在生产代码,除非附注释说明为什么一定不为 null
 
@@ -371,6 +495,7 @@ val name = user?.profile?.nickname ?: getString(R.string.user_anonymous)
 ```
 
 ### Java
+
 - 公开 API 参数 / 字段 / 返回值用 `@Nullable` / `@NonNull`(`androidx.annotation.*`) 标注
 - 集合返回值优先返回空集合而非 `null`
 
@@ -394,9 +519,10 @@ public List<Order> findOrders(long userId) {
 - Kotlin **禁止**用 `Any` / `Any?`(JSON tree、反射桥接除外)
 - 必须使用时**附注释说明原因**
 
-## 四、函数与类设计
+## 四、函数 / 类设计与包组织
 
 ### 强制规则
+
 - 公开方法 / 函数参数 ≤ **3 个**,超过则封装为 DTO / `data class`
 - Kotlin 优先**命名参数 + 默认参数**代替方法重载
 - 函数体不超过 **50 行**,超过则拆分
@@ -442,6 +568,7 @@ fun process(user: User?) {
 `if` / `else` / `else if` / `for` / `while` / `do-while` **即使只有一条语句**,必须使用 `{}` 包裹。
 
 **理由**:
+
 - 后续添加第二行时不会因为漏 `{}` 静默脱出条件体(经典回归 bug)
 - IDE 自动 reformat 与跨工具 merge 不会错位
 - Java 与 Kotlin 视觉一致,混编项目无歧义
@@ -499,6 +626,48 @@ for (Order o : orders) {
 }
 ```
 
+### 包组织(按功能聚合)
+
+**按功能聚合(package-by-feature),不按技术分层(package-by-layer)。**
+
+同一个功能/页面相关的所有类 —— 页面(Activity / Fragment)、其数据实体、业务逻辑(ViewModel / Presenter / UseCase)、数据访问(Repository)、列表 Adapter、UI 状态等 —— 放在**同一个功能包**下聚合,而不是按类型横切成 `activities/`、`models/`、`adapters/`、`repositories/` 这种分层包。
+
+**理由**:改一个功能时,相关文件都在一个包内,无需在多个分层目录间跳转;包之间按业务边界解耦,删除/迁移一个功能只动一个包;高内聚低耦合,符合就近维护。
+
+```text
+// ✅ 按功能聚合
+com.example.app/
+  login/                      <!-- 登录功能,自包含 -->
+    LoginActivity.kt
+    LoginViewModel.kt
+    LoginRepository.kt
+    LoginUiState.kt
+    Credential.kt             <!-- 该功能私有实体 -->
+  order/                      <!-- 订单功能 -->
+    OrderListActivity.kt
+    OrderDetailActivity.kt
+    OrderViewModel.kt
+    OrderRepository.kt
+    OrderAdapter.kt
+    Order.kt
+  common/                     <!-- 跨功能共享:基类、工具、网络、通用实体 -->
+    base/  network/  util/  model/
+
+// ❌ 按技术分层横切 —— 改一个功能要在多个目录间反复跳
+com.example.app/
+  activities/   LoginActivity.kt  OrderListActivity.kt  OrderDetailActivity.kt
+  viewmodels/   LoginViewModel.kt  OrderViewModel.kt
+  repositories/ LoginRepository.kt  OrderRepository.kt
+  adapters/     OrderAdapter.kt
+  models/       Credential.kt  Order.kt
+```
+
+**约束**:
+
+- 功能包名用业务语义小写单词(`login` / `order` / `profile`),不用 `ui` / `data` 等分层词作为顶层
+- 仅某功能使用的实体/工具,放该功能包内,可设 `internal` 收敛可见性;**被 2 个及以上功能共享**才上提到 `common/`
+- 功能包内可再按需细分子包(如复杂功能 `order/detail/`、`order/list/`),但仍以功能而非类型划分
+
 ## 五、Context 与内存泄漏
 
 - **禁止**长生命周期对象(单例、静态字段、长任务)持有 Activity / Fragment / View 引用
@@ -524,6 +693,7 @@ object UserManager {
 ## 六、错误处理
 
 ### 强制规则
+
 - UI 层**必须** try/catch 捕获预期异常并展示用户友好提示;**禁止**让异常崩溃到 `Thread.UncaughtExceptionHandler`
 - **禁止** `catch (Exception e) {}` 空捕获
 - **禁止** `catch (Throwable t)`(会吞 OOM / StackOverflow)
@@ -563,48 +733,54 @@ val result = calculate(x)
 
 ## 八、常见反模式(禁止)
 
-| 反模式 | 正确做法 |
-|---|---|
-| Kotlin `!!` 非空断言 | `?:` / `requireNotNull(x) { "..." }` 并附错误信息 |
-| `catch (Exception e) {}` 空块 | 只捕获预期具体异常,或重新抛 |
-| `catch (Throwable t)` | 只捕预期类型,OOM / StackOverflow 不该兜 |
-| `e.printStackTrace()` | 项目自有日志工具 |
-| Java `==` 比较对象 | `Objects.equals(a, b)` / `a.equals(b)` |
-| Kotlin `===` 滥用 | 仅在确实需要引用相等时使用 |
-| 暴露内部可变集合 | 返回不可变副本 |
-| 静态可变状态 / 单例存 UI 数据 | 局部状态 / 持久化存储 |
-| Kotlin 顶层 `var` | `val`;需可变用类封装 + 同步原语 |
-| 内部类持有外部 Activity | `static` 内部类 + `WeakReference` |
-| 拼接 SQL 字符串 | 参数化查询 |
-| 硬编码 dp / sp 值 | `@dimen/` |
-| 硬编码颜色值 `#FF0000` | `@color/color_primary` |
-| 用户可见文案硬编码 | `@string/...` |
-| 单行 `if` / `for` / `while` / `do-while` 无 `{}`(Kotlin 表达式 `if` 除外) | 即使只一行也写 `{}`;详见 §四「控制流大括号」 |
+
+| 反模式                                                               | 正确做法                                        |
+| ----------------------------------------------------------------- | ------------------------------------------- |
+| Kotlin `!!` 非空断言                                                  | `?:` / `requireNotNull(x) { "..." }` 并附错误信息 |
+| `catch (Exception e) {}` 空块                                       | 只捕获预期具体异常,或重新抛                              |
+| `catch (Throwable t)`                                             | 只捕预期类型,OOM / StackOverflow 不该兜              |
+| `e.printStackTrace()`                                             | 项目自有日志工具                                    |
+| Java `==` 比较对象                                                    | `Objects.equals(a, b)` / `a.equals(b)`      |
+| Kotlin `===` 滥用                                                   | 仅在确实需要引用相等时使用                               |
+| 暴露内部可变集合                                                          | 返回不可变副本                                     |
+| 静态可变状态 / 单例存 UI 数据                                                | 局部状态 / 持久化存储                                |
+| Kotlin 顶层 `var`                                                   | `val`;需可变用类封装 + 同步原语                        |
+| 内部类持有外部 Activity                                                  | `static` 内部类 + `WeakReference`              |
+| 拼接 SQL 字符串                                                        | 参数化查询                                       |
+| 硬编码 dp / sp 值                                                     | `@dimen/`                                   |
+| 硬编码颜色值 `#FF0000`                                                  | `@color/color_primary`                      |
+| 用户可见文案硬编码                                                         | `@string/...`                               |
+| 单行 `if` / `for` / `while` / `do-while` 无 `{}`(Kotlin 表达式 `if` 除外) | 即使只一行也写 `{}`;详见 §四「控制流大括号」                  |
+
 
 ## 九、代码自检(写代码时强制执行)
 
 **每次生成或修改 Android 代码后,必须逐条验证。任一未通过 → STOP,立即修正。**
 
-| # | 检查项 | 违规即 STOP |
-|---|--------|------------|
-| 1 | 公开类有类级 Javadoc / KDoc(中文),说明职责与协作关系 | ✓ |
-| 2 | 公开方法 / 函数有 Javadoc / KDoc,含 `@param` / `@return` / `@throws` | ✓ |
-| 3 | Activity / Fragment 类注释包含入口、参数 key、返回结果 | ✓ |
-| 4 | 回调接口注明每个参数语义 + 触发线程 | ✓ |
-| 5 | `data class` / 公开字段 / 配置常量逐个 `@property` / 字段注释 | ✓ |
-| 6 | 复杂业务逻辑有"why"行内注释,关联 PRD / 需求号 | ✓ |
-| 7 | 注释全部中文,无中英混用,无敷衍式"获取 / 设置 / 处理" | ✓ |
-| 8 | 注释与代码同步更新,无过时注释 | ✓ |
-| 9 | 公开方法参数 + 返回值类型完整,无 `Object` / `Any` 懒标注 | ✓ |
-| 10 | Kotlin 无 `!!`(必须使用时附注释说明) | ✓ |
-| 11 | Java 公开 API 用 `@Nullable` / `@NonNull` 标注 | ✓ |
-| 12 | 单例 / 长生命周期对象用 `applicationContext`,不持有 Activity | ✓ |
-| 13 | 用户可见文案走 `strings.xml`,颜色走 `colors.xml`,尺寸走 `dimens.xml` | ✓ |
-| 14 | 同一文件内字符串字面量 ≥ 2 次必须提取为常量 | ✓ |
-| 15 | 无空 `catch` 块、无 `catch (Throwable)`、无 `e.printStackTrace()` | ✓ |
-| 16 | 嵌套不超过 3 层,函数体不超过 50 行,单文件不超过 500 行 | ✓ |
-| 17 | 资源命名遵守:`activity_*` / `fragment_*` / `item_*` / `tv_*` / `et_*` / `btn_*` 等约定 | ✓ |
-| 18 | 无注释掉的代码块(垃圾代码),TODO 必须带责任人 + 日期 + 上下文 | ✓ |
-| 19 | `if` / `else` / `else if` / `for` / `while` / `do-while` 语句即使单行也带 `{}`(Kotlin 表达式 `if` 除外) | ✓ |
-
-**不执行自检就提交代码 = 违规。**
+
+| #   | 检查项                                                                                                                                                                                                                       | 违规即 STOP |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
+| 1   | 每个类(含 `private` / `internal` / 嵌套类)有类级 Javadoc / KDoc(中文),说明职责与协作关系                                                                                                                                                       | ✓        |
+| 2   | 方法 / 函数(不分可见性)有 Javadoc / KDoc,含 `@param` / `@return` / `@throws`;一目了然的简单 getter / setter、测试方法可省                                                                                                                          | ✓        |
+| 3   | Activity / Fragment 类注释包含入口、参数 key、返回结果                                                                                                                                                                                   | ✓        |
+| 4   | 回调接口注明每个参数语义 + 触发线程                                                                                                                                                                                                       | ✓        |
+| 5   | `data class` / 公开字段 / 配置常量逐个 `@property` / 字段注释                                                                                                                                                                           | ✓        |
+| 6   | 复杂业务逻辑有"why"行内注释,关联 PRD / 需求号                                                                                                                                                                                             | ✓        |
+| 7   | 注释全部中文,无中英混用,无敷衍式"获取 / 设置 / 处理"                                                                                                                                                                                           | ✓        |
+| 8   | 注释与代码同步更新,无过时注释                                                                                                                                                                                                           | ✓        |
+| 9   | 公开方法参数 + 返回值类型完整,无 `Object` / `Any` 懒标注                                                                                                                                                                                   | ✓        |
+| 10  | Kotlin 无 `!!`(必须使用时附注释说明)                                                                                                                                                                                                 | ✓        |
+| 11  | Java 公开 API 用 `@Nullable` / `@NonNull` 标注                                                                                                                                                                                 | ✓        |
+| 12  | 单例 / 长生命周期对象用 `applicationContext`,不持有 Activity                                                                                                                                                                           | ✓        |
+| 13  | 用户可见文案走 `strings.xml`,颜色走 `colors.xml`,尺寸走 `dimens.xml`                                                                                                                                                                   | ✓        |
+| 14  | 同一文件内字符串字面量 ≥ 2 次必须提取为常量                                                                                                                                                                                                  | ✓        |
+| 15  | 无空 `catch` 块、无 `catch (Throwable)`、无 `e.printStackTrace()`                                                                                                                                                                | ✓        |
+| 16  | 嵌套不超过 3 层,函数体不超过 50 行,单文件不超过 500 行                                                                                                                                                                                        | ✓        |
+| 17  | 资源命名遵守:layout 前缀(`activity_`* / `fragment_*` / `item_*`)、id 控件缩写(`tv_*` / `et_*` / `btn_*` / `rv_*` …)、drawable / selector 状态后缀(`_normal` / `_pressed` / `_disabled` …)、anim / menu / style / mipmap 命名,9-patch 带 `.9` 后缀 | ✓        |
+| 18  | 无注释掉的代码块(垃圾代码),TODO 必须带责任人 + 日期 + 上下文                                                                                                                                                                                     | ✓        |
+| 19  | `if` / `else` / `else if` / `for` / `while` / `do-while` 语句即使单行也带 `{}`(Kotlin 表达式 `if` 除外)                                                                                                                                | ✓        |
+| 20  | 新增类按**功能聚合**放对应功能包(`login/` / `order/`),不按 `activities/` / `models/` 分层横切;仅多功能共享才放 `common/`                                                                                                                              | ✓        |
+| 21  | Gradle 脚本(Groovy / kts):锁版本 / `exclude` / 自定义 task / 变体 / 关键魔法值有 why 注释,无复述式、无注释掉的配置块                                                                                                                                     | ✓        |
+
+
+**不执行自检就提交代码 = 违规。**

package/templates/claude-global/rules/Android/dwy-android-support-only.md

@@ -0,0 +1,112 @@
+---
+description: Android 老项目强制使用 Support Library,禁止 AndroidX —— 依赖坐标、import、选库、gradle 配置全部遵循此规则
+paths:
+  - "**/*.java"
+  - "**/*.kt"
+  - "**/*.gradle"
+  - "**/*.kts"
+  - "**/gradle.properties"
+---
+
+# Android Support Library 专用规范(禁用 AndroidX)
+
+## 适用前提(动手前先判断)
+
+本规则**仅用于维护尚未迁移到 AndroidX 的 Support Library 老项目**。先判断当前项目属于哪一类:
+
+- `gradle.properties` 有 `android.useAndroidx=true`,或代码中已大量 `import androidx.*` → 本项目**已是 AndroidX**,**本规则不适用**,按 androidx 正常开发,不要回退到 support
+- 依赖 `com.android.support:*`、import `android.support.*`、无 `android.useAndroidx=true` → 本项目是 **Support 老项目**,严格遵循本规则
+
+**理由**:Support 与 AndroidX 是同一套库前后两代的不同包名,**二者不可混用** —— 同一个类(如 `AppCompatActivity`)存在 `android.support.v7.app` 与 `androidx.appcompat.app` 两个包,混入后编译期报 `Duplicate class`、运行期 `NoClassDefFoundError`。老项目一旦混进 androidx,会陷入不可控的依赖地狱。要么整体维持 support,要么整体迁移 androidx,**禁止半迁移**。
+
+## 一、依赖坐标
+
+- 一律用 `com.android.support:*`,**禁止**任何 `androidx.*`
+- Material 组件用 `com.android.support:design`,**禁止** `com.google.android.material:material`
+- Support Library 版本**全项目统一锁定**(最后一个稳定版 `28.0.0`,可按项目实际调整,但所有 support 模块版本必须一致 —— 版本不一致会触发 `Manifest merger` / `Duplicate class` 报错)
+
+```groovy
+// ✅ Support
+dependencies {
+    implementation 'com.android.support:appcompat-v7:28.0.0'
+    implementation 'com.android.support:recyclerview-v7:28.0.0'
+    implementation 'com.android.support:design:28.0.0'
+    implementation 'com.android.support:cardview-v7:28.0.0'
+    implementation 'com.android.support.constraint:constraint-layout:1.1.3'
+}
+
+// ❌ AndroidX —— 一律禁止
+dependencies {
+    implementation 'androidx.appcompat:appcompat:1.6.1'
+    implementation 'com.google.android.material:material:1.11.0'
+    implementation 'androidx.constraintlayout:constraintlayout:2.0.4'
+}
+```
+
+## 二、gradle.properties
+
+```properties
+# 禁用 AndroidX:必须为 false 或不声明(默认即 false)
+android.useAndroidx=false
+# 禁用 Jetifier:它会把第三方库的 support 依赖自动改写成 androidx,与本规则直接冲突
+android.enableJetifier=false
+```
+
+## 三、import / 类引用
+
+**禁止**任何 `import androidx.*` 与 `import com.google.android.material.*`。常用类映射(**用左列,禁右列**):
+
+| 用途 | ✅ Support(用这个) | ❌ AndroidX(禁止) |
+|---|---|---|
+| AppCompatActivity | `android.support.v7.app.AppCompatActivity` | `androidx.appcompat.app.AppCompatActivity` |
+| Fragment | `android.support.v4.app.Fragment` | `androidx.fragment.app.Fragment` |
+| FragmentManager | `android.support.v4.app.FragmentManager` | `androidx.fragment.app.FragmentManager` |
+| RecyclerView | `android.support.v7.widget.RecyclerView` | `androidx.recyclerview.widget.RecyclerView` |
+| CardView | `android.support.v7.widget.CardView` | `androidx.cardview.widget.CardView` |
+| Toolbar | `android.support.v7.widget.Toolbar` | `androidx.appcompat.widget.Toolbar` |
+| ViewPager | `android.support.v4.view.ViewPager` | `androidx.viewpager.widget.ViewPager` |
+| ConstraintLayout | `android.support.constraint.ConstraintLayout` | `androidx.constraintlayout.widget.ConstraintLayout` |
+| ContextCompat | `android.support.v4.content.ContextCompat` | `androidx.core.content.ContextCompat` |
+| ActivityCompat | `android.support.v4.app.ActivityCompat` | `androidx.core.app.ActivityCompat` |
+| SwipeRefreshLayout | `android.support.v4.widget.SwipeRefreshLayout` | `androidx.swiperefreshlayout.widget.SwipeRefreshLayout` |
+| DrawerLayout | `android.support.v4.widget.DrawerLayout` | `androidx.drawerlayout.widget.DrawerLayout` |
+| LocalBroadcastManager | `android.support.v4.content.LocalBroadcastManager` | `androidx.localbroadcastmanager.content.LocalBroadcastManager` |
+| Material 组件 | `android.support.design.widget.*`(TabLayout / NavigationView / FloatingActionButton / Snackbar 等) | `com.google.android.material.*` |
+
+> 表中未列的类,按规律转换:`androidx.xxx` 的对应 support 包多在 `android.support.v4.*` / `android.support.v7.*` / `android.support.design.*` 下。拿不准时查 [AndroidX → Support 类映射](https://developer.android.com/jetpack/androidx/migrate/class-mappings) 反查。
+
+## 四、选库规则(第三方依赖)
+
+引入任何第三方库时,按顺序执行:
+
+1. **优先选仍依赖 Support Library 的版本线**。库的较新版本若已迁移到 androidx,**锁定在最后一个支持 support 的版本**,并在依赖处注释说明原因与升级前置条件
+2. 评估候选库先查其传递依赖:`./gradlew :app:dependencies`,确认无 `androidx.*` / `com.google.android.material` 渗入
+3. 传递依赖混入 androidx 时,用 `exclude` 排除,并替换为 support 等价物;**无法排除或无 support 等价物 → 换库**,不要将就
+4. **禁止**为使用某个只支持 androidx 的库而引入 androidx —— 一个 androidx 进来就破坏整套隔离,得不偿失
+
+```groovy
+// 库 foo 的 3.x 已迁 androidx,锁在最后支持 support 的 2.8.0(升级需先整体迁 androidx,见 issue #1234)
+implementation 'com.foo:bar:2.8.0'
+
+// 传递依赖混入 androidx,排除掉
+implementation('com.legacy:sdk:1.5.0') {
+    exclude group: 'androidx.appcompat'
+    exclude group: 'androidx.core'
+    exclude group: 'com.android.support'  // 同时排 support,防版本不一致,统一用项目锁定版
+}
+```
+
+## 五、自检(选库 / 改依赖 / 写代码后强制执行)
+
+**任一未通过 → STOP,立即修正。**
+
+| # | 检查项 | 违规即 STOP |
+|---|--------|------------|
+| 1 | 无 `import androidx.*`、无 `import com.google.android.material.*` | ✓ |
+| 2 | 依赖坐标全部 `com.android.support:*`,无 `androidx.*` / `com.google.android.material:material` | ✓ |
+| 3 | 所有 support 模块版本一致(默认 `28.0.0`) | ✓ |
+| 4 | `gradle.properties` 无 `android.useAndroidx=true`、无 `android.enableJetifier=true` | ✓ |
+| 5 | 新引入第三方库经 `:dependencies` 核查无 androidx 传递依赖,有则 `exclude` 或换库 | ✓ |
+| 6 | 为规避 androidx 而锁定版本的依赖,有注释说明原因与升级前置条件 | ✓ |
+
+**不执行自检就提交代码 = 违规。**