# Agent 行为准则 & HealthEmergency iOS 开发规范

---

## 一、Agent 行为准则

### 0. 语言强制
- 强制使用简体中文进行所有交互（代码除外）。

### 1. 抽象设计确认
- 涉及抽象设计、架构调整或新功能模块时，必须先用文字或 Mermaid 图对齐设计思路。
- 必须等待用户确认方案后，才能开始编写代码。

### 2. 任务清单确认
- 执行任何实质性任务前，必须先列出详细的任务清单。
- 必须等待用户明确回复（如"好的"、"开始"）后，才能进入执行阶段。

### 3. 分步执行与确认
- 代码量较大或逻辑复杂的任务，禁止一次性完成。
- 拆分为多个步骤，每步完成后汇报进度并询问"是否可以进行下一步？"。

### 4. 所有修改必须确认
- 对代码库的任何修改（新建文件、修改文件、删除文件、执行 pod install 等）前，必须先描述变更内容。
- 必须等待用户明确回复"确认"或"同意"后，才能执行。

### 5. 代码注释语言规范
- 所有注释使用简体中文。
- 标识符（变量名、函数名、类名）仍使用英文。

---

## 二、项目技术规范

### 技术栈

- **主语言**: Swift（混编 Objective-C，Swift 为主）
- **UI 框架**: UIKit
- **架构模式**: MVC + BasicModule 基础设施层
- **包管理**: CocoaPods，使用 `.xcworkspace` 打开项目
- **最低系统版本**: iOS 13.0
- **布局**: SnapKit（主要）+ frame
- **网络**: Moya + Alamofire
- **图片加载**: Kingfisher
- **主题**: SwiftTheme

---

## 三、项目目录结构

```
HealthEmergency/
├── BasicModule/                  # 基础设施层（非业务）
│   ├── Base/                     # 基类（MktViewController、MktNavigatonController）
│   ├── Network/                  # 网络层（RequestManager、RequestTarget、NetworkParser）
│   ├── Extension/                # Swift 扩展
│   ├── Util/                     # 工具类（ThemeManager、Foundation.swift）
│   ├── Helper/                   # POP 动画 & 自定义辅助类
│   ├── CacheKit/                 # 缓存工具
│   └── Configuration/            # APIKey 等配置（敏感，勿外传）
├── Class/                        # 业务模块
│   ├── Home/                     # 首页（应用）
│   ├── Dangan/                   # 档案（健康记录）
│   ├── AI/                       # AI 助手
│   ├── Knowledge/                # 知识库
│   ├── Mine/                     # 我的（用户中心）
│   ├── Market/                   # 市场/产品（未在主 TabBar）
│   ├── Message/                  # 消息（TUI IM 集成）
│   └── Login/                    # 登录模块
├── Resources/
│   └── Themes/                   # 主题配置（blue/red/green/purple.plist）
└── HealthEmergency-Bridging-Header.h
```

新增业务模块按以下结构组织：
```
Class/ModuleName/
├── ViewController/    # 视图控制器
├── View/              # 自定义视图
└── Model/             # 数据模型（Codable struct）
```

---

## 四、命名规范

**类名（PascalCase）：**
- 基类及核心组件使用 `Mkt` 前缀，如 `MktViewController`、`MktNavigatonController`
- 业务类按模块语义命名，如 `HomeViewController`、`DanganHomeViewController`
- 数据模型用 `Model` 后缀，如 `BannerModel`、`MarketProductModel`

**文件组织：**
- 扩展文件：`Extension+Feature.swift`，如 `Extension+UIView.swift`
- 模型文件：放在对应模块的 `Model/` 子目录

**方法名（camelCase）：**
```swift
func setupUI()
func updateThemeUI()
func loadData(page: Int)
```

**常量：**
```swift
// Swift 常量用 camelCase
let defaultPageSize = 20

// OC 宏用大写
JPScaleValue(16)
```

---

## 五、代码组织

```swift
// MARK: - Life Cycle
// MARK: - Setup
// MARK: - Network
// MARK: - Actions
// MARK: - ThemeProtocol / Theme
// MARK: - UITableViewDataSource
// MARK: - UITableViewDelegate
```

---

## 六、网络层规范

### 发起请求

项目网络层统一使用 `RequestTarget` + `RequestManager`，通过 Moya 封装：

```swift
// GET 请求（带分页参数）
RequestTarget.get("/api/v1/list", query: ["page": 1, "size": 20])
    .sendParsed(showHUD: true, type: [ItemModel].self) { success, data, msg in
        guard success, let items = data else { return }
        self.items = items
        self.tableView.reloadData()
    }

// POST 请求
RequestTarget.post("/api/v1/submit", body: ["key": "value"])
    .sendParsed(showHUD: true, type: ResultModel.self) { success, data, msg in
        if success {
            Mkt.makeToast("提交成功")
        }
    }

// 文件上传
RequestTarget.upload("/api/v1/upload", files: [fileData], names: ["file"])
    .sendParsed(showHUD: true, type: UploadResult.self) { success, data, msg in
        // ...
    }
```

### 响应码说明

| 响应码 | 含义 |
|--------|------|
| `0000` / `200` | 请求成功 |
| `4001` | Token 过期，自动跳转登录 |
| `-888` | 网络不可用 |
| `-999` | 请求超时 |
| `-666` | 服务器异常 |

### 数据模型结构

```swift
// 服务端统一响应结构
struct Response<T: Codable> {
    var retCode: String   // 响应码
    var retMsg: String    // 响应信息
    var retData: T?       // 业务数据
}

// 数据模型使用 Codable struct
struct ItemModel: Codable {
    var id: String?
    var name: String?
    var createdAt: String?
}
```

### 注意事项

- API 地址统一定义在 `BasicModule/Configuration/APIKey.swift`，禁止在业务代码中硬编码 URL
- SDK Key / Secret 统一放 `APIKey.swift`，禁止散落在业务文件
- 网络回调默认在主线程，可直接操作 UI

---

## 七、主题系统

项目支持 4 套主题（blue / red / green / purple），配置文件在 `Resources/Themes/*.plist`。

### 初始化（AppDelegate）

```swift
AppThemeManager.shared.setup()
```

### 切换主题

```swift
AppThemeManager.shared.switchTheme(to: .blue)
```

### 在视图中应用主题

```swift
override func viewDidLoad() {
    super.viewDidLoad()
    setupTheme()
}

private func setupTheme() {
    updateThemeUI()
    observeThemeChanges { [weak self] in
        self?.updateThemeUI()
    }
}

private func updateThemeUI() {
    // 使用 ThemeKey 绑定（推荐，自动响应主题切换）
    view.theme_backgroundColor = ThemeKey.backgroundColor
    titleLabel.theme_textColor = ThemeKey.textColor
    navBar.theme_backgroundColor = ThemeKey.navBarColor
}
```

### 常用 ThemeKey

```swift
ThemeKey.primaryColor          // 主色调
ThemeKey.backgroundColor       // 页面背景色
ThemeKey.textColor             // 正文文字色
ThemeKey.navBarColor           // 导航栏背景色
ThemeKey.navBarTextColor       // 导航栏文字色
ThemeKey.buttonBgColor         // 按钮背景色
ThemeKey.tabBarSelectedColor   // TabBar 选中色
```

---

## 八、常用工具速查

### Mkt 全局结构体（`BasicModule/Util/Foundation.swift`）

```swift
Mkt.appName           // App 名称
Mkt.isDebug           // 是否 Debug 模式
Mkt.isDevice          // 真机 vs 模拟器
Mkt.screenWidth       // 屏幕宽度
Mkt.screenHeight      // 屏幕高度
Mkt.safe_top          // 安全区上边距
Mkt.safe_bottom       // 安全区下边距
Mkt.topBarHeight      // 导航栏 + 安全区高度
Mkt.keyWindow         // 当前活跃 UIWindow
Mkt.makeToast("提示")  // Toast 提示
Mkt.jsonToModel()     // JSON ↔ Codable 模型转换
```

### 日志（DEBUG 模式有效）

```swift
dlog("请求参数: \(params)")   // 带文件名/函数名/行号自动输出
```

### JPConstant.h 宏（OC 层，通过 Bridging Header 可用）

```objc
JPScaleValue(16)     // 按屏幕宽度等比缩放数值（基准 375pt）
JPScaleFont(14)      // 等比缩放字体
JPRGBColor(r, g, b)  // RGB 0-255 创建颜色
JPStringEqual(a, b)  // 安全字符串比较
```

### 用户管理

```swift
UserManager.shared.isLoggedIn       // 是否已登录
UserManager.shared.currentUser      // 当前用户信息（UserInfo?）
UserManager.shared.token            // 当前 Token
```

---

## 九、UI 布局规范

**优先使用 SnapKit：**

```swift
titleLabel.snp.makeConstraints { make in
    make.top.equalToSuperview().offset(16)
    make.left.right.equalToSuperview().inset(20)
    make.height.equalTo(JPScaleValue(44))
}
```

**屏幕适配统一用 `JPScaleValue()`：**

```swift
// 设计稿 375pt 基准，所有固定尺寸都过 JPScaleValue
let itemHeight = JPScaleValue(80)
let fontSize = JPScaleFont(14)
```

**UIView 扩展（`Extension+UIView.swift`）常用方法：**

```swift
view.setCornerRadius(8)                        // 圆角
view.setShadow(color: .black, opacity: 0.1)    // 阴影
view.addGradient(colors: [.blue, .cyan])       // 渐变
```

---

## 十、内存管理

Block / 闭包内防循环引用，统一使用 `[weak self]`：

```swift
RequestTarget.get("/api/list")
    .sendParsed(type: [Item].self) { [weak self] success, data, msg in
        guard let self = self else { return }
        self.items = data ?? []
        self.tableView.reloadData()
    }
```

---

## 十一、各模块职责

| 模块 | 路径 | 职责 |
|------|------|------|
| **Home** | `Class/Home/` | 首页 Dashboard、Banner、应用入口 |
| **Dangan** | `Class/Dangan/` | 健康档案、体检记录 |
| **AI** | `Class/AI/` | AI 健康助手对话 |
| **Knowledge** | `Class/Knowledge/` | 健康知识库、文章 |
| **Mine** | `Class/Mine/` | 用户中心、设置、个人信息 |
| **Market** | `Class/Market/` | 产品/服务目录（不在主 TabBar） |
| **Message** | `Class/Message/` | IM 消息列表（TUIKit 集成） |
| **Login** | `Class/Login/` | 登录、注册、忘记密码 |
| **BasicModule/Network** | — | 全局网络请求封装，禁止绕过 |
| **BasicModule/Base** | — | 所有 VC 的基类，提供主题/导航能力 |

---

## 十二、禁止事项

- 禁止将 API Key、SDK AppID 等敏感信息硬编码在业务文件中（统一放 `APIKey.swift`）
- 禁止在主线程执行网络请求、数据库读写、文件 IO 等耗时操作
- 禁止绕过 `RequestTarget` / `RequestManager` 直接使用 Alamofire 发起请求
- 禁止在未通知用户的情况下引入新的 Pod 依赖
- 禁止修改 `BasicModule/Base/` 中的基类，除非经用户明确确认
- 禁止在 Swift Extension 中添加存储属性（使用 AssociatedObject 或重构为子类）
- 禁止未经确认自行切换主题或修改 `Resources/Themes/*.plist`