# 报表过滤条件与参数设计

过滤条件（Filter）与参数（Parameter）是报表的入口，设计不好会导致查不到数、查询慢、体验差。本文件覆盖直接SQL账表与动态表单报表的过滤/参数设计。

## 一、过滤条件类型

| 类型 | 说明 | 典型字段 |
|---|---|---|
| 文本 | 单行文本输入 | 单据编号、备注 |
| 下拉列表 | 固定选项（可枚举） | 单据状态、业务类型 |
| 基础资料 | 引用基础资料（F7） | 物料、客户、供应商、仓库 |
| 组织 | 组织选择器 | 创建组织、使用组织 |
| 日期 | 日期选择 | 日期范围 |
| 数值/金额 | 数值输入 | 金额范围 |
| 复选框 | 是否 | 是否含未审核 |

## 二、参数设计要点

### 1. 参数必须有合理默认值
- 日期范围：默认本月/本季度，避免用户忘选导致空结果
- 组织：默认当前用户业务组织
- 状态：默认"已审核"（A）

### 2. 参数命名与 SQL 引用
直接SQL账表参数在 SQL 中以 `@参数名` 引用：

```sql
WHERE FDate >= @StartDate AND FDate < DATEADD(DAY,1,@EndDate)
  AND FCreateOrgId = @OrgId
  AND FDocumentStatus = @Status
```

### 3. 多选参数
- 基础资料/组织参数支持多选，SQL 用 `IN (@Param)`：

```sql
WHERE FCustId IN (@CustomerIds)
```

### 4. 空参数处理
参数未选时：
- 要么设默认值兜底
- 要么 SQL 中做空值兼容：

```sql
WHERE (@CustomerId IS NULL OR FCustId = @CustomerId)
```

## 三、过滤条件配置步骤（直接SQL账表）

1. 账表设计器 → 过滤条件设计
2. 新增过滤项：设置标题、字段标识、控件类型（F7基础资料/下拉/日期/文本）
3. 下拉类过滤项：配置枚举/固定值（如单据状态 A/B/C 的映射）
4. 设置默认值与必填项
5. 保存后 SQL 中引用对应参数

## 四、单据状态过滤（高频）

金蝶单据状态 FDocumentStatus 常用值：

| 值 | 含义 |
|---|---|
| A | 审核通过 |
| B | 暂存 |
| C | 已关闭/作废 |
| D | 重新审核中（视版本） |

基础资料禁用状态 FForbidStatus：A=使用中，B=禁用。

**报表默认建议**：`FDocumentStatus = 'A'`，除非业务需要含暂存/未审核。

## 五、组织参数与数据范围

- 报表涉及业务数据时，**几乎必有组织过滤**
- 组织参数建议：
  - 控件类型选"组织"（支持组织树选择）
  - 支持多选 + 含下级组织（平台组织控件可配置）
  - SQL：`FCreateOrgId IN (@Orgs)`

## 六、常见问题

| 问题 | 原因 | 解决 |
|---|---|---|
| 查询结果为空 | 参数默认值为空 | 设默认值（当前月/当前组织） |
| 参数不生效 | SQL 中参数名与设计不一致 | 核对 @参数名 大小写/命名 |
| 日期查询不准 | 用 = 比较日期，忽略时间 | 用范围 `>=` 和 `<` 下一天 |
| 多选失效 | 用 = 而非 IN | 改 `IN (@Param)` |
| 看不到某组织数据 | 组织参数未选/数据权限 | 配置组织过滤与权限 |
| 下拉无选项 | 枚举未配置 | 配置枚举映射 |

## 七、动态表单报表的参数

动态表单报表参数通过表单参数集合管理（插件中读取）：

```csharp
// 读取参数值（插件内）
object orgId = this.View.GetParameter("OrgId");
```

- 参数在 BOS 表单设计器的"参数"节点定义
- 插件可在 OnInitialize 中设置默认值
- 用户查询时平台自动弹出参数录入界面（可配置）
