improve(web): enhance two-stage key input UX with clear format guidance

[the-dev-z]

Pull Request - Frontend | 前端 PR

💡 提示 Tip: 推荐 PR 标题格式 `type(scope): description`
例如: `improve(web): enhance two-stage key input UX with clear format guidance`

---

📝 Description | 描述

English:

This PR enhances the two-stage private key input UX by adding clear guidance on character requirements:

Problems Solved:

1. Users confused about whether "32 characters" includes "0x" prefix
2. No guidance on supported input formats
3. Users receiving "incomplete key" errors despite having correct number of characters

Solutions:

1. Updated descriptions to explicitly say "hex characters" instead of just "characters"
2. Added help text below input fields showing exact character counts for both formats
3. Clear messaging: "Enter 32 hex chars (without 0x) or 34 chars (with 0x)"

中文：

本 PR 通過添加清晰的字符要求指導來增強兩階段私鑰輸入的用戶體驗：

解決的問題：

1. 用戶困惑「32 位字符」是否包含 "0x" 前綴
2. 沒有支持的輸入格式說明
3. 用戶儘管輸入了正確數量的字符仍收到「私鑰不完整」錯誤

解決方案：

1. 更新描述明確說明「十六進制字符」而不僅是「字符」
2. 在輸入框下方添加幫助文本，顯示兩種格式的確切字符數
3. 清晰的消息：「請輸入 32 位（不含 0x）或 34 位（含 0x 前綴）」

---

🎯 Type of Change | 变更类型

• ✨ New feature | 新功能
• 🎨 Code style update | 代码样式更新
• ♻️ Refactoring | 重构
• 🐛 Bug fix | 修复 Bug
• 💥 Breaking change | 破坏性变更
• ⚡ Performance improvement | 性能优化 (UX improvement)

---

🔗 Related Issues | 相关 Issue

Improves:

• Follow-up to PR fix(web): fix button disabled validation for two-stage key input #937 (button validation fix)
• User confusion: "所以32是不包含0x?" (Does 32 include 0x or not?)
• User question: "用戶會知道包含0x就是前34位？" (Will users know it's 34 chars with 0x?)

User Feedback:

• Users didn't know whether to include "0x" prefix
• Confusion about exact character count needed
• Need for clear, upfront guidance instead of error messages

---

📋 Changes Made | 具体变更

Change 1: Add Help Text (Commit 1)

File: `web/src/i18n/translations.ts`

English translations:

// Before
stage1Description: 'Enter the first {length} characters of your private key'

// After
stage1Description: 'Enter the first {length} hex characters of your private key'
helpText: '💡 Accepts {length} hex characters with or without "0x" prefix'

Chinese translations:

// Before
stage1Description: '请输入私钥的前 {length} 位字符'

// After  
stage1Description: '请输入私钥的前 {length} 位十六进制字符'
helpText: '💡 可包含或省略 "0x" 前綴（{length} 位 hex 字符）'

File: `web/src/components/TwoStageKeyModal.tsx`

Added help text below input fields:

<div className="text-gray-400 text-xs mt-1">
  {t('twoStageKey.helpText', language, {
    length: expectedPart1Length,
  })}
</div>

---

Change 2: Clarify Exact Character Counts (Commit 2)

Updated help text to show exact numbers:

English:

helpText: '💡 Enter {length} hex chars (without 0x) or {totalWithPrefix} chars (with 0x)'
// Displays: "💡 Enter 32 hex chars (without 0x) or 34 chars (with 0x)"

Chinese:

helpText: '💡 請輸入 {length} 位（不含 0x）或 {totalWithPrefix} 位（含 0x 前綴）'
// Displays: "💡 請輸入 32 位（不含 0x）或 34 位（含 0x 前綴）"

Added parameter:

{t('twoStageKey.helpText', language, {
  length: expectedPart1Length,          // 32
  totalWithPrefix: expectedPart1Length + 2,  // 34
})}

---

🎨 UI Impact | 界面影响

Before (修改前)

第一部分 (32 位字符)
┌─────────────────────────────┐
│ [密碼輸入框]                 │
└─────────────────────────────┘
                                ← ❌ No guidance
[下一步]  [取消]

Issues:

• No explanation of what "32 characters" means
• No guidance on "0x" prefix handling
• Users must guess or encounter errors

---

After (修改後)

第一部分 (32 位字符)
┌─────────────────────────────┐
│ [密碼輸入框]                 │
└─────────────────────────────┘
💡 請輸入 32 位（不含 0x）      ← ✅ Clear guidance
   或 34 位（含 0x 前綴）
[下一步]  [取消]

Benefits:

• Clear explanation: 32 hex chars OR 34 total chars
• Upfront guidance prevents errors
• Users know both formats are supported

---

🧪 Testing | 测试

Manual Testing | 手动测试

Test Case 1: User sees help text

• Open two-stage modal
• Expected: Help text visible below input
• Result: ✅ "💡 請輸入 32 位（不含 0x）或 34 位（含 0x 前綴）"

Test Case 2: Input without 0x prefix

• Input: 32 hex characters (no "0x")
• Help text guidance: "32 位（不含 0x）"
• Result: ✅ Accepted

Test Case 3: Input with 0x prefix

• Input: "0x" + 32 hex characters (34 total)
• Help text guidance: "34 位（含 0x 前綴）"
• Result: ✅ Accepted

Test Case 4: Bilingual support

• Switch language EN ↔ ZH
• Expected: Help text updates correctly
• Result: ✅ Both languages show clear guidance

Visual Testing | 视觉测试

Element	Before	After
Description	"32 位字符"	"32 位十六進制字符" ✅
Help Text	❌ None	"💡 32 位（不含 0x）或 34 位" ✅
Clarity	❌ Ambiguous	✅ Crystal clear

---

📊 Impact Analysis | 影响分析

User Experience Improvement

Before:

1. User opens modal: "Enter first 32 characters"
2. User confused: "32 with or without 0x?"
3. User tries: "0x" + 30 hex chars (32 total)
4. Gets error: "Please enter at least 32 characters"
5. User frustrated: "But I have 32 characters!"
6. ❌ Poor UX

After:

1. User opens modal: "Enter first 32 hex characters"
2. Sees help text: "💡 32 位（不含 0x）或 34 位（含 0x 前綴）"
3. User understands: "I need 32 hex chars, so 34 total with 0x"
4. Inputs correctly on first try
5. ✅ Smooth UX

Metrics

Metric	Impact
User Confusion	⬇️ Reduced (clear guidance upfront)
Error Rate	⬇️ Reduced (know format before typing)
Success Rate	⬆️ Increased (first-try success)
Support Tickets	⬇️ Reduced (self-service guidance)

---

📦 Files Changed | 文件变更

web/src/components/TwoStageKeyModal.tsx  | 12 ++++++++++++
web/src/i18n/translations.ts             | 10 ++++++----
2 files changed, 18 insertions(+), 4 deletions(-)

Summary:

• 2 files modified
• 20 lines added, 4 lines modified
• No breaking changes
• Frontend-only changes (no backend impact)

---

✅ Checklist | 检查清单

Code Quality | 代码质量

• Code follows project style | 代码遵循项目风格
• Self-review completed | 已完成代码自查
• Comments added where needed | 已添加必要注释
• Code builds successfully | 代码构建成功
• No TypeScript errors | 无 TypeScript 错误

Testing | 测试

• Manual testing completed | 完成手动测试
• All test scenarios passed | 所有测试场景通过
• Tested both languages (EN/ZH) | 测试双语显示
• Visual verification done | 完成视觉验证

Documentation | 文档

• Detailed commit messages | 详细的提交信息
• Clear PR description | 清晰的 PR 描述
• Screenshots/examples provided | 提供截图/示例

Git

• Commits follow conventional format | 提交遵循 Conventional Commits 格式
• Rebased on latest `dev` branch | 已 rebase 到最新 `dev` 分支
• No merge conflicts | 无合并冲突
• Focused, logical commits | 聚焦、合理的提交

---

💡 Additional Notes | 补充说明

Why This Matters

User Psychology:

• Users prefer upfront guidance over error messages
• Clear expectations reduce anxiety and frustration
• Explicit numbers (32 or 34) better than ambiguous descriptions

Design Principle:

• "Make the right thing easy and the wrong thing hard"
• Help text acts as inline documentation
• Prevents errors instead of handling them

Implementation Details

Incremental Improvement:

• Commit 1: Add basic help text with format explanation
• Commit 2: Refine to show exact character counts (32 vs 34)
• Result: Crystal clear guidance for users

Bilingual Consistency:

• Both EN and ZH versions equally clear
• No translation ambiguity
• Consistent terminology ("hex chars")

Related Work

This PR builds on PR #937:

• PR fix(web): fix button disabled validation for two-stage key input #937: Fixed button validation logic ✅
• This PR: Improves user guidance and clarity ✅
• Together: Complete UX solution for two-stage input

---

By submitting this PR, I confirm | 提交此 PR，我确认：

• I have read the Contributing Guidelines | 已阅读贡献指南
• I agree to the Code of Conduct | 同意行为准则
• My contribution is licensed under AGPL-3.0 | 贡献遵循 AGPL-3.0 许可证

---

🌟 Thank you for reviewing! | 感谢审阅！

This PR completes the UX improvements for two-stage private key input.

[github-actions]

🤖 Advisory Check Results

These are advisory checks to help improve code quality. They won't block your PR from being merged.

📋 PR Information

Title Format: ⚠️ Suggestion - Consider using type(scope): description

Recommended format

Valid types: feat, fix, docs, style, refactor, perf, test, chore, ci, security, build

Examples:

• feat(trader): add new trading strategy
• fix(api): resolve authentication issue
• docs: update README

PR Size: 🟢 Small (22 lines: +18 -4)

🔧 Backend Checks

Go Formatting: ✅ Good
Go Vet: ✅ Good
Tests: ✅ Passed

Fix locally:

go fmt ./...      # Format code
go vet ./...      # Check for issues
go test ./...     # Run tests

⚛️ Frontend Checks

Build & Type Check: ✅ Success

Fix locally:

cd web
npm run build  # Test build (includes type checking)

---

📖 Resources

• Contributing Guidelines
• Migration Guide

Questions? Feel free to ask in the comments! 🙏

---

These checks are advisory and won't block your PR from being merged. This comment is automatically generated from pr-checks-run.yml.

[xqliu]

感觉可以说不要前面的 0x 而不是十六进制，很多不学习计算机的不知道 16 进制跟 0x 对应

[github-actions]

🤖 Advisory Check Results

These are advisory checks to help improve code quality. They won't block your PR from being merged.

📋 PR Information

Title Format: ⚠️ Suggestion - Consider using type(scope): description

Recommended format

Valid types: feat, fix, docs, style, refactor, perf, test, chore, ci, security, build

Examples:

• feat(trader): add new trading strategy
• fix(api): resolve authentication issue
• docs: update README

PR Size: 🟢 Small (18 lines: +16 -2)

🔧 Backend Checks

Go Formatting: ✅ Good
Go Vet: ✅ Good
Tests: ✅ Passed

Fix locally:

go fmt ./...      # Format code
go vet ./...      # Check for issues
go test ./...     # Run tests

⚛️ Frontend Checks

Build & Type Check: ✅ Success

Fix locally:

cd web
npm run build  # Test build (includes type checking)

---

📖 Resources

• Contributing Guidelines
• Migration Guide

Questions? Feel free to ask in the comments! 🙏

---

These checks are advisory and won't block your PR from being merged. This comment is automatically generated from pr-checks-run.yml.

[cla-assistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 12 committers have signed the CLA.

✅ tinkle-community
❌ deloz
❌ ljh740
❌ xqliu
❌ tangmengqiu
❌ wquguru
❌ hzb1115
❌ 0xEmberZz
❌ Im-Sue
❌ CoderMageFox
❌ the-dev-z
❌ zpng
_{You have signed the CLA already but the status is still pending? Let us recheck it.}