180 lines
13 KiB
Markdown
180 lines
13 KiB
Markdown
# 2026-06-10
|
||
|
||
## 通用报表引擎 - 补充前端 CRUD 能力
|
||
|
||
为 `common/report` 包补充了配置的 CRUD 接口，使前端可以直接维护报表配置，无需操作数据库。
|
||
|
||
### 新增文件变更
|
||
- `model/model.go`: 新增 SaveBusinessReq/SaveReportReq/SaveFieldReq/SaveExtractConfigReq 等请求结构体，SaveResult/DeleteResult 响应结构体
|
||
- `config/loader.go`: 新增 Create/Update/Delete + GetByID 方法（Business/Report/Field/ExtractConfig 四种配置）
|
||
- `api.go`: 新增 SaveBusiness/SaveReport/SaveField/SaveExtractConfig + Delete/Get 接口（新增/修改合一，id 为空则新增）
|
||
- `example_usage.go`: 新增第五、六节，CRUD 调用示例 + 任意新平台零代码接入流程
|
||
|
||
### 关键设计决策
|
||
- **Save 合一**：通过 `ID *int64` 区分新增（nil）和修改（有值），简化前端调用
|
||
- **软删除**：status → INACTIVE + deleted_at=NOW()，数据不丢失
|
||
- **缓存失效**：写操作后自动失效对应业务/报表缓存，保证下次读取一致性
|
||
- 所有 CRUD 方法先调用 initTables() 确保表存在
|
||
|
||
### example_usage.go 完整重写
|
||
将示例文件从分节的注释风格重写为6个完整场景的 Go 函数示例：
|
||
1. **快手电商完整接入**（最详细，从业务注册到前端查询6步全流程）
|
||
2. **已有配置的 CRUD 二次开发参考**（业务/报表/字段/抽取 增删改查）
|
||
3. **任意平台接入通用模式**（淘宝示例，零硬编码）
|
||
4. **外部业务服务调用**（goview-report 等直接 import）
|
||
5. **Direct 模式示例**（不聚合的逐行抽取）
|
||
6. **前端 HTTP API 交互流程**（伪代码，展示 API 调用顺序）
|
||
|
||
每个场景都有实际可运行的代码片段、生成的 SQL 预览、返回值输出示例。
|
||
|
||
## 报表引擎管理前端页面
|
||
|
||
为报表引擎创建了可直接使用的前端管理页面，访问 `/admin/report`。
|
||
|
||
### 新增文件
|
||
- `controller/report/report_controller.go`: HTTP API Controller，16个端点暴露公共报表服务的全部能力（业务/报表/字段/抽取配置的 CRUD、数据抽取触发、自动建表、用户选择查询）
|
||
- `controller/report/report_admin_controller.go`: 嵌入式HTML SPA，5个Tab页：
|
||
- **业务管理**：列表 CRUD
|
||
- **报表配置**：按业务筛选列表 CRUD
|
||
- **字段配置**：按业务+报表筛选，维度/指标/筛选角色管理
|
||
- **抽取配置**：按业务+报表筛选，支持 DIRECT/AGGREGATE 模式配置 + 一键执行抽取
|
||
- **数据查询**：可视化维度选择器、指标聚合选择器、筛选条件构建器、查询结果展示
|
||
- `main.go`: 注册 reportCtrl.ReportController 到 RouteRegister + `/admin/report` 页面路由
|
||
|
||
### 技术要点
|
||
- 纯原生 HTML/CSS/JS，零框架依赖，与现有管理后台 `/admin` 风格统一
|
||
- 所有 CRUD 通过 `ID *int64` 区分新增（nil）/修改（有值）
|
||
- 查询Tab支持动态字段选择：维度多选、指标聚合方式选择、筛选条件动态构建（支持 BETWEEN/IN 等操作符）
|
||
- 管理后台页面增加了返回链接 `← 返回管理后台`
|
||
|
||
## 修复 report_common_ddl.sql 语法错误
|
||
|
||
PostgreSQL 不支持 MySQL 风格的内联 `COMMENT '...'` 语法。修复了全部5张表的列定义：
|
||
- 移除所有列定义中的内联 `COMMENT 'xxx'`（MySQL 语法）
|
||
- 已有的 `COMMENT ON COLUMN` 独立语句保留不变
|
||
- `report_extract_log` 表补充了缺失的 `COMMENT ON COLUMN` 语句（business_code/report_code/extract_code/stat_date/extract_type/status/total_count/success_count/fail_count）
|
||
|
||
关键区别：MySQL 支持 `column_name VARCHAR(64) COMMENT 'xxx'`，PostgreSQL 必须用 `COMMENT ON COLUMN table.column IS 'xxx'`。
|
||
|
||
## 补充 tenant_id 到报表系统表
|
||
|
||
5张报表系统表原先缺失 `tenant_id`，与项目核心表（`init_core_tables.sql`）不一致。修改内容：
|
||
- **DDL SQL** (`sql/report_common_ddl.sql`)：5张表全部新增 `tenant_id BIGINT NOT NULL DEFAULT 0` 列，所有 UNIQUE 约束和索引都加入 tenant_id
|
||
- **Go initTables** (`common/report/report.go`)：同步更新 5 张表的 DDL 定义，加上 tenant_id
|
||
- 约束变更：`uk_business_report_code UNIQUE (business_code, report_code)` → `(tenant_id, business_code, report_code)`，其余类推
|
||
|
||
当前 report 模块租户支持为占位符级别（硬编码 tenant_id=1），后续需从 context 动态获取。
|
||
- **单独迁移脚本**: `sql/report_add_tenant_id.sql`，对已存在的表执行 ALTER TABLE ADD COLUMN + 重建约束/索引
|
||
|
||
## 快手电商报表初始化种子数据
|
||
|
||
**初版（已废弃）**：字段名随意捏造，与真实 DDL 不对齐。
|
||
|
||
**重写版** `sql/seed_data_report_kuaishou.sql`（基于 seed_data_kuaishou.sql 实际 DDL）：
|
||
- 1 条业务配置 (kuaishou_ecommerce)
|
||
- 5 条报表配置：order_analysis / item_analysis / refund_analysis / cps_order_analysis / dropshipping_analysis
|
||
- 76 条字段配置（订单23+商品15+售后12+分销13+代发13），含维度/指标/衍生字段
|
||
- 5 条抽取配置（AGGREGATE 聚合模式，每个报表一条）
|
||
|
||
**严格设计原则**：
|
||
- sourceField 对齐源表实际列名（camelCase：oid, status, createTime, totalFee, buyerNick 等）
|
||
- targetField / field_code 使用 snake_case（stat_date, total_fee, buyer_nick 等）
|
||
- 金额字段源表存分(BIGINT)，报表提供衍生元字段(CALCULATED expression / 100.0)
|
||
- 增量抽取依据统一用 updateTime（毫秒时间戳 BIGINT）
|
||
- transform_rules：ts_to_date FORMAT createTime → stat_date(yyyy-MM-dd)
|
||
- 所有 INSERT 使用 ON CONFLICT DO NOTHING 保证幂等
|
||
|
||
## 修复报表管理前端编辑不显示数据问题
|
||
|
||
在 `report_admin_controller.go` 中修复了编辑弹窗不显示数据的问题：
|
||
|
||
**根因**：
|
||
- GoFrame `MiddlewareHandlerResponse` 包裹响应为 `{code:0, data: <struct>}`，而单条查询返回结构体为 `getBusinessRes{Data: ...}` 序列化为 `{"data": {...}}`，最终响应为 `{code:0, data: {"data": {...}}}` 双层嵌套
|
||
- 某些 GoFrame 版本可能序列化 Go 字段名（首字母大写 `Data`）而非 json tag（`data`），导致 `res.data` 为 undefined
|
||
|
||
**修复内容**：
|
||
1. `api()` 函数增加兼容逻辑：当 `json.data.Data` 存在而 `json.data.data` 不存在时，自动取 `json.data.Data`
|
||
2. `api()` 函数增加 `console.log` 调试日志，打印原始响应和解包后的数据
|
||
3. 四个编辑函数（`openBizModal/openReportModal/openFieldModal/openExtractModal`）：
|
||
- 增加 fallback：`res.data !== undefined ? res.data : res.Data`
|
||
- 增加数据有效性校验：`if (!d || !d.id)` 时弹出错误提示并阻止打开空表单
|
||
- 增加 `console.log` 调试日志
|
||
|
||
## 修复 report_report_config 查询 SQL 永假条件问题
|
||
|
||
**现象**：查询 `report_report_config` 时生成的 SQL 包含 `WHERE (("id" = 1) AND ("id" = 0 AND "business_code" = '' AND ...))`，id 不可能同时为 1 和 0，导致查询始终返回 0 行。
|
||
|
||
**根因**：`common/db/gfdb/gfdb.go` 中 `Model()` 方法使用了 `OmitNil()`（只过滤 nil 指针，不过滤零值）。当 GoFrame v2 内部的软删除机制（`deleted_at IS NULL`）自动构建 struct WHERE 条件时，由于 `OmitNil()` 不忽略零值字段，结构体中所有字段的零值（`id=0`, `business_code=""`, `report_code=""` 等）都被加入 WHERE 条件，与显式的 `Where("id", 1)` 叠加形成 `id=1 AND id=0` 的永假条件。
|
||
|
||
**修复**：`OmitNil()` **保留**，额外追加 `.OmitEmptyWhere()`，两者同时生效：
|
||
- `OmitNil()`：保持 INSERT/UPDATE 的 Data() 行为不变（nil 指针/map 字段不写入 SQL，走 DB 默认值），避免破坏数据引擎写入逻辑
|
||
- `OmitEmptyWhere()`：过滤 struct WHERE 条件中的零值字段，解决软删除 hook 注入零值条件的问题
|
||
|
||
最终代码：`OmitNil().OmitEmptyWhere()`
|
||
|
||
**影响范围**：`common/db/gfdb/gfdb.go` - 全局 DB Model 初始化。写入行为完全兼容，查询条件不再包含零值 struct 字段。
|
||
|
||
**安全性审计（2026-06-10）**：逐文件审查了数据引擎核心同步路径全部 40+ 处 `gfdb.Model()` 调用：
|
||
- 100% 传字符串表名（非 struct），不会触发 struct WHERE 推断
|
||
- 100% 使用 `Where("col", val)` 字符串键值对（非 struct/map），`OmitEmptyWhere()` 对此无效
|
||
- `OmitEmptyWhere()` 不影响 `Data()`/`Insert()`/`Update()`/`Save()`
|
||
- 结论：`OmitEmptyWhere()` 对数据引擎核心同步逻辑完全无影响，唯一生效场景是 `common/report` 软删除 hook
|
||
|
||
## 修复 GetXxxByID 方法零值结构体返回问题
|
||
|
||
**现象**：前端编辑报表/业务/字段/抽取配置时一直提示"未获取到XX数据（ID=N）"。与上述 OmitNil 问题同根：SQL 返回 0 行时，GoFrame 的 `One()` 可能不返回 `sql.ErrNoRows`（驱动差异），此时 `GetXxxByID` 判断 `err == nil` 就返回了零值结构体 `{ID: 0, ...}`。Controller 包装为 `{code:0, data:{"data":{id:0}}}`，前端 `!d.id` 判定失败弹出错误提示。
|
||
|
||
**修复**：`common/report/config/loader.go` 中全部 7 个 `One()` 调用方法，在 `err` 检查之外增加 `result.IsEmpty()` 检查：
|
||
- `GetBusinessByID` / `GetReportByID` / `GetFieldByID` / `GetExtractConfigByID`：四者模式一致，`_` 改为 `result` 变量并追加 `if result.IsEmpty()`
|
||
- `GetBusiness` / `GetReport`（by code）、`GetExtractLog`：同上，追加 `IsEmpty()` 守卫
|
||
|
||
**双重防御**：gfdb.go 的 `OmitEmptyWhere()` 是根本修复（消除错误 SQL）；loader.go 的 `IsEmpty()` 是兜底守卫（即使 SQL 返回 0 行也不返回零值结构体）。
|
||
|
||
## 修复编辑弹窗数据提取的三层兼容
|
||
|
||
**根因**：`api()` 返回 `json.data` 给调用者。当 GoFrame `MiddlewareHandlerResponse` 双层包裹时（`{code:0, data: {"data": {...}}}`），`api()` 返回 `{"data": {...}}`，调用者通过 `res.data` 正确提取。但当 GoFrame 单层包裹时（`{code:0, data: {...}}`），`api()` 直接返回 `{...config...}`，调用者 `res.data` 为 undefined → `d` 为 undefined → 触发 "未获取到XX数据" 错误。
|
||
|
||
**修复**：4 个编辑函数（`openBizModal`/`openReportModal`/`openFieldModal`/`openExtractModal`）的数据提取改为三层 fallback：
|
||
```javascript
|
||
const d = res && res.data !== undefined ? res.data : (res && res.Data !== undefined ? res.Data : res);
|
||
```
|
||
- 第一层：`res.data`（双层包裹，json tag 小写）
|
||
- 第二层：`res.Data`（Go 字段名大写 D）
|
||
- 第三层：`res` 本身（单层包裹，数据直接在 res 里）
|
||
|
||
同时 console.log 增加打印 `raw:` 和 `data:` 便于排查。
|
||
|
||
## 修复报表引擎实体缺失 TenantId 字段 → 查询 tenant_id 不匹配返回零值
|
||
|
||
**现象**：`GET /report/business?id=1` 返回 `code: 0` 但 data 为全零值 `{id: 0, businessCode: "", ...}`，尽管 DB 中实际有数据。
|
||
|
||
**根因**：四个报表引擎实体结构体均缺失 `TenantId` 字段，但 DDL 中表定义有 `tenant_id BIGINT NOT NULL DEFAULT 0`：
|
||
1. `CreateBusiness` 序列化 `BusinessConfig` 时，JSON 中无 `tenant_id` → insert map 中无 `tenant_id` key
|
||
2. `insertHook` 检查 `in.Data[i]["tenant_id"]` 是否存在 → 不存在 → 不设置 → DB 用 DEFAULT 0
|
||
3. `selectHook` 从 `ctxWithUser` 获取 `TenantId=1`，注入 `WHERE tenant_id = 1`
|
||
4. DB 行 `tenant_id=0` 与查询 `tenant_id=1` 不匹配 → 查不到行 → 返回零值结构体
|
||
|
||
**修复**（`common/report/model/model.go`）：给 `BusinessConfig`、`ReportConfig`、`FieldConfig`、`ExtractConfig` 四个结构体新增 `TenantId uint64 \`orm:"tenant_id" json:"tenant_id"\``。
|
||
|
||
**原理**：添加后序列化 JSON 包含 `"tenant_id": 0`，`insertHook` 检测到 key 存在且为零值，自动赋值为 `userInfo.TenantId`。
|
||
|
||
**调试日志**（`common/report/config/loader.go`）：`GetBusinessByID` 增加 `g.Log().Infof` 打印 `id`、`err`、`IsEmpty`、`biz.ID`、`biz.BusinessCode`，便于排查后续类似问题。同时补充 import `"github.com/gogf/gf/v2/frame/g"`。
|
||
|
||
## 修复 GoFrame One(&struct) 直接映射失效 → 改用两步模式
|
||
|
||
**现象**：修复 TenantId 后，SQL 能正确执行并返回1行（`[rows:1]`, `IsEmpty=false`），但 struct 字段全为零值（`biz.ID=0, biz.BusinessCode=""`）。
|
||
|
||
**根因**：`loader.go` 中 7 处 `One(&struct)` 直接传结构体指针，在 GoFrame v2.10.0 + `selectHook` 修改 SQL 的组合下，struct 自动映射失效 —— 查询返回 `gdb.Record` 但未 populate 结构体。
|
||
|
||
**修复**：全部 7 处改为项目已验证的两步模式（参照 `dao/dict/api_interface_dao.go`）：
|
||
```go
|
||
// 旧写法（struct 映射失效）
|
||
result, err := gfdb.DB(ctx).Model(ctx, "table").Where(...).One(&biz)
|
||
|
||
// 新写法（先取 Record，再手动 Struct）
|
||
r, err := gfdb.DB(ctx).Model(ctx, "table").Where(...).One()
|
||
if err = r.Struct(&biz); err != nil { return nil, err }
|
||
```
|
||
|
||
**影响的方法**：`GetBusiness`、`GetBusinessByID`、`GetReport`、`GetReportByID`、`GetFieldByID`、`GetExtractConfigByID`、`GetExtractLog`。
|