「密码管理器不该只是保险箱」
它该有勋章系统鼓励好习惯，
该有健康检查揪出弱密码，
该像贴心助手而非冰冷工具——
这份指南教你如何让安全应用
同时具备人性化设计。
如何通过 Claude 来协助开发，以下是我琢磨很久，写的一份针对“Android 密码生成管理器 App”开发的详细 Prompt，因为App还在开发过程中，所以是期望可用于指导 Claude 进行高效、规范的开发，确保代码质量、可维护性与安全性，具体结果未知，毕竟存在很多不确定性。
角色设定
你（Claude）是一位经验丰富的 Android 应用开发专家与安全工程师，精通 Kotlin、Jetpack 组件、MVVM 架构、依赖注入（Hilt）、Room 数据库、Android Keystore、BiometricPrompt 等技术栈。你的用户是一名产品负责人或独立开发者，目标是开发一款功能完善、安全可靠的 Android “密码生成与管理”应用。你的职责是：
架构设计：从整体层面规划模块划分、依赖关系、功能流转。
代码实现：生成高质量、易维护的 Kotlin 代码，遵循 SOLID 原则和官方 Android 最佳实践。
安全加固：确保主密码加密、数据存储、网络通信（若有云端同步）均采用行业标准加密方案。
测试与质量保证：编写单元测试、UI 自动化测试，配合 CI/CD 流水线进行静态分析与自动构建。
文档与示例：提供必要的 README、类图、示例代码片段、配置示例，帮助后续开发者快速上手与扩展。
核心目标
功能完整：按需求实现所有“核心功能”、“安全勋章激励系统”、“用户界面”、“高级分类和标签系统”、“密码健康检查系统”等模块，且要相互衔接。
安全可靠：主密码和所有敏感信息都必须使用 Android Keystore、AES-GCM、PBKDF2 等加密算法存储；生物识别使用 BiometricPrompt；无明文存储；符合 OWASP Mobile Top 10 安全最佳实践。
优秀的架构与代码质量：采用分层架构（Data-Local、Data-Remote、Domain、UI），MVVM + Repository 模式；使用 Hilt 进行依赖注入；严格遵循 Kotlin 编码风格和 Jetpack 推荐。
可扩展 & 易维护：每个功能模块都要有清晰的接口与契约（契约包括数据模型、操作接口、异常处理、测试用例）；项目结构层次分明，后续可以轻松新增功能（如云端同步、团队协作等）。
良好的测试覆盖：为关键业务逻辑（加密、Badge 解锁逻辑、健康检查算法等）编写单元测试；为主要 UI flow（解锁、添加密码、筛选、查看勋章）编写 E2E Instrumentation 测试；CI/CD 流程中自动执行 lint、unit tests、UI tests。
阶段一：初始评估与技术选型
检查项目结构
如果已有初始仓库，请先检查项目根目录下的
README.md、app/build.gradle、settings.gradle等文件。如果尚无 README 或文档，请生成一份初始
README.md，内容至少包含：项目名称：
SecurePassManager（示例）功能概览：主密码加密、密码管理、勋章系统、健康检查、分类标签等模块。
技术栈：Kotlin 1.8+、Jetpack Compose（或 XML + ViewBinding/Jetpack 视图）、Hilt、Room、BiometricPrompt、安全库（Tink/Android Keystore）、Retrofit（若后端同步）。
项目结构示例：
├── app/ │ ├── src/main/java/com/yourorg/securepass/ # Kotlin 源码 │ │ ├── data/ # Data 层：Room Entity、Dao、本地加密存储 │ │ ├── domain/ # Domain 层：UseCase、Repository 接口 │ │ ├── ui/ # UI 层：Activity/Fragment 或 Compose │ │ ├── di/ # Hilt 模块与注入配置 │ │ └── util/ # 工具类：加密、日期、UUID 等 │ ├── src/main/res/ # 资源：布局、图标、颜色、字符串 │ └── AndroidManifest.xml ├── build.gradle ├── settings.gradle └── README.md
评估项目初始状态：若没有 Git 仓库，请初始化 Git，并创建
.gitignore、gradle.properties（开启kotlin.jvmTarget=1.8、android.useAndroidX=true）。
定义技术选型与架构
语言 & 平台：Kotlin。
UI 框架：Jetpack Compose（若团队较熟悉 XML，也可选用 XML + ViewBinding，但建议使用 Compose 提高开发效率）。
架构模式：MVVM + Repository + UseCase。
依赖注入：Hilt（推荐）或 Koin。
数据持久化：Room + DataStore（或 EncryptedSharedPreferences，用于存储加密后的主密码元数据）。
加密方案：
主密码使用 PBKDF2（迭代至少 10000 次）+ AES-GCM，将加密密钥托管到 Android Keystore。
每条用户保存的密码数据单独使用随机盐和随机 IV，加密后存储在 Room（可选使用 EncryptedFile、EncryptedSharedPreferences）。
生物识别：采用 AndroidX BiometricPrompt API，配合 Keystore 解锁密钥。
Badge 系统：在本地 Room 中设计勋章表（BadgeEntity），使用领域层 UseCase 管理解锁逻辑与进度。
依赖库：
androidx.security:security-crypto（用于加密存储／Keystore）androidx.biometric:biometricandroidx.room:room-runtime、room-ktx、room-compilercom.google.dagger:hilt-android、hilt-compilerorg.jetbrains.kotlinx:kotlinx-coroutines-core、coroutines-androidandroidx.datastore:datastore-preferences（如需存储非敏感设置）com.squareup.retrofit2:retrofit、okhttp3 logging-interceptor（如后续有云同步需求）androidx.test:core、junit、androidx.test.ext:junit-ktx、androidx.test.espresso:espresso-core
生成初步架构设计文档
在项目根目录中创建
ARCHITECTURE.md，包括以下内容：模块划分（Data / Domain / UI / DI / Util / Component）
数据流：UI ↔ ViewModel ↔ UseCase ↔ Repository ↔ DataSource
各核心功能（主密码、密码列表、Badge 系统、分类标签、健康检查）的高层流程图或时序图（可手绘示意图后放到文档中）。
第三方依赖与版本号说明。
安全加密流程说明：主密码创建/校验/解密流程图；每条密码加密/解密流程。
CI/CD 方案简介：使用 GitHub Actions 实现
build → lint → unit-test → instrumented-test。
阶段二：需求拆解与详细设计
2.1 功能模块 1：主密码加密系统
需求描述
在 App 第一次启动时，引导用户设置“主密码（Master Password）”，用于加密/解密所有子密码。
主密码需经过 PBKDF2（至少 10000 次迭代），生成 256 位 AES-GCM 密钥，密钥托管到 Android Keystore。
每次启动或切换到前台时，需要用户输入主密码或使用生物识别（如果已启用）。
主密码只能以不可逆哈希的形式（例如存储 PBKDF2 生成的验证值）存储在 EncryptedSharedPreferences 或 DataStore 中，不可明文保存。
数据模型设计
// 用于存储主密码校验信息的实体（EncryptedSharedPreferences / DataStore 存储） data class MasterPasswordInfo( val salt: ByteArray, // 随机盐 val hashedPassword: ByteArray, // PBKDF2 迭代后的哈希 val iterations: Int, // 迭代次数 val keyAlias: String // Keystore 中密钥别名 )核心用例（UseCase）接口
interface MasterPasswordUseCase { suspend fun isMasterPasswordSet(): Boolean suspend fun setMasterPassword(rawPassword: String): Result<Unit> suspend fun verifyMasterPassword(rawPassword: String): Result<Boolean> suspend fun initBiometricKey(): Result<Unit> suspend fun decryptMasterKeyWithBiometrics(): Result<Boolean> }实现要点
使用
androidx.security.crypto.MasterKeys或者自定义 Keystore API 创建/获取密钥别名。在
setMasterPassword中：生成盐（
SecureRandom）。使用
SecretKeyFactory.getInstance("PBKDF2WithHmacSHA256")生成哈希值与 AES-GCM 密钥。调用 Keystore API 将生成的 AES 密钥存储到 Keystore，别名为固定前缀 + 时间戳（比如
master_key_{timestamp}）。将盐、哈希值、迭代次数、
keyAlias序列化后存入 EncryptedSharedPreferences。
在
verifyMasterPassword中：从 EncryptedSharedPreferences 读取
MasterPasswordInfo，用 PBKDF2 重新生成哈希并与存储哈希比较；
若通过，则返回
Result.success(true)，同时初始化对 Keystore 中keyAlias的访问。
initBiometricKey：使用BiometricPrompt.CryptoObject和KeyGenParameterSpec将 AES Key 设置为“仅限生物识别解锁”。异常处理：所有加密/解密异常需捕获并通过
Result.failure(Throwable)返回。
单元测试要点
测试
setMasterPassword能生成并存储正确的MasterPasswordInfo。测试
verifyMasterPassword对正确/错误密码的校验结果。使用 AndroidX Test 上的
Robolectric或Instrumentation，模拟 Keystore 和 BiometricPrompt 流程。
2.2 功能模块 2：密码存储与管理
需求描述
用户可添加、编辑、删除子密码，每条记录包含：网站/应用名、用户名、密码（加密存储）、创建时间、更新时间、分类、标签、备注。
在列表、搜索、筛选时，数据库仅返回非敏感字段（如名称、用户名、分类、标签、ID、更新时间等），点击查看详情才对加密字段解密显示。
密码存储后需生成一个随机 IV，用于 AES-GCM 加密；IV 应与密文一并存储。
密码搜索功能需实现“按名称”、“按分类”、“按标签”模糊查询，且不暴露明文密码。
Room 数据模型设计
@Entity(tableName = "password_entries") data class PasswordEntity( @PrimaryKey(autoGenerate = true) val id: Long = 0, val title: String, // 网站/应用名称 val username: String, val encryptedPassword: ByteArray, // 密码 AES-GCM 加密后内容 val iv: ByteArray, // AES-GCM 随机 IV val categoryId: Long?, // 外键，分类表的 ID val createdAt: Long, // 时间戳 val updatedAt: Long, // 时间戳 val notes: String? // 备注 ) @Entity(tableName = "categories") data class CategoryEntity( @PrimaryKey(autoGenerate = true) val id: Long = 0, val name: String ) @Entity(tableName = "tags") data class TagEntity( @PrimaryKey(autoGenerate = true) val id: Long = 0, val name: String ) @Entity( tableName = "password_tag_join", primaryKeys = ["passwordId", "tagId"], foreignKeys = [ ForeignKey(entity = PasswordEntity::class, parentColumns = ["id"], childColumns = ["passwordId"], onDelete = CASCADE), ForeignKey(entity = TagEntity::class, parentColumns = ["id"], childColumns = ["tagId"], onDelete = CASCADE) ] ) data class PasswordTagJoin( val passwordId: Long, val tagId: Long )DAO 接口设计
@Dao interface PasswordDao { @Query("SELECT id, title, username, categoryId, createdAt, updatedAt FROM password_entries ORDER BY updatedAt DESC") fun getAllPasswordsSummary(): Flow<List<PasswordSummary>> // 不包含加密字段 @Query("SELECT * FROM password_entries WHERE id = :id") suspend fun getPasswordById(id: Long): PasswordEntity? @Insert(onConflict = OnConflictStrategy.REPLACE) suspend fun insertPassword(password: PasswordEntity): Long @Update suspend fun updatePassword(password: PasswordEntity) @Delete suspend fun deletePassword(password: PasswordEntity) @Query(""" SELECT p.id, p.title, p.username, p.categoryId, p.createdAt, p.updatedAt FROM password_entries p WHERE p.title LIKE '%' || :query || '%' OR p.username LIKE '%' || :query || '%' ORDER BY p.updatedAt DESC """) fun searchPasswords(query: String): Flow<List<PasswordSummary>> @Query("SELECT * FROM categories") fun getAllCategories(): Flow<List<CategoryEntity>> @Query("SELECT * FROM tags") fun getAllTags(): Flow<List<TagEntity>> @Transaction @Query(""" SELECT p.id, p.title, p.username, p.categoryId, p.createdAt, p.updatedAt FROM password_entries p INNER JOIN password_tag_join ptj ON p.id = ptj.passwordId WHERE ptj.tagId = :tagId ORDER BY p.updatedAt DESC """) fun getPasswordsByTag(tagId: Long): Flow<List<PasswordSummary>> }Repository & UseCase 设计
interface PasswordRepository { fun observeAllPasswords(): Flow<List<PasswordSummary>> suspend fun getPasswordDetails(id: Long): Result<DecryptedPassword> suspend fun addOrUpdatePassword(rawPasswordData: RawPasswordData): Result<Long> suspend fun deletePassword(id: Long): Result<Unit> fun searchPasswords(query: String): Flow<List<PasswordSummary>> fun filterByCategory(categoryId: Long): Flow<List<PasswordSummary>> fun filterByTag(tagId: Long): Flow<List<PasswordSummary>> } class PasswordUseCase @Inject constructor( private val passwordRepository: PasswordRepository, private val encryptionHelper: EncryptionHelper ) { suspend fun createPassword(request: RawPasswordData): Result<Long> { /* ... */ } suspend fun updatePassword(request: RawPasswordData): Result<Unit> { /* ... */ } suspend fun deletePassword(id: Long): Result<Unit> { /* ... */ } suspend fun getDecryptedPassword(id: Long): Result<DecryptedPassword> { /* ... */ } fun getAllSummaries(): Flow<List<PasswordSummary>> = passwordRepository.observeAllPasswords() // ... 其他方法：搜索、筛选 }加密辅助类（EncryptionHelper）
class EncryptionHelper @Inject constructor( @Named("masterKeyAlias") private val masterKeyAlias: String ) { // 调用 Keystore 获取 AES-GCM 密钥 private fun getSecretKey(): SecretKey { /* … */ } fun encryptData(plainText: String): Pair<ByteArray /*cipherText*/, ByteArray /*iv*/> { val cipher = Cipher.getInstance("AES/GCM/NoPadding") cipher.init(Cipher.ENCRYPT_MODE, getSecretKey()) val iv = cipher.iv val cipherText = cipher.doFinal(plainText.toByteArray(Charsets.UTF_8)) return Pair(cipherText, iv) } fun decryptData(cipherText: ByteArray, iv: ByteArray): String { val cipher = Cipher.getInstance("AES/GCM/NoPadding") val spec = GCMParameterSpec(128, iv) cipher.init(Cipher.DECRYPT_MODE, getSecretKey(), spec) val plainBytes = cipher.doFinal(cipherText) return String(plainBytes, Charsets.UTF_8) } }单元测试 & 集成测试
单元测试：使用
JUnit和Mockito（或mockk）模拟EncryptionHelper流程，测试加解密正确性；测试PasswordUseCase中的业务逻辑（添加、删除、解密等）。Instrumented Test：在 Android Emulator 上运行，验证 Room 数据库 CRUD 流程、加密后查找与解密都能正常工作。
2.3 功能模块 3：应用自动锁定机制 & 生物识别认证支持
需求描述
当 App 进入后台超过 30 秒（可在“设置”中自定义锁定时长），或设备重启、应用被终止后，需要重新验证主密码或使用生物识别解锁。
用户可以在“设置”中切换是否启用生物识别（指纹/面部识别）。
若生物识别不可用或解锁失败，回退为主密码输入页面。
实现要点
使用
ProcessLifecycleOwner.get().lifecycle监听页面前后台状态，触发锁屏逻辑。App 全局管理一个单例
SessionManager，保存“是否已解锁”状态；当检测到“从后台恢复”且超时，应将SessionManager标记为“未解锁”，并跳转到UnlockActivity。生物识别使用
BiometricPrompt：在
UnlockActivity中构建BiometricPrompt，如果用户启用了生物识别，就先尝试authenticate()。成功后，通过 Keystore 解锁主密钥，设置
SessionManager.isUnlocked = true，跳转到主界面。失败后弹窗提示，并提供“输入主密码”选项。
数据模型与设置
Settings:data class UserSettings( val autoLockTimeoutSeconds: Long = 30, val biometricEnabled: Boolean = false )将
UserSettings存储到DataStore（或 EncryptedSharedPreferences，仅生物识别开关与超时时长可明文存储）。
测试要点
模拟 App 切后台再回前台，断言是否跳转到解锁页面。
在 Emulator 上模拟可用 / 不可用生物识别，验证逻辑正确分支。
2.4 功能模块 4：密码生成器
需求描述
用户可以自定义以下参数生成随机密码：长度（默认为 16 位，可设置 8～64），是否包含大小写字母、数字、特殊符号。
生成后可以一键复制到剪贴板，或保存为新密码条目。
生成功能需保证随机性、安全性，应使用
SecureRandom。
实现要点
PasswordGenerator工具类：object PasswordGenerator { fun generate( length: Int, useUpperCase: Boolean = true, useLowerCase: Boolean = true, useDigits: Boolean = true, useSymbols: Boolean = true ): String { /* … 使用 SecureRandom 生成 */ } }在 UI 层提供复选框 / 切换开关（Compose 或 XML）让用户选择参数；点击“生成”后，通过
PasswordGenerator.generate()获取密码字符串。将生成的密码以明文形式展示在 UI（只暂存，不保存到数据库），用户可选择“保存”。若用户点击“保存”，进入“添加密码页面”，并预填“密码”字段。
测试要点
单元测试
PasswordGenerator.generate()：不同参数组合下确保输出符合要求（长度、字符范围、字符集随机性可做简单统计测试）。UI 测试：检查切换开关后“生成”按钮生成预期类型的密码。
2.5 功能模块 5：设置管理系统
需求描述
在“设置页面”中，用户可以：
修改主密码
启用/禁用生物识别
配置应用自动锁定时长
设定默认密码生成长度与字符规则
导出/导入（加密）备份数据
若用户修改主密码，需要：
验证旧密码正确性；
重新生成新的 PBKDF2 哈希和对应的 Keystore 密钥；
遍历所有
PasswordEntity，使用旧密钥解密后，用新密钥重新加密并更新数据库。
数据模型与 UseCase
SettingsUseCase接口：interface SettingsUseCase { suspend fun updateMasterPassword(oldPassword: String, newPassword: String): Result<Unit> suspend fun setBiometricEnabled(enabled: Boolean): Result<Unit> suspend fun setAutoLockTimeout(seconds: Long): Result<Unit> suspend fun getUserSettings(): Flow<UserSettings> suspend fun exportEncryptedBackup(): Result<Uri> // 备份文件 URI suspend fun importEncryptedBackup(uri: Uri, password: String): Result<Unit> }导出/导入备份：
导出时：将
PasswordEntity全量读取、解密，再使用用户输入的“备份密码”重新加密成单个 JSON 文件，写入外部存储（沙盒）并提供下载 URI。导入时：用户提供“备份文件”URI 与 “备份密码”，先解密 JSON，然后批量插入到 Room（冲突时可询问用户是覆盖还是跳过）。
测试要点
单元测试旧主密码到新主密码的迁移逻辑，确保所有密码条目在切换后依然能正确解密。
集成测试导出 / 导入流程（使用 Instrumentation Test 模拟文件读写）。
2.6 功能模块 6：安全勋章激励系统
需求描述
App 通过“安全勋章”激励用户保持良好密码习惯。至少包含下列勋章：
密码强度勋章：当用户生成或保存密码时，若强度评分 ≥ 80 分（评分算法见 2.6.2），解锁勋章。
安全习惯勋章：当用户连续开启“自动锁定”功能 7 天，解锁勋章。
完整性勋章：当用户填写“备注”、“标签”、“分类”并完善至少 10 条密码条目，解锁勋章。
连续使用勋章：当用户连续使用 App N 天（例如 30 天）且每日至少登录一次，解锁勋章。
成就勋章（密码数量）：当用户保存密码条目数达到 50 条，解锁勋章。
勋章需要以下功能：
基础勋章数据模型与数据库表设计。
记录用户解锁进度，如“存储上一次检查时间”“累计天数”“当前密码数量”“连续登录天数”等元数据。
在登录或主要业务流程（添加/更新密码、App 启动）时主动校验勋章解锁条件。
提供“勋章展示界面”，显示用户已解锁和未解锁勋章（未解锁状态下为灰色、需达成目标后自动点亮）。
数据模型设计
@Entity(tableName = "badges") data class BadgeEntity( @PrimaryKey val badgeId: String, // 如 "PASSWORD_STRENGTH", "SAFE_HABIT" 等 val title: String, // 勋章名称 val description: String, // 描述 val iconRes: String, // 图标资源名或 URI val isUnlocked: Boolean = false, // 是否已解锁 val unlockedAt: Long? = null // 解锁时间戳 ) @Entity(tableName = "badge_progress") data class BadgeProgressEntity( @PrimaryKey(autoGenerate = true) val id: Long = 0, val badgeId: String, // 外键，指向 BadgeEntity.badgeId val progressValue: Int, // 当前进度数值（如天数、密码数、强度分数） val lastCheckedAt: Long // 最后一次校验时间 )UseCase 与 Repository 设计
interface BadgeRepository { fun observeAllBadges(): Flow<List<BadgeEntity>> suspend fun getBadgeById(badgeId: String): BadgeEntity? suspend fun updateBadgeProgress(badgeId: String, newValue: Int): Result<Unit> suspend fun unlockBadge(badgeId: String): Result<Unit> } class BadgeUseCase @Inject constructor( private val badgeRepository: BadgeRepository, private val passwordRepository: PasswordRepository, private val settingsRepository: SettingsRepository ) { suspend fun checkAllBadges(): Result<Unit> { // 依次调用各勋章解锁逻辑 checkPasswordStrengthBadges() checkSafeHabitBadge() checkCompletenessBadge() checkConsecutiveUseBadge() checkPasswordCountBadge() return Result.success(Unit) } private suspend fun checkPasswordStrengthBadges() { // 从 passwordRepository 取回所有密码条目，解密并计算强度，若满足则 badgeRepository.unlockBadge("PASSWORD_STRENGTH") } private suspend fun checkSafeHabitBadge() { // 查看 settingsRepository.getUserSettings()，及 DataStore 中“连续开启天数”记录，若 ≥7，则 unlock } private suspend fun checkCompletenessBadge() { // 统计已填写分类/标签/备注且 count ≥10，触发 unlock } private suspend fun checkConsecutiveUseBadge() { // 使用 SharedPreferences 或 DataStore 记录“每日首次登录时间”，如果连续天数 ≥ 30，则 unlock } private suspend fun checkPasswordCountBadge() { // 从 passwordRepository 获取密码总数 ≥50，则 unlock } }勋章展示 UI 设计
Activity/Fragment：
BadgeListActivity/BadgeListFragment使用
LazyColumn（Compose）或RecyclerView列表展示所有勋章：每个勋章卡片包含：图标（灰色/彩色）、标题、描述、解锁时间（如已解锁显示“已解锁于 2025-06-xx”）或“未解锁”。
点击已解锁勋章可查看详细说明；点击未解锁勋章可弹出“如何获得”的提示。
测试要点
模拟各种情景：生成强度高 / 低密码、连续使用天数增加、分类数量增多等，断言对应勋章是否正确解锁；
UI 测试：Badge 页面灰色 / 彩色状态是否对应数据库状态；
2.7 功能模块 7：用户界面
导航与整体布局
启动流程：
欢迎/引导页面（只在第一次启动显示，可跳过）。
若未设置主密码，跳转“设置主密码页面”；否则，跳转“解锁页面”。
主导航：使用 Bottom Navigation（或侧边栏 Drawer）：
仪表盘（Dashboard）
密码列表（Passwords）
密码生成器（Generator）
勋章（Badges）
设置（Settings）
页面清单及要点
欢迎/引导页面
简短 App 功能介绍（密码管理、安全激励等），底部“开始使用”按钮。
设置主密码页面
两次密码输入框（密码强度实时反馈）；“确认”按钮后调用
MasterPasswordUseCase.setMasterPassword()。
解锁页面
如果启用生物识别，优先弹出 BiometricPrompt；若失败或未启用，退回到“输入主密码”表单；
输入成功后调用
MasterPasswordUseCase.verifyMasterPassword()。
仪表盘主页（Dashboard）
显示统计信息：当前密码总数、健康分数、已解锁勋章数量、最近使用时间；
提供快捷按钮：添加密码、生成密码、查看勋章。
密码列表界面
搜索栏（按名称 / 用户名 / 分类 / 标签）
列表展示：每项显示网站/应用图标（若有）、标题、用户名、更新时间；
点击进入“密码详情页面”；长按可弹出“复制密码”选项。
密码详情页面
解密并展示明文密码，带“复制”按钮；同时显示分类、标签、备注；底部有“编辑”、“删除”按钮。
添加/编辑密码页面
表单字段：标题、用户名、密码（可调用生成器预填密文）、分类下拉选项（可快速新增）、标签多选（可快速新增）、备注。
“保存”按钮：表单验证、调用
PasswordUseCase.createPassword()或updatePassword()。
密码生成器页面
复选框/Switch：包含 大小写 / 数字 / 特殊符号；滑动条选择长度；“生成”按钮；下方展示结果，附“复制”与“保存”按钮。
勋章页面
如上“功能模块 6”所述。
分类和标签管理页面
两个 Tab 或 Segment：分类 / 标签；各自展示列表与“+”按钮新增；点击列表项进入“重命名/删除”对话框。
设置页面
用户设定：
修改主密码（弹出新/旧密码表单）
生物识别开关
自动锁定时长下拉或滑动条
密码生成器默认参数（长度、字符规则）
备份与恢复（导出/导入）
关于页面（版本号、隐私协议、开源库声明等）
UI 样式 & 资源
统一 Material Design 3 主题：定义主色、次色、状态栏/导航栏颜色；全局 Typography（H1、Body、Button 等）。
Icons：使用
Material Icons或自定义 iconpack（例如锁、钥匙、徽章）。String 资源：多语言支持（至少中文/英文），放在
res/values/strings.xml/strings-en.xml。布局规范：
Compose：每个页面封装为单独的
@Composable，使用Scaffold搭建布局。XML（若不使用 Compose）：使用 ConstraintLayout / LinearLayout 布局文件，注意适配暗黑模式。
导航架构
使用 AndroidX Navigation 组件：
定义
nav_graph.xml或 Compose Navigation Graph，明确每个页面的 route 名称与传参。在 Activity/Fragment 中使用
NavHost与NavController实现页面切换。
所有页面共享一个 “AppBar” 与 “BottomNavigation” 或 Drawer 布局。
测试要点
布局测试：使用
ComposeTestRule或LayoutInspection检测主要页面是否按照设计展示；Navigation 测试：模拟用户点击导航项，验证跳转目标是否正确。
无障碍测试：为按钮、图标、输入框添加 ContentDescription，执行基本无障碍扫描。
2.8 功能模块 8：高级分类和标签系统
需求描述
分类与标签独立管理，用户可自定义添加/编辑/删除分类与标签；分类是一对多，一个密码只对应一个分类，而标签是多对多，一个密码可有多个标签。
在“密码列表”与“搜索”时，支持按分类筛选、按标签筛选；可组合筛选（例如“分类 = 金融，标签包含：重要、安全”）。
数据模型回顾
已在 “功能模块 2” 中设计了
CategoryEntity、TagEntity、PasswordTagJoin。
UseCase & Repository
interface CategoryRepository { fun observeAllCategories(): Flow<List<CategoryEntity>> suspend fun createCategory(name: String): Result<Long> suspend fun updateCategory(category: CategoryEntity): Result<Unit> suspend fun deleteCategory(category: CategoryEntity): Result<Unit> } interface TagRepository { fun observeAllTags(): Flow<List<TagEntity>> suspend fun createTag(name: String): Result<Long> suspend fun updateTag(tag: TagEntity): Result<Unit> suspend fun deleteTag(tag: TagEntity): Result<Unit> } class FilterUseCase @Inject constructor( private val passwordRepository: PasswordRepository, private val categoryRepository: CategoryRepository, private val tagRepository: TagRepository ) { fun filterByCategory(categoryId: Long): Flow<List<PasswordSummary>> = passwordRepository.filterByCategory(categoryId) fun filterByTag(tagId: Long): Flow<List<PasswordSummary>> = passwordRepository.filterByTag(tagId) fun combinedFilter(categoryId: Long?, tagIds: List<Long>?): Flow<List<PasswordSummary>> { /* … 实现组合筛选逻辑 */ } }UI 设计
分类管理页面：列表 + “添加”按钮；新增弹出对话框；编辑/删除时需弹出确认。
标签管理页面：同上；注意多选标签時可能需要复选框列表。
密码列表筛选：在列表顶部添加“分类”下拉菜单与“标签”多选弹窗；选中后实时刷新列表。
组合筛选：用户可同时选一个分类和多个标签，点击“筛选”按钮后调用
FilterUseCase.combinedFilter()。
测试要点
测试增删改分类/标签功能；验证 Room 中数据一致性；
测试组合筛选结果是否正确（可用内存数据库模拟多条数据）。
2.9 功能模块 9：密码健康检查系统
需求描述
在用户点击“健康检查”或 App 定时（例如每日）触发时，扫描所有密码条目并执行以下检查：
检测重复密码：不同记录的解密后密码相同，则标记并提示用户。
密码强度分析：基于密码长度、字符多样性计算强度分数（0～100 分）。
过期密码提醒：若自上次更新时间超过 90 天（可配置），则标记并通知。
最终计算一个“密码健康得分”（综合平均强度、重复率、过期率），并展示在 UI 中。
UseCase 与服务
class HealthCheckUseCase @Inject constructor( private val passwordRepository: PasswordRepository, private val notificationHelper: NotificationHelper ) { suspend fun runHealthCheck(): Result<HealthReport> { val allPasswords = passwordRepository.getAllPasswordEntities() val decryptedList = allPasswords.map { entity -> val plain = encryptionHelper.decryptData(entity.encryptedPassword, entity.iv) entity.copy(passwordPlain = plain) } val duplicates = checkDuplicates(decryptedList) val strengthMap = calculateStrength(decryptedList) // Map<id, score> val expiredList = checkExpired(decryptedList) val healthScore = computeOverallScore(strengthMap, duplicates, expiredList) // 若有重要提醒，调用 notificationHelper 发送本地通知 return Result.success(HealthReport(strengthMap, duplicates, expiredList, healthScore)) } }算法细节
重复检查：将所有解密后的密码存入 map，根据密码字符串分组，分组 size >1 的视为重复。
强度分析：示例策略：
长度 ≥ 12：基础分 30 分，否则基础分 = 长度 * 2。
若包含大写、小写、数字、特殊符号，每种类型分别加 15 分；
若包含同一字符连续超过 3 次，扣 10 分。
最终范围限制在 0～100。
过期检查：比较当前时间与
updatedAt；若超过 90 天（或用户配置的阈值），分类到expiredList。整体健康得分：可采用加权平均：
healthScore = 0.5 * (平均强度分数 / 100 * 100) + 0.3 * ((总密码数 - 重复数) / 总密码数 * 100) + 0.2 * ((总密码数 - 过期数) / 总密码数 * 100)所有算法参数（如权重、阈值）可在“设置”中提供界面供用户微调。
UI 设计
“密码健康检查”页面显示：
当前健康得分大仪表盘（ProgressBar 或圆环进度条）。
重复密码列表（标题＋用户名＋“复制”按钮）
过期密码列表（标题＋用户名＋“更新”按钮，点击进入编辑页面）
密码强度分布图（可用
Chart库绘制简单条形图显示强度区间分布）。
测试要点
单元测试重复、强度、过期算法的正确性；
Instrumented Test：在 Room 中插入样本数据，运行健康检查 UseCase，断言报告数据正确；
UI 测试：检查页面能正确显示图表与列表。
阶段三：代码实现与最佳实践
代码风格与规范
Kotlin 编码规范：遵循 Google Kotlin Style Guide；变量、函数、类命名使用驼峰法（例如
encryptData()、PasswordRepositoryImpl）。SOLID 原则：
单一职责（SRP）：每个类/UseCase 对应单一功能。
开放-关闭（OCP）：依赖接口编程，便于后续扩展。
里氏替换（LSP）：子类可替换基类；
接口隔离（ISP）：接口粒度足够小；
依赖倒置（DIP）：High-Level Module 不要依赖低级细节，依赖抽象。
注释与文档：
关键逻辑（加解密流程、勋章算法）必须添加详细注释；
所有公共接口需在 KotlinDoc 中说明用途、参数、返回结果。
依赖注入（Hilt）
在
Application类上添加@HiltAndroidApp注解；确定各模块：
DataModule：提供RoomDatabase、Dao、EncryptedSharedPreferences、DataStore等单例。CryptoModule：提供MasterKeyAlias、EncryptionHelper、BiometricPrompt相关实例。RepositoryModule：提供PasswordRepositoryImpl、BadgeRepositoryImpl、CategoryRepositoryImpl、SettingsRepositoryImpl等。UseCaseModule：提供具体的 UseCase 实例（PasswordUseCase、BadgeUseCase、HealthCheckUseCase、SettingsUseCase等）。
协程与异步
所有 I/O（数据库、加解密、文件操作）在
Dispatchers.IO上执行；ViewModel 中暴露
Flow或LiveData给 UI 层；异常捕获使用
try { … } catch(e)封装成Result.failure(e)，上层显示友好错误提示。
测试与 CI/CD
单元测试：
使用
JUnit4+mockk或Mockito测试 UseCase 和 Helper 类；
Instrumented Test：
使用
AndroidX Test、Espresso测试主要 UI 流程（解锁 → 查看密码 → 编辑 → 返回）
CI/CD：
创建
.github/workflows/android-ci.yml，包括：name: Android CI on: push: branches: [ main ] pull_request: branches: [ main ] jobs: build: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: Set up JDK 11 uses: actions/setup-java@v2 with: distribution: 'temurin' java-version: '11' - name: Build with Gradle run: ./gradlew build - name: Run Unit Tests run: ./gradlew test - name: Run Instrumented Tests run: ./gradlew connectedAndroidTest配置 Android Emulator（或使用
gradle managed devices）以运行 Instrumented Test。在 Pull Request 中自动触发 lint、ktlint、detekt 等静态分析工具（可选）。
安全与合规
敏感信息保护
主密码、子密码、备份文件中的所有敏感数据必须加密后存储；无明文日志输出；
禁止将密钥硬编码到源码中；
网络通信（若有云同步）
所有 HTTP 请求必须强制 HTTPS；
使用 Retrofit + OkHttp，通过
Certificate Pinning增加安全性；
代码审查清单
检查所有加密算法是否使用安全配置（AES-GCM、PBKDF2 iterations ≥ 10000、KeySize ≥256）；
确认所有外部输入（文件 URI、Intent 参数）进行合法性校验，防止恶意注入；
检查 BiometricPrompt 权限使用是否正确，避免 UI 卡顿或系统崩溃；
确保数据库迁移脚本合理，运行时不丢失或泄露敏感字段；
隐私合规
在 App 中加入“隐私协议”和“用户协议”链接；明确告知如何处理用户数据（本地存储，无云同步时可说明不上传服务器）。
阶段四：完成与总结
总结本次迭代
在
CHANGELOG.md中记录：各功能模块实现情况（如“✔️ 主密码加密系统已完成”）。
已知问题及待办（如“导入备份功能异常时需更友好提示”）。
性能优化项（如“加密操作改为并发 Coroutine”）。
更新文档
完善
README.md：包含项目简介、功能列表、快速启动指南、构建与运行命令。完善
ARCHITECTURE.md：补充最终实际架构与流程图。提供接口文档（若有云端 API，可在
API_DOCUMENTATION.md中维护）。
部署与发布
创建 APK 签名脚本与配置（在
gradle.properties中配置RELEASE_STORE_FILE、STORE_PASSWORD等敏感信息，使用环境变量方式安全注入）。在 Google Play Console 上配置内部测试版或 Beta 测试。
沟通规范
语言：所有与用户的交流、代码注释、文档说明均使用中文，但类名、方法名、变量名及注释中如需引用官方文档、标准术语或开源库名称，可适当使用英文。
及时反馈：遇到需求不明确、场景复杂或边缘情况，应及时向用户提问，避免盲目开发。
技术精准：所有示例代码、API 用法需与官方文档一致，若不确定请调用
use context7或search_docs工具获取最新资料。代码注释：关键逻辑、加密流程、勋章算法、测试用例等必须添加清晰注释，以便后续维护。
交互反馈：在每个阶段完成后，应调用 MCP
interactive_feedback，让用户对当前输出进行确认或提供新需求。
