# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

这是一个 **MFA Authenticator (多因素身份验证器)** HarmonyOS 应用程序,使用 ArkTS (扩展的 TypeScript) 和 ArkUI 框架开发。应用实现了基于时间的一次性密码(TOTP)算法,用于生成双因素认证验证码。

### 核心功能
- TOTP 验证码生成(30秒自动刷新)
- 账户管理(添加、编辑、删除)
- 本地加密存储
- 搜索功能
- 暗色模式支持
- Apple Design 风格的简洁 UI

## 构建系统

项目使用 Hvigor 作为构建工具:

- **构建命令**: 通过 DevEco Studio 或 `hvigorw` 脚本构建
- **清理**: `hvigorw clean`
- **构建**: `hvigorw assembleHap`
- **调试构建**: `hvigorw --mode debug assembleHap`
- **发布构建**: `hvigorw --mode release assembleHap`

## 测试

项目包含两种测试类型:

- **本地单元测试**: `entry/src/test/` - 使用 Hypium 框架
- **设备测试**: `entry/src/ohosTest/` - 需要在设备或模拟器上运行
- **运行测试**: 通过 DevEco Studio 的测试配置运行

依赖的测试框架:
- `@ohos/hypium`: 单元测试框架
- `@ohos/hamock`: Mock 工具

## 代码架构

### 模块结构

```
entry/src/main/ets/
├── common/
│   ├── constants/
│   │   └── AppConstants.ets          # 应用常量(TOTP周期、UI常量等)
│   └── utils/
│       ├── Base32.ets                 # Base32 编解码工具
│       ├── TOTPGenerator.ets          # TOTP 算法实现
│       └── StorageUtil.ets            # 本地存储工具(Preferences)
├── model/
│   └── Account.ets                    # 账户数据模型
├── viewmodel/
│   └── AccountViewModel.ets           # 账户业务逻辑
├── view/
│   └── components/
│       ├── AccountCard.ets            # 账户卡片组件
│       └── ProgressRing.ets           # 圆形进度指示器
├── pages/
│   ├── AccountListPage.ets            # 主页面(账户列表)
│   ├── AddAccountPage.ets             # 添加账户页面
│   └── AccountDetailPage.ets          # 账户详情/编辑页面
├── entryability/
│   └── EntryAbility.ets               # 应用入口
└── entrybackupability/
    └── EntryBackupAbility.ets         # 备份恢复功能
```

### 核心模块说明

#### 1. TOTP 算法实现
- **TOTPGenerator.ets**: 基于 RFC 6238 标准实现
  - 使用 HarmonyOS 的 `cryptoFramework` 生成 HMAC-SHA1
  - 支持自定义时间步长和验证码位数
  - 提供进度计算方法

#### 2. 数据存储
- **StorageUtil.ets**: 使用 Preferences API 进行持久化
- **Account Model**: JSON 序列化存储账户信息
- 支持加密存储(未来可扩展)

#### 3. UI 组件
- **AccountCard**: 显示账户信息、验证码、进度环
  - 点击复制验证码
  - 长按显示操作菜单
- **ProgressRing**: 圆形进度指示器,显示倒计时

#### 4. 页面结构
1. **AccountListPage** (主页)
   - 账户列表展示
   - 搜索功能
   - 定时器自动刷新验证码

2. **AddAccountPage** (添加账户)
   - Tab 切换:扫码/手动输入
   - 表单验证

3. **AccountDetailPage** (编辑账户)
   - 编辑发行者和账户名
   - 查看密钥(可切换显示/隐藏)

### ArkTS 开发要点

- **文件扩展名**: `.ets` (ArkTS 文件)
- **UI 组件**: 使用声明式语法,如 `Text`, `RelativeContainer`, `Button` 等
- **状态管理**: 使用装饰器 `@State`, `@Prop`, `@Link` 等
- **日志输出**: 使用 `hilog` API,格式: `hilog.info(DOMAIN, tag, message)`
- **资源引用**: 使用 `$r('app.type.name')` 格式,如 `$r('app.string.EntryAbility_label')`

### 配置文件

- **build-profile.json5**: 应用构建配置,包含签名、目标 SDK 版本等
- **module.json5**: 模块配置,定义 abilities、页面、权限等
- **oh-package.json5**: 依赖包管理
- **code-linter.json5**: 代码检查规则

## SDK 版本

- **目标 SDK**: HarmonyOS 6.0.0(20)
- **兼容 SDK**: HarmonyOS 6.0.0(20)
- **运行时**: HarmonyOS

## UI 设计规范

### 配色方案(Apple Design 风格)
- **主色**: `#007AFF` (浅色) / `#0A84FF` (深色)
- **背景色**: `#F2F2F7` (浅色) / `#000000` (深色)
- **卡片背景**: `#FFFFFF` (浅色) / `#1C1C1E` (深色)
- **文字颜色**: 主要 / 次要 / 三级 (响应式暗色模式)

### 设计元素
- **圆角**: 12-16vp
- **间距**: 8/12/16/24vp 系统
- **字体大小**:
  - 标题: 28-32fp
  - 正文: 15-17fp
  - 验证码: 36fp (等宽字体)
  - 辅助文字: 13fp

### 交互规范
- 卡片点击: 复制验证码
- 长按: 显示操作菜单
- 进度环: 30秒倒计时动画

## 注意事项

- 所有源代码文件使用 `.ets` 扩展名
- 页面路径在 `entry/src/main/resources/base/profile/main_pages.json` 中注册
- 使用 `@kit.*` 导入系统能力,如 `@kit.AbilityKit`, `@kit.ArkUI`
- 日志使用统一的 `AppConstants.LOG_DOMAIN` 和 `AppConstants.LOG_TAG`
- TOTP 密钥必须是 Base32 格式
- 应用支持自动暗色模式切换

## 开发建议

- 在 DevEco Studio 中打开项目进行开发和调试
- 使用 HarmonyOS 模拟器或真机进行测试
- 验证码刷新使用定时器,注意在页面销毁时清理定时器
- 添加新页面时记得更新 `main_pages.json`