197 lines
5.9 KiB
Markdown
197 lines
5.9 KiB
Markdown
# 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）：**
|
||
```objc
|
||
- (void)setupNavigationBar;
|
||
- (void)loadUserDataWithType:(NSInteger)type;
|
||
```
|
||
|
||
**属性修饰符规范：**
|
||
```objc
|
||
@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
|
||
```
|
||
|
||
**宏常量：**
|
||
```objc
|
||
#define kNavBgColor [UIColor colorWithHexString:@"#00AE68"] // 颜色用 k 前缀
|
||
#define SCREEN_WIDTH [UIScreen mainScreen].bounds.size.width // 系统级用大写
|
||
```
|
||
|
||
---
|
||
|
||
### 代码组织（#pragma mark）
|
||
|
||
```objc
|
||
#pragma mark - ————— Life Cycle —————
|
||
|
||
#pragma mark - ————— Setter / Getter —————
|
||
|
||
#pragma mark - ————— Private Methods —————
|
||
|
||
#pragma mark - ————— Network —————
|
||
|
||
#pragma mark - ————— UITableViewDataSource —————
|
||
|
||
#pragma mark - ————— UITableViewDelegate —————
|
||
```
|
||
|
||
---
|
||
|
||
### 内存管理
|
||
|
||
Block 内防循环引用，使用项目全局 `kWeakSelf` 宏：
|
||
|
||
```objc
|
||
kWeakSelf(self);
|
||
[self.manager doSomethingWithCompletion:^{
|
||
[weakself updateUI];
|
||
}];
|
||
```
|
||
|
||
---
|
||
|
||
### UI 布局
|
||
|
||
frame 与 Masonry 均可使用，根据实际场景判断，不强制统一。
|
||
|
||
屏幕适配使用项目已定义宏（基于 375pt 基准）：
|
||
```objc
|
||
kRealValue(x) // 尺寸等比缩放
|
||
kFontSize(x) // 字体等比缩放
|
||
```
|
||
|
||
---
|
||
|
||
### 网络层规范
|
||
|
||
项目网络层使用 `XJPNetAPI` + `JKCQNetworkingWithCache`，
|
||
回调通过 `performSelector` 动态分发，**遵循以下固定签名**：
|
||
|
||
**发起请求：**
|
||
```objc
|
||
// init:tag:NeedToken: 初始化，self 作为代理，tag 区分同一 VC 内的不同请求
|
||
XJPNetAPI *api = [[XJPNetAPI alloc] init:self tag:@"USERINFO" NeedToken:token];
|
||
[api getUserInfo:paramDic];
|
||
```
|
||
|
||
**实现回调（固定方法签名，不得修改）：**
|
||
```objc
|
||
// 请求成功
|
||
- (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` 发起网络请求
|