Files

T

NSArray 9dab8404af chore: 添加 CLAUDE.md 项目开发规范文档

包含 Agent 行为准则、技术栈、目录结构、命名规范、网络层、主题系统等开发规范。

2026-04-21 15:23:04 +08:00

10 KiB

Raw Blame History

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）：

func setupUI()
func updateThemeUI()
func loadData(page: Int)

常量：

// Swift 常量用 camelCase
let defaultPageSize = 20

// OC 宏用大写
JPScaleValue(16)

五、代码组织

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

六、网络层规范

发起请求

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

// 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`	服务器异常

数据模型结构

// 服务端统一响应结构
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）

AppThemeManager.shared.setup()

切换主题

AppThemeManager.shared.switchTheme(to: .blue)

在视图中应用主题

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

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

八、常用工具速查

Mkt 全局结构体（`BasicModule/Util/Foundation.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 模式有效）

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

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

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

用户管理

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

九、UI 布局规范

优先使用 SnapKit：

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

屏幕适配统一用 JPScaleValue()：

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

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

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

十、内存管理

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

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

10 KiB Raw Blame History Unescape Escape