邹方成
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): 添加称号效果参数验证测试
65 lines
5.4 KiB
Markdown
65 lines
5.4 KiB
Markdown
**后端 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`。
|
||
- 响应约定：
|
||
- 列表：`{ 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.ts`
|
||
- `getList(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` 页面：搜索区、表格列、对话框、分页与刷新逻辑。
|
||
|
||
**验收标准**
|
||
- 管理端已登录用户可访问“运营管理/发货统计”。
|
||
- 列表支持分页、筛选、排序（默认按发货时间倒序）。
|
||
- 能创建/编辑/删除记录并实时刷新；可查看详情。
|
||
- 后端输入校验与统一错误码生效；鉴权与日志记录正常。
|
||
- 查询性能在典型数据量下良好（建议索引已列出）。
|
||
|
||
请确认以上方案，我将按该设计进行代码实现与联调。 |