# passwd-app

**Repository Path**: shuishouxinbade/passwd-app

## Basic Information

- **Project Name**: passwd-app
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-10
- **Last Updated**: 2026-06-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Passwd Vault

一款基于 Flutter 的密码管理工具，界面参考 1Password 设计风格，支持暗色/亮色主题，对接自托管后端 API。

## 功能特性

- 🔐 **主密码认证** — 注册 / 登录 / 修改主密码
- 🔑 **账号密码管理** — 新建、查看、编辑、删除，AES 加密存储
- 🔍 **搜索与筛选** — 关键词搜索、按分类/标签筛选、收藏列表
- 🏷️ **分类与标签** — 自定义分类（带颜色标识）和标签
- ⚡ **密码生成器** — 可自定义长度和字符类型
- 📊 **密码强度指示** — 直观显示密码强度等级
- 📋 **一键复制** — 密码、用户名、URL 快速复制
- 🌓 **暗色/亮色主题** — 自动跟随系统设置
- ⚙️ **可配置服务器地址** — 登录前/后均可修改，带连接测试

## 技术栈

| 层 | 技术选型 |
|---|---|
| 框架 | Flutter 3.44 + Dart 3.12 |
| 状态管理 | Provider + ChangeNotifier |
| HTTP 客户端 | Dio（含 Auth / Error 拦截器） |
| 本地存储 | flutter_secure_storage |
| 路由 | go_router（声明式 + 鉴权重定向） |
| UI | Material 3 + 自定义 1Password 风格主题 |
| 序列化 | json_annotation + build_runner |

## 项目结构

```
lib/
├── main.dart                       # 入口 + MultiProvider + GoRouter
├── core/
│   ├── constants.dart              # API 地址、存储 key、分页参数
│   ├── exceptions.dart             # 自定义异常类
│   └── theme.dart                  # 暗色/亮色主题配置
├── models/                         # 数据模型（JSON 序列化）
│   ├── user.dart
│   ├── account.dart
│   ├── category.dart
│   ├── tag.dart
│   └── auth_response.dart
├── services/                       # API 服务层
│   ├── api_client.dart             # Dio 单例 + 拦截器
│   ├── server_config.dart          # 服务器地址持久化 + 连接测试
│   ├── auth_service.dart
│   ├── account_service.dart
│   ├── category_service.dart
│   └── tag_service.dart
├── providers/                      # 状态管理
│   ├── auth_provider.dart
│   ├── account_provider.dart
│   ├── category_provider.dart
│   └── tag_provider.dart
├── screens/                        # 页面
│   ├── login/
│   │   ├── login_screen.dart       # 登录（含服务器状态指示）
│   │   └── register_screen.dart    # 注册（含密码强度）
│   ├── home/
│   │   ├── home_screen.dart        # 底部导航壳
│   │   ├── account_list_screen.dart
│   │   └── favorites_screen.dart
│   ├── account/
│   │   ├── account_detail_screen.dart
│   │   └── account_form_screen.dart  # 新建/编辑 + 密码生成器
│   ├── categories/
│   │   └── categories_screen.dart
│   ├── profile/
│   │   ├── profile_screen.dart       # 个人信息 + 标签管理
│   │   └── change_password_screen.dart
│   └── admin/
│       └── user_management_screen.dart
└── widgets/                        # 可复用组件
    ├── account_card.dart
    ├── category_chip.dart
    ├── tag_chip.dart
    ├── password_field.dart
    ├── strength_indicator.dart
    ├── empty_state.dart
    ├── loading_overlay.dart
    ├── search_bar.dart
    └── server_url_dialog.dart
```

## 截图预览

| 登录页 | 账号列表 | 账号详情 |
|---|---|---|
| 暗色主题，服务器状态指示 | 搜索 + 分类筛选 + FAB | 密码复制 + 强度显示 |

## 快速开始

### 前置要求

- Flutter SDK >= 3.12
- 后端 API 服务（见 [api-docs.md](api-docs.md)）

### 安装

```bash
# 克隆项目
git clone <repo-url> passwd_app
cd passwd_app

# 安装依赖
flutter pub get

# 生成 JSON 序列化代码
dart run build_runner build

# 启动（Windows）
flutter run -d windows

# 启动（Web，热重载更快）
flutter run -d chrome

# 启动（Android）
flutter run
```

### 配置服务器地址

启动后在 **登录页右上角** 点击齿轮图标 ⚙️，输入 API 服务器地址：

```
http://localhost:8000
```

支持点击 **Test Connection** 验证地址是否可用。配置会自动保存，下次启动无需重新设置。


## 更新应用图标

准备一张 **1024×1024** PNG 图片放到 `assets/app_icon.png`，然后运行：

```bash
dart run flutter_launcher_icons
```

会自动生成 **Android**、**Web**、**Windows** 三平台图标。

`pubspec.yaml` 中的配置：

```yaml
flutter_launcher_icons:
  android: true
  windows:
    generate: true
  web:
    generate: true
  image_path: "assets/app_icon.png"
  adaptive_icon_background: "#0F1117"
```

## 设计参数

| 属性 | 值 |
|---|---|
| 风格 | 现代简洁 · 类 1Password |
| 主色 | `#3B82F6`（清爽蓝） |
| 暗色背景 / 卡片 | `#0F1117` / `#1A1D24` |
| 亮色背景 / 卡片 | `#F8FAFC` / `#FFFFFF` |
| 卡片圆角 | 16px |
| 按钮圆角 | 12px |
| 间距 | 宽松（padding 16-20px） |

## APK 编译发布

### 调试版 APK

```bash
flutter build apk --debug
```

产物路径：`build/app/outputs/flutter-apk/app-debug.apk`

### 发布版 APK

```bash
# 默认（split per abi，体积更小）
flutter build apk --release

# 体积更小
flutter build apk --split-per-abi --target-platform android-arm64

# 或打单一通用包
flutter build apk --release --split-per-abi=false
```

产物路径：
- `build/app/outputs/flutter-apk/app-release.apk`（通用包）
- `build/app/outputs/flutter-apk/app-arm64-v8a-release.apk`（arm64）
- `build/app/outputs/flutter-apk/app-armeabi-v7a-release.apk`（armv7）
- `build/app/outputs/flutter-apk/app-x86_64-release.apk`（x86_64）

### 发布前需要

1. **生成签名密钥**（如果首次发布）：
   ```bash
   keytool -genkey -v -keystore release.jks -keyalg RSA -keysize 2048 -validity 10000 -alias release
   ```

2. **配置签名**：在 `android/app/build.gradle` 中配置 `signingConfigs`，或创建 `android/key.properties`。

3. **修改版本号**：在 `pubspec.yaml` 中更新 `version: x.y.z+n`。

4. **确认 API 地址**：打包前在 App 内配置正确的服务器地址，或修改 `lib/core/constants.dart` 中的默认 `baseUrl`。

> 提示：首次 `flutter build apk --release` 如果没有配置签名，会生成未签名的 apk，安装前需额外签名。建议先完成签名配置。

## 环境适配

所有依赖支持 **Windows / macOS / Linux / Android / iOS / Web** 全平台。

- `flutter_secure_storage` 在 Windows 上使用 Credential Manager，Web 上使用内存存储
- Web 下刷新页面 Token 会丢失，需重新登录（适合 UI 调试）

## Roadmap

> 参考 1Password、Bitwarden、KeePass 等主流密码管理器的功能整理。

### 🥇 高优先级

- [ ] **密码自动填充（Autofill）** — Android Autofill Framework 支持，在其他 App 中直接填充密码
- [ ] **密码健康检查** — 检测弱密码、重复密码、已泄露密码（Have I Been Pwned）、长时间未修改的账号
- [ ] **条目分组展示** — 按分类分组展开/收起，替代当前平面列表
- [ ] **TOTP 两步验证码** — 在账号中绑定 TOTP 密钥，离线生成 6 位验证码
- [ ] **附件支持** — 为账号添加文件附件（如密钥文件、证件照片）
- [ ] **身份 / 银行卡 / 笔记条目** — 除账号外，支持身份证、银行卡、安全笔记等条目类型
- [ ] **条目收藏置顶** — 收藏的账号在列表顶部固定展示

### 🥈 体验提升

- [ ] **批量操作** — 批量移动分类、添加标签、删除账号
- [ ] **导出 / 导入** — CSV / JSON 导出，从 Bitwarden / 1Password / Chrome 导入
- [ ] **深色 / 亮色模式手动切换** — 始终深色 / 始终亮色 / 跟随系统
- [ ] **搜索历史 / 最近使用** — 顶部显示最近访问的账号
- [ ] **密码过期提醒** — 设置有效期（30/60/90 天），到期标记
- [ ] **账号图标自动获取** — 根据 URL 自动拉取网站 favicon
- [ ] **密码自动生成配置记忆** — 记住上次生成时使用的长度和字符类型
- [ ] **URL 一键打开** — 点击 URL 自动用浏览器打开
- [ ] **密码字段自定义** — 允许用户添加自定义字段（如 API Key、密钥对）
- [ ] **条目版本历史** — 查看和恢复账号的修改历史
- [ ] **紧急联系人 / 遗产模式** — 指定紧急联系人，长期不登录自动授权访问

### 🥉 锦上添花

- [ ] **Android 桌面 Widget** — 快捷搜索 / 常用账号一键复制
- [ ] **本地网络自动发现** — 自动扫描局域网内的后端服务地址
- [ ] **WebDAV 同步** — 不依赖后端 API，直接通过 WebDAV 同步加密数据
- [ ] **指纹查看密码后自动隐藏** — 查看密码后倒计时自动重新隐藏
- [ ] **剪贴板自动清除** — 复制密码后 N 秒自动清除剪贴板
- [ ] **多语言支持** — 英文 / 日文等
- [ ] **数据统计** — 账号总数、分类分布、密码强度分布图表
- [ ] **条目分享** — 通过加密链接临时分享账号给他人
- [ ] **SSH 密钥管理** — 存储和管理 SSH 私钥
- [ ] **浏览器扩展** — 类似 Bitwarden 浏览器插件，自动填充网页
- [ ] **自托管状态页** — 显示后端服务运行状态、同步时间、数据库大小

## 后端 API

API 文档详见 [api-docs.md](api-docs.md)。后端基于 FastAPI，提供：

- 用户认证（注册 / 登录 / 登出）
- 账号密码 CRUD（AES-256 加密存储）
- 分类与标签管理
- 管理员用户管理

## 许可证

MIT