Authenticator/CLAUDE.md

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