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

配送点重复编码提醒

项目概述

• 功能：新增配送点时，将目标唯一键冲突转换为中文业务提醒。
• 技术栈：Go、Gin、GORM、PostgreSQL。
• 运行环境：项目现有 Go 1.26.1 环境。

目录结构说明

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。

操作日志

操作时间：2026-08-10 12:24:49
操作类型：扩展
影响模块：配送点创建错误处理

操作前状态：数据库唯一键原始英文错误直接返回前端，暴露 SQLSTATE 与约束名。
具体操作：新增精确错误映射并接入平台端、气站端创建入口；新增三个单元测试。
操作后状态：目标配送点编码冲突返回中文提醒，其他错误行为不变。
代码变更：delivery_error.go、delivery_error_test.go、platform/delivery/delivery.go、gas/delivery.go。
验证结果：三个相关 Go 包测试通过。
风险评估：依赖既有 PostgreSQL 约束名；约束重命名后需同步更新常量。未改变数据库唯一规则。