From 117cec431b796c8326366b9ee74c835ce6067f3b Mon Sep 17 00:00:00 2001
From: wangjia <809946525@qq.com>
Date: Mon, 25 May 2026 22:09:21 +0800
Subject: [PATCH] =?UTF-8?q?docs(claude):=20=E8=A1=A5=E5=85=85=E5=8F=91?=
 =?UTF-8?q?=E7=89=88=E6=B5=81=E7=A8=8B=E3=80=81=E5=BC=82=E5=B8=B8=E4=B8=8A?=
 =?UTF-8?q?=E6=8A=A5=E3=80=81=E6=8B=BC=E9=9F=B3=E6=90=9C=E7=B4=A2=E8=A7=84?=
 =?UTF-8?q?=E8=8C=83?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CLAUDE.md | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 3f7f049..b1666bc 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -251,3 +251,55 @@ cd client && flutter test
   tx.Set("gorm:query_option", "FOR UPDATE").Where(...).First(&model)
   ```
 - 适用场景：单号生成（`number_rules`）、库存扣减（`inventories`）、任何 check-then-act 模式
+
+### 发版流程
+
+使用 `/release <version>` slash command：
+
+```
+/release 1.0.2
+```
+
+执行顺序：本地 build → test → 更新 CHANGELOG.md → git commit → tag → push main+tag。
+CI/CD（Forgejo）收到 tag 后自动：编译 → 测试 → 创建 Release → 部署 EC2 → Telegram 通知。
+
+**CHANGELOG 格式**（Keep a Changelog）：
+```markdown
+## [1.0.2] - YYYY-MM-DD
+
+### 新功能
+- ...
+
+### 改进
+- ...
+
+### 修复
+- ...
+```
+只保留有内容的分类。`/release` 会检查 CHANGELOG 是否已有该版本节，没有则从 git log 自动生成。
+
+### 异常上报
+
+客户端异常已在两处统一捕获，**无需**在每个业务层重复处理：
+- `main.dart`：`FlutterError.onError` + `runZonedGuarded` 捕获所有未处理异常
+- `api_client.dart`：Dio 拦截器自动上报所有 HTTP 5xx 错误
+
+需要**手动调用** `reportError(e, st)` 的场景：
+- 技术性异常（JSON 解析失败、第三方 SDK 崩溃等）
+- **不需要**上报：`AppException` 及其子类（已知业务错误）
+
+```dart
+} catch (e, st) {
+  reportError(e, st);  // 一行，fire-and-forget
+  rethrow;
+}
+```
+
+### 搜索实现（拼音）
+
+商品名搜索同时支持汉字、全拼、首字母：
+- `products` 表有 `name_pinyin`（全拼）和 `name_initials`（首字母）两列
+- Create / Update / FindOrCreate 写入时自动调用 `util.ToPinyin()` 生成，**无需手动维护**
+- 启动时对 `name_pinyin = ''` 的存量数据自动回填（`backfillPinyin`）
+- 库存搜索 SQL 同时 LIKE 匹配 name、code、name_pinyin、name_initials
+- 新增其他需要拼音搜索的实体时，复用 `backend/internal/util/pinyin.go` 的 `ToPinyin()`