fix: 配送点编码重复时返回中文提醒

docs/项目文档_配送点重复编码提醒_v1.0.md

@@ -0,0 +1,53 @@
+# 配送点重复编码提醒
+
+## 项目概述
+
+- 功能：新增配送点时，将目标唯一键冲突转换为中文业务提醒。
+- 技术栈：Go、Gin、GORM、PostgreSQL。
+- 运行环境：项目现有 Go 1.26.1 环境。
+
+## 目录结构说明
+
+```text
+platforms/backend/api/internal/logic/
+├── common/
+│   ├── delivery_error.go       # 配送点创建错误转换
+│   └── delivery_error_test.go  # 错误转换单元测试
+├── gas/delivery.go             # 气站端配送点新增入口
+└── platform/delivery/delivery.go # 平台端配送点新增入口
+```
+
+## 核心文件说明
+
+- `common/delivery_error.go`：精确识别 PostgreSQL `23505` 与约束 `idx_delivery_basic_delivery_code`，返回“配送点编码已存在，请更换后重试”；其他错误保持原样。
+- `platform/delivery/delivery.go`：平台端创建失败时调用公共转换函数。
+- `gas/delivery.go`：气站端创建失败时调用同一公共转换函数。
+- `common/delivery_error_test.go`：覆盖目标约束、普通数据库错误、其他唯一约束三个分支。
+
+## 变更记录
+
+- 新增配送点重复编码的中文提醒。
+- 平台端和气站端行为保持一致。
+- 保留数据库全局唯一约束、归档占用规则和现有前端顶部提醒。
+- 未新增依赖，未修改公共接口、数据库结构或配送点编码编辑规则。
+
+## 维护指南
+
+- 若数据库约束名称调整，需要同步更新 `deliveryCodeUniqueConstraint`。
+- 新增其他唯一字段提示时，应按约束名精确映射，不能将全部 `23505` 错误统一解释为配送点编码重复。
+- 验证命令：`go test ./internal/logic/common ./internal/logic/platform/delivery ./internal/logic/gas`。
+
+## 操作日志
+
+```text
+操作时间：2026-08-10 12:24:49
+操作类型：扩展
+影响模块：配送点创建错误处理
+
+操作前状态：数据库唯一键原始英文错误直接返回前端，暴露 SQLSTATE 与约束名。
+具体操作：新增精确错误映射并接入平台端、气站端创建入口；新增三个单元测试。
+操作后状态：目标配送点编码冲突返回中文提醒，其他错误行为不变。
+代码变更：delivery_error.go、delivery_error_test.go、platform/delivery/delivery.go、gas/delivery.go。
+验证结果：三个相关 Go 包测试通过。
+风险评估：依赖既有 PostgreSQL 约束名；约束重命名后需同步更新常量。未改变数据库唯一规则。
+```