Projects

项目简介 项目名称：0907 Wallet 系统类型：基于浏览器的 Web3 去中心化钱包 系统定位：轻量化、本地化、自托管的钱包系统 系统代码框架: React + Next.js 核心目标 提供安全可靠的钱包账户生成与管理能力 支持基本的转账、消息签名与资产查看功能 实现完整的本地化存储，全流程不上传私钥 非目标说明（可选） 不构建链下后端服务 不提供中心化账户体系 不托管任何用户资产 1. 代码规范 1.1 代码命名规范 1.1.1 组件命名（React 组件、页面） 规则：大驼峰（PascalCase） 文件命名：同名 .tsx 文件也必须 PascalCase 示例： AccountCard.tsx → 正确 UserProfile.tsx → 正确 account-card.tsx → 错误 1.1.2 接口、类型、枚举命名 规则：大驼峰（PascalCase） 建议：接口可加 I 前缀（团队统一即可），类型可加 T 前缀（可选） 示例： interface UserInfo { ... } interface IUserInfo { ... } // 也可 type NetworkConfig = { ... } type TResponse<T> = { ... } enum ChainId { Ethereum = 1, Sepolia = 11155111 } 1.1.3 常量命名（全局配置、魔法值） 规则：全大写 + 下划线分隔（SCREAMING_SNAKE_CASE） 示例： const API_BASE_URL = "https://api.0907wallet.com"; const DEFAULT_CHAIN_ID = 1; const MAX_RETRY_COUNT = 5; const SUPPORTED_CHAINS = [1, 5, 11155111]; 1.1.4 普通变量、函数、属性命名 规则：小驼峰（camelCase） 布尔值建议：以 is、has、should、can 开头 示例： const walletAddress = "0x1234...abcd"; let isConnected = false; const hasBalance = balance > 0; function connectWallet() { ... } async function fetchUserInfo() { ... } 1.1.5 文件与文件夹命名 类型 命名规则 示例 组件 / 页面 PascalCase AccountCard.tsx、settings/page.tsx 工具函数 kebab-case 或 camelCase storage.ts、format-address.ts hooks 以 use 开头 useWallet.ts、useDebounce.ts 样式 与组件同名 AccountCard.module.css 常量/配置 kebab-case chains.config.ts 1.2 代码注释规范 1.2.1 文件头注释（每个文件必须） /** * @file 文件简要描述（一句话） * @description 更详细说明（可选） * @author 张三（github: zhangsan） * @date 2025-04-05 */ 1.2.2 导出函数 / 组件 / Hook 必须写 JSDoc /** * 初始化 IndexedDB 数据库（支持自动按需建表） * * @returns IndexedDB 实例 * @example const db = await initDB(); */ export async function initDB(): Promise<IDBPDatabase> { ... } /** * 账户卡片组件（带悬停复制动画） * * @param address - 钱包地址（0x...） * @param name - 可选账户别名 */ export default function AccountCard({ address, name }: { address: string; name?: string; }) { ... } 1.2.3 复杂逻辑必须解释「为什么」 // 为什么关闭再升级？ // IndexedDB 只有在 versionchange 事务中才能创建 objectStore， // 当前连接无法创建新表，必须关闭后以新版本重新打开 db.close(); 1.2.4 TODO / FIXME 统一格式 // TODO: [高] 支持多签钱包（@李四，2025-07-01） // FIXME: 快速移入移出会导致多个 setTimeout 残留 1.2.5 禁止的注释（直接打回） // 错误示例（解释「做什么」而不是「为什么」） const a = 1; // 定义变量 a setLoading(true); // 设置 loading 为 true // 错误：过时注释 const MAX_RETRY = 3; // 最大重试次数 5 次（实际是 3） 1.3 其他强制规范（快速记忆版） 项目 要求 类型优先 能用 TypeScript 解决的绝不写注释 props 类型 必须显式声明 interface/type，禁止 any 自定义 Hook 必须以 use 开头，文件名也必须是 useXxx.ts async 函数 必须 try-catch 或返回错误状态 console.log 上线前必须删除或改为 logger 魔法值 全部提取为常量（参考 1.1.3） 2. 系统功能范围（Scope） 2.1 基础功能 用户密码创建与验证 ...

模块概览 👉 模块代码仓库（walletManagement） 项目 内容 模块名称 钱包管理（Wallet Management） 路由路径 /walletManagement 功能范围 随机 HD 钱包生成、助记词展示、钱包加密/解密、加密钱包与地址本地持久化（IndexedDB） 访问权限 依赖本地用户密码记录（userManagement 模块）；若无用户记录则重定向 /userManagement 目录结构与文件职责 app/walletManagement/ ├── components │ ├── GenerateWallet.tsx | ├── ImportWallet.tsx ├── lib │ ├── cryptoWallet.ts │ ├── generateWallet.ts | ├── importWallet.ts │ ├── saveAddress.ts │ └── saveWallet.ts ├── page.tsx └── test-cryptoWallet.ts 文件路径 职责详解 page.tsx 路由入口，渲染 GenerateWallet 组件（页面本身不包含业务逻辑） components/GenerateWallet.tsx 核心 UI 与交互：密码校验 → 生成钱包 → 加密 → 保存 → 助记词展示；包含用户友好提示与错误处理 lib/generateWallet.ts 使用 ethers + bip39 生成随机 HD 钱包、英文与中文助记词并做一致性校验 lib/cryptoWallet.ts 提供钱包加密/解密接口，定义 IEncryptedWallet 类型（负责使用用户密码派生密钥对 wallet 进行 AES-GCM 加密） lib/saveWallet.ts IndexedDB 封装：对 Wallets 表（或 store）进行保存/读取/删除/列出 lib/saveAddress.ts IndexedDB 封装：对 Addresses 表保存地址记录、读取、删除、列出 test-cryptoWallet.ts 单元测试：验证加密/解密、密钥派生一致性、异常场景（解密失败、篡改检测） lib/importWallet.ts 使用 bip39 和 ethers 从英文或中文助记词导入 HDNodeWallet（中文先转换为英文助记词再导入） 1. 详细交互流程 1.1 页面访问与前置检查 用户访问 /walletManagement ...

模块概览 👉 模块代码仓库 项目 内容 模块名称 用户管理（User Management） 路由路径 /userManagement 功能范围 密码设置、已有钱包登录、本地加密存储 访问权限 未登录状态下强制跳转到此页面，已登录放行 目录结构与文件职责 app/userManage/ ├── components/ │ ├── Login.tsx │ └── Register.tsx ├── lib/ │ └── savePassword.ts └── page.tsx 文件路径 职责详解 page.tsx 1. 路由入口 2. 检测 IndexedDB 是否已有钱包记录 3. 已登录 → 跳转 /（首页） 4. 未登录 → 渲染登录/注册切换界面 components/Login.tsx 纯展示组件： • 密码输入解锁本地钱包 • “忘记密码”删除本地数据 components/Register.tsx 1. 设置密码（强度校验） 2. 加密存储 lib/savePassword.ts 核心加密逻辑： • 将密码进行 SHA256 处理 • 存入 IndexedDB 1. 详细交互流程 1.1 页面访问与前置检查 访问任意页面 → AuthGuard 检测未登录 → 重定向至 /userManagement page.tsx 检查 IndexedDB 无 user:current 数据 → 默认展示 Register.tsx 1.2 初始化密码流程 首次登录/忘记密码 检查 IndexedDB 有无 user:current, 若有则删除本地 IndexedDB 数据库用户和钱包相关内容 二次确认密码加密存储至 IndexedDB 2. 安全设计原则 密码永不以明文形式出现在内存、网络、日志中 助记词/私钥只在内存中短时存在，解密后立即覆盖 所有敏感数据均使用用户密码派生的密钥进行 AES-GCM 加密存储 提供“一键删除本地数据”功能（对应“忘记密码”场景）

模块概览 app ├── components │ ├── AuthGuard.tsx │ ├── InitProvider.tsx │ └── Logo.tsx ├── globals.css ├── layout.tsx ├── lib ├── auth.ts ├── storage.ts └── transform.ts 公用库( lib ) auth hash storage 公用组件( components ) AuthGuard Initialer Logo 1. 公用库设计 auth.ts // app/lib/auth.ts /** * @file 钱包认证与账户管理核心模块 * @description 负责钱包连接、签名验证、登录状态持久化、登出等完整认证流程 * 支持 MetaMask、WalletConnect、Coinbase Wallet 等主流钱包 * @author Guangyang Zhong | github: https://github.com/cgcj0907 * @date 2025-08-16 */ export const LOGIN_FLAG_KEY = 'isLoggedIn'; export const LOGIN_EXPIRES_KEY = 'loginExpiresAt'; const DEFAULT_EXPIRE_MINUTES = 10; /**获取过期时间 */ export function getLoginExpiresAt(): number | null {} /**检查登录状态是否合法 */ export function isLoggedInLocal(): boolean {} /** 刷新过期时间（默认 +10 分钟）并确保 flag = '1' */ export function refreshLoginExpiry(minutes = DEFAULT_EXPIRE_MINUTES) {} /** 退出登录（本地清理） */ export function logoutLocal() {} transform.ts // @/app/lib/hash.ts /** * @file 密码哈希与 ArrayBuffer/Base64 互转工具 * @description 提供安全的密码 SHA-256 哈希（返回 Base64）和高性能的二进制 ↔ Base64 转换工具 * @author Guangyang Zhong | github: https://github.com/cgcj0907 * @date 2025-11-27 */ /** * 将 ArrayBuffer 转换为 Base64 字符串 * * 使用 Uint8Array + btoa 的经典写法，比 Buffer.toString('base64') 更兼容浏览器环境 * * @param buffer 要转换的 ArrayBuffer * @returns Base64 编码字符串 * @example * const b64 = arrayBufferToBase64(hashBuffer); */ export function arrayBufferToBase64(buffer: ArrayBuffer): string {} /** * 将 Base64 字符串转换为 Uint8Array * * @param base64 Base64 编码的字符串 * @returns 对应的 Uint8Array * @example * const uint8 = base64ToUint8Array(storedHash); */ export function base64ToUint8Array(base64: string): Uint8Array {} /** * 对明文密码进行安全的 SHA-256 哈希，并返回 Base64 编码结果 * * 使用 Web Crypto API（crypto.subtle），在所有现代浏览器中均为原生实现，安全且高性能。 * * @param password 明文密码 * @returns SHA-256 哈希后的 Base64 字符串（固定 44 字符） * @example * const hashed = await hashPassword('mySecret123'); * // → "iOcJ9qP3b...==" */ export async function hashPassword(password: string): Promise<string> {} storage.ts 👉 关于 IndexedDB 的使用方法请见：IndexedDB 浏览器数据库 ...