Skip to content

PRODUCT.md

Latest commit

 

History

History
286 lines (209 loc) · 11.9 KB

PRODUCT.md

File metadata and controls

286 lines (209 loc) · 11.9 KB
Raw

BaseConversion 产品需求文档（PRD）

本文档是 RESEARCH.md 的正式化与细化，结合多轮需求澄清后的最终结论。 状态：待确认（确认后作为开工依据）

1. 产品概述

项 内容
名称 BaseConversion
包名 com.baseconversion.app
定位 面向程序员的纯本地、零广告、零学习成本安卓进制转换器
平台 Android 10 (API 29) 及以上
语言 中英双语，跟随系统
商业化 完全开源，无广告、无订阅、无内购
网络 无任何联网权限，纯本地计算

1.1 一句话描述

打开即用，在二进制 / 八进制 / 十进制 / 十六进制之间实时联动转换，支持大整数、补码与 IEEE 754 浮点数位模式，无需点击"转换"按钮。

2. 目标用户与场景

场景 典型诉求
嵌入式开发 地址 / 掩码计算、寄存器值在十进制与十六进制间换算
协议分析 十六进制报文解读、浮点字节反推真实数值
算法学习 理解位运算、补码、IEEE 754 浮点存储

核心痛点：现有 App 要么功能残缺（不支持浮点/大数），要么广告弹窗烦人。

3. 产品原则

  1. 零广告：无启动页广告、无插屏、无 Banner。
  2. 零学习成本：实时联动，无转换按钮；智能键盘按进制禁用非法键。
  3. 纯本地：无网络权限，数据不出设备。
  4. 轻量：零第三方运行时依赖（仅 AndroidX / Compose 等官方库）。
  5. 开源：完全开源，不设付费墙。

4. 术语定义

术语 定义
进制 二进制(2)、八进制(8)、十进制(10)、十六进制(16)
位宽 8 / 16 / 32 / 64 位（有符号补码）或"任意"（无符号任意精度）
补码 二补数（two's complement），负数按选定 n 位取模表示
IEEE 754 浮点数存储标准；本产品指 binary32（float32）与 binary64（float64）

5. MVP 功能清单

5.1 双模式

界面顶部提供显式模式切换（Tab 或分段开关）：

  • 整数模式：位置计数法 + 补码，支持大整数与负数。
  • 浮点模式：IEEE 754 位模式展示。

两种模式算法独立、界面状态独立。

5.2 整数模式

5.2.1 四个进制框

  • 同时显示二进制、八进制、十进制、十六进制四个输入框。
  • 四框均可直接编辑，编辑任意一框，其余三框实时刷新（双向联动）。
  • 每个框旁有独立复制图标；键盘"复制"键复制当前焦点框的值。

5.2.2 大整数与位宽

  • 位宽选择器：任意 / 8 / 16 / 32 / 64。
  • 任意位宽：无符号、非负、任意精度（Java BigInteger）。
  • 固定位宽（8/16/32/64）：按 n 位有符号补码解释，允许负数。

5.2.3 负数规则

  • 负号 - 仅十进制可输入，其他进制禁用负号（避免歧义）。
  • 固定位宽下输入负数：其余进制显示该数的 n 位补码位型。
  • "任意"位宽下不支持负数（无符号）。

5.2.4 补码显示（推荐默认，待确认）

  • 固定位宽 n 时，二进制按 n 位补零显示；十六进制按 n/4 位、八进制按 ⌈n/3⌉ 位补零显示，保证补码位型可读。
  • "任意"位宽不补零，显示自然长度。

5.2.5 范围与溢出

  • 固定位宽 n 的十进制有效范围：[-2^(n-1), 2^(n-1)-1]。
  • 超出范围：自动截断并提示（⚠️），见「补充」方式 A。

5.3 浮点模式

  • 仅十进制框可编辑，其余三框只读展示位模式。
  • 输入十进制浮点值（支持负数、小数），实时计算并展示：
    • float32（binary32） 的 IEEE 754 位模式（二进制 32 位 / 十六进制 8 位 / 八进制位型）；
    • float64（binary64） 的 IEEE 754 位模式（二进制 64 位 / 十六进制 16 位 / 八进制位型）；
    • 实际存储十进制值：因浮点无法精确表示，额外显示 float32 / float64 各自四舍五入后实际存储的值（如输入 0.1 → float32 ≈ 0.1000000014901161）。
  • 舍入方式：IEEE 754 就近舍入（round-to-nearest-even）。
  • 特殊值：支持 NaN、+Infinity、-Infinity、-0.0 的展示。

5.4 实时联动

  • 整数模式：四框双向实时联动，无"转换"按钮。
  • 浮点模式：十进制输入 → 位模式实时刷新。

5.5 智能键盘（应用内自定义键盘）

使用应用内键盘（类似计算器），非法键按当前进制动态置灰禁用。

5.5.1 键盘布局（目标）

┌───────────────────────────────────────┐
│ [2] [8] [10] [16]    [0x] [0b] [0o] │  ← 顶部快捷栏：进制切换 + 前缀
├───────────────────────────────────────┤
│  7    8    9    A    B    C    ⌫退格  │
│  4    5    6    D    E    F    C清空  │
│  1    2    3   粘贴  复制   . 小数点  │
│  -负号  0                             │
└───────────────────────────────────────┘

5.5.2 按键清单

数字 0-9、字母 A-F（十六进制启用）、小数点 .、负号 -、退格 ⌫、清空 C、粘贴、复制。

5.5.3 动态禁用规则

当前输入进制 禁用按键
二进制 2-9、A-F、负号
八进制 8-9、A-F、负号
十进制 A-F（负号可用）
十六进制 负号（数字与 A-F 全可用）
浮点模式（十进制输入） A-F

5.5.4 交互行为

  • 长按退格连续删除：约 100ms 间隔连续删除。
  • 进制切换快捷栏：[2][8][10][16] 一键切换当前输入进制，键盘禁用状态同步更新。
  • 前缀快捷：0x / 0b / 0o 对应十六进制 / 二进制 / 八进制（行为细节见 §9 待确认）。

5.6 复制、粘贴与输入纠错

  • 复制：每框旁图标 + 键盘"复制"键（复制焦点框值）。
  • 粘贴：粘贴到当前焦点框；自动解析 0x / 0b / 0o 前缀；非法字符自动过滤。
  • 输入纠错：非法字符自动过滤，不产生错误状态。

6. 主题与国际化

  • 深色模式：运行时跟随系统（浅色 + 深色均可用）。
  • 语言：中英双语，跟随系统；默认（fallback）英文，中文 values-zh。
  • 数值字体：数字/字母字段使用等宽（monospace）字体，便于对齐阅读（待确认）。
  • 配色：使用 MaterialTheme 配色，禁止硬编码（详见技术文档）。

7. 边界与错误处理

场景 处理
固定位宽溢出 自动截断并提示（⚠️）
粘贴含非法字符/前缀 过滤非法字符、解析前缀
空输入 其余框显示空/占位
浮点特殊值 NaN / ±Infinity / -0.0 正确展示
负数（任意位宽） 不支持，负号禁用

8. 后续版本（Backlog，不做进 MVP）

  • 历史记录（Room 数据库）
  • 位运算视图（二进制位图）
  • 任意进制（2-36）
  • 主题切换（高对比度等）
  • 长二进制/十六进制自动分组（4 位 / 8 位分隔）
  • 位运算符号（<< >> & | ^ ~）与进制运算
  • 历史记录上/下快速调取

9. 待确认点（已在下文「补充」中确认）

# 事项 推荐默认
1 固定位宽显示是否补零（§5.2.4） 固定位宽补零，任意位宽不补零
2 固定位宽十进制范围是否严格 signed 严格 [-2^(n-1), 2^(n-1)-1]
3 前缀按钮 0x/0b/0o 行为 切换对应进制，并在焦点框插入前缀
4 主题是否关闭 Material You 动态取色 关闭，用固定自定义配色
5 App 图标 待设计，当前为默认占位图标
6 数值等宽字体 采用等宽字体

补充

第 2 项：固定位宽十进制范围是否严格 signed

我的建议：默认严格 signed，但界面提供 signed/unsigned 切换开关。

为什么默认 signed？

场景 例子 预期行为
8 位有符号 输入 0xFF → 十进制显示 -1 这是补码标准，程序员看到 0xFF 在 8 位 signed 下立刻知道是 -1
16 位有符号 输入 0x8000 → -32768 边界值测试常用
32 位有符号 输入 0xFFFFFFFF → -1 嵌入式开发中 0xFFFFFFFF 作为 -1 是常识

如果默认 unsigned，0xFF 显示 255，程序员会困惑："这是 8 位有符号还是无符号？"

交互设计

┌────────────────────────────┐
│  位宽: [ 8位 ▼ ]  [● Signed  ○ Unsigned] │
│                            │
│  十六进制: 0x FF           │
│  十进制:   -1   ← (signed) │
│  二进制:   1111 1111       │
└────────────────────────────┘

切换 signed/unsigned 时：

  • 数值不变，十进制显示实时变化
  • 0xFF → Signed: -1 / Unsigned: 255
  • 给用户直观感受"同一串位，不同解释"

输入超出范围的处理

如果当前是 8 位 signed（范围 -128 ~ 127），用户输入十进制 200：

  • 方式 A（推荐）：自动截断到 8 位，显示 0xC8（即 -56），并在输入框旁提示 ⚠️ "超出 8 位 signed 范围，已按补码截断"
  • 方式 B：禁止输入，键盘禁用超出范围的数字（体验差，不推荐）
  • 方式 C：自动扩展位宽（违背"固定位宽"的设定，不推荐）

推荐 A：程序员工具应该允许"故意溢出"，这是调试掩码、位运算的常见操作。

其他待确认点快速建议

# 事项 我的建议 理由
1 固定位宽补零 ✅ 同意推荐：固定位宽补零，任意位宽不补零 8 位显示 0x0A 比 0xA 更专业；任意位宽按实际长度显示
3 前缀按钮行为 ✅ 同意推荐：点击 0x 切换十六进制 + 在输入框插入前缀 但注意：如果输入框已有内容，前缀是插入到开头还是替换全部？建议插入到开头，不破坏已有输入
4 Material You 动态取色 ✅ 同意推荐：关闭，用固定配色 工具类 App 需要专业感，动态取色在不同用户手机上看起来不一致，影响品牌认知
5 App 图标 建议：极简风格，一个 0x 或 01 符号，单色/双色 工具类 App 图标越简单越专业，参考计算器、终端类 App
6 等宽字体 ✅ 必须：数值全部用等宽字体 二进制/十六进制对齐是刚需，推荐 JetBrains Mono 或 Roboto Mono（Android 自带）

第 3 项补充细节：前缀按钮的边界情况

当前输入框内容: "1A2B"
用户点击 0x 按钮:
→ 结果: "0x1A2B"（前缀插入开头，不替换）

当前输入框内容: "0x1A2B"
用户点击 0x 按钮:
→ 结果: "1A2B"（再次点击移除前缀，toggle 行为）

当前输入框内容: "0b1010"
用户点击 0x 按钮:
→ 结果: "0x1010"（替换前缀，不保留旧前缀）

这样设计最符合程序员直觉：前缀按钮是快捷切换当前进制表示法，不是简单的文本插入。

总结

我的核心建议：

  1. 固定位宽：默认 signed，提供 signed/unsigned toggle，溢出自动截断并提示
  2. 前缀按钮：toggle 行为（插入/移除），切换进制时自动替换前缀
  3. Material You：关闭，固定专业配色（深灰 + 强调色，类似终端/IDE 风格）
  4. 字体：等宽字体必须，数值对齐是底线体验

10. 明确不做

  • 不做房贷计算器、单位换算等无关功能
  • 不做订阅制付费、内购
  • 不做联网权限
  • 不做社交分享、排行榜
  • 不做启动页广告、插屏广告