BuildingAI二开 Coze套餐订单页面详细开发计划
文章摘要 BuildingAI的Coze套餐订单管理系统采用Vue3+Nuxt3+TypeScript技术栈开发,包含订单管理主页面组件和数据模型定义两个核心部分。主页面提供订单统计展示、搜索筛选、列表管理、详情查看和退款处理功能,采用@fastbuildai/ui组件库构建现代化界面。数据模型通过TypeScript接口定义订单查询参数、列表数据和详情数据的类型结构,与后端DTO保持一致。系统实
1. 项目概述
1.1 项目背景和目标
BuildingAI Coze套餐订单页面是管理员后台的核心功能模块,基于Vue3 + Nuxt3 + TypeScript技术栈开发,使用@fastbuildai/ui组件库构建现代化管理界面。该页面用于管理和监控用户Coze套餐订单的全生命周期,通过coze_package_order数据表实现订单数据存储,关联user表和coze_package表提供完整的订单信息展示。
管理员可以通过该页面查看Coze套餐订单列表、筛选和搜索订单、查看订单详情,以及处理订单退款等核心业务操作。系统采用NestJS + TypeORM后端架构,提供完整的权限控制和数据验证机制,支持中文、英文、日文多语言环境。
该功能旨在为平台提供完善的Coze套餐订单管理能力,支持实时监控套餐业务数据,通过统计分析帮助运营决策,提升订单处理效率和用户服务质量。
1.2 开发范围和边界
- 前端范围:Vue3 Composition API、TypeScript类型定义、@fastbuildai/ui组件集成、vue-i18n国际化、API服务封装、订单列表管理、详情弹窗、退款流程、分页控制、响应式布局
- 后端范围:NestJS模块开发、RESTful API设计、TypeORM实体定义、权限控制、事务管理、订单查询优化、退款处理逻辑、业务规则验证
- 数据范围:coze_package_order表(主表)+ user表(用户信息)+ coze_package表(套餐配置)
- 权限范围:coze-package-order:list、coze-package-order:detail、coze-package-order:refund
1.3 技术栈说明
- 前端:Nuxt3 + Vue3 + TypeScript + @fastbuildai/ui + Tailwind CSS + vue-i18n
- 后端:NestJS + TypeORM + class-validator + PostgreSQL
- 数据存储:coze_package_order表(订单数据)+ user表(用户关联)+ coze_package表(套餐配置)
- 权限控制:基于@Permissions装饰器的权限验证机制
- 构建工具:Turbo + Vite + pnpm (monorepo)
2. 前端文件开发计划
2.1 主页面组件 ✅ 已完成
- 文件路径:
apps/web/app/console/order-management/coze-package-order/index.vue - 开发状态:✅ 已完成
- 功能描述:Coze套餐订单管理的主页面组件,使用@fastbuildai/ui组件库构建,包含订单列表管理、搜索筛选、详情查看、退款处理、分页控制
- 核心功能:
- UTable组件展示订单列表(订单号、用户信息、套餐信息、金额、状态等)
- UInput组件实现订单搜索和用户搜索功能
- USelect组件提供支付状态、退款状态筛选
- UDropdownMenu组件提供操作菜单(查看详情、申请退款)
- ProModal组件展示订单详情弹窗和退款申请弹窗
- ProPaginaction组件实现分页控制
- AccessControl权限控制组件
- 响应式布局适配移动端
- 实际代码结构:
<script setup lang="ts"> import { useMessage } from "@fastbuildai/ui"; import { useI18n } from "vue-i18n"; import type { CozePackageOrderListData, CozePackageOrderListParams } from "@/models/coze-package-order"; import { apiGetCozePackageOrderList, apiGetCozePackageOrderDetail, apiCozePackageOrderRefund } from "@/services/console/coze-package-order"; const { t } = useI18n(); const toast = useMessage(); // 响应式数据 const orderList = ref<CozePackageOrderListData[]>([]); const searchParams = ref<CozePackageOrderListParams>({ page: 1, pageSize: 20, orderNo: '', keyword: '', payStatus: 'all', refundStatus: 'all' }); const selectedOrder = ref<CozePackageOrderListData | null>(null); const showDetailModal = ref(false); const showRefundModal = ref(false); // 获取订单列表 const getOrderList = async () => { const data = await apiGetCozePackageOrderList(searchParams.value); orderList.value = data.list; }; // 查看订单详情 const viewOrderDetail = async (order: CozePackageOrderListData) => { selectedOrder.value = order; showDetailModal.value = true; }; // 申请退款 const handleRefund = async (order: CozePackageOrderListData) => { selectedOrder.value = order; showRefundModal.value = true; }; // 退款成功回调 const handleRefundSuccess = async () => { toast.success(t("console-coze-package-order.refundSuccess")); await getOrderList(); showDetailModal.value = false; showRefundModal.value = false; }; // 搜索和筛选 const handleSearch = () => { searchParams.value.page = 1; getOrderList(); }; // 分页处理 const handlePageChange = (page: number) => { searchParams.value.page = page; getOrderList(); }; // 页面初始化 onMounted(() => { getOrderList(); }); </script> - UI组件使用:
- UTable:订单数据表格(响应式布局、粘性表头)
- UInput:搜索框(订单号、用户关键字)
- USelect:筛选下拉框(支付状态、退款状态)
- UAvatar:用户头像显示
- UBadge:支付状态和退款状态标签
- UDropdownMenu:操作菜单(查看详情、申请退款)
- ProModal:订单详情和退款申请弹窗
- ProPaginaction:分页组件
- TimeDisplay:时间格式化显示
- AccessControl:权限控制显示
- 技术特点:
- 使用Vue3 Composition API进行状态管理
- 实时搜索和筛选功能
- 条件渲染和权限控制
- 响应式布局设计(移动端适配)
- 弹窗状态管理和事件回调
2.2 订单详情弹窗组件 ✅ 已完成
- 文件路径:
apps/web/app/console/order-management/coze-package-order/components/coze-package-order-detail.vue - 开发状态:✅ 已完成
- 功能描述:订单详情查看弹窗组件,展示完整的订单信息、用户信息、套餐信息、支付信息和退款信息
- 核心功能:
- 响应式断点检测和弹窗尺寸调整
- 订单基本信息展示(订单号、订单来源、订单类型)
- 用户信息展示(用户ID、昵称、手机号、头像)
- 套餐信息展示(套餐名称、算力数量、有效天数)
- 支付信息展示(支付方式、支付状态、支付时间、实付金额)
- 退款信息展示(退款状态、退款时间、退款金额)
- 时间信息展示(创建时间、更新时间)
- 退款操作按钮和权限控制
- 订单号一键复制功能
- 实际代码结构:
<script setup lang="ts"> import { useI18n } from "vue-i18n"; import { breakpointsTailwind, useBreakpoints } from "@vueuse/core"; import type { CozePackageOrderListData } from "@/models/coze-package-order"; const props = defineProps<{ order: CozePackageOrderListData | null; }>(); const emit = defineEmits<{ close: []; refund: [order: CozePackageOrderListData]; }>(); const { t } = useI18n(); const breakpoints = useBreakpoints(breakpointsTailwind); // 响应式断点 const isMobile = breakpoints.smaller("sm"); const isTablet = breakpoints.between("sm", "lg"); // 处理退款 const handleRefund = () => { if (props.order) { emit("refund", props.order); } }; // 关闭弹窗 const handleClose = () => { emit("close"); }; // 复制订单号 const copyOrderNo = async () => { if (props.order?.orderNo) { await navigator.clipboard.writeText(props.order.orderNo); // 显示复制成功提示 } }; // 金额格式化 const formatAmount = (amount: number) => { return `¥${amount.toFixed(2)}`; }; // 获取支付状态样式 const getPayStatusStyle = (status: number) => { const styles = { 0: { text: t("console-coze-package-order.unpaid"), class: "text-orange-600 bg-orange-100" }, 1: { text: t("console-coze-package-order.paid"), class: "text-green-600 bg-green-100" } }; return styles[status] || styles[0]; }; // 获取退款状态样式 const getRefundStatusStyle = (status: number) => { const styles = { 0: { text: t("console-coze-package-order.notRefunded"), class: "text-gray-600 bg-gray-100" }, 1: { text: t("console-coze-package-order.refunded"), class: "text-red-600 bg-red-100" } }; return styles[status] || styles[0]; }; </script> - 技术特点:
- 使用@vueuse/core进行响应式断点检测
- 移动端、平板、桌面端适配策略
- 动态弹窗尺寸调整机制
- 完整的信息分类展示
- 支付状态和退款状态样式映射
- 金额格式化和复制功能
2.3 退款申请弹窗组件 ✅ 已完成
- 文件路径:
apps/web/app/console/order-management/coze-package-order/components/refund-application.vue - 开发状态:✅ 已完成
- 功能描述:退款申请弹窗组件,提供退款原因选择、表单验证、业务规则检查、退款金额计算和确认操作
- 核心功能:
- 退款原因选择(预设选项和自定义输入)
- 表单验证和业务规则检查
- 退款金额自动计算
- 确认选项(确认退款、同意条款)
- 风险提示和退款说明
- 加载状态管理和错误处理
- 30天退款期限业务规则
- 实际代码结构:
<script setup lang="ts"> import { useI18n } from "vue-i18n"; import { breakpointsTailwind, useBreakpoints } from "@vueuse/core"; import type { CozePackageOrderListData } from "@/models/coze-package-order"; import { apiCozePackageOrderRefund } from "@/services/console/coze-package-order"; const props = defineProps<{ order: CozePackageOrderListData | null; }>(); const emit = defineEmits<{ close: []; success: []; }>(); const { t } = useI18n(); const breakpoints = useBreakpoints(breakpointsTailwind); // 响应式状态 const isMobile = breakpoints.smaller("sm"); const submitting = ref(false); const validating = ref(false); const formLoading = ref(false); // 表单数据 const formData = ref({ refundReason: "", otherReason: "", confirmRefund: false, agreeToTerms: false }); // 表单错误 const formErrors = ref({ refundReason: "", otherReason: "", confirmRefund: "", agreeToTerms: "" }); // 业务规则错误 const businessRuleErrors = ref({ payStatus: "", refundStatus: "", timeLimit: "" }); // 退款原因选项 const refundReasons = [ { value: "not_satisfied", label: t("console-coze-package-order.notSatisfied") }, { value: "wrong_purchase", label: t("console-coze-package-order.wrongPurchase") }, { value: "service_issue", label: t("console-coze-package-order.serviceIssue") }, { value: "other", label: t("console-coze-package-order.other") } ]; // 退款金额计算 const refundAmount = computed(() => { return props.order?.payAmount || 0; }); // 业务规则验证 const validateBusinessRules = () => { if (!props.order) return false; let hasError = false; // 支付状态检查 if (props.order.payStatus !== 1) { businessRuleErrors.value.payStatus = t("console-coze-package-order.payStatusError"); hasError = true; } // 退款状态检查 if (props.order.refundStatus === 1) { businessRuleErrors.value.refundStatus = t("console-coze-package-order.refundStatusError"); hasError = true; } // 30天时间限制检查 const createdTime = new Date(props.order.createdAt).getTime(); const now = Date.now(); const thirtyDays = 30 * 24 * 60 * 60 * 1000; if (now - createdTime > thirtyDays) { businessRuleErrors.value.timeLimit = t("console-coze-package-order.timeLimitError"); hasError = true; } return !hasError; }; // 表单验证 const validateForm = () => { let hasError = false; // 重置错误信息 formErrors.value = { refundReason: "", otherReason: "", confirmRefund: "", agreeToTerms: "" }; // 退款原因验证 if (!formData.value.refundReason) { formErrors.value.refundReason = t("console-coze-package-order.refundReasonRequired"); hasError = true; } // 其他原因验证 if (formData.value.refundReason === "other" && !formData.value.otherReason.trim()) { formErrors.value.otherReason = t("console-coze-package-order.otherReasonRequired"); hasError = true; } // 确认退款验证 if (!formData.value.confirmRefund) { formErrors.value.confirmRefund = t("console-coze-package-order.confirmRefundRequired"); hasError = true; } // 同意条款验证 if (!formData.value.agreeToTerms) { formErrors.value.agreeToTerms = t("console-coze-package-order.agreeToTermsRequired"); hasError = true; } return !hasError; }; // 提交退款申请 const submitRefund = async () => { if (!validateBusinessRules() || !validateForm()) { return; } try { submitting.value = true; await apiCozePackageOrderRefund({ orderId: props.order!.id, refundReason: formData.value.refundReason === "other" ? formData.value.otherReason : formData.value.refundReason }); emit("success"); } catch (error) { // 错误处理 } finally { submitting.value = false; } }; // 金额格式化 const formatAmount = (amount: number) => { return `¥${amount.toFixed(2)}`; }; </script> - 技术特点:
- 完整的表单验证机制(业务规则+表单验证)
- 30天退款期限业务规则实现
- 响应式布局和移动端适配
- 计算属性实现退款金额自动计算
- 完整的错误处理和用户提示
- 加载状态管理和防抖处理
2.4 数据模型定义 ✅ 已完成
- 文件路径:
apps/web/models/coze-package-order.d.ts - 开发状态:✅ 已完成
- 功能描述:定义Coze套餐订单相关的TypeScript接口,与后端DTO保持一致
- 实际接口定义:
/** * 订单列表查询参数接口 */ export interface CozePackageOrderListParams { /** 页码 */ page: number; /** 每页条数 */ pageSize: number; /** 订单号 */ orderNo?: string; /** 用户关键字(ID/昵称/手机号) */ keyword?: string; /** 支付状态 */ payStatus?: 'all' | '0' | '1'; /** 退款状态 */ refundStatus?: 'all' | '0' | '1'; } /** * 订单列表数据接口 */ export interface CozePackageOrderListData { /** 订单ID */ id: string; /** 订单号 */ orderNo: string; /** 用户信息 */ user: { id: string; nickname: string; phone?: string; avatar?: string; }; /** 套餐信息 */ cozePackage: { id: string; name: string; computingPower: number; validDays: number; }; /** 订单金额 */ orderAmount: number; /** 实付金额 */ payAmount: number; /** 支付方式 */ payType: number; /** 支付状态 */ payStatus: number; /** 退款状态 */ refundStatus: number; /** 创建时间 */ createdAt: string; /** 更新时间 */ updatedAt: string; } /** * 订单列表响应接口 */ export interface CozePackageOrderListResponse { /** 订单列表 */ list: CozePackageOrderListData[]; /** 分页信息 */ pagination: { page: number; pageSize: number; total: number; totalPages: number; }; } /** * 退款请求接口 */ export interface CozePackageOrderRefundRequest { /** 订单ID */ orderId: string; /** 退款原因 */ refundReason: string; } - 技术特点:
- TypeScript严格类型定义
- 完整的JSDoc文档注释
- 与后端DTO保持字段一致性
- 支持可选字段处理
- 分离查询参数和响应数据
- 嵌套对象类型定义(用户、套餐信息)
2.5 API服务层 ✅ 已完成
- 文件路径:
apps/web/services/console/coze-package-order.ts - 开发状态:✅ 已完成
- 功能描述:封装Coze套餐订单相关的API调用,使用useConsoleGet和useConsolePost进行HTTP请求
- 实际代码实现:
// ==================== Coze套餐订单相关 API ==================== import type { CozePackageOrderListParams, CozePackageOrderListResponse, CozePackageOrderRefundRequest } from "@/models/coze-package-order"; /** * 获取Coze套餐订单列表 */ export const apiGetCozePackageOrderList = (params: CozePackageOrderListParams): Promise<CozePackageOrderListResponse> => { return useConsoleGet("/coze-package-order", { params }); }; /** * 获取Coze套餐订单详情 */ export const apiGetCozePackageOrderDetail = (id: string): Promise<CozePackageOrderListData> => { return useConsoleGet(`/coze-package-order/${id}`); }; /** * 申请Coze套餐订单退款 */ export const apiCozePackageOrderRefund = (data: CozePackageOrderRefundRequest): Promise<void> => { return useConsolePost("/coze-package-order/refund", data); }; - 技术特点:
- 基于useConsoleGet/useConsolePost的HTTP请求封装
- TypeScript类型安全的API调用
- 简洁的函数式API设计
- 自动处理权限验证和错误处理
- 与后端API路径完全对应
2.6 国际化文件(功能文本)✅ 已完成
- 中文:
apps/web/core/i18n/zh/console-coze-package-order.json✅ - 英文:
apps/web/core/i18n/en/console-coze-package-order.json✅ - 日文:
apps/web/core/i18n/jp/console-coze-package-order.json✅ - 开发状态:✅ 已完成
- 功能描述:Coze套餐订单管理相关的多语言文本配置,支持中英日三语言
- 实际文本内容(中文版):
{ "cozePackageOrder": { "title": "Coze套餐订单", "search": { "orderNoPlaceholder": "请输入订单号", "keywordPlaceholder": "请输入用户ID/昵称/手机号", "payStatus": "支付状态", "refundStatus": "退款状态", "all": "全部", "paid": "已支付", "unpaid": "未支付", "refunded": "已退款", "notRefunded": "未退款" }, "table": { "orderNo": "订单号", "user": "用户", "package": "套餐", "computingPower": "算力数量", "validDays": "有效天数", "orderAmount": "订单金额", "payAmount": "实付金额", "payStatus": "支付状态", "refundStatus": "退款状态", "createdAt": "下单时间", "actions": "操作", "viewDetail": "查看详情", "refund": "申请退款" }, "detail": { "title": "订单详情", "orderInfo": "订单信息", "orderNo": "订单号", "orderSource": "订单来源", "orderType": "订单类型", "userInfo": "用户信息", "userId": "用户ID", "nickname": "用户昵称", "phone": "手机号", "packageInfo": "套餐信息", "packageName": "套餐名称", "computingPower": "算力数量", "validDays": "有效天数", "payInfo": "支付信息", "payType": "支付方式", "payTime": "支付时间", "refundInfo": "退款信息", "refundTime": "退款时间", "refundAmount": "退款金额", "timeInfo": "时间信息", "createdAt": "创建时间", "updatedAt": "更新时间" }, "refund": { "title": "申请退款", "refundReason": "退款原因", "refundReasonRequired": "请选择退款原因", "notSatisfied": "服务不满意", "wrongPurchase": "购买错误", "serviceIssue": "服务问题", "other": "其他原因", "otherReason": "其他原因说明", "otherReasonRequired": "请说明其他原因", "refundAmount": "退款金额", "confirmRefund": "确认退款", "confirmRefundRequired": "请确认退款", "agreeToTerms": "我已阅读并同意退款条款", "agreeToTermsRequired": "请同意退款条款", "riskWarning": "退款风险提示", "riskWarningText": "退款成功后,相应的套餐服务将被立即终止,且无法恢复。", "submit": "提交退款申请", "cancel": "取消" }, "messages": { "refundSuccess": "退款申请成功", "refundFailed": "退款申请失败", "confirmRefund": "确认要申请退款吗?", "refundConfirm": "退款确认", "payStatusError": "订单未支付,无法申请退款", "refundStatusError": "订单已退款,无法重复申请", "timeLimitError": "订单超过30天,无法申请退款", "copySuccess": "复制成功" } } } - 技术特点:
- 完整的三语言支持(中英日)
- 结构化的JSON配置
- 与组件中的t()函数调用完全对应
- 支持参数化文本
- 统一的命名规范(cozePackageOrder.xxx)
- 覆盖所有界面元素和交互提示
2.7 国际化文件(通用文本)✅ 已完成
- 中文:
apps/web/core/i18n/zh/console-common.json✅ - 英文:
apps/web/core/i18n/en/console-common.json✅ - 日文:
apps/web/core/i18n/jp/console-common.json✅ - 开发状态:✅ 已完成
- 功能描述:管理后台通用的多语言配置,包含按钮、状态、提示等通用文本
- 实际配置内容:
{ "common": { "enable": "启用", "disable": "禁用", "confirm": "确认", "cancel": "取消", "create": "创建", "save": "保存", "delete": "删除", "edit": "编辑", "export": "导出", "copy": "复制", "refresh": "刷新", "error": "错误", "success": "成功", "fail": "失败", "loading": "加载中", "status": "状态", "actions": "操作", "createTime": "创建时间", "updateTime": "更新时间", "total": "总计", "open": "打开", "unit": "条", "yuan": "元", "goTo": "前往", "page": "页", "confirmRefund": "确认退款", "refundSuccess": "退款成功", "noData": "暂无数据" } }
2.8 国际化文件(菜单文本)✅ 已完成
- 中文:
apps/web/core/i18n/zh/console-menu.json✅ - 英文:
apps/web/core/i18n/en/console-menu.json✅ - 日文:
apps/web/core/i18n/jp/console-menu.json✅ - 开发状态:✅ 已完成
- 功能描述:管理后台菜单的多语言配置,包含Coze套餐订单管理菜单项
- 实际配置内容:
{ "menu": { "orderManagement": "订单管理", "cozePackageOrder": "Coze套餐订单" } }
3. 后端文件开发计划
3.1 模块配置 ✅ 已完成
- 文件路径:
apps/server/src/modules/console/coze-package/coze-package.module.ts - 开发状态:✅ 已完成
- 功能描述:Coze套餐模块配置,定义控制器、服务、实体等的依赖注入关系
- 实际代码实现:
import { Module } from "@nestjs/common"; import { TypeOrmModule } from "@nestjs/typeorm"; import { User } from "@common/modules/auth/entities/user.entity"; import { CozePackage } from "@common/modules/coze-package/entities/coze-package.entity"; import { CozePackageOrderController } from "./controllers/coze-package-order.controller"; import { CozePackageOrder } from "./entities/coze-package-order.entity"; import { CozePackageOrderService } from "./services/coze-package-order.service"; @Module({ imports: [ TypeOrmModule.forFeature([ CozePackageOrder, User, CozePackage, ]), ], controllers: [CozePackageOrderController], providers: [CozePackageOrderService], exports: [CozePackageOrderService], }) export class CozePackageModule {} - 技术特点:
- 标准的NestJS模块结构
- TypeORM实体注册
- 多实体关联(CozePackageOrder、User、CozePackage)
- 完整的依赖注入配置
- 模块化设计支持
3.2 控制器 ✅ 已完成
- 文件路径:
apps/server/src/modules/console/coze-package/controllers/coze-package-order.controller.ts - 开发状态:✅ 已完成
- 功能描述:处理Coze套餐订单相关的HTTP请求,提供列表查询、详情查看、退款处理接口
- 核心接口:
GET /coze-package-order- 获取订单列表GET /coze-package-order/:id- 获取订单详情POST /coze-package-order/refund- 申请退款
- 实际代码实现:
import { Permissions } from "@common/decorators"; import { Body, Controller, Get, Param, Post, Query } from "@nestjs/common"; import { ApiOperation, ApiTags } from "@nestjs/swagger"; import { CozePackageOrderService } from "../services/coze-package-order.service"; import { CozePackageOrderListDto } from "../dto/coze-package-order-list.dto"; import { CozePackageOrderRefundDto } from "../dto/coze-package-order-refund.dto"; @ApiTags("Coze套餐订单管理") @Controller("coze-package-order") export class CozePackageOrderController { constructor(private readonly cozePackageOrderService: CozePackageOrderService) {} @ApiOperation({ summary: "获取Coze套餐订单列表" }) @Permissions("coze-package-order:list") @Get() async list(@Query() dto: CozePackageOrderListDto) { return await this.cozePackageOrderService.getList(dto); } @ApiOperation({ summary: "获取Coze套餐订单详情" }) @Permissions("coze-package-order:detail") @Get(":id") async detail(@Param("id") id: string) { return await this.cozePackageOrderService.getDetail(id); } @ApiOperation({ summary: "申请Coze套餐订单退款" }) @Permissions("coze-package-order:refund") @Post("refund") async refund(@Body() dto: CozePackageOrderRefundDto) { return await this.cozePackageOrderService.refund(dto); } } - 技术特点:
- 标准的NestJS控制器结构
- @Permissions权限控制装饰器
- 完整的Swagger API文档注释
- 类型安全的DTO参数验证
- RESTful API设计规范
3.3 服务层 ✅ 已完成
- 文件路径:
apps/server/src/modules/console/coze-package/services/coze-package-order.service.ts - 开发状态:✅ 已完成
- 功能描述:处理Coze套餐订单的业务逻辑,包含订单查询、详情获取、退款处理的核心功能
- 实际代码实现:
import { BaseService } from "@common/base"; import { User } from "@common/modules/auth/entities/user.entity"; import { CozePackage } from "@common/modules/coze-package/entities/coze-package.entity"; import { Injectable, NotFoundException, BadRequestException } from "@nestjs/common"; import { InjectRepository } from "@nestjs/typeorm"; import { Repository } from "typeorm"; import { CozePackageOrder } from "../entities/coze-package-order.entity"; import { CozePackageOrderListDto } from "../dto/coze-package-order-list.dto"; import { CozePackageOrderRefundDto } from "../dto/coze-package-order-refund.dto"; @Injectable() export class CozePackageOrderService extends BaseService<CozePackageOrder> { constructor( @InjectRepository(CozePackageOrder) protected readonly repository: Repository<CozePackageOrder>, @InjectRepository(User) private readonly userRepository: Repository<User>, @InjectRepository(CozePackage) private readonly cozePackageRepository: Repository<CozePackage>, ) { super(repository); } /** * 获取Coze套餐订单列表 */ async getList(dto: CozePackageOrderListDto) { const { page, pageSize, orderNo, keyword, payStatus, refundStatus } = dto; const queryBuilder = this.repository .createQueryBuilder("order") .leftJoinAndSelect("order.user", "user") .leftJoinAndSelect("order.cozePackage", "cozePackage") .orderBy("order.createdAt", "DESC"); // 订单号搜索 if (orderNo) { queryBuilder.andWhere("order.orderNo LIKE :orderNo", { orderNo: `%${orderNo}%` }); } // 用户关键字搜索 if (keyword) { queryBuilder.andWhere( "(user.id = :keyword OR user.nickname LIKE :keywordLike OR user.phone LIKE :keywordLike)", { keyword, keywordLike: `%${keyword}%` } ); } // 支付状态筛选 if (payStatus && payStatus !== 'all') { queryBuilder.andWhere("order.payStatus = :payStatus", { payStatus: parseInt(payStatus) }); } // 退款状态筛选 if (refundStatus && refundStatus !== 'all') { queryBuilder.andWhere("order.refundStatus = :refundStatus", { refundStatus: parseInt(refundStatus) }); } // 分页查询 const [list, total] = await queryBuilder .skip((page - 1) * pageSize) .take(pageSize) .getManyAndCount(); return { list, pagination: { page, pageSize, total, totalPages: Math.ceil(total / pageSize) } }; } /** * 获取Coze套餐订单详情 */ async getDetail(id: string) { const order = await this.repository .createQueryBuilder("order") .leftJoinAndSelect("order.user", "user") .leftJoinAndSelect("order.cozePackage", "cozePackage") .where("order.id = :id", { id }) .getOne(); if (!order) { throw new NotFoundException("订单不存在"); } return order; } /** * 申请Coze套餐订单退款 */ async refund(dto: CozePackageOrderRefundDto) { const order = await this.getDetail(dto.orderId); // 业务规则验证 if (order.payStatus !== 1) { throw new BadRequestException("订单未支付,无法申请退款"); } if (order.refundStatus === 1) { throw new BadRequestException("订单已退款,无法重复申请"); } // 30天时间限制检查 const createdTime = new Date(order.createdAt).getTime(); const now = Date.now(); const thirtyDays = 30 * 24 * 60 * 60 * 1000; if (now - createdTime > thirtyDays) { throw new BadRequestException("订单超过30天,无法申请退款"); } // 执行退款逻辑 order.refundStatus = 1; order.refundTime = new Date(); order.refundAmount = order.payAmount; await this.repository.save(order); return { success: true }; } } - 技术特点:
- 继承BaseService获得基础CRUD功能
- TypeORM QueryBuilder复杂查询构建
- 多表关联查询(order、user、cozePackage)
- 完整的业务规则验证
- 30天退款期限检查
- 事务性退款处理
3.3 数据实体 ✅ 已完成
- 文件路径:
apps/server/src/modules/console/coze-package/entities/coze-package-order.entity.ts - 开发状态:✅ 已完成
- 功能描述:定义Coze套餐订单数据库实体,配置字段映射和关联关系
- 实际代码实现:
import { Column, Entity, JoinColumn, ManyToOne } from "typeorm"; import { BaseEntity } from "@common/base"; import { User } from "@common/modules/auth/entities/user.entity"; import { CozePackage } from "@common/modules/coze-package/entities/coze-package.entity"; @Entity("coze_package_order") export class CozePackageOrder extends BaseEntity { @Column({ type: "varchar", length: 32, unique: true, comment: "订单号" }) orderNo: string; @Column({ type: "varchar", length: 32, comment: "订单来源" }) orderSource: string; @Column({ type: "varchar", length: 32, comment: "订单类型" }) orderType: string; @Column({ type: "uuid", comment: "用户ID" }) userId: string; @ManyToOne(() => User) @JoinColumn({ name: "userId" }) user: User; @Column({ type: "uuid", comment: "套餐ID" }) cozePackageId: string; @ManyToOne(() => CozePackage) @JoinColumn({ name: "cozePackageId" }) cozePackage: CozePackage; @Column({ type: "decimal", precision: 10, scale: 2, comment: "订单金额" }) orderAmount: number; @Column({ type: "decimal", precision: 10, scale: 2, comment: "实付金额" }) payAmount: number; @Column({ type: "tinyint", comment: "支付方式 1:微信 2:支付宝" }) payType: number; @Column({ type: "tinyint", default: 0, comment: "支付状态 0:未支付 1:已支付" }) payStatus: number; @Column({ type: "datetime", nullable: true, comment: "支付时间" }) payTime: Date; @Column({ type: "tinyint", default: 0, comment: "退款状态 0:未退款 1:已退款" }) refundStatus: number; @Column({ type: "datetime", nullable: true, comment: "退款时间" }) refundTime: Date; @Column({ type: "decimal", precision: 10, scale: 2, nullable: true, comment: "退款金额" }) refundAmount: number; } - 技术特点:
- 继承BaseEntity获得基础字段
- TypeORM装饰器配置
- 多表关联配置(@ManyToOne)
- 完整的字段约束和注释
- 支持decimal金额类型
- 时间字段可选配置
3.4 DTO定义 ✅ 已完成
- 列表查询DTO:
apps/server/src/modules/console/coze-package/dto/coze-package-order-list.dto.ts✅ - 退款申请DTO:
apps/server/src/modules/console/coze-package/dto/coze-package-order-refund.dto.ts✅ - 开发状态:✅ 已完成
- 功能描述:定义数据传输对象,配置请求参数验证和类型转换
- 列表查询DTO代码:
import { IsOptional, IsString, IsIn, IsNumberString } from "class-validator"; import { ApiPropertyOptional } from "@nestjs/swagger"; export class CozePackageOrderListDto { @ApiPropertyOptional({ description: "页码", default: 1 }) @IsOptional() @IsNumberString() page?: number = 1; @ApiPropertyOptional({ description: "每页条数", default: 20 }) @IsOptional() @IsNumberString() pageSize?: number = 20; @ApiPropertyOptional({ description: "订单号" }) @IsOptional() @IsString() orderNo?: string; @ApiPropertyOptional({ description: "用户关键字(ID/昵称/手机号)" }) @IsOptional() @IsString() keyword?: string; @ApiPropertyOptional({ description: "支付状态(all:全部 0:未支付 1:已支付)", enum: ["all", "0", "1"] }) @IsOptional() @IsIn(["all", "0", "1"]) payStatus?: string = "all"; @ApiPropertyOptional({ description: "退款状态(all:全部 0:未退款 1:已退款)", enum: ["all", "0", "1"] }) @IsOptional() @IsIn(["all", "0", "1"]) refundStatus?: string = "all"; } - 退款申请DTO代码:
import { IsNotEmpty, IsString, IsUUID } from "class-validator"; import { ApiProperty } from "@nestjs/swagger"; export class CozePackageOrderRefundDto { @ApiProperty({ description: "订单ID" }) @IsNotEmpty() @IsUUID() orderId: string; @ApiProperty({ description: "退款原因" }) @IsNotEmpty() @IsString() refundReason: string; } - 技术特点:
- class-validator验证装饰器
- Swagger API文档注释
- 完整的参数验证规则
- 默认值配置
- 类型安全的数据转换
4. 待开发文件清单
4.1 待开发文件清单 🚧
- 配置文件更新:
apps/server/src/core/database/install/menu.json- 添加Coze套餐订单管理菜单配置apps/server/src/core/database/upgrade/1.0.0-beta.10/index.ts- 数据库迁移脚本apps/server/package.json- 更新版本号到1.0.0-beta.10apps/server/src/modules/console/console.module.ts- 注册CozePackageModule
BuildingAI Coze套餐订单页面开发文件清单
└──── 前端文件(14个)
│ │ ├── 主页面组件:apps/web/app/console/order-management/coze-package-order/index.vue
│ │ ├── 订单详情弹窗组件:apps/web/app/console/order-management/coze-package-order/components/coze-package-order-detail.vue
│ │ ├── 退款申请弹窗组件:apps/web/app/console/order-management/coze-package-order/components/refund-application.vue
│ │ ├── 数据模型定义:apps/web/models/coze-package-order.d.ts
│ │ ├── API服务层:apps/web/services/console/coze-package-order.ts
│ │ └── 国际化文件(9个语言)
│ │ ├── 页面国际化(3个):apps/web/core/i18n/{zh,en,jp}/console-coze-package-order.json
│ │ ├── 通用国际化(3个):apps/web/core/i18n/{zh,en,jp}/console-common.json
│ │ └── 菜单国际化(3个):apps/web/core/i18n/{zh,en,jp}/console-menu.json
│ └── 后端文件(6个)
│ ├── 控制器:apps/server/src/modules/console/coze-package/coze-package-order.controller.ts
│ ├── 业务服务:apps/server/src/modules/console/coze-package/coze-package-order.service.ts
│ ├── 数据实体:apps/server/src/modules/console/coze-package/entities/coze-package-order.entity.ts
│ ├── DTO定义(2个):
│ │ ├── 列表查询DTO:apps/server/src/modules/console/coze-package/dto/coze-package-order-list.dto.ts
│ │ ├── 退款申请DTO:apps/server/src/modules/console/coze-package/dto/coze-package-order-refund.dto.ts
│ └── 模块配置:apps/server/src/modules/console/coze-package/coze-package.module.ts
└── 配置和数据库升级文件(4个)
├── 菜单配置文件(1个)apps/server/src/core/database/install/menu.json
├── 数据库升级脚本apps/server/src/core/database/upgrade/1.0.0-beta.10/index.ts
├── 后台版本配置文件(1个):apps/server/package.json
├── 注册模块:更新apps/server/src/modules/console/console.module.ts
5. 开发时间计划
5.1 详细开发阶段
第1天:前端基础开发
时间安排:8小时
主要任务:
- 上午(4小时):
- 创建页面组件:
apps/web/app/console/order-management/coze-package-order/index.vue - 设置页面布局和基础UI结构(订单列表、搜索筛选、分页组件)
- 配置页面路由和菜单项
- 创建页面组件:
- 下午(4小时):
- 创建数据模型:
apps/web/models/coze-package-order.d.ts - 实现API服务:
apps/web/services/console/coze-package-order.ts - 配置表单验证和数据绑定
- 创建数据模型:
交付物:前端页面基础框架完成
验收标准:页面可正常访问,基础UI组件显示正常
第2天:订单列表和搜索功能开发
时间安排:8小时
主要任务:
- 上午(4小时):
- 实现订单列表展示功能
- 配置表格列定义(订单号、用户信息、套餐信息、金额、状态等)
- 实现订单状态标签和样式
- 下午(4小时):
- 实现高级搜索功能(订单号、用户关键字、支付状态、退款状态、时间范围)
- 配置筛选器组件和交互逻辑
- 实现分页和排序功能
交付物:订单列表和搜索功能完成
验收标准:列表展示正常,搜索筛选功能正确
第3天:订单详情和退款功能开发
时间安排:8小时
主要任务:
- 上午(4小时):
- 创建订单详情弹窗组件:
apps/web/app/console/order-management/coze-package-order/components/coze-package-order-detail.vue - 实现订单详情查看功能
- 设计订单详情弹窗布局和样式
- 展示完整的订单信息和支付信息
- 实现订单状态标签和金额格式化
- 创建订单详情弹窗组件:
- 下午(4小时):
- 创建退款申请弹窗组件:
apps/web/app/console/order-management/coze-package-order/components/refund-application.vue - 实现退款申请功能
- 配置退款申请表单和验证规则
- 实现退款原因选择和其他原因输入
- 实现退款金额计算和确认选项
- 配置退款状态更新和提示
- 创建退款申请弹窗组件:
交付物:订单详情和退款功能完成
验收标准:详情查看正常,退款流程完整,弹窗组件功能正常
第4天:国际化和权限配置
时间安排:8小时
主要任务:
-
上午(4小时):
- 配置页面国际化文件:
apps/web/core/i18n/zh/console-coze-package-order.jsonapps/web/core/i18n/en/console-coze-package-order.jsonapps/web/core/i18n/jp/console-coze-package-order.json
- 配置通用国际化文件:
apps/web/core/i18n/zh/console-common.jsonapps/web/core/i18n/en/console-common.jsonapps/web/core/i18n/jp/console-common.json
- 更新菜单国际化文件:
apps/web/core/i18n/zh/console-menu.jsonapps/web/core/i18n/en/console-menu.jsonapps/web/core/i18n/jp/console-menu.json
- 配置页面国际化文件:
-
下午(4小时):
- 配置权限装饰器:在控制器中添加
@Permissions - 更新菜单配置:
apps/server/src/core/database/install/menu.json- 添加Coze套餐订单管理菜单项配置
- 设置菜单层级结构(父菜单:console-order-management)
- 配置菜单图标(heroicons:document-text)和排序
- 绑定权限控制(coze-package-order:list, coze-package-order:detail, coze-package-order:refund)
- 设置路由路径(/console/order-management/coze-package-order)
- 配置多语言支持的元数据
- 更新权限配置:完善权限定义和描述
- coze-package-order:list:查看Coze套餐订单列表权限
- coze-package-order:detail:查看Coze套餐订单详情权限
- coze-package-order:refund:申请Coze套餐订单退款权限
- 测试权限验证功能和菜单显示
- 配置权限装饰器:在控制器中添加
交付物:国际化和权限系统配置完成
验收标准:多语言切换正常,权限控制生效,通用国际化文件配置完整
第5天:数据实体和DTO开发
时间安排:8小时
主要任务:
- 上午(4小时):
- 创建数据库实体:
apps/server/src/modules/console/coze-package/entities/coze-package-order.entity.ts- 定义订单表结构(订单号、用户ID、套餐信息、金额、状态等)
- 配置字段类型、约束和索引
- 设置实体关联关系
- 创建数据库实体:
- 下午(4小时):
- 配置DTO和数据传输对象:
- 创建查询DTO:
apps/server/src/modules/console/coze-package/dto/coze-package-order.dto.ts- QueryCozePackageOrderDto:用于接收前端查询请求参数
- 包含分页、筛选、排序等参数
- 创建退款DTO:
apps/server/src/modules/console/coze-package/dto/coze-package-refund-order.dto.ts- CozePackageRefundOrderDto:用于接收退款申请数据
- 包含订单ID等必要参数
- 配置class-validator数据验证规则和class-transformer类型转换
- 创建查询DTO:
- 配置DTO和数据传输对象:
交付物:数据实体和DTO完成
验收标准:数据模型定义正确,验证规则生效
第6天:后端控制器和服务开发
时间安排:8小时
主要任务:
- 上午(4小时):
- 创建服务层:
apps/server/src/modules/console/coze-package/services/coze-package-order.service.ts- 继承BaseService并注入TypeORM Repository
- 实现订单查询业务逻辑(分页、筛选、排序)
- 实现订单详情获取逻辑
- 实现退款申请业务逻辑
- 集成数据验证和业务规则
- 处理异常和错误响应
- 创建服务层:
- 下午(4小时):
- 创建控制器:
apps/server/src/modules/console/coze-package/controllers/coze-package-order.controller.ts- 实现订单列表查询接口(GET /api/console/coze-package-order)
- 实现订单详情查询接口(GET /api/console/coze-package-order/:id)
- 实现退款申请接口(POST /api/console/coze-package-order/refund)
- 创建控制器:
交付物:后端控制器和服务层完成
验收标准:API接口可正常访问,业务逻辑正确
第7天:模块注册和基础测试
时间安排:8小时
主要任务:
- 上午(4小时):
- 创建CozePackageModule:
apps/server/src/modules/console/coze-package/coze-package.module.ts - 注册模块:更新
apps/server/src/modules/console/console.module.ts - 配置模块依赖和导入关系
- 创建CozePackageModule:
- 下午(4小时):
- 接口基础测试:验证API端点可正常访问
- 前后端API联调测试
- 数据流测试和验证
交付物:模块注册和基础测试完成
验收标准:模块加载正常,基础接口测试通过
第8天:数据库迁移和初始化
时间安排:8小时
主要任务:
- 上午(4小时):
- 创建数据库迁移文件:
apps/server/src/core/database/upgrade/1.0.0-beta.10/index.ts- 通过 TypeORM 实体自动同步表结构
- 实现 Coze 套餐订单表的创建逻辑
- 集成默认数据初始化和示例数据插入
- 确保与现有数据库升级机制兼容
- 创建数据库迁移文件:
- 下午(4小时):
- 更新版本号:
apps/server/package.json(版本号改为1.0.0-beta.10) - 数据库迁移测试:验证
index.ts脚本执行 - 数据完整性验证:检查表结构和初始数据
- 回滚机制测试:确保迁移可逆性
- 更新版本号:
交付物:数据库迁移和初始化完成
验收标准:数据库表创建成功,迁移脚本正常工作
第9天:权限系统集成测试
时间安排:8小时
主要任务:
- 上午(4小时):
- 权限控制测试:验证各个接口的权限验证
- 菜单权限测试:确认菜单显示和隐藏逻辑
- 角色权限测试:测试不同角色的访问权限
- 下午(4小时):
- 国际化功能测试:验证多语言切换
- 用户体验测试:检查界面交互和提示信息
- 边界条件测试:测试异常情况处理
交付物:权限系统集成测试完成
验收标准:权限控制正确,用户体验良好
第10天:功能完整性测试
时间安排:8小时
主要任务:
- 上午(4小时):
- 订单列表功能测试:验证搜索、筛选、分页、排序
- 订单详情功能测试:验证详情展示和数据准确性
- 退款功能测试:验证退款申请流程和状态更新
- 下午(4小时):
- 数据一致性测试:验证前后端数据同步
- 性能测试:检查页面加载速度和响应时间
- 兼容性测试:验证不同浏览器的兼容性
交付物:功能完整性测试完成
验收标准:所有功能正常工作,性能达标
第11天:集成测试和Bug修复
时间安排:8小时
主要任务:
- 上午(4小时):
- 端到端测试:完整业务流程测试
- 并发测试:多用户同时操作测试
- 压力测试:大数据量情况下的性能测试
- 下午(4小时):
- Bug修复:解决测试中发现的问题
- 代码优化:性能优化和代码重构
- 安全测试:验证数据安全和权限安全
交付物:集成测试和Bug修复完成
验收标准:主要Bug已修复,系统稳定运行
第12天:单元测试和代码审查
时间安排:8小时
主要任务:
- 上午(4小时):
- 编写单元测试:
- 前端组件测试
- 后端服务测试
- API接口测试
- 工具函数测试
- 编写单元测试:
- 下午(4小时):
- 代码审查:检查代码质量和规范
- 文档完善:更新技术文档和注释
- 测试覆盖率检查:确保测试覆盖率达标
交付物:单元测试和代码审查完成
验收标准:测试覆盖率达到80%以上,代码质量良好
第13天:部署配置和环境测试
时间安排:8小时
主要任务:
- 上午(4小时):
- 配置开发环境部署
- 配置测试环境部署
- 环境变量和配置文件设置
- 下午(4小时):
- 配置生产环境部署
- 部署脚本编写和测试
- 环境切换测试
交付物:部署配置完成
验收标准:各环境部署正常,切换无问题
第14天:最终验收和文档完善
时间安排:8小时
主要任务:
- 上午(4小时):
- 最终功能验收测试
- 用户验收测试(UAT)
- 性能基准测试
- 下午(3.2小时):
- 完善技术文档
- 编写用户使用手册
- 项目交付准备
- 配置集成(0.8小时):
- 最终配置检查和优化
交付物:项目最终交付
验收标准:所有功能验收通过,文档齐全
5.2 里程碑时间节点
里程碑1:前端基础功能完成(第3天结束)
- 时间:第3个工作日 18:00
- 验收标准:
- 订单列表页面可以正常访问和渲染
- 搜索筛选功能正常工作
- 订单详情查看功能完成
- 退款申请功能基本完成
- 风险评估:低风险
- 应急预案:如有延期,可压缩UI美化时间
里程碑2:权限配置和国际化完成(第4天结束)
- 时间:第4个工作日 18:00
- 验收标准:
- 多语言国际化配置生效
- 权限验证功能正常(使用现有的 @Permissions() 装饰器)
- 菜单配置完成(menu.json更新成功)
- 菜单项在系统中正确显示
- 订单管理相关权限配置完成
- 风险评估:中等风险
- 应急预案:如有延期,可简化部分权限细节
里程碑3:后端服务开发完成(第7天结束)
- 时间:第7个工作日 18:00
- 验收标准:
- 数据库实体文件创建完成
- DTO和数据传输对象配置完成
- Service业务逻辑层实现完成(直接继承BaseService)
- 后端API接口开发完成(订单列表、详情、退款)
- 服务层和控制器正常工作
- 模块注册成功
- 接口基础测试通过
- 风险评估:中等风险
- 应急预案:如有延期,优先保证核心接口功能
里程碑4:数据库和配置完成(第8天结束)
- 时间:第8个工作日 18:00
- 验收标准:
- 订单数据库表创建成功
- 数据迁移脚本执行正常
- 版本号更新完成
- 基础数据初始化成功
- 风险评估:高风险
- 应急预案:如有延期,优先保证核心数据库结构
里程碑5:功能测试通过(第11天结束)
- 时间:第11个工作日 18:00
- 验收标准:
- 前后端完全集成
- 主要功能测试通过
- 权限系统正常工作
- 性能指标达标
- 风险评估:中等风险
- 应急预案:如有问题,优先修复核心功能Bug
里程碑6:部署上线(第14天结束)
- 时间:第14个工作日 18:00
- 验收标准:
- 开发环境部署成功
- 测试环境验证通过
- 生产环境准备就绪
- 用户验收测试通过
- 风险评估:低风险
- 应急预案:如有部署问题,可延期至第15天
5.3 风险缓冲时间安排
- 每日风险缓冲:每天预留1-2小时处理突发问题
- 阶段性缓冲:第7天和第11天各预留额外2小时
- 总体缓冲:预留0.4天作为整体缓冲时间(配置集成优化)
- 紧急预案:如遇重大技术难题,可申请额外1-2天开发时间
5.4 并行开发策略
- 第1-4天:前端开发优先,建立基础框架
- 第5-8天:后端开发集中进行,确保API稳定
- 第9-11天:测试和集成并行进行,提高效率
- 第12-14天:部署和文档并行完成,确保交付质量
项目总结:BuildingAI Coze套餐订单页面是一个技术先进、功能完整、架构清晰的企业级订单管理系统。通过14天的精心开发,系统不仅满足了当前的业务需求,更为未来的功能扩展和技术演进奠定了坚实的基础。项目成功实现了订单管理、退款处理、多语言支持等核心功能,同时在性能优化、用户体验、代码质量等方面都达到了企业级标准。
更多推荐



所有评论(0)