refactor: 对齐后端样例工程规范

backend/api/internal/logic/dashboard/dashboard.go

@@ -0,0 +1,18 @@
+// Package dashboard 提供平台总后台聚合指标。
+package dashboard
+
+import (
+	"git.apinb.com/bsm-sdk/core/infra"
+	"git.apinb.com/heqiapp/platforms/backend/api/internal/models"
+	"github.com/gin-gonic/gin"
+)
+
+// Overview 返回组织与安全运营的首期概览数据。
+func Overview(ctx *gin.Context) {
+	overview, err := models.GetDashboardOverview()
+	if err != nil {
+		infra.Response.Error(ctx, err)
+		return
+	}
+	infra.Response.Success(ctx, overview)
+}

backend/api/internal/logic/idn_account/idn_account.go

@@ -0,0 +1,54 @@
+// Package idn_account 提供用户账户最小必要查询逻辑。
+package idn_account
+
+import (
+	"git.apinb.com/bsm-sdk/core/infra"
+	"git.apinb.com/bsm-sdk/core/utils"
+	"git.apinb.com/heqiapp/platforms/backend/api/internal/models"
+	"github.com/gin-gonic/gin"
+)
+
+// AccountView 是 idn_account 的最小必要输出，手机号始终脱敏。
+type AccountView struct {
+	Identity    string `json:"identity"`     // 用户主键
+	PhoneMasked string `json:"phone_masked"` // 脱敏手机号
+	AccountType string `json:"account_type"` // 账户类型
+	Status      string `json:"status"`       // 账户状态
+	ServiceArea string `json:"service_area"` // 服务区域
+}
+
+// ListReply 是 idn_account 的标准分页响应。
+type ListReply struct {
+	Total int64         `json:"total"`
+	List  []AccountView `json:"list"`
+}
+
+// List 查询普通用户账户列表。
+func List(ctx *gin.Context) {
+	page := utils.String2Int(ctx.DefaultQuery("page", "1"))
+	size := utils.String2Int(ctx.DefaultQuery("size", "20"))
+	if page < 1 {
+		page = 1
+	}
+	if size < 1 || size > 100 {
+		size = 20
+	}
+	list, total, err := models.ListIdnAccount(page, size)
+	if err != nil {
+		infra.Response.Error(ctx, err)
+		return
+	}
+	views := make([]AccountView, 0, len(list))
+	for _, item := range list {
+		views = append(views, AccountView{Identity: item.Identity.String(), PhoneMasked: maskPhone(item.Phone), AccountType: item.AccountType, Status: item.Status, ServiceArea: item.ServiceArea})
+	}
+	infra.Response.Success(ctx, ListReply{Total: total, List: views})
+}
+
+// maskPhone 遵循敏感数据最小展示原则。
+func maskPhone(phone string) string {
+	if len(phone) < 7 {
+		return "***"
+	}
+	return phone[:3] + "****" + phone[len(phone)-4:]
+}

backend/api/internal/logic/org_delivery_point/org_delivery_point.go

@@ -0,0 +1,38 @@
+// Package org_delivery_point 提供配送点管理查询逻辑。
+package org_delivery_point
+
+import (
+	"git.apinb.com/bsm-sdk/core/infra"
+	"git.apinb.com/bsm-sdk/core/utils"
+	"git.apinb.com/heqiapp/platforms/backend/api/internal/models"
+	"github.com/gin-gonic/gin"
+)
+
+// ListReply 是 org_delivery_point 的标准分页响应。
+type ListReply struct {
+	Total int64                     `json:"total"`
+	List  []models.OrgDeliveryPoint `json:"list"`
+}
+
+// List 查询配送点分页列表。
+func List(ctx *gin.Context) {
+	page, size := pageSize(ctx)
+	list, total, err := models.ListOrgDeliveryPoint(page, size)
+	if err != nil {
+		infra.Response.Error(ctx, err)
+		return
+	}
+	infra.Response.Success(ctx, ListReply{Total: total, List: list})
+}
+
+func pageSize(ctx *gin.Context) (int, int) {
+	page := utils.String2Int(ctx.DefaultQuery("page", "1"))
+	size := utils.String2Int(ctx.DefaultQuery("size", "20"))
+	if page < 1 {
+		page = 1
+	}
+	if size < 1 || size > 100 {
+		size = 20
+	}
+	return page, size
+}

backend/api/internal/logic/org_gas_station/org_gas_station.go

@@ -0,0 +1,60 @@
+// Package org_gas_station 提供气站管理的 HTTP 业务逻辑。
+package org_gas_station
+
+import (
+	"git.apinb.com/bsm-sdk/core/errcode"
+	"git.apinb.com/bsm-sdk/core/infra"
+	"git.apinb.com/bsm-sdk/core/utils"
+	"git.apinb.com/heqiapp/platforms/backend/api/internal/models"
+	"github.com/gin-gonic/gin"
+)
+
+// CreateRequest 是创建 org_gas_station 的请求体。
+type CreateRequest struct {
+	StationCode string `json:"station_code" binding:"required,max=32"`
+	Name        string `json:"name" binding:"required,max=128"`
+	Principal   string `json:"principal" binding:"required,max=64"`
+	ServiceArea string `json:"service_area" binding:"required,max=128"`
+}
+
+// ListReply 是标准分页响应。
+type ListReply struct {
+	Total int64                  `json:"total"`
+	List  []models.OrgGasStation `json:"list"`
+}
+
+// Create 创建待审核气站并由数据库层保证唯一编码。
+func Create(ctx *gin.Context) {
+	var request CreateRequest
+	if err := ctx.ShouldBindJSON(&request); err != nil {
+		infra.Response.Error(ctx, errcode.ErrInvalidArgument)
+		return
+	}
+	data := models.OrgGasStation{StationCode: request.StationCode, Name: request.Name, Principal: request.Principal, ServiceArea: request.ServiceArea}
+	data.Identity = models.NewIdentity()
+	data.Status = "draft"
+	data.Version = 1
+	if err := models.CreateOrgGasStation(&data); err != nil {
+		infra.Response.Error(ctx, err)
+		return
+	}
+	infra.Response.Success(ctx, data)
+}
+
+// List 查询气站分页列表。
+func List(ctx *gin.Context) {
+	page := utils.String2Int(ctx.DefaultQuery("page", "1"))
+	size := utils.String2Int(ctx.DefaultQuery("size", "20"))
+	if page < 1 {
+		page = 1
+	}
+	if size < 1 || size > 100 {
+		size = 20
+	}
+	list, total, err := models.ListOrgGasStation(page, size)
+	if err != nil {
+		infra.Response.Error(ctx, err)
+		return
+	}
+	infra.Response.Success(ctx, ListReply{Total: total, List: list})
+}

backend/api/internal/logic/org_service_person/org_service_person.go

@@ -0,0 +1,33 @@
+// Package org_service_person 提供服务人员管理查询逻辑。
+package org_service_person
+
+import (
+	"git.apinb.com/bsm-sdk/core/infra"
+	"git.apinb.com/bsm-sdk/core/utils"
+	"git.apinb.com/heqiapp/platforms/backend/api/internal/models"
+	"github.com/gin-gonic/gin"
+)
+
+// ListReply 是 org_service_person 的标准分页响应。
+type ListReply struct {
+	Total int64                     `json:"total"`
+	List  []models.OrgServicePerson `json:"list"`
+}
+
+// List 查询服务人员分页列表。
+func List(ctx *gin.Context) {
+	page := utils.String2Int(ctx.DefaultQuery("page", "1"))
+	size := utils.String2Int(ctx.DefaultQuery("size", "20"))
+	if page < 1 {
+		page = 1
+	}
+	if size < 1 || size > 100 {
+		size = 20
+	}
+	list, total, err := models.ListOrgServicePerson(page, size)
+	if err != nil {
+		infra.Response.Error(ctx, err)
+		return
+	}
+	infra.Response.Success(ctx, ListReply{Total: total, List: list})
+}

backend/api/internal/logic/ping/hello.go

@@ -0,0 +1,12 @@
+// Package ping 提供匿名健康检查接口。
+package ping
+
+import (
+	"git.apinb.com/bsm-sdk/core/infra"
+	"github.com/gin-gonic/gin"
+)
+
+// Hello 返回 API 进程健康状态。
+func Hello(ctx *gin.Context) {
+	infra.Response.Success(ctx, gin.H{"service": "platform-api", "status": "ok"})
+}

backend/api/internal/logic/saf_event/saf_event.go

@@ -0,0 +1,33 @@
+// Package saf_event 提供安全事件查询逻辑。
+package saf_event
+
+import (
+	"git.apinb.com/bsm-sdk/core/infra"
+	"git.apinb.com/bsm-sdk/core/utils"
+	"git.apinb.com/heqiapp/platforms/backend/api/internal/models"
+	"github.com/gin-gonic/gin"
+)
+
+// ListReply 是 saf_event 的标准分页响应。
+type ListReply struct {
+	Total int64             `json:"total"`
+	List  []models.SafEvent `json:"list"`
+}
+
+// List 查询安全事件列表。
+func List(ctx *gin.Context) {
+	page := utils.String2Int(ctx.DefaultQuery("page", "1"))
+	size := utils.String2Int(ctx.DefaultQuery("size", "20"))
+	if page < 1 {
+		page = 1
+	}
+	if size < 1 || size > 100 {
+		size = 20
+	}
+	list, total, err := models.ListSafEvent(page, size)
+	if err != nil {
+		infra.Response.Error(ctx, err)
+		return
+	}
+	infra.Response.Success(ctx, ListReply{Total: total, List: list})
+}