CodeNote 知识库

外观

二维码显示规范 ​

目标 ​

所有二维码显示必须使用同一套渲染逻辑，保证前后端、不同页面间显示一致。

规范 ​

1. 渲染引擎统一 ​

  • Android 端：使用 QrCodeBitmapGenerator（com.codenote.core.common）生成二维码位图
  • 服务端：使用 QrCodeImageService.generateImage() / generateFromContent() 渲染图片
  • 禁止在各 Feature 中重复编写 QR 码生成函数

2. 颜色参数必传 ​

所有二维码渲染必须传入 foregroundColor 和 backgroundColor，不设默认值：

kotlin
fun generate(content: String, size: Int, foregroundColor: String, backgroundColor: String): Bitmap?

不允许硬编码 BLACK/WHITE。

3. 参数规则 ​

参数类型说明
contentString二维码编码内容
sizeInt图片尺寸 px，范围 100~2000
foregroundColorString六位十六进制颜色，如 #FF0000
backgroundColorString同上
logoUrlString?可选，居中嵌入的 LOGO 图片 URL

4. Composable 组件 ​

  • 二维码预览：使用 QrCodePreviewCard composable（位于 QrCodeFormScreen.kt，将来应抽到公共 UI 组件）
  • 所有二维码图片展示应通过 produceState 或 LaunchedEffect 异步生成 Bitmap，避免在主线程渲染

5. Android 端调用示例 ​

kotlin
// 在 Composable 中异步加载
val bitmap by produceState<Bitmap?>(null, content, foregroundColor, backgroundColor, size) {
    value = QrCodeBitmapGenerator.generate(content, size, foregroundColor, backgroundColor)
}

6. 服务端调用 ​

  • 管理后台预览：调 /api/qr-codes/{id}/image（服务端用 QrCodeImageService.generateImage(id)）
  • 其他场景：调 /api/qr-codes/render?content=...&size=...&fg=...&bg=...

7. DTO 字段约定 ​

QrCodeDto / QrCode 实体必须包含以下字段供客户端渲染：

  • foregroundColor: String — 前景色
  • backgroundColor: String — 背景色

8. 非功能性要求 ​

  • 性能：二维码生成在 Dispatchers.Default 上执行
  • 缓存：预览图已在 ViewModel 层缓存（previewBitmap），列表页缩略图可考虑 LRU 缓存