已完成用户APP首期功能开发

交付用户端首期页面、配套接口、后台资源及测试文档。用户APP构建、静态分析和三个管理后台构建通过；完整测试仍有2项失败，后端模型注释检查未通过，详见交付记录。

backend/api/cmd/cli/address_migration.go

@@ -0,0 +1,65 @@
+// 功能描述：只扩展用户地址的联系人和幂等字段，不执行全库迁移或初始化。
+// 版本：1.0.0。
+package main
+
+import (
+	"fmt"
+	"git.apinb.com/bsm-sdk/core/database"
+	dbsql "git.apinb.com/bsm-sdk/core/database/sql"
+	"git.apinb.com/heqiapp/platforms/backend/api/internal/config"
+	"gorm.io/gorm"
+)
+
+// migrateUserAddress 使用当前环境的已有数据库配置，事务失败全部回滚。
+func migrateUserAddress() error {
+	return migrateClientColumns([]string{
+		`ALTER TABLE user_address ADD COLUMN IF NOT EXISTS contact_name varchar(64) NOT NULL DEFAULT '', ADD COLUMN IF NOT EXISTS contact_phone varchar(32) NOT NULL DEFAULT '', ADD COLUMN IF NOT EXISTS request_no varchar(64) NOT NULL DEFAULT ''`,
+		`COMMENT ON COLUMN user_address.contact_name IS '收货联系人姓名；历史记录为空，编辑时补齐'`,
+		`COMMENT ON COLUMN user_address.contact_phone IS '收货联系人手机号；历史记录为空，编辑时补齐'`,
+		`COMMENT ON COLUMN user_address.request_no IS '客户端新增请求幂等标识，同一用户重试不重复新增，历史记录为空'`,
+	})
+}
+
+// migrateTicketContact 仅补齐报修故障分类和提交时的联系人快照。
+func migrateTicketContact() error {
+	return migrateClientColumns([]string{
+		`ALTER TABLE cs_ticket ADD COLUMN IF NOT EXISTS fault_type varchar(32) NOT NULL DEFAULT '', ADD COLUMN IF NOT EXISTS contact_name varchar(64) NOT NULL DEFAULT '', ADD COLUMN IF NOT EXISTS contact_phone varchar(32) NOT NULL DEFAULT ''`,
+		`COMMENT ON COLUMN cs_ticket.fault_type IS '故障类型：leak=燃气泄漏，valve=阀门故障，alarm=报警器故障，other=其他；历史记录为空'`,
+		`COMMENT ON COLUMN cs_ticket.contact_name IS '用户提交工单时的联系人姓名快照，历史记录为空'`,
+		`COMMENT ON COLUMN cs_ticket.contact_phone IS '用户提交工单时的联系电话快照，历史记录为空'`,
+	})
+}
+
+// migrateTicketContract 只增加可选合同关联，旧工单保持0且不改变原处理规则。
+func migrateTicketContract() error {
+	return migrateClientColumns([]string{
+		`ALTER TABLE cs_ticket ADD COLUMN IF NOT EXISTS gasorder_contract_id bigint NOT NULL DEFAULT 0`,
+		`COMMENT ON COLUMN cs_ticket.gasorder_contract_id IS '关联供气合同内部主键；0=非合同申请；非0由本人合同校验后写入，不代表合同已修改'`,
+		`CREATE INDEX IF NOT EXISTS idx_cs_ticket_gasorder_contract_id ON cs_ticket(gasorder_contract_id)`,
+	})
+}
+
+// migrateClientColumns 在已有远程配置中执行明确字段扩展，锁超时或失败全部回滚。
+func migrateClientColumns(statements []string) error {
+	config.New(serviceKey)
+	if config.Spec.Databases == nil {
+		return fmt.Errorf("database configuration required")
+	}
+	db, err := database.NewDatabase(config.Spec.Databases.Driver, config.Spec.Databases.Source, dbsql.SetOptions(nil))
+	if err != nil {
+		return fmt.Errorf("connect configured database failed")
+	}
+	sqlDB, err := db.DB()
+	if err != nil {
+		return err
+	}
+	defer sqlDB.Close()
+	return db.Transaction(func(tx *gorm.DB) error {
+		for _, statement := range append([]string{`SET LOCAL lock_timeout = '5s'`}, statements...) {
+			if err := tx.Exec(statement).Error; err != nil {
+				return err
+			}
+		}
+		return nil
+	})
+}