f9-web-ai-test/工作进度/工作进度-5.md

工作进度-5：新增报表「自动配置参数与列 + 默认初始化报表」

时间：2026-10-20（承接工作进度-4） 环境：后端 .NET 8 + FreeSql + MediatR（Windows/SQLite），前端 Vue3 + Element Plus + Vite 目标：把工作进度-4 删除内嵌设计器时一起丢失的能力补回来 —— 新增报表时自动识别数据源参数与明细列，并默认生成一张可用的报表（模板 + 配置一次落库）

---

一、背景

工作进度-4 移除了自研网页设计器（ReportDesigner.vue），报表管理页只保留「配置 / 参数 / 预览 / 模板源码」。

结果：

• 新增报表必须先手工上传 .grf 才能预览，否则只有 1 个 Field1 占位列；
• Config.Parms（查询参数）全靠手填，控件类型是纯文本；
• 数据源有哪些字段（明细列）只能去下载模板里看。

本轮补齐：选数据源 → 自动带出参数与明细列 → 保存时自动生成 .grf → 立即可预览。

---

二、后端

2.1 新增文件

文件	说明
Application/Dtos/SYS/Reports/ReportScaffoldDtos.cs	ReportParameterDefDto（参数定义） / ReportDataSourceInfoDto（数据源） / ReportFieldDefDto（明细列） / ReportProbeRequestDto / ReportProbeResultDto
Application/Interfaces/Reports/IReportDataProviderMeta.cs	可选元数据接口：Label / GetParameters() / GetFieldLabels()，未实现的 Provider 行为不变（默认接口方法）

2.2 服务

IReportService / ReportService 新增两个方法：

方法	说明
GetDataSourcesAsync()	遍历 DI 注册的 IReportDataProvider 字典，返回 DsName + 中文名 + 参数定义
ProbeAsync(request)	按 DsName（优先）或 DataSql 执行一次查询，返回参数定义 + 明细字段（列名/中文名/类型）+ 前 3 行样本；失败时 Error 带原因且不抛 500

探测细节：

• Provider 分支：provider.GetData(pairs, mediator) → 取第一个有数据的记录集 → 首行键名即列名 → IReportDataProviderMeta.GetFieldLabels() 提供中文标题
• SQL 分支：ExecuteDataTable(sql)（只绑定 SQL 里出现的 @参数）→ DataTable.Columns 即列名
• 参数取值：请求值 > Parms[].DefaultValue；缺少默认值直接传空，查询失败只记 Error
• 错误分级：有 DsName 但找不到实现 → 未找到数据源实现：xxx；两者都空 → 请先选择数据源（DsName）或填写数据 SQL

2.3 接口

端点	说明
GET api/sys/report/datasources	数据源清单（参数定义随附）
POST api/sys/report/scaffold	结构探测：{ dsName, dataSql, parms, params } → { parameters, fields, rows, total, error }

路由说明：datasources 为字面量段，优先于 {id} 匹配，不影响原详情接口。

2.4 示例 Provider 补元数据

RepDt_Sys_Users 实现 IReportDataProviderMeta：

• 参数：q_dep（部门 / AntdUI.Select / Ds_Service=/sys/department）、q_like（关键字 / AntdUI.Input）
• 字段中文名：EmployeeCode=工号, EmployeeName=姓名, Gender=性别, DepName=部门, WorktypeName=工种, Phone=电话, RuzhiDate=入职日期

新增数据源时实现该接口即可被编辑器自动识别，未实现也能正常查询。

---

三、前端（components/report/ReportEditor.vue）

3.1 数据源与自动识别

项	实现
数据源输入	el-select（filterable + allow-create）：列出来自 /sys/report/datasources 的「中文名（DsName）」，也可手输未登记名称
自动触发	选中数据源即调用 POST /sys/report/scaffold（onDsChange）
手动触发	配置页「自动识别参数与列」按钮；参数页 / 明细字段页也可再次识别
结果	覆盖 Parms（名称/标签/提示/控件类型/Ds_Service/Ds_Static/默认值）+ 填充明细列，并自动切到「明细字段」tab

3.2 明细字段 tab

新增第三个左栏 tab（明细字段 (n)）：

• 列卡片：启用勾选 / 字段名（可改） / 列标题（可改） / 列宽（0.8~8cm）/ 删除
• + 添加列 手工补列（数据源无数据时用）
• 生成模板：按当前字段生成 .grf，新建时随保存写入，编辑时点保存才覆盖（有二次确认）
• 底部展示探测返回的样本行，便于核对字段含义

编辑已有报表时，若模板是 JSON 格式，会反解出 DetailGrid.Recordset.Field + Column.Width + ColumnTitleCell.Text 回填到明细字段；_WR7_ 压缩模板无法反解（留空，不影响继续使用）。

3.3 默认生成模板（buildTemplate()）

结构派生自内置示例模板 employee_directory.grf（GR7 兼容 Version=6.8.5.0）：

区块	内容
DetailGrid	记录集字段 = 启用的明细列；Column.Width 按 17cm 均分（1.2~4）；ColumnTitleCell.Text = 列标题
ReportHeader[0]	报表标题（名称）
ReportHeader[1]	每个查询参数一组「标签 StaticBox + Parameter 绑定 StaticBox」，每行 4 组
Parameter	参数名 = Parms[].Label（与后端 Parameter_Data 键一致，如 部门 / 关键字）
PageHeader / PageFooter	系统名水印 + 页码 + 打印时间（与示例一致）

保存语义：

• 新建：templateJson = buildTemplate()（无字段时退化为单列占位，保证不会出现「未配置模板」）
• 编辑：默认不提交模板（避免覆盖设计器上传的 .grf）；只有点了「生成模板」（templateDirty）才写入

3.4 顺带修复（工作进度-4 遗留 5 的一部分）

参数「控件类型」由纯文本输入改为分组下拉 + 可手输，数据来自 utils/gridreport/controls 注册中心（38 个 AntdUI / F9 控件），与报表中心查询面板同源。

---

四、验证记录

4.1 接口层

GET  /api/sys/report/datasources
  → [{ dsName: RepDt_Sys_Users, label: 职工花名册,
       parameters: [q_dep/部门/AntdUI.Select/Ds_Service=/sys/department, q_like/关键字/AntdUI.Input] }]

POST /api/sys/report/scaffold  { dsName: RepDt_Sys_Users }
  → PARMS=2  FIELDS=7  TOTAL=942  ERR=（空）
    EmployeeCode/工号, EmployeeName/姓名, Gender/性别, DepName/部门,
    WorktypeName/工种, Phone/电话, RuzhiDate/入职日期
    ROW0={EmployeeCode:"",EmployeeName:"付华芳",Gender:"女",DepName:"丝业生产中心",...}

POST /api/sys/report/scaffold  { dataSql: "SELECT id AS Id, code AS Code, name AS Name FROM sys_rbac_menus LIMIT 5" }
  → SQL_FIELDS=3  TOTAL=5  ERR=（空）   Id,Code,Name

POST /api/sys/report/scaffold  { dsName: RepDt_Not_Exists }
  → BAD_ERR=未找到数据源实现：RepDt_Not_Exists

4.2 页面全链路（无头 Edge，/report/manage）

LIST_ITEMS=2  TOPBAR=新增报表
ADD_BTN=true  LEFT_TABS=配置,参数 (0),明细字段 (0)   ← 新增后进入空表单
DS_OPTIONS=1 [职工花名册（RepDt_Sys_Users）]          ← 下拉来自注册表
选中后自动识别：
  LEFT_TABS2=配置,参数 (2),明细字段 (7)
  DETECT_INFO=已识别 7 列 / 2 参数
  FIELD_NAMES=EmployeeCode,EmployeeName,Gender,DepName,WorktypeName,Phone,RuzhiDate
  SAMPLE=EmployeeCode= | EmployeeName=付芳华 | Gender=女 | DepName=丝业生产中心 | ...
保存（未上传任何 .grf）：
  AFTER_SAVE_TOPBAR=编辑报表 · 诊断自动配置报表
  AFTER_SAVE_TAG=模板已配置
  VIEWER_CHILDREN=3
  VIEWER_TEXT=诊断自动配置报表 部门：（全部） 关键字：（全部） 工号 姓名 性别 部门 工种 电话 入职日期
              付芳华 女 丝业生产中心 15884942961 2012-02-01 何均 女 ...
  ALERT=保存成功
后端核对：
  API_ROW={ hasTemplate:true }
  TPL_FIRST3={            ← 生成的是 JSON 模板（非 _WR）
  TPL_FIELDS=7
  TPL_COLUMNS=工号,姓名,性别,部门,工种,电话,入职日期
  TPL_PARAM=部门,关键字
  CFG_DS=RepDt_Sys_Users  PARMS=q_dep/AntdUI.Select,q_like/AntdUI.Input
  CLEANUP=200             ← 测试报表已删除

4.3 编译 / 运行

• 后端 dotnet build：0 错误 0 警告（先停 F9WebAiTest.Api 进程再编译，避免 MSB3027）
• 前端无 lint 诊断；无头 Edge 实跑整页（识别 → 保存 → GR7 渲染）通过
• 服务：后端 http://localhost:3000、前端 http://localhost:5173 均在运行

---

五、当前状态

项	状态
新增报表：数据源下拉 + 一键识别参数与列	✅
新增报表：保存自动生成 .grf（默认初始化），保存后直接可预览	✅
明细字段可编辑（字段名 / 标题 / 列宽 / 启用）并据此生成模板	✅
编辑已有 JSON 模板：反解明细列回填	✅（_WR7_ 压缩模板无法反解）
SQL 数据源（无 DsName）也能探测列	✅
参数控件类型：38 个注册控件分组下拉	✅
探测失败不阻断：提示原因，仍可手工加列保存	✅

---

六、遗留与后续建议

1. Provider 参数声明需手工补：新增 IReportDataProvider 时建议同时实现 IReportDataProviderMeta，否则编辑器只能识别字段、参数要手填。
2. _WR7_ 模板不能反解列：编辑这类报表时「明细字段」为空，重新生成会覆盖设计器排版（已有二次确认）。若需要，可在后端通过 GR7 库或 gr.wr.decodeWR 的等价实现解码后再解析。
3. 探测会执行真实查询：大报表（如 942 条职工）识别需要等待查询完成；后续可给 Provider 增加「仅取结构」的轻量方法（如返回空参数 + LIMIT 0）。
4. 列宽均分：自动生成的列宽按 17cm 均分，超宽字段（地址、备注）仍需到设计器里调整。
5. 进度-4 遗留项仍在：Report_FavoriteGroup 未实现、历史废弃列未 DROP、进度-3 的 Number() 精度隐患等。