# BindVault 功能 README

> BindVault：个人数字身份与绑定关系管理系统。  
> 用于管理手机号、邮箱、邮箱别名、第三方账号、域名、支付方式、订阅、恢复方式、风控事件，以及它们之间的绑定关系。

## MVP 运行方式

当前 MVP 使用 SQLite 存储数据，由 `server.py` 同时提供静态页面和 API。

```bash
python3 server.py
```

然后访问：

```text
http://localhost:8080
```

数据库默认写入：

```text
data/bindvault.sqlite3
```

Docker Compose 运行：

```bash
docker compose up --build
```

## 1. 项目目标

BindVault 不是一个普通密码本，而是一个“个人数字资产台账”。

它要解决的问题是：

- 我有哪些手机号、邮箱、域名、Apple ID、Google 账号、Claude/OpenAI 账号？
- 某个手机号绑定了哪些平台？
- 某个邮箱是否还能收验证码？
- 某个 Apple ID / Google 账号使用了哪个邮箱、哪个手机号、哪个恢复方式？
- 哪些账号被锁定、冻结、申诉中？
- 哪些账号存在同手机号、多账号关联风险？
- 哪些域名、订阅、礼品卡、支付方式快到期？
- 账号出问题时，应该从哪里恢复？

核心价值：

```text
资产清单化
绑定关系可追踪
风险状态可管理
恢复路径可查询
敏感凭据不明文存储
```

---

## 2. 设计原则

### 2.1 不做明文密码库

BindVault 不直接存储明文密码、2FA Secret、恢复码、银行卡完整信息。

这些敏感数据应该放在：

```text
Vaultwarden
Bitwarden
KeePassXC
1Password
其他密码管理器
```

BindVault 只保存引用位置，例如：

```text
Vaultwarden 条目名：Apple/apple01
KeePassXC 路径：Digital Assets/Apple/apple01
```

### 2.2 以“绑定关系”为核心

系统的核心不是账号本身，而是：

```text
手机号 / 邮箱 / 域名 / 支付方式 / 设备
        ↓
绑定了哪些平台账号
        ↓
这些绑定在登录、验证、恢复、风控中分别扮演什么角色
```

### 2.3 先做个人单用户版本

MVP 阶段只需要支持个人使用，不需要复杂组织、多租户、审批流。

后续可扩展：

```text
多用户
团队共享
资产分组
权限控制
审计日志
加密字段
```

---

## 3. 核心功能模块

## 3.1 仪表盘 Dashboard

首页展示个人数字资产概览。

### 需要展示

- 手机号数量
- 邮箱数量
- 账号数量
- 域名数量
- 订阅数量
- 风险事件数量
- 已锁定账号数量
- 申诉中账号数量
- 即将到期资产数量
- 高风险绑定数量

### 推荐卡片

```text
总资产数
正常账号
异常账号
高风险绑定
即将到期域名
即将到期订阅
待处理事件
```

### 推荐图表

- 平台账号分布：Apple / Google / OpenAI / Claude / Telegram / GitHub
- 账号状态分布：正常 / 待验证 / 已锁定 / 已冻结 / 申诉中 / 已注销
- 手机号绑定数量排行
- 邮箱绑定数量排行
- 最近风险事件时间线

---

## 3.2 手机号管理 Phone Numbers

用于维护所有个人手机号、虚拟号、海外号、备用号。

### 字段设计

| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 唯一 ID |
| phone_number | string | 手机号，建议 E.164 格式，如 +86131xxxx0000 |
| country_region | string | 国家/地区，如 CN、US、TR |
| carrier | string | 运营商，如 中国移动、联通、T-Mobile |
| owner | string | 实名人，如 本人、家人、公司 |
| sim_type | enum | physical / esim / virtual |
| status | enum | available / inactive / cannot_receive_sms / released / high_risk |
| purpose | string | 用途说明 |
| is_primary | boolean | 是否主力号码 |
| can_receive_sms | boolean | 是否可收短信 |
| can_receive_call | boolean | 是否可接电话 |
| last_verified_at | datetime | 最近验证时间 |
| expires_at | datetime | 到期时间，可选 |
| notes | text | 备注 |

### 状态枚举

```text
available              可用
inactive               停用
cannot_receive_sms     不可收短信
released               已释放
high_risk              高风险
unknown                未知
```

### 功能要求

- 新增手机号
- 编辑手机号
- 删除手机号
- 查看手机号绑定了哪些账号
- 标记手机号是否还能收验证码
- 标记手机号风险等级
- 查询“绑定数量最多”的手机号
- 查询“已不可收码但仍绑定账号”的手机号

---

## 3.3 邮箱管理 Emails

用于维护 Gmail、Outlook、QQ 邮箱、自定义域名邮箱、Cloudflare Email Routing 别名。

### 字段设计

| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 唯一 ID |
| email | string | 邮箱地址 |
| email_type | enum | gmail / outlook / qq / custom_domain / cloudflare_routing / alias |
| provider | string | Gmail、Cloudflare、腾讯企业邮等 |
| domain | string | 所属域名，如 yunzhihui.ltd |
| forward_to | string | 转发目标邮箱 |
| status | enum | available / cannot_receive / inactive / high_risk |
| can_receive_email | boolean | 是否可收信 |
| can_send_email | boolean | 是否可发信 |
| purpose | string | 用途 |
| is_primary | boolean | 是否主邮箱 |
| last_verified_at | datetime | 最近验证时间 |
| notes | text | 备注 |

### 功能要求

- 新增邮箱
- 编辑邮箱
- 删除邮箱
- 查看邮箱绑定了哪些账号
- 标记是否能收信
- 维护转发目标
- 标记 Cloudflare Routing 地址
- 查询“一个邮箱绑定多个敏感账号”的风险

---

## 3.4 域名管理 Domains

用于维护个人域名及其 DNS、邮箱路由、到期信息。

### 字段设计

| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 唯一 ID |
| domain | string | 域名 |
| registrar | string | 注册商 |
| dns_provider | string | DNS 服务商，如 Cloudflare |
| status | enum | active / expired / transferring / high_risk |
| expires_at | datetime | 到期时间 |
| auto_renew | boolean | 是否自动续费 |
| email_routing_enabled | boolean | 是否开启邮件路由 |
| notes | text | 备注 |

### 功能要求

- 新增域名
- 编辑域名
- 记录注册商和 DNS 服务商
- 标记是否开启 Cloudflare Email Routing
- 到期提醒
- 查看该域名下有哪些邮箱别名
- 查看该域名关联哪些账号

---

## 3.5 账号管理 Accounts

用于维护第三方平台账号。

### 字段设计

| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 唯一 ID |
| platform | string | 平台，如 Apple、Google、OpenAI、Claude、GitHub |
| account_identifier | string | 登录账号，如邮箱、手机号、用户名 |
| display_name | string | 展示名 |
| region | string | 注册地区，如 CN、US、TR |
| status | enum | normal / pending_verify / locked / suspended / appealing / recovered / deleted / unusable |
| login_email_id | string | 登录邮箱 ID，关联 emails |
| login_phone_id | string | 登录手机号 ID，关联 phone_numbers |
| recovery_email_id | string | 恢复邮箱 ID |
| recovery_phone_id | string | 恢复手机号 ID |
| two_factor_type | enum | none / sms / email / authenticator / passkey / hardware_key |
| credential_ref | string | 密码管理器条目引用 |
| recovery_ref | string | 恢复码/密保信息引用 |
| registered_at | datetime | 注册时间 |
| last_login_at | datetime | 最近登录时间 |
| last_verified_at | datetime | 最近验证时间 |
| notes | text | 备注 |

### 账号状态枚举

```text
normal           正常
pending_verify   待验证
locked           已锁定
suspended        已冻结
appealing        申诉中
recovered        已恢复
deleted          已注销
unusable         不可用
unknown          未知
```

### 功能要求

- 新增账号
- 编辑账号
- 删除账号
- 按平台筛选
- 按状态筛选
- 查看账号绑定了哪些手机号、邮箱、域名、支付方式
- 标记账号锁定、冻结、申诉中
- 记录账号恢复方式
- 记录密码管理器引用
- 不允许明文保存密码

---

## 3.6 绑定关系管理 Bindings

这是系统最核心的模块。

一个账号可能绑定多个资产：

```text
Apple ID
  - 登录邮箱：apple01@example.com
  - 受信任手机号：+86131xxxx0000
  - 恢复邮箱：backup@gmail.com
  - 支付方式：土耳其礼品卡
```

一个资产也可能绑定多个账号：

```text
+86131xxxx0000
  - Apple ID A：受信任手机号
  - Apple ID B：恢复手机号
  - Google A：2FA 手机号
  - Telegram：登录手机号
```

### 字段设计

| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 唯一 ID |
| asset_type | enum | phone / email / domain / payment / device / subscription |
| asset_id | string | 对应资产 ID |
| account_id | string | 账号 ID |
| platform | string | 冗余字段，方便查询 |
| binding_role | enum | login / recovery / trusted_phone / two_factor / notification / payment / owner |
| status | enum | active / removed / unknown / risky |
| bound_at | datetime | 绑定时间 |
| unbound_at | datetime | 解绑时间 |
| can_unbind | boolean | 是否可解绑 |
| risk_level | enum | low / medium / high |
| notes | text | 备注 |

### 绑定角色枚举

```text
login             登录方式
recovery          恢复方式
trusted_phone     受信任手机号
two_factor        二次验证
notification      通知邮箱/手机号
payment           支付方式
owner             所有者/实名关联
alias             邮箱别名
unknown           未知
```

### 功能要求

- 新增绑定关系
- 编辑绑定关系
- 删除/标记已解绑
- 查看某手机号绑定了哪些账号
- 查看某邮箱绑定了哪些账号
- 查看某账号绑定了哪些资产
- 高风险检测：
  - 一个手机号绑定超过 N 个账号
  - 不可收短信手机号仍作为 2FA
  - 不可收信邮箱仍作为恢复邮箱
  - 已停用域名邮箱仍作为登录邮箱
  - 已锁定账号仍绑定主力手机号
- 支持关系图展示，可选

---

## 3.7 支付方式 Payment Methods

用于维护礼品卡、虚拟卡、银行卡、PayPal、余额等。

### 字段设计

| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 唯一 ID |
| payment_type | enum | gift_card / virtual_card / bank_card / paypal / balance / crypto |
| provider | string | Apple Gift Card、Wise、PayPal 等 |
| region | string | 地区 |
| masked_identifier | string | 脱敏标识，如 **** 1234 |
| currency | string | 币种，如 USD、TRY、CNY |
| balance | decimal | 余额，可选 |
| status | enum | active / inactive / expired / high_risk |
| expires_at | datetime | 到期时间 |
| credential_ref | string | 凭据引用 |
| notes | text | 备注 |

### 功能要求

- 新增支付方式
- 编辑支付方式
- 记录余额
- 记录地区
- 记录绑定账号
- 不保存完整卡号和 CVV
- 支持到期提醒

---

## 3.8 订阅管理 Subscriptions

用于维护机场、云服务、Apple 订阅、域名、SaaS 等。

### 字段设计

| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 唯一 ID |
| service_name | string | 服务名称 |
| account_id | string | 关联账号 |
| plan_name | string | 套餐 |
| price | decimal | 价格 |
| currency | string | 币种 |
| billing_cycle | enum | monthly / quarterly / yearly / lifetime / custom |
| status | enum | active / cancelled / expired / trial |
| started_at | datetime | 开始时间 |
| next_billing_at | datetime | 下次扣费时间 |
| payment_method_id | string | 支付方式 |
| notes | text | 备注 |

### 功能要求

- 新增订阅
- 编辑订阅
- 到期提醒
- 统计月度/年度订阅成本
- 查看订阅关联的账号和支付方式

---

## 3.9 风险事件 Incidents

用于记录账号锁定、风控、申诉、验证码失败等事件。

### 字段设计

| 字段 | 类型 | 说明 |
|---|---|---|
| id | string | 唯一 ID |
| account_id | string | 关联账号 |
| platform | string | 平台 |
| incident_type | enum | locked / suspended / verification_failed / payment_failed / login_failed / appeal / recovered |
| severity | enum | low / medium / high / critical |
| status | enum | open / processing / resolved / abandoned |
| occurred_at | datetime | 发生时间 |
| resolved_at | datetime | 解决时间 |
| description | text | 事件描述 |
| action_taken | text | 已采取动作 |
| next_action | text | 下一步动作 |
| evidence_ref | string | 证据截图/文件引用 |
| notes | text | 备注 |

### 功能要求

- 新增事件
- 编辑事件
- 关闭事件
- 关联账号
- 展示账号事件时间线
- 支持待处理事件列表
- 支持按严重等级筛选

---

## 3.10 标签与分组 Tags / Groups

用于自定义分类。

### 示例标签

```text
主力
备用
外区
中国大陆
土耳其区
美国区
高风险
已申诉
可收码
不可收码
Cloudflare Routing
Apple ID
OpenAI
```

### 功能要求

- 给手机号、邮箱、账号、域名、支付方式、订阅打标签
- 按标签筛选
- 支持自定义标签颜色

---

## 4. 搜索与筛选

全局搜索必须支持：

```text
手机号
邮箱
平台名称
账号登录名
域名
备注
标签
```

常用筛选：

```text
平台 = Apple
状态 = 已锁定
地区 = 土耳其
绑定手机号 = +86xxx
邮箱类型 = Cloudflare Routing
风险等级 = 高
即将到期 = 30 天内
```

---

## 5. 风险检测规则

MVP 阶段先做静态规则检测。

### 规则 1：不可收码手机号仍作为 2FA

条件：

```text
phone.status in [cannot_receive_sms, inactive, released]
AND binding.binding_role in [two_factor, trusted_phone, recovery]
AND binding.status = active
```

风险等级：High

### 规则 2：不可收信邮箱仍作为登录/恢复邮箱

条件：

```text
email.status in [cannot_receive, inactive]
AND binding.binding_role in [login, recovery]
AND binding.status = active
```

风险等级：High

### 规则 3：一个手机号绑定太多账号

条件：

```text
count(active bindings where asset_type = phone and asset_id = current_phone_id) >= threshold
```

默认阈值：5

风险等级：Medium

### 规则 4：已锁定账号仍使用主力手机号

条件：

```text
account.status in [locked, suspended, unusable]
AND phone.is_primary = true
AND binding.status = active
```

风险等级：Medium

### 规则 5：域名快到期但仍承载邮箱别名

条件：

```text
domain.expires_at <= now + 30 days
AND email.domain = domain.domain
AND email.status = available
```

风险等级：High

---

## 6. 数据导入导出

### 6.1 导入

支持 CSV 导入：

```text
phone_numbers.csv
emails.csv
accounts.csv
bindings.csv
domains.csv
subscriptions.csv
```

导入时需要：

- 字段映射
- 重复检查
- 预览导入结果
- 错误行提示

### 6.2 导出

支持导出：

```text
CSV
JSON
SQLite backup
```

导出时默认不包含敏感凭据，只导出台账信息。

---

## 7. 安全要求

### 7.1 禁止明文敏感信息

以下字段不应该明文保存：

```text
密码
2FA Secret
恢复码
完整银行卡号
CVV
身份证号
短信验证码
邮箱验证码
```

### 7.2 敏感引用字段

可以保存引用：

```text
credential_ref
recovery_ref
evidence_ref
```

例如：

```text
Vaultwarden: Apple/apple01
KeePassXC: DigitalAssets/Apple/apple01
LocalFile: encrypted/screenshots/apple-lock-2026-05-24.png
```

### 7.3 本地优先

MVP 建议支持本地部署：

```text
Docker Compose
SQLite / PostgreSQL
本地文件备份
```

### 7.4 备份提醒

系统应提示用户定期备份数据库。

---

## 8. 推荐技术栈

如果项目未指定技术栈，推荐：

### 前端

```text
React
TypeScript
Vite
Tailwind CSS
shadcn/ui
React Router
TanStack Query
```

### 后端

二选一：

```text
Node.js + NestJS / Express + Prisma
```

或：

```text
Go + Gin/Fiber + GORM/sqlc
```

### 数据库

MVP：

```text
SQLite
```

正式自托管：

```text
PostgreSQL
```

### 部署

```text
Docker
Docker Compose
```

---

## 9. 页面设计

### 9.1 页面列表

```text
/dashboard
/phones
/emails
/domains
/accounts
/bindings
/payments
/subscriptions
/incidents
/tags
/settings
```

### 9.2 详情页要求

每类资产都应该有详情页。

例如手机号详情页：

```text
手机号基础信息
状态
是否可收短信
绑定账号列表
风险提示
最近验证时间
备注
事件记录
```

账号详情页：

```text
账号基础信息
登录邮箱
登录手机号
恢复邮箱
恢复手机号
2FA 类型
绑定关系图
风险事件时间线
密码管理器引用
备注
```

---

## 10. API 设计建议

### 10.1 REST API

```text
GET    /api/phones
POST   /api/phones
GET    /api/phones/:id
PUT    /api/phones/:id
DELETE /api/phones/:id

GET    /api/emails
POST   /api/emails
GET    /api/emails/:id
PUT    /api/emails/:id
DELETE /api/emails/:id

GET    /api/accounts
POST   /api/accounts
GET    /api/accounts/:id
PUT    /api/accounts/:id
DELETE /api/accounts/:id

GET    /api/bindings
POST   /api/bindings
PUT    /api/bindings/:id
DELETE /api/bindings/:id

GET    /api/incidents
POST   /api/incidents
PUT    /api/incidents/:id
DELETE /api/incidents/:id

GET    /api/risks
POST   /api/import
GET    /api/export
```

### 10.2 查询参数

```text
GET /api/accounts?platform=Apple&status=locked
GET /api/bindings?asset_type=phone&asset_id=xxx
GET /api/risks?level=high
```

---

## 11. 数据库表建议

```text
phone_numbers
emails
domains
accounts
bindings
payment_methods
subscriptions
incidents
tags
tag_relations
risk_findings
attachments
settings
```

### 通用字段

所有表建议包含：

```text
id
created_at
updated_at
deleted_at
notes
```

---

## 12. MVP 版本范围

第一版只做这些：

```text
1. 手机号管理
2. 邮箱管理
3. 账号管理
4. 绑定关系管理
5. 风险事件管理
6. Dashboard 概览
7. 全局搜索
8. CSV 导入导出
9. Docker Compose 部署
```

暂时不做：

```text
团队权限
复杂审批
浏览器插件
自动登录检测
短信自动读取
邮箱自动扫描
密码自动填充
```

---

## 13. 验收标准

### 13.1 基础验收

- 可以新增手机号
- 可以新增邮箱
- 可以新增账号
- 可以建立手机号/邮箱与账号之间的绑定关系
- 可以在手机号详情页看到它绑定了哪些账号
- 可以在账号详情页看到它绑定了哪些手机号和邮箱
- 可以标记账号为已锁定、申诉中、已恢复
- 可以记录风险事件
- 可以搜索邮箱、手机号、平台账号

### 13.2 风险验收

- 不可收码手机号仍作为 2FA 时，系统能提示高风险
- 不可收信邮箱仍作为恢复邮箱时，系统能提示高风险
- 一个手机号绑定超过阈值时，系统能提示中风险
- 域名 30 天内到期且仍有邮箱别名时，系统能提示高风险

### 13.3 安全验收

- 系统不提供明文密码字段
- 系统不保存短信验证码
- 系统不保存完整银行卡号和 CVV
- 导出数据不包含敏感凭据
- 支持数据库备份

---

## 14. Codex 实现要求

请按以下优先级实现：

```text
P0：数据库模型、CRUD、页面基础结构
P1：绑定关系、详情页、搜索筛选
P2：风险检测、Dashboard、导入导出
P3：标签、附件、关系图、备份提醒
```

代码要求：

- 使用清晰的模块划分
- 前后端类型尽量统一
- 所有枚举集中定义
- 表单字段需要基础校验
- 列表页支持分页、搜索、筛选
- 详情页展示关联数据
- 删除操作需要二次确认
- 所有时间字段使用 ISO 8601
- 手机号建议使用 E.164 格式
- 邮箱字段需要格式校验
- 不要实现明文密码存储

---

## 15. 示例数据

### 手机号

```json
{
  "phone_number": "+86131xxxx0000",
  "country_region": "CN",
  "carrier": "China Mobile",
  "owner": "self",
  "status": "available",
  "can_receive_sms": true,
  "is_primary": true,
  "notes": "主力手机号，不建议绑定过多外区账号"
}
```

### 邮箱

```json
{
  "email": "apple01@yunzhihui.ltd",
  "email_type": "cloudflare_routing",
  "provider": "Cloudflare",
  "domain": "yunzhihui.ltd",
  "forward_to": "example@gmail.com",
  "status": "available",
  "can_receive_email": true,
  "can_send_email": false,
  "notes": "用于 Apple ID 注册，只收信不发信"
}
```

### 账号

```json
{
  "platform": "Apple",
  "account_identifier": "apple01@yunzhihui.ltd",
  "region": "US",
  "status": "normal",
  "two_factor_type": "sms",
  "credential_ref": "Vaultwarden: Apple/apple01",
  "recovery_ref": "Vaultwarden: Apple/apple01-recovery"
}
```

### 绑定关系

```json
{
  "asset_type": "email",
  "binding_role": "login",
  "platform": "Apple",
  "status": "active",
  "risk_level": "low",
  "notes": "Apple ID 登录邮箱"
}
```

---

## 16. README 一句话定位

BindVault 是一个个人数字身份与绑定关系管理系统，用于维护手机号、邮箱、域名、账号、支付方式、订阅和恢复信息之间的关系，帮助用户清晰掌握自己的数字资产、绑定链路和风险状态。