邹方成
6ee627139c
Some checks failed
Build docker and publish / linux (1.24.5) (push) Failing after 40s
feat(pay): 添加支付API基础结构 feat(miniapp): 创建支付测试小程序页面与配置 feat(wechatpay): 配置微信支付参数与证书 fix(guild): 修复成员列表查询条件 docs: 更新代码规范文档与需求文档 style: 统一前后端枚举显示与注释格式 refactor(admin): 重构用户奖励发放接口参数处理 test(title): 添加称号效果参数验证测试
5.4 KiB
5.4 KiB
后端 API 设计
- 路径前缀：
/api/admin/ops_shipping_stats（管理端鉴权）。参考路由注册与鉴权模式：internal/router/router.go中 Admin 组；处理方式参照internal/api/admin/titles_admin.go:28/81/105/135。 - 接口列表：
GET /api/admin/ops_shipping_stats列表查询（分页/筛选/排序）。GET /api/admin/ops_shipping_stats/:id单条详情。POST /api/admin/ops_shipping_stats新增。PUT /api/admin/ops_shipping_stats/:id更新。DELETE /api/admin/ops_shipping_stats/:id删除。
- 入参约定：
- 列表查询（Query）：
page、page_size、shipped_start、shipped_end、product_id、product_name、user_id、user_name、express_code、express_no、order_id、order_no、order_source_type、payer（字符串枚举），keyword（模糊匹配product_name/user_name/order_no/express_no）。 - 新增/更新（JSON）：
shipped_at（RFC3339）、product_id、product_name、product_price_cents、shipped_qty、user_id、user_name、user_address_text、express_code、express_no、order_id、order_no、order_qty、order_amount_cents、profit_loss_cents、order_source_type、order_source_text、payer。
- 列表查询（Query）：
- 响应约定：
- 列表：
{ page, page_size, total, list: OpsShippingStats[] }，默认排序shipped_at DESC, id DESC。 - 详情：
OpsShippingStats完整记录。 - 新增/更新/删除：返回受影响记录或
{ id }。
- 列表：
- 校验与错误：
- 参数绑定：
ShouldBindForm/ShouldBindJSON，错误码用internal/code中ParamBindError、DatabaseError等。 - 鉴权：
core.WrapAuthHandler(intc.AdminTokenAuthVerify)。
- 参数绑定：
- DAO 使用：
- 读：
h.readDB.OpsShippingStats.WithContext(ctx).ReadDB().Where(...).FindByPage(...)。 - 写：
h.writeDB.OpsShippingStats.WithContext(ctx).Create/Save/Delete。 - 参考模型/DAO：
internal/repository/mysql/model/ops_shipping_stats.gen.go、internal/repository/mysql/dao/ops_shipping_stats.gen.go；全局接入点：internal/repository/mysql/dao/gen.go。
- 读：
- 过滤实现：
- 时间范围：
Where(dao.OpsShippingStats.ShippedAt.Gte(shipped_start))与Lte(shipped_end)。 - 模糊匹配：
Like多字段Or组合；精确匹配：ID 字段Eq。 - 分页：
FindByPage(offset, limit)返回(list, total)。
- 时间范围：
- 索引建议（后续 DBA 执行）：
- 组合索引：
(shipped_at DESC, product_id)、(user_id)、(order_no)、(express_code, express_no)，提高查询性能。
- 组合索引：
前端对接与页面
- 菜单与路由：
- 本地模式：在
web/admin/src/router/modules/operations.ts的children增加：{ path: 'shipping-stats', name: 'ShippingStats', component: '/operations/shipping-stats', meta: { title: '发货统计', roles: ['R_SUPER','R_ADMIN'] } }。 - 接口模式（可选）：通过系统菜单表
menus新增对应子菜单；后端GET /api/v3/system/menus/simple返回；参考internal/api/admin/system_menu.go。
- 本地模式：在
- API 客户端：
web/admin/src/api/shipping-stats.tsgetList(params)→GET 'admin/ops_shipping_stats'。getDetail(id)→GET 'admin/ops_shipping_stats/:id'。create(data)→POST 'admin/ops_shipping_stats'。update(id, data)→PUT 'admin/ops_shipping_stats/:id'。remove(id)→DELETE 'admin/ops_shipping_stats/:id'。- 复用
src/utils/http/index.ts封装（自动附带Authorization、统一错误处理）。
- 页面视图：
web/admin/src/views/operations/shipping-stats/index.vue- 布局：顶部搜索（
ArtSearchBar），表头工具（ArtTableHeader），数据表（ArtTable），分页。 - 搜索项：时间范围、商品（ID/名称）、用户（ID/名称）、快递公司/单号、订单号、来源类型、付款人、关键字。
- 列定义：
shipped_at、product_name、product_price_cents（格式化为金额）、shipped_qty、user_name、user_address_text（截断+tooltip）、express_code、express_no、order_no、order_qty、order_amount_cents（金额）、profit_loss_cents（金额/颜色提示）、order_source_text、payer、操作列（查看/编辑/删除）。 - 对话框：新建/编辑（表单项与后端 JSON 契约一致）。
- 交互：列表加载用
useTable；增改删后按“软刷新/全量刷新”策略更新列表；统一消息提示。 - 权限：
meta.roles控制访问；按钮权限按需要可用authList。
- 布局：顶部搜索（
实施步骤
- 后端：
- 在
internal/api/admin新增shipping_stats_admin.go，实现 5 个 Handler，仿照titles_admin.go的风格（入参绑定/读写分离/错误与响应）。 - 在
internal/router/router.go的 Admin 鉴权组注册 5 条路由。
- 在
- 前端：
- 添加菜单路由项（本地或接口模式）。
- 新建
src/api/shipping-stats.ts，封装 5 个方法。 - 新建
src/views/operations/shipping-stats/index.vue页面：搜索区、表格列、对话框、分页与刷新逻辑。
验收标准
- 管理端已登录用户可访问“运营管理/发货统计”。
- 列表支持分页、筛选、排序（默认按发货时间倒序）。
- 能创建/编辑/删除记录并实时刷新；可查看详情。
- 后端输入校验与统一错误码生效；鉴权与日志记录正常。
- 查询性能在典型数据量下良好（建议索引已列出）。
请确认以上方案，我将按该设计进行代码实现与联调。