# 直接SQL账表开发全流程

直接SQL账表（Direct SQL Report）是金蝶云星空最高效的报表开发方式：零 C# 代码，通过 SQL 直接取数，5 分钟可上线一张报表。本文件覆盖从创建到发布的全流程。

## 核心原理

直接SQL账表本质是"安全沙箱"：系统允许开发者在账表中编写 T-SQL 查询底层业务数据库，将结果以账表形式呈现。

**关键约束（务必告知用户）：**
- 只允许 `SELECT` 查询语句
- `INSERT` / `UPDATE` / `DELETE` / `CREATE` 等写操作被系统禁止
- 依赖对金蝶数据库结构（动态视图、业务表）和 SQL 的掌握

## 开发前环境准备

- 金蝶云星空 BOS 开发平台（协同开发平台）账号，且已分配开发权限
- 数据库查询权限（SQL Server）
- 基础 T-SQL 能力：SELECT、JOIN、聚合（SUM/COUNT）、WHERE

## 五步开发流程

### 第 1 步：创建账表对象

1. 登录 BOS 平台，在对象导航树中选择目标业务域（如 财务会计 → 总账 / 供应链 → 销售管理）
2. 右键 → 新建 → 选择"账表"（报表）→ 选择"直接SQL账表"
3. 设置账表名称、编码（如 RPT_SALES_SUMMARY）、所属分类

### 第 2 步：编写取数 SQL

在账表的"取数SQL"中编写查询。规范：

```
-- 示例：各销售员本月销售收入汇总
SELECT
    e.FNumber       AS 销售员编码,
    e.FName         AS 销售员,
    o.FBillNo       AS 订单号,
    o.FDate         AS 订单日期,
    o.FAmount       AS 订单金额
FROM T_SAL_SALEORDER o
INNER JOIN T_BD_STAFF e ON o.FSalerId = e.FSTAFFID
WHERE o.FDocumentStatus = 'A'          -- 已审核
  AND o.FDate >= '2026-01-01'
```

**SQL 编写要点：**
- 表名以 `T_` 开头，物理表名、字段标识可从数据字典技能（kingdee-cloud-dictionary）查询
- 单据头 + 单据明细：通过头表 FID 与明细表 FENTRYID 关联（明细表头字段 FID 指向头表 FID）
- 审核状态过滤：`FDocumentStatus = 'A'`（A=审核通过）；禁用状态 `FForbidStatus`
- 组织过滤：业务单据通常有创建组织 FCreateOrgId / 使用组织 FUseOrgId
- 避免 `SELECT *`，只取需要的列
- 需要聚合时用 GROUP BY + 聚合函数

### 第 3 步：配置数据集与字段映射

1. 账表设计器 → 数据集：将 SQL 的查询列映射为账表字段
2. 设置字段标题、类型（文本/金额/数量/日期）、对齐、汇总方式
3. 金额/数量字段可设置合计（汇总行）
4. 字段宽度、格式（小数位、千分位）按需设置

### 第 4 步：设计过滤条件与参数

在账表设计器中配置过滤项（见 filter-params.txt）：
- 单据编号、日期范围、组织、业务员、物料等常用过滤
- 参数带默认值，避免空查询
- 组织类参数关联组织选择器

### 第 5 步：权限配置与发布

1. 保存并发布账表（发布到应用）
2. 功能授权：系统管理 → 用户管理/角色管理 → 功能权限 → 勾选该账表功能
3. 数据权限：按组织/用户配置数据范围（见 data-scope.txt）
4. 分配后用户才能看到并打开报表

## 发布后必查清单

- [ ] 功能权限已分配（否则列表看不到 → 最常见的"看不见报表"原因）
- [ ] 数据权限范围正确（组织/角色）
- [ ] 参数有默认值（否则查询可能为空或报错）
- [ ] SQL 只用了 SELECT（写操作语句会被系统拦截）
- [ ] 字段映射齐全（SQL 列都要映射，否则列不显示）

## 性能优化建议

- 只 SELECT 必要列，避免 `SELECT *`
- WHERE 条件优先过滤：日期范围、组织、状态
- 大表查询加合适的索引（SQL Server 层面）
- 避免在 WHERE 中对列做函数运算（如 `YEAR(FDate)`，应改用范围比较 `FDate >= ... AND FDate < ...`）
- 大量数据考虑分页或汇总先行
- 常用过滤条件字段建议建索引：FBillNo、FDate、FCreateOrgId、FDocumentStatus

## 直接SQL账表 vs 其他方式

| 对比项 | 直接SQL账表 | 动态表单报表 |
|---|---|---|
| 代码 | 零代码 | C# 插件 |
| 图表 | 不支持 | 支持 |
| 下钻 | 需表单插件 | 原生支持 |
| 复杂取数 | 仅 SQL 能力 | 任意代码 |
| 开发速度 | 最快 | 较慢 |
