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