junhong_cmp_fiber/internal/routes/employee_collection.go

package routes

import (
	"github.com/gofiber/fiber/v2"

	"github.com/break/junhong_cmp_fiber/internal/handler/admin"
	"github.com/break/junhong_cmp_fiber/internal/model/dto"
	"github.com/break/junhong_cmp_fiber/pkg/constants"
	"github.com/break/junhong_cmp_fiber/pkg/errors"
	"github.com/break/junhong_cmp_fiber/pkg/middleware"
	"github.com/break/junhong_cmp_fiber/pkg/openapi"
)

// requireEmployeeCollectionConfigAccess 限制线下收款方式字典维护仅超级管理员可用，
// 非超级管理员与其他不可见资源返回同一禁止访问错误，避免可枚举差异。
func requireEmployeeCollectionConfigAccess(handler fiber.Handler) fiber.Handler {
	return func(c *fiber.Ctx) error {
		if middleware.GetUserTypeFromContext(c.UserContext()) != constants.UserTypeSuperAdmin {
			return errors.New(errors.CodeForbidden, "无权限操作该资源或资源不存在")
		}
		return handler(c)
	}
}

func registerEmployeeCollectionRoutes(router fiber.Router, handler *admin.EmployeeCollectionHandler, doc *openapi.Generator, basePath string) {
	// 路由前缀必须交给 Group：Register 的 basePath 只用于生成 OpenAPI 文档，不参与路由注册，
	// 否则相对路径会落到 /api/admin 根上并抢占同层后续路由。
	group := router.Group("/employee-collection-payment-methods")
	paymentMethodPath := basePath + "/employee-collection-payment-methods"
	wrap := requireEmployeeCollectionConfigAccess

	Register(group, doc, paymentMethodPath, "GET", "", handler.ListPaymentMethods, RouteSpec{
		Summary:     "查询线下收款方式",
		Description: "超级管理员可查询全部字典项；其他后台账号仅返回启用项，用于新核销申请选择收款方式。",
		Tags:        []string{"员工代收款"},
		Input:       new(dto.EmployeeCollectionPaymentMethodListRequest),
		Output:      new(dto.EmployeeCollectionPaymentMethodListResponse),
		Auth:        true,
	})
	Register(group, doc, paymentMethodPath, "POST", "", wrap(handler.CreatePaymentMethod), RouteSpec{
		Summary:     "创建线下收款方式",
		Description: "仅超级管理员。稳定编码在未删除记录中唯一。",
		Tags:        []string{"员工代收款"},
		Input:       new(dto.CreateEmployeeCollectionPaymentMethodRequest),
		Output:      new(dto.EmployeeCollectionPaymentMethodResponse),
		Auth:        true,
	})
	Register(group, doc, paymentMethodPath, "PUT", "/:id", wrap(handler.UpdatePaymentMethod), RouteSpec{
		Summary:     "更新线下收款方式",
		Description: "仅超级管理员。可修改名称、排序、启停与备注；已被核销申请引用时不允许修改稳定编码。",
		Tags:        []string{"员工代收款"},
		Input:       new(dto.IDReq),
		Body:        new(dto.UpdateEmployeeCollectionPaymentMethodRequest),
		Output:      new(dto.EmployeeCollectionPaymentMethodResponse),
		Auth:        true,
	})
	Register(group, doc, paymentMethodPath, "DELETE", "/:id", wrap(handler.DeletePaymentMethod), RouteSpec{
		Summary:     "删除线下收款方式",
		Description: "仅超级管理员。已被核销申请引用的字典项不可物理删除，只能停用。",
		Tags:        []string{"员工代收款"},
		Input:       new(dto.IDReq),
		Output:      nil,
		Auth:        true,
	})
}

// registerEmployeeCollectionBillRoutes 注册员工代收款账单查询、统计与关闭路由。
// 账单可见性由应用层强制：欠款人仅见本人账单，超级管理员见全部。
func registerEmployeeCollectionBillRoutes(router fiber.Router, handler *admin.EmployeeCollectionHandler, doc *openapi.Generator, basePath string) {
	group := router.Group("/employee-collection-bills")
	billPath := basePath + "/employee-collection-bills"
	adminOnly := requireEmployeeCollectionConfigAccess

	Register(group, doc, billPath, "GET", "", handler.ListBills, RouteSpec{
		Summary: "查询员工代收款账单",
		Description: "欠款人仅返回本人欠款账单，超级管理员返回全部；支持账单编号（即账单记录标识）、来源、状态、" +
			"欠款人姓名或账号（子串模糊）、客户名称（子串模糊）、产生时间与核销通过时间筛选与分页。" +
			"产生时间参数为 `start_time`/`end_time`，核销通过时间为 `decided_start_time`/`decided_end_time`，" +
			"两类均为带显式时区的 RFC3339 秒级闭区间（含两端）；旧参数名 `created_from`/`created_to` 与旧日期格式一律以参数非法拒绝。" +
			"核销通过时间取该账单已通过分摊关联的申请表审批终态时间。" +
			"响应并列返回未核销金额（应收减已核销）与剩余可核销金额（应收减已核销减审批中预占），已关闭账单两者为零。",
		Tags:   []string{"员工代收款"},
		Input:  new(dto.EmployeeCollectionBillListRequest),
		Output: new(dto.EmployeeCollectionBillListResponse),
		Auth:   true,
	})
	// 统计必须先于 /:id 注册，保证路径按字面量优先匹配。
	Register(group, doc, billPath, "GET", "/statistics", handler.StatisticsBills, RouteSpec{
		Summary: "查询员工代收款账单统计",
		Description: "与账单列表使用相同筛选条件（含核销通过时间与模糊筛选）与可见性范围，" +
			"返回应收、已核销、未核销金额合计与待处理账单数；不接受分页参数。",
		Tags:   []string{"员工代收款"},
		Input:  new(dto.EmployeeCollectionBillStatisticsRequest),
		Output: new(dto.EmployeeCollectionBillStatisticsResponse),
		Auth:   true,
	})
	Register(group, doc, billPath, "GET", "/:id", handler.GetBill, RouteSpec{
		Summary: "查询员工代收款账单详情",
		Description: "返回账单、来源退款冲销、分摊、核销申请与企业微信审批历史，并返回操作日志安全投影" +
			"（动作、操作账号名称、时间与前后值摘要，不含凭证内容与完整收款原文）与来源订单快照" +
			"（来源单号、业务类型、来源金额、来源创建时间、资产标识；来源不可读时字段为空值且不阻断详情）。" +
			"附件只返回对象键引用。无权限与不存在返回同一错误。",
		Tags:   []string{"员工代收款"},
		Input:  new(dto.IDReq),
		Output: new(dto.EmployeeCollectionBillDetailResponse),
		Auth:   true,
	})
	Register(group, doc, billPath, "POST", "/:id/close", adminOnly(handler.CloseBill), RouteSpec{
		Summary:     "关闭员工代收款账单",
		Description: "仅超级管理员。仅允许关闭待核销或部分核销且不存在审批中分摊的账单；关闭只作废未核销余额并保留已核销金额。",
		Tags:        []string{"员工代收款"},
		Input:       new(dto.IDReq),
		Body:        new(dto.CloseEmployeeCollectionBillRequest),
		Output:      new(dto.EmployeeCollectionBillResponse),
		Auth:        true,
	})
}

// registerEmployeeCollectionApplicationRoutes 注册核销申请的创建、重提与受控查询路由。
// 可见性与代办权限由应用层强制：非超级管理员只能为本人账单操作，超级管理员代办必须填写原因。
func registerEmployeeCollectionApplicationRoutes(router fiber.Router, handler *admin.EmployeeCollectionHandler, doc *openapi.Generator, basePath string) {
	group := router.Group("/employee-collection-applications")
	applicationPath := basePath + "/employee-collection-applications"

	Register(group, doc, applicationPath, "POST", "", handler.CreateApplication, RouteSpec{
		Summary:     "创建核销申请",
		Description: "员工为本人可见账单创建；超级管理员可为账单欠款人代办且必须填写 acting_reason。服务端按账单可核销余额与付款金额校验分摊，任一失败不保存申请与预占。",
		Tags:        []string{"员工代收款"},
		Input:       new(dto.SubmitEmployeeCollectionApplicationRequest),
		Output:      new(dto.EmployeeCollectionApplicationSubmitResponse),
		Auth:        true,
	})
	Register(group, doc, applicationPath, "GET", "", handler.ListApplications, RouteSpec{
		Summary:     "查询核销申请",
		Description: "非超级管理员仅返回本人申请，超级管理员返回全部；支持状态、收款方式、申请人与创建时间筛选和分页。",
		Tags:        []string{"员工代收款"},
		Input:       new(dto.EmployeeCollectionApplicationListRequest),
		Output:      new(dto.EmployeeCollectionApplicationListResponse),
		Auth:        true,
	})
	Register(group, doc, applicationPath, "GET", "/:id", handler.GetApplication, RouteSpec{
		Summary:     "查询核销申请详情",
		Description: "返回申请事实、账单分摊与全部审批尝试历史；附件只返回对象键引用。无权限与不存在返回同一错误。",
		Tags:        []string{"员工代收款"},
		Input:       new(dto.IDReq),
		Output:      new(dto.EmployeeCollectionApplicationDetailResponse),
		Auth:        true,
	})
	Register(group, doc, applicationPath, "PUT", "/:id", handler.ResubmitApplication, RouteSpec{
		Summary:     "修改并重提核销申请",
		Description: "仅申请人或被代办的超级管理员，且仅已驳回申请可修改；重提新增一条审批尝试记录与新的企业微信审批实例，历史材料不被覆盖。",
		Tags:        []string{"员工代收款"},
		Input:       new(dto.IDReq),
		Body:        new(dto.SubmitEmployeeCollectionApplicationRequest),
		Output:      new(dto.EmployeeCollectionApplicationSubmitResponse),
		Auth:        true,
	})
}