统一数据桥：CCFlow 数据源体系架构与技术说明
为表单、流程、低代码与大屏提供一致的数据访问能力——应用与外部系统之间的可配置桥梁。
一、定位与价值
数据源是 CCFlow / ccfast 平台中面向业务应用的统一数据组件。单据、实体、流程、门户等上层应用不直接对接第三方系统，而是通过数据源完成数据读取、下拉展示、结果集查询与业务过程调用。
其核心使命可以概括为：
应用层（流程 / 表单 / 大屏 / 低代码） ↕ 数据源（枚举 / 字典 / 查询 / 过程） ↕ 外部系统（本机库 / 关系数据库 / WebApi）这与官方概念文档中的数据源结构图一致：数据源是应用与外部系统之间的桥梁，将异构的数据获取方式收敛为统一的四类能力。
二、工程全貌
2.1 目录与模块分层
前端工程采用「树表一体管理页 + 实体定义 + 向导创建 + 后端执行」的分层结构：
Vue3/src/WF/Admin/ ├── TreeEns_DBSrc.ts ← 管理入口：左侧树 + 右侧列表 └── FrmLogic/ ├── SFDBSrc/ ← 数据源连接（根节点） │ ├── SFDBSrc.ts ← 基础实体 │ ├── SFDBSrcLocal.ts ← 本机数据源 │ ├── SFDBSrcSQL.ts ← 关系数据库数据源 │ ├── SFDBSrcWebApi.ts ← WebApi 数据源 │ └── GPN_*.ts ← 新建向导 ├── SFTable/ ← 字典 ├── SFSearch/ ← 查询 ├── SFProc/ ← 过程 ├── SysEnum/ ← 枚举（仅本机数据源） └── Sync/ ← 数据同步（基于查询结果落地）2.2 管理界面：树表联动
TreeEns_DBSrc继承PageBaseTreeEns，是数据源管理的唯一入口页：
| 层级 | 含义 | 实现方式 |
|---|---|---|
| 一级节点 | 数据源实例 | 从Sys_SFDBSrc表加载，如local、各 SQL/WebApi 连接 |
| 二级节点 | 能力分类 | 运行时虚拟构造，非数据库记录 |
| 右侧列表 | 具体配置项 | 按节点类型切换不同实体集合与列定义 |
每个数据源下固定挂载四类（本机额外含枚举）：
数据源（SFDBSrc） ├── 字典（SFTable） nodeID: {srcNo},SFTable ├── 查询（SFSearch） nodeID: {srcNo},Search ├── 过程（SFProc） nodeID: {srcNo},Proc ├── 枚举（SysEnum） nodeID: local,Enums（仅本机） └── 数据同步（Sync） nodeID: {srcNo},SyncGetDtls(nodeID)根据节点后缀分发到不同实体，动态调整列与工具栏按钮；BtnClick统一处理新建、编辑、删除、属性维护等操作，并通过EnName参数路由到具体编辑表单。
2.3 实体模型与数据表
| 模块 | 实体类 | 数据表 | 职责 |
|---|---|---|---|
| 数据源 | SFDBSrc | Sys_SFDBSrc | 连接信息、类型、WebApi 结果转换模式 |
| 字典 | SFTable | Sys_SFTable | 下拉/树形选项数据定义 |
| 查询 | SFSearch | Sys_SFSearch | 参数化结果集查询 |
| 过程 | SFProc | Sys_SFProc | 参数化执行与返回 |
| 枚举 | SysEnumMain | Sys_EnumMain | 整型/字符串常量集合 |
| 同步 | Sync | Sys_Sync | 将查询结果同步到表或实体 |
所有子能力通过FK_SFDBSrc（或DBSrcNo）关联到父数据源；多租户场景下辅以OrgNo隔离。
2.4 多态实现：同一能力，多种接入
以字典为例，SFTable是统一抽象，具体实现按接入方式拆分：
| 实现类 | 适用场景 |
|---|---|
SFTableSQLNoName/SFTableSQLTree | SQL 编号名称 / 树结构字典 |
SFTableWebApiNoName/SFTableWebApiTree | WebApi 字典 |
EnTableNoName/EnTableTree | 平台实体字典 |
SFTableBPClass/SFTableHandler/SFTableJS | 类、Handler、JS 等扩展方式 |
查询（SFSearchSQL/SFSearchWebApi）、过程（SFProcSQL/SFProcWebApi）同样遵循此模式。
新建时，TreeEns_DBSrc根据数据源类型选择向导：
- 本机 →
GPN_Local - 关系库 →
GPN_DBSrcSQL - WebApi →
GPN_DBSrcWebApi
2.5 运行时执行链路
配置完成后，运行时由后端BP.Sys.*服务执行：
前端实体.GenerData() / BSEntity.DoMethodReturnJSON() ↓ 后端 BP.Sys.SFTable / SFSearch / SFProc ↓ 按 FK_SFDBSrc 选择连接 → 执行 SQL / 调用 WebApi ↓ 返回 JSON → 表单下拉 / Pop 填充 / 流程事件表达式支持系统变量与参数占位，例如：
~@Key~、~@WebUser.No~（SQL 字典）@Token、@WebUser.No、@WorkID（WebApi 路径与 POST 体）
2.6 与上层应用的集成点
数据源能力被表单、流程等模块引用式消费，而非硬编码：
- 表单字段
UIBindKey绑定枚举或字典编号 - 查询支持
AddSln将返回列智能映射到表单字段（SFColumnSln） - 过程支持
SFParaSln将参数映射到表单属性 - 数据同步以
SFSearch为数据源，定时或手动写入目标表/实体
三、核心概念说明
以下定义与官方数据源文档保持一致。
3.1 数据源类型
| 类型 | 说明 | 典型用途 |
|---|---|---|
| 本机数据源 | ccfast 默认数据库，local为内置编号 | 枚举、系统字典、平台内表数据 |
| 关系数据库数据源 | 通过连接串访问外部 RDBMS | ERP、历史库、报表库 |
| WebApi 数据源 | 通过 HTTP 协议与参数获取数据 | 第三方 SaaS、微服务、开放接口 |
3.2 四类数据能力
枚举（SysEnum）
用户定义的命名常量集合，由一组整型或字符串键值组成。
- 示例：性别
0=女、1=男；政治面貌0=群众、1=团员、2=党员 - 支持 Int / String 两种类型，可配置显示颜色
- 仅挂载于本机数据源，存储在
Sys_EnumMain/Sys_Enums - 删除前会检查
MapAttr.UIBindKey引用，防止破坏已发布表单
字典（SFTable）
用于下拉框、级联选择、树形选择的数据结构。
| 结构 | 字段要求 | 示例 |
|---|---|---|
| 编码字典 | 编号 + 名称 | 城市、角色类型、产品类型 |
| 树结构字典 | 编号 + 名称 + 父节点编号 | 部门、菜单、分类 |
支持无参/有参；有参时通过SelectStatement中的占位符实现级联，如按省份过滤城市。
查询（SFSearch）
输入参数，返回结果集。
| 类型 | 说明 | 示例 |
|---|---|---|
| 实体查询（单行） | ResultNum = 1 | 按客户编号取客户详情 |
| 集合查询（多行） | ResultNum = 0 | 人员列表、车辆台账、客户关系表 |
支持参数定义（SFParas）、返回列定义（SFColumns）及与表单字段的映射方案。
过程（SFProc）
输入参数，执行并返回结果，侧重「动作」而非「读取」。
- 示例：账户注销、出入库、修改密码、作废单据
- 支持 GET / POST（WebApi）
- 常用于流程事件、节点事件中的业务调用
数据同步（Sync）— 扩展能力
以已配置的查询为数据来源，按规则写入：
- 同步到数据库表 / 后端实体 / 前端实体
- 清空方式或追加方式
- 可配置定时任务规则（
GPE_AutoSync）
四、典型应用场景
4.1 枚举
| 场景 | 说明 |
|---|---|
| 表单下拉字段 | 性别、状态、审批结果等固定选项 |
| 流程条件判断 | 按枚举值分支 |
| 列表显示翻译 | 将存储值转为可读标签 |
| 大屏图例 / 状态色 | 配合EnableColor做可视化区分 |
特点：值域稳定、变更少、无需访问外部系统，适合本机维护。
4.2 字典
| 场景 | 说明 |
|---|---|
| 表单下拉框 | 部门、岗位、产品类型 |
| 级联下拉 | 省 → 市 → 区，一级选项驱动下一级 SQL/API |
| 树形选择器 | 组织架构、产品分类 |
| 接收人规则 | 流程按部门/角色字典解析处理人 |
| 外部主数据 | 通过 WebApi 字典对接第三方编码表 |
特点：选项来自业务主数据，可能随组织、权限、上下文变化；支持动态参数。
4.3 查询
| 场景 | 说明 |
|---|---|
| Pop 弹窗选择 | 从客户/物料库中选一条或多条 |
| 装载填充 | 选客户后自动带出地址、联系人 |
| 从表填充 | 主表选订单，从表加载明细行 |
| 实体查询 | 根据单号加载一条完整业务记录 |
| 大屏 / 报表数据源 | 多行集合查询驱动图表与列表 |
| 数据同步源 | Sync模块的数据输入 |
特点：面向读，返回结构化数据集；实体查询与集合查询分别服务「详情回填」与「列表展示」。
4.4 过程
| 场景 | 说明 |
|---|---|
| 流程节点事件 | 审批通过后调用 ERP 过账接口 |
| 流程结束事件 | 触发库存扣减、积分变更 |
| 表单按钮 | 保存前校验、作废、密码修改 |
| 与外部系统写操作 | 创建第三方工单、注销账户 |
特点：面向写/执行，强调副作用与事务性操作；参数通常来自表单字段或流程上下文。
4.5 组合示例
请假流程 ├── 枚举：请假类型（事假/病假/年假） ├── 字典：申请人部门（树结构，本机 SQL） ├── 查询：年假余额（实体查询，按工号返回剩余天数） └── 过程：同步考勤系统（WebApi POST，流程结束时调用）五、设计优点
5.1 统一抽象，降低集成成本
流程、表单、大屏只需认识「枚举 / 字典 / 查询 / 过程」四类接口，无需关心底层是 SQL 还是 HTTP。更换对接方式时，多数情况下只需调整数据源配置，上层绑定关系可保持不变。
5.2 连接与定义分离
SFDBSrc管理连接，SFTable/SFSearch/SFProc管理业务语义。同一 ERP 连接下可配置 dozens 个字典与查询，避免连接信息重复维护。
5.3 多态扩展清晰
通过EnName+ 独立实体类（如SFTableSQLNoName、SFTableWebApiNoName）实现编辑表单的差异化，公共字段收敛在基类实体，扩展新型接入时模式可复制。
5.4 参数化与上下文注入
统一支持~@Key~、@WebUser.No、@Token、@WorkID等占位符，使级联、权限过滤、流程上下文传递可在配置层完成，减少定制代码。
5.5 与低代码体系深度耦合
- 查询/过程的
AddSln可自动映射到表单字段 - 枚举删除前检查表单引用
- 字典创建时可指定默认字段名（
FK_Val），加速表单设计
5.6 多租户友好
OrgNo贯穿字典、查询、过程、同步；枚举在集团/SAAS 模式下支持组织隔离与共享策略。
六、设计局限与改进方向
6.1 树节点为 UI 层虚拟构造
二级节点（字典/查询/过程等）并非数据库记录，而是由TreeEns_DBSrc.Init()动态push生成，nodeID采用{srcNo},{Type}字符串拼接。
- 影响：节点解析逻辑分散在
includes('SFTable')等字符串判断中，扩展新分类需改多处 - 建议：可考虑枚举化节点类型，或下沉为配置表驱动
6.2 EnName 路由的多态依赖
编辑入口依赖实体AtPara.EnName字段定位具体表单类，缺失时报「数据错误」。
- 影响：配置不完整时排错成本较高；全局搜索双击行需依次尝试多个实体类型
- 建议：建立类型注册表，或在一级元数据中显式存储
ItemType
6.3 枚举能力仅限本机
外部系统的码表只能通过字典（WebApi/SQL）模拟，无法使用枚举的轻量配置与颜色能力。
- 影响：概念上「固定小码表」与「外部码表」路径不统一
- 建议：文档中明确边界——枚举用于平台内常量，字典用于动态主数据
6.4 表达式能力强大但学习曲线陡
SQL 语句、API 路径、POST JSON、参数别名需同时掌握，对实施人员要求较高。
- 影响：配置错误往往在运行时暴露
- 建议：强化
SFTableSQLNoName等编辑页中的「测试」按钮与TestParas用例（现有能力可进一步产品化）
6.5 同步模块与查询耦合
Sync强依赖SFSearch作为数据源，无法直接从字典或过程同步。
- 影响：部分「字典 → 本地缓存表」场景需先包装为查询
- 建议：评估是否支持字典直同步，或提供向导自动生成查询
6.6 代码层面的重复检索
部分GetDtls分支存在连续两次Retrieve调用（如过程、查询节点），属于可优化的实现细节。
七、架构关系图
7.1 模块依赖
flowchart TB subgraph UI["管理界面"] TE[TreeEns_DBSrc] end subgraph Root["数据源根"] DS[SFDBSrc] DSL[SFDBSrcLocal] DSS[SFDBSrcSQL] DSW[SFDBSrcWebApi] end subgraph Cap["四类能力 + 同步"] TB[SFTable 字典] SE[SFSearch 查询] PR[SFProc 过程] EN[SysEnum 枚举] SY[Sync 数据同步] end subgraph Runtime["运行时"] BP[BP.Sys 后端服务] end subgraph App["上层应用"] FRM[表单] WF[流程] SCR[大屏] end TE --> DS DS --> DSL & DSS & DSW DSL & DSS & DSW --> TB & SE & PR DSL --> EN SE --> SY TB & SE & PR & EN --> BP BP --> FRM & WF & SCR7.2 数据流
sequenceDiagram participant App as 表单/流程 participant FE as 前端实体 participant BE as BP.Sys participant Ext as 外部系统 App->>FE: 请求字典/查询/过程 FE->>BE: GenerData / DoMethodReturnJSON BE->>BE: 解析 FK_SFDBSrc alt 本机/SQL BE->>Ext: 执行 SQL else WebApi BE->>Ext: HTTP 请求 end Ext-->>BE: 结果集/执行结果 BE-->>FE: JSON FE-->>App: 下拉项/填充数据/执行反馈八、关键代码索引
| 文件 | 作用 |
|---|---|
TreeEns_DBSrc.ts | 树表管理、节点分发、按钮事件 |
SFDBSrc/SFDBSrc.ts | 数据源基类、连接测试 |
SFTable/SFTable.ts | 字典元数据、GenerData |
SFSearch/SFSearch.ts | 查询元数据、列映射AddSln |
SFProc/SFProc.ts | 过程元数据、参数映射AddSln |
SysEnum/SysEnumMain.ts | 枚举注册、SaveDtls |
Sync/Sync.ts | 同步规则、定时配置入口 |
九、总结
CCFlow 数据源体系以SFDBSrc 为根、四类能力为枝、多态实体为叶，在单一管理界面中完成了从连接配置到业务数据定义的全链路治理。它将「读」（枚举、字典、查询）与「写」（过程）清晰拆分，又通过统一的参数与上下文机制保持体验一致。
对于实施团队：枚举管常量、字典管选项、查询管数据集、过程管动作——按此分工配置，即可覆盖绝大多数表单与流程的数据交互需求。对于架构评审：优势在于抽象统一与低代码亲和；代价在于配置复杂度与 UI 层虚拟树的可维护性，需在文档、测试工具与类型注册方面持续加强。
参考文档：数据源设置 DBSrc（腾讯文档）
