feat(card): 优化销卡功能并添加写卡操作

zuoxiao

2 天以前 465c8abaa982fba6868a900d25316c70afc20fb7

 README.md

@@ -232,6 +232,171 @@
- CardData: 卡片数据
- ProjectDataBean: 项目数据

## 数据类管理规范

### Bean包结构组织

项目中所有的数据类（Data Class）都应该统一放在`bean`包下的相应子目录中，按照功能和用途进行分类：

```
generallibrary/src/main/java/com/dayu/general/bean/
├── net/        # 网络接口相关数据类
├── card/       # 卡片相关数据类  
├── db/         # 数据库实体类
└── ...         # 其他功能模块数据类
```

#### 1. 网络接口数据类 (bean/net/)

所有API接口的请求和响应数据类都放在`net`目录下：

```kotlin
// 请求数据类示例
data class RechargeRequest(
    val rechargeType: Int,
    val cardNum: String,
    val money: String,
    // ... 其他字段
)

// 响应数据类示例  
data class CardCancelResult(
    val projectNo: Int,
    val cardNum: String,
    val orderNo: String
)
```

#### 2. 卡片相关数据类 (bean/card/)

所有卡片操作相关的数据类放在`card`目录下：

```kotlin
data class UserCard(
    var cardType: String = "",
    var balance: Int = 0,
    var userCode: String = "",
    // ... 其他字段
)
```

#### 3. 数据库实体类 (bean/db/)

所有Room数据库的实体类放在`db`目录下：

```kotlin
@Entity(tableName = "card_data")
data class CardData(
    @PrimaryKey val id: Long,
    val cardNumber: String,
    // ... 其他字段
)
```

### 数据类命名规范

1. **接口响应数据类**: 以`Result`结尾
   - `CardCancelResult` - 销卡接口响应
   - `RechargeResult` - 充值接口响应
   - `WaterPriceResult` - 水价接口响应

2. **接口请求数据类**: 以`Request`结尾
   - `RechargeRequest` - 充值接口请求
   - `SearchUserBeanRequest` - 用户搜索请求

3. **业务实体数据类**: 使用业务名称
   - `UserCard` - 用户卡片数据
   - `ClearCard` - 清零卡数据

4. **数据库实体类**: 使用表名对应的实体名
   - `CardData` - 卡片数据表
   - `ProjectDataBean` - 项目数据表

### 数据类创建最佳实践

#### 1. 文件头注释规范

```kotlin
package com.dayu.general.bean.net

/**
 * 销卡结果数据类
 * @author: zuo
 * @date: 2025/01/17
 * @description: 销卡接口返回数据
 */
data class CardCancelResult(
    val projectNo: Int,     // 项目编号
    val cardNum: String,    // 卡号
    val orderNo: String     // 订单号
)
```

#### 2. 字段注释规范

- 每个字段都应该添加行内注释说明用途
- 对于枚举值或特殊含义的字段，详细说明取值范围

#### 3. 导入使用规范

在Activity或其他类中使用数据类时，应该导入具体的数据类：

```kotlin
// 正确的导入方式
import com.dayu.general.bean.net.CardCancelResult
import com.dayu.general.bean.net.RechargeResult

// 在代码中使用
private fun handleCancelResult(result: CardCancelResult) {
    // 处理销卡结果
}
```

#### 4. 禁止内联定义

**禁止**在Activity或其他类中内联定义数据类：

```kotlin
// ❌ 错误做法 - 不要在Activity中内联定义数据类
class CardCancelActivity : BaseNfcActivity() {
    
    // ❌ 禁止这样做
    data class CardCancelResult(
        val projectNo: Int,
        val cardNum: String,
        val orderNo: String
    )
}

// ✅ 正确做法 - 在bean包中定义数据类
// 文件: generallibrary/src/main/java/com/dayu/general/bean/net/CardCancelResult.kt
data class CardCancelResult(
    val projectNo: Int,
    val cardNum: String, 
    val orderNo: String
)
```

### 数据类管理优势

1. **统一管理**: 所有数据类集中在bean包下，便于查找和维护
2. **职责分离**: 业务逻辑和数据结构分离，代码结构更清晰
3. **复用性强**: 数据类可以在多个模块间复用
4. **易于重构**: 数据结构变更时只需修改一个文件
5. **类型安全**: 编译期类型检查，减少运行时错误

### 迁移现有代码

对于已经存在的内联数据类，应该按照以下步骤进行迁移：

1. 在bean包的相应子目录下创建数据类文件
2. 移动数据类定义到新文件
3. 在原文件中添加导入语句
4. 测试确保功能正常
5. 提交代码变更

通过统一的数据类管理规范，可以提高代码的可维护性和可读性，使项目结构更加清晰规范。

## 开发环境要求

- Android Studio Arctic Fox或更高版本