xj-ios/CLAUDE.md

Agent 行为准则 & XinjiangProject iOS 开发规范

---

一、Agent 行为准则

0. 语言强制

• 强制使用简体中文进行所有交互（代码除外）。

1. 抽象设计确认

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

2. 任务清单确认

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

3. 分步执行与确认

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

4. 所有修改必须确认

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

9. 代码注释语言规范

• 所有注释使用简体中文。
• 标识符（变量名、函数名、类名）仍使用英文。

---

二、项目技术规范

技术栈

• 主语言: Objective-C
• 混编: 允许 OC/Swift 混编，OC 为主。引入 Swift 文件前必须征得用户确认。
• UI 框架: UIKit
• 架构模式: MVC + Manager 层
• 包管理: CocoaPods，使用 .xcworkspace 打开项目
• 最低系统版本: iOS 12.0

---

项目目录结构

XinjiangProject/
├── Project/                  # 业务模块（按功能划分）
│   ├── Base/                 # 基类 ViewController
│   ├── AppDelegate/
│   ├── Login_Register/
│   ├── HomeV2/
│   ├── Homepage/
│   ├── Monitoring/
│   ├── MainCenter/
│   ├── BANK/
│   ├── SOS/
│   ├── Qusetion/
│   ├── TUIChat/
│   ├── CustomTUIChat/
│   └── simulationUser(模拟用户)/
├── Manager/                  # 业务逻辑管理层
│   ├── NetworkHelpManager/   # 网络层（XJPNetAPI、JKCQNetworkingWithCache）
│   ├── UserManager/
│   ├── AudioManager/
│   ├── TUIManager/
│   └── RuntimeManager/
├── Categorys/                # UIKit 分类扩展
├── Utils/                    # 工具类
├── Define/                   # 宏定义（颜色、字体、接口地址、Key）
└── ThirdParty/               # 本地化第三方库

新增模块按以下结构组织：

Project/ModuleName/
├── Controller/
├── View/
└── Model/

---

命名规范

类名（PascalCase）：

• 新建类统一使用前缀 XJ，如 XJOrderViewController、XJUserModel
• 历史遗留 HQ 前缀类（如 HQUserInfo）维护时保持原前缀，不得重命名
• 分类命名：ClassName+ExtensionName，如 UIView+Extension

方法名（camelCase）：

- (void)setupNavigationBar;
- (void)loadUserDataWithType:(NSInteger)type;

属性修饰符规范：

@property (nonatomic, strong) UIView      *containerView; // 对象用 strong
@property (nonatomic, copy)   NSString    *userName;      // 字符串/Block 用 copy
@property (nonatomic, assign) NSInteger    pageIndex;     // 基本类型用 assign
@property (nonatomic, weak)   id<Protocol> delegate;      // 代理用 weak

宏常量：

#define kNavBgColor   [UIColor colorWithHexString:@"#00AE68"] // 颜色用 k 前缀
#define SCREEN_WIDTH  [UIScreen mainScreen].bounds.size.width  // 系统级用大写

---

代码组织（#pragma mark）

#pragma mark - ————— Life Cycle —————

#pragma mark - ————— Setter / Getter —————

#pragma mark - ————— Private Methods —————

#pragma mark - ————— Network —————

#pragma mark - ————— UITableViewDataSource —————

#pragma mark - ————— UITableViewDelegate —————

---

内存管理

Block 内防循环引用，使用项目全局 kWeakSelf 宏：

kWeakSelf(self);
[self.manager doSomethingWithCompletion:^{
    [weakself updateUI];
}];

---

UI 布局

frame 与 Masonry 均可使用，根据实际场景判断，不强制统一。

屏幕适配使用项目已定义宏（基于 375pt 基准）：

kRealValue(x)  // 尺寸等比缩放
kFontSize(x)   // 字体等比缩放

---

网络层规范

项目网络层使用 XJPNetAPI + JKCQNetworkingWithCache， 回调通过 performSelector 动态分发，遵循以下固定签名：

发起请求：

// init:tag:NeedToken: 初始化，self 作为代理，tag 区分同一 VC 内的不同请求
XJPNetAPI *api = [[XJPNetAPI alloc] init:self tag:@"USERINFO" NeedToken:token];
[api getUserInfo:paramDic];

实现回调（固定方法签名，不得修改）：

// 请求成功
- (void)Sucess:(id)response tag:(NSString *)tag {
    if ([tag isEqualToString:@"USERINFO"]) {
        // 处理用户信息数据
    }
}

// 请求失败
- (void)Failed:(NSString *)message tag:(NSString *)tag {
    [self showMBProgressHUDOnlyWithString:message];
}

注意事项：

• Sucess 为项目约定拼写（非笔误），禁止修改方法名
• 同一 VC 内多个请求通过 tag 字符串区分，在回调中用 if/else 分支处理
• API 地址统一定义在 StatusMacros.h，禁止在业务代码中硬编码 URL

---

禁止事项

• 禁止将 API Key、SDKAPPID 等敏感信息硬编码在业务文件中（统一放 ThirdMacros.h）
• 禁止在主线程执行网络请求、数据库读写、文件 IO 等耗时操作
• 禁止在 Category 中声明存储属性（需用 objc_setAssociatedObject）
• 禁止修改 Sucess:tag: / Failed:tag: 的方法签名
• 禁止未经确认自行封装或绕过 XJPNetAPI 发起网络请求