init: init proj

2025-10-19 12:32:16 +08:00
commit 21c23d9400
52 changed files with 2924 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,160 @@
+# 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`