面向工程落地的产品设计

M Wallet 实施所需的分页规格。

路由地图与模块边界

这个产品应作为一个身份绑定的账户系统来构建，钱包、支付、IBC、凭证和冷签名模块都围绕当前选中账户组合。

入口 /home 账户切换器、MID 状态、余额、付款请求、官方提醒。

资产 /wallet FCA、USDF、未来 MXCD、外部资产、收款地址、兑换入口。

支付 /pay QR 联系人、付款请求、结构化备注、收据、确认。

公司 /ibc/accounts/{company_id} 公司账户、角色、发票、收据、服务记录。

身份 /mid/credentials 数字 ID、驾照、地址证明、税号、证书。

安全 /wallet/vault NFC Vault Card、受保护资产、签名会话、恢复。

官方 /notifications 已签名广播、续期通知、安全提醒、付款深链接。

服务 /services/invoices/{id} 官方发票、支付轨道选择、收据附加。

控制 /settings/security 可信设备、Passkey、限额、通知偏好、恢复。

共享 /receipts/{id} 支付, swap, IBC, credential proof, and service-payment record.

模块

主对象

共享 resources

必须产出

身份 and accounts

用户、MID 凭证、账户、角色、设备会话。

所有模块读取当前选中账户上下文。

账户授权结果和审计链。

钱包与兑换

余额、资产元数据、报价、订单、交易。

Vault 策略、收据服务、网络状态。

报价响应、交易结果、收据。

支付沟通

已验证联系人、类型化消息、付款请求。

余额服务、交易服务、收据服务。

消息状态、结算状态、收据引用。

IBC 与服务

公司账户、角色分配、发票、申报记录。

凭证证明、服务发票、支付轨道。

已签名服务事件和绑定公司记录的收据。

实施原则

后端工程师应把 M Wallet 视为已认证账户系统。地址、资产、卡片、发票和收据都属于身份绑定的账户上下文。

身份优先

每个敏感操作都引用 user_id、mid_id、account_id、设备会话和风险上下文。

账户是容器

Personal、IBC、Vault、Merchant 和 Agent 账户应共享统一账户模型，并按类型配置权限。

收据就是记录

付款、兑换、发票和凭证分享动作都应产生不可变收据或审计事件。

结构化沟通

支付沟通不是开放聊天，而是存储类型化消息：联系人卡、请求、备注、收据、确认。

政策门控

Swap、IBC 付款、大额提现、凭证分享和 Vault Card 签名必须通过政策检查。

未来轨道必须明确标记

在获得正式批准和储备框架前，MXCD 相关能力必须标记为 future 或 policy-gated。

核心数据模型

这些对象构成后端最小词汇表。前端页面应能基于这些资源组合出所有页面。

用户与 MID 凭证

表示已验证个人及其身份可信状态。

user_id用户主 UUID

mid_iddid:mid 标识符

kyc_levelbasic / resident / business

credential_statusactive / expiring / revoked

residency_statusnone / pending / active

risk_flags政策标记数组

账户

个人钱包、IBC 公司钱包、Vault 账户和未来账户类型的通用账户容器。

account_id账户 UUID

account_typepersonal / ibc / vault / merchant

display_name面向用户的账户名称

primary_addressFC Chain 地址

rolesowner / director / agent / accountant

policy_profile限额和审批规则

资产余额

余额按账户和网络归属。外部资产与 FC Chain 主轨道保持分离。

asset_codeFCA / USDF / MXCD / BTC / ETH

networkfc_chain / bitcoin / ethereum / tron / solana / bnb

available可用金额

locked待处理、Vault 或政策锁定

fiat_valueUSD 展示价值

rail_typenative / payment / future / external

支付沟通

围绕已验证联系人和付款的类型化结构消息。

conversation_id会话 UUID

counterparty_mid已验证联系人 DID

message_typecontact / request / note / receipt / confirmation

amount可选金额

asset_codeUSDF / FCA / future MXCD

statusdraft / pending / paid / settled / declined

IBC 账户

与 MID 所有人或授权角色关联的公司专属钱包与服务记录。

company_idIBC UUID

registry_number官方 company number

company_statusdraft / active / renewal_due / suspended

role_assignments用户与角色

invoice_ids服务 and government invoices

receipt_ids已附加记录

凭证卡片

Apple Wallet 风格凭证，由主管机构签发，并支持选择性披露。

credential_id卡片 UUID

credential_typemid / driver_license / address / tax / ibc_certificate

issuer_id主管机构或注册处

statuspending / verified / expiring / revoked

expires_at续期触发

disclosure_rules可分享范围

Vault Card

用于高价值操作的 NFC 冷钱包卡和签名会话状态。

vault_card_id卡片 UUID

card_statusactive / backup / lost / disabled

card_roleprimary / backup_1 / backup_2

protected_assets覆盖的资产或账户

last_signed_at最近一次 NFC 签名

signing_policy阈值和限额

通知与广播

已签名官方广播、付款通知、IBC 发票通知或安全提醒。

notice_id通知 UUID

channelpayment / official / security / ibc

signature_statusverified / failed / unknown

prioritylow / normal / urgent

target_account_id可选账户范围

action_url深链接路由

分页实施规格

只要遵守账户上下文、角色策略、类型化操作和审计日志，每个页面都可以独立实施。

01. Home · 居民账户首页

主入口页面，展示账户切换器、MID 凭证状态、FC Chain 余额、快捷操作、最新付款请求和基础设施状态。

/home

UI 区块

包含应用身份和通知的头部
Personal / IBC 账户 switcher
MID 凭证摘要
总资产和 FCA/USDF 拆分
发送、请求、兑换、收款、扫描操作
最新已验证付款请求

必需数据

me with MID state
accounts[]
selected_account
balances[]
latest_payment_request
notification_counts

操作

切换账户
打开付款编辑器
打开兑换报价
打开 QR 扫描
查看付款请求
打开官方广播

获取会话GET /v1/me

账户列表GET /v1/accounts

账户摘要GET /v1/accounts/{account_id}/summary

最新收件箱GET /v1/inbox?account_id={id}&limit=3

加载中无 MID 凭证MID 已验证IBC 账户可用付款请求待处理官方提醒未读

02. Wallet · 资产与受控兑换

展示 FC Chain 主轨道、外部网络、USDF/MXCD 政策说明、受控兑换模块和 MID Vault Card 状态。

/wallet

UI 区块

主轨道：FCA、USDF、MXCD Future
合规安全的 USDF/MXCD 说明
兑换组件
外部网络资产
MID Vault Card 模块

必需数据

balances[] by network
asset_metadata[]
swap_supported_pairs[]
vault_status
network_status[]

操作

充值或收款
提现或发送
预览兑换
打开 Vault Card
查看资产详情
复制收款地址

余额GET /v1/accounts/{account_id}/balances

资产元数据GET /v1/assets/metadata

兑换交易对GET /v1/swap/pairs?account_id={id}

Vault 状态GET /v1/vault/cards?account_id={id}

余额为零入账待确认网络降级资产未启用MXCD 仅为未来能力

03. Swap · 已验证资产兑换

控制led exchange flow for FC Chain internal pairs. MVP should start with USDF and FCA. Future MXCD routes remain policy-gated.

/wallet/swap

UI 区块

From 资产选择器
To 资产选择器
报价输出
路径和政策元数据
预览确认
Swap 收据

必需数据

account_limits
eligible_assets[]
quote_id
rate and expires_at
fees[]
policy_result

后端规则

报价必须快速过期
执行时使用 idempotency key
大额 Swap 可能需要 Vault Card
生成 Swap 收据
审计报价和执行

QuotePOST /v1/swap/quotes

ExecutePOST /v1/swap/orders

Order detailGET /v1/swap/orders/{order_id}

ReceiptGET /v1/receipts/{receipt_id}

报价加载中报价已过期余额不足超过限额需要 Vault已结算

04. Pay · QR 联系人与支付沟通

围绕已验证联系人的结构化支付沟通。它不是开放聊天，而是支持交易的消息系统。

/pay

UI 区块

MID QR scanner / contact add
支付 templates
Conversation timeline
Request review
Receipt sharing

消息类型

contact_card
payment_request
payment_note
receipt
confirmation

规则

只有已验证联系人可以请求付款
MVP 不允许任意自由文本
备注必须附加到付款记录
收据链接到结算交易

Scan resolvePOST /v1/contacts/resolve-qr

Add contactPOST /v1/contacts

Conversation listGET /v1/payment-conversations

Create messagePOST /v1/payment-conversations/{id}/messages

未知 QR联系人已验证请求待处理已付款已结算已拒绝

05. IBC · 公司钱包账户

Independent company account space with its own FC Chain 地址, balances, roles, invoices, receipts, and vault policies.

/ibc/accounts/{company_id}

UI 区块

Company identity header
Operating wallet balance
Vault reserve
Role grid
Bills and receipts
Application path

Roles

Owner: full signing
Director: approve bills
Agent: file services
Accountant: read receipts

Rules

IBC operations require role check
Government invoices are signed
Large withdrawals require Vault Card
Receipts attach to company record

List companiesGET /v1/ibc/accounts

Company detailGET /v1/ibc/accounts/{company_id}

InvoicesGET /v1/ibc/accounts/{company_id}/invoices

RolesGET /v1/ibc/accounts/{company_id}/roles

无公司申请草稿公司有效续期到期角色被拒发票待缴

06. 凭证中心 · 数字卡片与证书

Verified cards for personal and business credentials, with status lifecycle and selective disclosure.

/mid/credentials

Card types

MID Digital ID
Driver license
Address proof
Tax number
IBC certificate
Good standing certificate

状态生命周期

待审核
已验证
即将过期
需要续期
已撤销
已归档

操作

View card
Share limited proof
Request renewal
Export proof QR
Attach to IBC service

List cardsGET /v1/credentials

Card detailGET /v1/credentials/{credential_id}

Create proofPOST /v1/credentials/{credential_id}/proofs

续期请求POST /v1/credentials/{credential_id}/renewals

空钱包待审核已验证即将过期已撤销证明已生成

07. MID Vault Card · NFC 冷钱包

Card-based cold signing for large transfers, company reserve withdrawals, and protected long-term holdings.

/wallet/vault

UI 区块

Primary card status
Backup cards
Protected assets
Signing flow
Lost card procedure

Signing session

Review transaction
Biometric confirmation
Tap NFC card
Card signs payload
App broadcasts transaction

Rules

Never expose card secret
Signing payload must be human-readable before tap
Backup card enrollment requires step-up authentication
Lost card disables future signing

CardsGET /v1/vault/cards

Start signingPOST /v1/vault/signing-sessions

提交签名POST /v1/vault/signing-sessions/{id}/signature

Report lostPOST /v1/vault/cards/{card_id}/report-lost

无卡片卡片有效备份就绪需要轻触签名失败卡片丢失

08. 广播与通知

用于政府消息、IBC 续期提醒、付款请求和安全提醒的已签名官方通道。

/notifications

频道

付款
官方广播
安全提醒
IBC 发票
凭证续期

必需数据

signature_status
issuer_id
priority
target_account_id
action_url

Rules

官方通知必须验证签名
签名失败的消息应隔离
安全提醒可能要求用户立即处理
通知应深链接到记录

InboxGET /v1/notifications

Mark readPOST /v1/notifications/{notice_id}/read

Verify issuerGET /v1/issuers/{issuer_id}

PreferencesPATCH /v1/notification-preferences

未读已签名签名失败紧急需要操作已归档

09. 服务缴费 · 发票到收据

官方 service fee payment path for registry renewals, filings, certificates, and future government services.

/services/invoices/{invoice_id}

UI 区块

发票摘要
发行方和签名状态
可用支付轨道
角色审批检查
付款确认
收据记录

必需数据

invoice_id
issuer_signature
amount
accepted_assets[]
service_context
receipt_id

规则

只有已签名发票可付款
IBC 发票需要角色审批
付款结果创建收据
收据附加到服务记录
使用 idempotency key

Invoice detailGET /v1/services/invoices/{invoice_id}

支付发票POST /v1/services/invoices/{invoice_id}/payments

ReceiptGET /v1/receipts/{receipt_id}

ExportGET /v1/receipts/{receipt_id}/export.pdf

发票待缴签名已验证角色被拒付款处理中已结算收据已归档

10. 设置与恢复 · 账户控制中心

Operational security surface for trusted devices, passkeys, transaction limits, notification preferences, recovery contacts, and account export controls.

/settings/security

UI 区块

Profile and selected account context
Trusted devices
Passkeys and biometrics
支付 and swap limits
Recovery and backup cards
通知 preferences

必需数据

device_sessions[]
auth_methods[]
limit_profile
recovery_methods[]
vault_cards[]
notification_preferences

Rules

移除设备需要强化验证
提高限额应触发冷静期
恢复设置变更会产生紧急安全通知
导出操作必须审计

DevicesGET /v1/security/devices

Auth methodsGET /v1/security/auth-methods

LimitsPATCH /v1/accounts/{account_id}/limits

RecoveryPOST /v1/security/recovery-methods

设备可信新登录需要强化验证冷静期恢复待处理可导出

Payload 与事件契约

这些示例刻意保持简洁，用来定义前端集成、幂等性、审计日志和未来合规审查所需的数据形态。

付款请求消息

{
  "message_type": "payment_request",
  "conversation_id": "conv_123",
  "counterparty_mid": "did:mid:resident:789",
  "account_id": "acct_personal_01",
  "amount": "125.00",
  "asset_code": "USDF",
  "note_template": "service_payment",
  "expires_at": "2026-05-01T00:00:00Z"
}

兑换报价请求

{
  "account_id": "acct_personal_01",
  "from_asset": "USDF",
  "to_asset": "FCA",
  "amount": "250.00",
  "idempotency_key": "uuid-client-generated",
  "policy_context": {
    "purpose": "wallet_rebalance"
  }
}

凭证证明请求

{
  "credential_id": "cred_driver_license_01",
  "scope": ["name", "credential_status", "expiry"],
  "recipient_type": "service",
  "recipient_id": "registry_service",
  "expires_in_seconds": 900,
  "user_consent": true
}

Vault 签名会话

{
  "account_id": "acct_ibc_01",
  "operation_type": "large_transfer",
  "human_readable_payload": "Send 4,500 USDF to FC...9A2",
  "required_card_role": "primary",
  "expires_at": "2026-04-26T12:30:00Z"
}

已签名官方广播

{
  "notice_id": "notice_2026_001",
  "channel": "official",
  "issuer_id": "dro_registry",
  "signature_status": "verified",
  "priority": "urgent",
  "action_url": "/services/invoices/inv_001"
}

收据对象

{
  "receipt_id": "rcpt_001",
  "source_type": "service_payment",
  "account_id": "acct_ibc_01",
  "transaction_hash": "0x...",
  "asset_code": "USDF",
  "amount": "350.00",
  "status": "settled",
  "audit_event_id": "audit_001"
}

权限与安全策略

安全 is account-specific. The backend should calculate required assurance before every sensitive operation and return the next required step.

操作

最低认证要求

后端结果

查看余额

已认证设备会话

返回允许账户范围内的余额。

发送小额付款

MID active + Passkey 或生物识别

创建交易、收据和审计事件。

兑换 USDF/FCA

MID active + 账户限额 + 报价策略

返回报价或所需强化验证挑战。

IBC 发票付款

有效公司角色 + 已签名发票 + 付款策略

创建付款并把收据附加到公司记录。

大额转账

生物识别 + MID Vault Card 签名

启动签名会话并等待 NFC 签名。

分享凭证证明

凭证已验证 + 用户同意

生成带有效期和审计事件的有限证明 token。

后端开发清单

这是进入实施计划前可以交给工程团队的实用清单。

基础底座

用户、MID 凭证、账户、角色和设备会话表
账户范围 API 授权中间件
所有敏感操作的审计事件表

账本与资产

按账户和网络查询余额服务
资产元数据 and network status service
待处理交易和收据生成

支付沟通

从 MID QR 解析已验证联系人
只允许类型化消息模型
付款请求到交易的关联

IBC 账户

公司账户模型
角色分配和审批规则
发票、收据、导出和服务记录附加

凭证中心

凭证卡片 lifecycle
发行方和签名验证
选择性披露证明接口

Vault Card

NFC 卡登记
签名会话生命周期
丢卡与备份卡流程

Swap

带有效期的报价服务
带幂等性的执行接口
限额、风险和未来 MXCD 政策门控

通知

已签名官方广播 verification
带频道的收件箱服务
跳转到付款、IBC、凭证和安全记录的深链接

Phase 1 · 核心账户MID 凭证、账户切换、余额、收款地址、基础收据。

Phase 2 · 支付 layerQR 联系人、类型化付款请求、付款备注、收据、确认。

Phase 3 · IBC 服务公司账户、角色策略、已签名发票、服务缴费、记录。

Phase 4 · 高级安全控制led swap, Vault Card signing, external rails, future MXCD policy gates.

MVP recommendation: build 身份 + account switcher + balances + payment conversation + IBC invoices + receipts first. Add controlled swap and Vault Card signing as gated modules after the core account and audit model is stable.