数据源（DataSource）定义编写指南¶

目标：Agent 直接生成/修改 workspace 数据源定义，并正确理解默认库解析、动态表落库、脚本按名访问。知识以本文为准。不写原理；不依赖外链。

术语：数据源 = DataSource（产品文档「数据源」）。挂在**软件（Application）下，描述该软件连接哪个数据库；表单动态表（TLK_/LOG_/PARM_）、平台运行表（T_DOCUMENT 等）落在**默认数据源**指向的库上。数据源是**应用级扁平单文件，不是模块资源，不是目录型资源。

产出物一览¶

部分	落盘	形态
数据源定义	`datasource/{数据源名}.datasource`	JAXB XML 根 `dataSource`；`id` 为根属性

storage/workspace/{软件名}.application/datasource/{数据源名}.datasource

路径相对 storage/workspace。形态同角色：单文件 {name}.datasource，不是 {name}.datasource/ 目录。

新建最低配置（常规业务软件）：

目录已存在：{软件}.application/datasource/
至少一个 .datasource：id、name、parentId=软件 id、applicationid=软件 id、defaultDataSource=true
useType=JDBC（或 JNDI）+ 连通的驱动/URL/账号（或 JNDI 名）+ 正确 dbType
（推荐）poolsize、timeout；不需要读写分离则 readonly=false
软件 activated=true 时：保存/启动会按默认库初始化 RT 静态表并对表单做动态表同步
不走设计器 save 时：落盘默认 .datasource 后向 workspace/.sync/ 投递 *.init_default_datasource（见下），以补齐 DataSourceEnv + T_XXXX，并按 .done/.failed 判定可用性

约定：

JAXB；根元素 dataSource（驼峰）；id 在 根属性
URL/密码等长文本用 <![CDATA[...]]>
文件名 = name + .datasource；同软件 datasource/ 下不重名
parentId = 软件 id；applicationid 建议写且 = 软件 id
name 勿含 / % \（落盘会替换为 =47/=37/=92）
**勿**把数据源放到 module/ 下；永远在应用级 datasource/
**勿**再往 .application 写 datasourceId（历史字段）；默认库以本文件 defaultDataSource 为准
同软件建议仅一个 defaultDataSource=true；可有多个非默认库给脚本/报表/外部表用

默认库初始化与可用性检查（手工/Agent 落盘后）¶

Agent / 手工落盘默认 .datasource **不走**设计器 activated=true save 时，平台**不会**自动执行 DataSourceEnv + 平台 RT 静态表（T_DOCUMENT 等 T_XXXX）。须向 workspace/.sync/ 投递 *.init_default_datasource（**不要求**事先 rebuild 索引）。

本触发同时承担「初始化 + 可用性检查」：平台用真实 JDBC/JNDI 建连并建 RT 表；成功**归档到 .sync/.done/，**失败**归档到 .sync/.failed/。Agent **据此决定下一步，勿再依赖 Python 第三方库做 JDBC 探测。机制见 design/workspace-structure-and-mechanism.md §7.4。

场景	是否投递 `*.init_default_datasource`
默认库（`defaultDataSource=true`）新建/改连接后	是（必做）
非默认附加数据源	否（本触发不适用）
仅同步某表单动态表 `TLK_*`	用 `.create_form_table`（见 FORM_SKILL），不用*本触发

前提¶

目标为该软件默认库（defaultDataSource=true）；软件宜已 activated=true
监视仅 Runtime / Manager / Job 启用；Designer 不处理 .sync/。投递后需对应服务在跑

投递约定¶

项	约定
路径	`{myapps.storage.root}/workspace/.sync/{任意前缀}.init_default_datasource`
内容	一行 `.datasource` 逻辑 URI（相对 workspace 根，以 `/` 开头）
前缀	建议 `{数据源名}-{时间戳}`，避免与旧归档混淆

# 文件：workspace/.sync/main-20260719120000.init_default_datasource
/LeaveOA.application/datasource/main.datasource

Agent 收尾步骤（按序）¶

写完并保存 datasource/{name}.datasource（defaultDataSource=true）
跑本 skill 脚本（推荐）或手工投递触发文件：

python "<skill-dir>/scripts/init_default_datasource.py" "<path/to/name.datasource>"
# 可选：--initial-delay 2 --poll-interval 2 --timeout 180
#       --workspace "<storage/workspace>"

延时检查归档（勿投递后立刻判定）：监视器处理需要时间，必须按下面策略等待后再读 .done/.failed。

参数	默认	含义
`--initial-delay`	`2`s	投递后先等待再做第一次归档检查（给 `SyncMonitorListener` 响应时间）
`--poll-interval`	`2`s	之后每隔此时长再查一次 `.done` / `.failed`
`--timeout`	`120`s	自投递起最长等待；超时仍未归档 → exit `3`

手工投递时同样遵守：投递后 sleep ≥2s，再每 2s 轮询 .sync/.done/ 与 .sync/.failed/（看触发文件名是否出现），总等待建议 ≤120s。

监视器侧：读 URI → 读盘加载 DataSource → 校验默认库 → DataSourceEnv + AbstractApplicationInitDAO.initTables（T_XXXX）
按归档决定下一步：

结果	位置	Agent 行为
成功	`.sync/.done/{触发文件名}`	可继续（角色/模块/表单、`*.create_form_table` 等）
失败	`.sync/.failed/{触发文件名}`	必须警告用户；查 URL/账号/网络/库/activated/URI；修正后重新投递新文件（勿改 `.failed` 内旧文件指望重试）；勿假装数据源已可用
超时未归档	仍在 `.sync/` 根或消失但未进 done/failed	确认 Runtime/Manager/Job 已监听 `.sync/`；Designer 不处理；就绪前勿声称已初始化

本触发**不**做全量 TLK_*；单表仍用 *.create_form_table。

写入 .sync/{name}.init_default_datasource
  → SyncMonitorListener（或启动 drain）
  → 读 datasource URI → 读盘加载 DataSource
  → DataSourceEnv + initTables（T_XXXX）
  → 成功 → .sync/.done/；失败 → .sync/.failed/

1. 心智模型¶

软件 Application
  ├─ datasource/*.datasource   ← 本文；默认库驱动 RT+动态表
  ├─ role/*.role
  ├─ module/*.module/ … 表单/视图
  │     └─ 表单保存 → 在「默认数据源」库上 createOrUpdate TLK_/LOG_/PARM_
  └─ datamodel/ …              ← 可选；可选任意本软件数据源做导入/同步

概念	说明
默认数据源	`defaultDataSource=true`；激活软件时初始化该库上平台静态表 + 同步全部表单动态表
附加数据源	`defaultDataSource=false`；不驱动上述初始化；供 `queryByDSName(name,…)`、报表/OLAP/数据模型/Excel 选库
JDBC	`useType=JDBC`；本文件写 driver/url/username/password
JNDI	`useType=JNDI`；本文件写 `jndiName`（容器已配 DataSource）
读写分离	`readonly=true`；写走主库字段，读走 `readonly*` 一套
按名访问	iScript/`DATABASE`/`DB` 的 `ByDSName` 第一个参数是数据源 `name`*（文件名去掉后缀），不是 id

模块 / 表单 XML **不**内嵌数据源 id：业务文档默认进软件默认库。要查别的库必须用脚本按名或报表等显式选源。

系统库（用户/域等 T_USER…）通常由平台全局 JPA/Hibernate 配置，**不等于**业务软件 .datasource；业务软件默认库可与系统库同实例不同 schema/库名，也可完全独立。

连接池实现：运行侧常用 Druid（com.alibaba.druid）。poolsize/timeout 写入本配置，供池化连接使用。

2. DataSource 属性 → `.datasource` XML¶

属性表¶

属性	XML	类型	默认	说明
`id`	根属性	string	须生成	`__` + 短 UUID
`name`	子元素	string	—	必填；文件名；脚本 `dsName`/`DATASOURCENAME` 用此名
`parentId`	子元素	string	—	= 软件 id
`applicationid`	子元素	string		建议=软件 id
`description`	CDATA	string		描述
`remark`	CDATA	string		少用
`defaultDataSource`	bool	false	默认库须 true；同软件建议仅一个 true
`useType`	子元素	string	`JDBC`	`JDBC` / `JNDI`
`driverClass`	子元素	string		JDBC 驱动类；JNDI 时可空
`url`	CDATA	string		JDBC URL；可含 `${ENV:default}` 占位
`username`	子元素	string		可含占位
`password`	CDATA	string		可含占位
`dbType`	子元素	int	—	必填语义；见 dbType 表；驱动 DDL/DAO 方言
`poolsize`	子元素	string		连接池大小，如 `20`（字符串数字）
`timeout`	子元素	string		超时秒数等，如 `3600`
`jndiName`	子元素	string		`useType=JNDI` 时必填倾向
`readonly`	bool	false	`true`=开启读写分离
`readonlyUseType`	子元素	string	`JDBC`	只读侧 `JDBC`/`JNDI`
`readonlyDriverClass`	子元素	string		只读 JDBC 驱动
`readonlyUrl`	CDATA	string		只读 JDBC URL
`readonlyUsername`	子元素	string
`readonlyPassword`	CDATA	string
`readonlyDbType`	子元素	int	`0`	只读库类型；未开分离时常 `0`
`readonlyPoolsize`	子元素	string
`readonlyTimeout`	子元素	string
`readonlyJndiName`	子元素	string		只读 JNDI；命名以样例 `readonlyJndi*` 为准

不落盘/运行期：连接句柄、DataSourceEnv 缓存、测试连接结果等。API 详情可能返回软件级 datasourceName（默认库名称），那是派生字段，不是 .application XML 属性。

`id` 生成¶

统一规则：__ + 短 UUID。示例：__MpEzTToulqZtNEFisw6。须全局/库内不冲突。

默认库解析（运行时）¶

软件层**不再**持久化默认库 id。解析顺序：

列出该软件下全部 DataSource
优先 defaultDataSource=true 的项
若都未标记 → 取列表**第一项**（兼容旧包）

历史 .application 可能仍有 <datasourceId>…</datasourceId>：新写忽略；以此处 defaultDataSource 为准。

无可用默认数据源或默认库连不上时：

激活软件**不会**初始化该软件 RT 静态表
表单动态表 createOrUpdate 会跳过/失败
前台文档读写会失败

环境变量占位¶

url / username / password（及只读对应字段）可写：

${环境变量名:默认值}

例：${DB_HOST:localhost}、${DB_PORT:3306}。部署时用环境变量覆盖，便于多环境同一份 workspace。

`name` 约束¶

同应用 datasource/ 唯一
脚本、sys_function.DATASOURCENAME、数据模型/报表下拉：均认 name
改名：改文件名 + <name>；已写死旧 name 的脚本/报表配置会断 → 同步改引用
重命名软件时会销毁并重建 DataSourceEnv（见 APPLICATION_SKILL）；数据源自身改名也可能触发连接重建

3. dbType 与驱动 / URL¶

值	库	常见 driverClass	JDBC URL 骨架
`1`	Oracle	`oracle.jdbc.OracleDriver` 或 `oracle.jdbc.driver.OracleDriver`	`jdbc:oracle:thin:@host:1521:ORCL` 或 `@//host:1521/service`
`2`	SQL Server	`com.microsoft.sqlserver.jdbc.SQLServerDriver`	`jdbc:sqlserver://host:1433;DatabaseName=dbname`
`3`	DB2	`com.ibm.db2.jcc.DB2Driver`	`jdbc:db2://host:50000/dbname`
`4`	MySQL（最常见）	5.x `com.mysql.jdbc.Driver`；8.x `com.mysql.cj.jdbc.Driver`	`jdbc:mysql://host:3306/dbname?useUnicode=true&characterEncoding=utf8&useSSL=false`（8.x 常加 `&serverTimezone=Asia/Shanghai`）
`5`	HSQL / H2 系	`org.hsqldb.jdbcDriver` 等	`jdbc:hsqldb:…`（以环境为准）
`6`	PostgreSQL	`org.postgresql.Driver`	`jdbc:postgresql://host:5432/dbname`
`7`	达梦 DM	`dm.jdbc.driver.DmDriver`	`jdbc:dm://host:5236/dbname`
`8`	人大金仓 KingBase	`com.kingbase8.Driver`	`jdbc:kingbase8://host:54321/dbname`
`9`	OceanBase	`com.oceanbase.jdbc.Driver`（或兼容 MySQL 驱动视部署）	`jdbc:oceanbase://host:2881/dbname` 或 MySQL 协议 URL
`10`	神通 Oscar	`com.oscar.Driver`	`jdbc:oscar://host:2003/dbname`

产品 UI 文案常见：Oracle、SQLServer、DB2、MYSQL、HSQL、POSTGRESQL、DM、KINGBASE、OSCAR；数值以表为准。OceanBase 有独立方言实现（Builder/Definition/Validator）。

dbType 必须与真实库一致：方言决定动态表 DDL、DAO、分页/函数差异。选错会出现建表失败、类型映射错误、运行 SQL 不兼容。

设计器「选择库类型后驱动类常自动带出」：手写 workspace 时按上表填 driverClass，勿留空（JDBC）。

各库 DDL 方言（平台内建）¶

动态表同步按 dbType 走对应包（概念名即可，不必记路径）：

库	Builder / Definition / Validator（概念）
MySQL	Mysql*
Oracle	Oracle*
SQL Server	Mssql*
PostgreSQL	PostgreSQL*
KingBase	KingBase*（schema 常强制 `PUBLIC.`）
OceanBase	OceanBase*（schema 常强制 `PUBLIC.`）
DM	DmSQL*
DB2	DB2*
HSQLDB/H2	Hsqldb*
Oscar	Oscar*

字段 JDBC Types → 列类型映射因库而异（例：CLOB→MySQL LONGTEXT、Oracle CLOB、PG TEXT；TIMESTAMP→MySQL DATETIME 等）。Agent 一般不手写 DDL，只要 dbType/连通正确，由表单/数据模型同步生成。

4. JDBC / JNDI / 读写分离¶

JDBC（默认）¶

必填倾向：useType=JDBC、driverClass、url、username、password、dbType、defaultDataSource（默认库）。

可用性：默认库落盘后**必须**投递 *.init_default_datasource 并等待 .done/.failed（见上「默认库初始化与可用性检查」及 §4.1）。设计器「测试数据库」可作人工复核。MySQL 注意 5.x/8.x 驱动类与 serverTimezone。

4.1 初始化脚本退出码（必做）¶

python "<skill-dir>/scripts/init_default_datasource.py" "<path/to/name.datasource>"
# 延时：--initial-delay 2 --poll-interval 2 --timeout 120

退出码	含义	Agent 行为
`0`	已进 `.sync/.done/`	默认可继续后续落盘/表单同步
`1`	已进 `.sync/.failed/`	必须警告用户；修正连接或环境后重新投递；勿假装已可用
`2`	文件/XML/非默认库/路径错误	先修 `.datasource` 再投递
`3`	超时未归档	检查 Runtime/Manager/Job 是否监听 `.sync/`；Designer 不处理

脚本仅用 Python 标准库：投递后按 initial-delay → 轮询 poll-interval → 总 timeout 检查归档；真实建连由平台 InitDefaultDataSourceSyncHandler 完成（无第三方 JDBC 包）。**禁止**投递后立即读盘判定成功/失败。

警告话术要点（exit 1）：默认数据源初始化失败；不通则 RT 表未就绪、表单 *.create_form_table 会失败、前台文档读写会失败。

JNDI¶

useType=JNDI，填 jndiName（容器内已绑定的名）。驱动/URL/账号可省略或仅作备用；以容器为准。只读侧对称用 readonlyUseType=JNDI + readonlyJndiName。

读写分离¶

readonly=true 时完整配置两套：

写/主：原 useType…dbType…poolsize…
读：readonlyUseType…readonlyUrl/readonlyJndiName…readonlyDbType…

未开启时：样例常保留 readonly=false、readonlyUseType=JDBC、readonlyDbType=0，其余 readonly 字段可空。

读写分离打开后：查询类走只读库；写入/事务仍走主库。只读库应是主库副本或兼容结构，否则读到陈旧/缺表数据。

5. 骨架 XML¶

JDBC MySQL（默认库）¶

文件：LeaveOA.application/datasource/main.datasource

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<dataSource id="__dsLeaveOAmain001">
  <name>main</name>
  <parentId>__a1b2c3d4e5f6g7h8i9j</parentId>
  <applicationid>__a1b2c3d4e5f6g7h8i9j</applicationid>
  <description><![CDATA[业务主库]]></description>
  <defaultDataSource>true</defaultDataSource>
  <useType>JDBC</useType>
  <driverClass>com.mysql.jdbc.Driver</driverClass>
  <url><![CDATA[jdbc:mysql://${DB_HOST:localhost}:${DB_PORT:3307}/obpm_leave?useUnicode=true&characterEncoding=utf8&useSSL=false]]></url>
  <username>${DB_USER:root}</username>
  <password><![CDATA[${DB_PASSWORD:password}]]></password>
  <dbType>4</dbType>
  <poolsize>20</poolsize>
  <timeout>3600</timeout>
  <readonly>false</readonly>
  <readonlyUseType>JDBC</readonlyUseType>
  <readonlyDbType>0</readonlyDbType>
</dataSource>

MySQL 8 示例差异：

  <driverClass>com.mysql.cj.jdbc.Driver</driverClass>
  <url><![CDATA[jdbc:mysql://localhost:3306/obpm_leave?useUnicode=true&characterEncoding=utf8&useSSL=false&serverTimezone=Asia/Shanghai]]></url>

JDBC PostgreSQL（附加库示例）¶

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<dataSource id="__dsLeaveOApg001">
  <name>report_pg</name>
  <parentId>__a1b2c3d4e5f6g7h8i9j</parentId>
  <applicationid>__a1b2c3d4e5f6g7h8i9j</applicationid>
  <defaultDataSource>false</defaultDataSource>
  <useType>JDBC</useType>
  <driverClass>org.postgresql.Driver</driverClass>
  <url><![CDATA[jdbc:postgresql://127.0.0.1:5432/report]]></url>
  <username>postgres</username>
  <password><![CDATA[postgres]]></password>
  <dbType>6</dbType>
  <poolsize>10</poolsize>
  <timeout>3600</timeout>
  <readonly>false</readonly>
  <readonlyUseType>JDBC</readonlyUseType>
  <readonlyDbType>0</readonlyDbType>
</dataSource>

JNDI 要点片段¶

  <useType>JNDI</useType>
  <jndiName>java:comp/env/jdbc/obpmLeave</jndiName>
  <dbType>4</dbType>
  <defaultDataSource>true</defaultDataSource>

读写分离要点片段¶

  <readonly>true</readonly>
  <readonlyUseType>JDBC</readonlyUseType>
  <readonlyDriverClass>com.mysql.jdbc.Driver</readonlyDriverClass>
  <readonlyUrl><![CDATA[jdbc:mysql://ro-host:3306/obpm_leave?useUnicode=true&characterEncoding=utf8&useSSL=false]]></readonlyUrl>
  <readonlyUsername>readonly</readonlyUsername>
  <readonlyPassword><![CDATA[ro_pass]]></readonlyPassword>
  <readonlyDbType>4</readonlyDbType>
  <readonlyPoolsize>20</readonlyPoolsize>
  <readonlyTimeout>3600</readonlyTimeout>

根元素错误示例（禁止）：<datasource>、<DataSource>。必须 dataSource。

6. 与平台表 / 动态表的关系¶

默认数据源库上两类结构：

类别	前缀/表	何时出现
平台静态表（应用初始化）	`T_DOCUMENT`、`T_FLOWSTATERT`、`T_ACTORRT`、`T_UPLOAD`…	软件 `activated=true` 且默认库可用时初始化
动态表	`TLK_<表单名>`、`LOG_<表单名>`、`PARM_<表单名>`	表单保存/同步；列=`ITEM_`+字段名（大写）+固定系统列

文档头：T_DOCUMENT.MAPPINGID → TLK_<表单名>.ID。

仅手写 .datasource 文件：连接与表同步依赖**下次启动 / 导入 / 设计器保存**。激活保存副作用（走平台 API 时）：解析默认库 → 初始化 RT 表 → 全表单 createOrUpdate 动态表；软件 **name 变更**会销毁并重建 DataSourceEnv。

附加数据源：一般不参与上述初始化；用于跨库查询、报表、数据模型、Excel 导出到物理表等。

用户中心等系统表由平台全局库管理，与业务默认库可同可异；脚本改 t_user 等时注意目标是否本数据源。

7. 消费者与关联功能¶

消费者	如何用数据源
表单 / 文档 / 视图列表	隐式默认库；视图 SQL/DQL 也打默认库
流程运行数据	默认库上流程 RT 表
数据模型 `datamodel/`	配置时选数据源；可「从数据源导入」表/视图，或「同步到数据源」落物理表
元数据管理	管理软件下数据源及表单元数据、索引优化
UReport / OLAP / 图表	选本应用数据源或另配；脚本可设 SQL/存储过程/自定义 DRDataSource
Excel 导入导出到库表	选 `dataSourceId` + 目标表（运行 API：`getAppDataSources` / `getDataSourceTables` / `getDataSourceTableSchema`）
iScript	按 name 调用 `*ByDSName`
定时任务	可用 `DataSourceDesignTimeService` / `createOrUpdate` 等设计态服务执行 SQL

菜单 / 角色 / 模块 **不**引用数据源 id。报表菜单只挂报表资源；报表内部再选数据源。

8. 脚本与运行时 API（按名）¶

dsName / dataSourceName = 数据源 name。

`DATABASE` / `DB`（iScript 常用）¶

方法	作用
`queryByDSName(dsName, sql)`	查询；返回 Collection（元素为 Map/Document 风格，`.get("列名")`）
`countByDSName(dsName, sql)`	计数
`insertByDSName(dsName, sql)`	插入
`updateByDSName(dsName, sql)`	更新
`deleteByDSName(dsName, sql)`	删除
`beginTransaction(dsName)`	开事务
`commitTransaction(dsName)`	提交
`rollbackTransaction(dsName)`	回滚
`closeSessionAndConnection()`	关连接/清一级缓存（无 dsName）

脚本里常见别名：DB.queryByDSName / 顶层 queryByDSName（视脚本环境注入而定）。动态表例：tlk_表单名、列 item_字段名（库大小写随方言）。

`sys_function.DATASOURCENAME`¶

取**当前软件默认数据源名称**，避免写死：

var dName = sys_function.DATASOURCENAME;
DB.updateByDSName(dName, sql);

干预/回滚/终止流程等常用脚本集合惯用此写法。

设计态服务（定时任务等）¶

var process = Packages.cn.myapps.designtime.common.service.DesignTimeServiceFactory
  .resolve("cn.myapps.designtime.datasource.service.DataSourceDesignTimeService");
process.queryInsert(dsName, sql, getApplication());

const DataSourceDesignTimeServiceImpl =
  new Packages.cn.myapps.designtime.datasource.service.DataSourceDesignTimeServiceImpl();
DataSourceDesignTimeServiceImpl.createOrUpdate(dataSourceName, sql, applicationId);

注意：设计态服务与运行态 DB.* 场景不同；定时任务里按文档/环境选用。

最小查询例¶

(() => {
  const sql = "select id, name from t_user where domainid='" + getDomainid() + "'";
  const datas = DB.queryByDSName(sys_function.DATASOURCENAME, sql);
  return datas;
})()

SQL 拼接注意注入与引号；优先参数化若环境支持，否则严格转义业务入参。

9. 命名与 id¶

规则	要求
name	非空；同应用 `datasource/` 唯一；作文件名；英数/下划线稳妥
id	全局不与其它设计态对象冲突
默认库	同应用一个 `defaultDataSource=true`
重命名	改文件名 + `<name>`；同步所有按名脚本/报表/模型引用
危险字符	避免 `/` `%` `\`
根元素	`dataSource`
id 位置	`<dataSource id="…">` 属性，不是子元素

10. 新建清单（Agent）¶

1. 确认软件 id（读 {软件}.application 根属性 id）、activated、工作区路径
2. 生成 dsId；定 name（查 datasource/ 不冲突）；定是否默认库
3. 定 dbType + driverClass + url（或 JNDI）；账号密码或占位符
4. 写 datasource/{name}.datasource：
   parentId=applicationid=软件id
   defaultDataSource=true|false
   useType、池参数、readonly 套件
5. 若本软件尚无默认库：本文件必须 defaultDataSource=true（或保证解析能落到可用项）
6. （可选）额外库 defaultDataSource=false，供报表/脚本（不投递 init_default_datasource）
7. 默认库：跑 scripts/init_default_datasource.py（投递后延时轮询 .done/.failed）
   - exit 0（.done）→ 继续
   - exit 1（.failed）→ 警告用户，勿声称已可用；修正后重新投递
   - exit 3（超时）→ 确认 Runtime/Manager/Job 已监听 .sync/；勿投递后立刻判定
8. 部署侧：库已建、账号权限足够建表/DML；环境变量已设；监视服务在跑
9. 表单动态表：按 FORM_SKILL 投递 *.create_form_table（依赖本步已成功）

与软件新建配合¶

常规包顺序：软件目录 + .application → 默认 .datasource → 角色 → 模块/表单。无默认库则后续表单动态表无意义。细节路径见 APPLICATION_SKILL；字段细节以本文为准。

11. 校验与常见错误¶

问题	处理
表单无表 / 同步跳过	查是否有 defaultDataSource、`.init_default_datasource` 是否进 `.done/`、dbType
连接/初始化失败	查 `.sync/.failed/`；修 URL/账号/防火墙/SSL/时区后重新投递；MySQL 8 换 `cj` + serverTimezone；exit 1 须警告用户
触发一直停在 `.sync/`	Designer 不处理；需 Runtime/Manager/Job；脚本 exit 3
前台文档报错	默认库；RT 表是否已进 `.done/`；软件 activated
旧包 datasourceId 无效	删依赖；改用 `.datasource` + `defaultDataSource`
根元素错误	必须 `dataSource`
id 写成子元素	改为根属性
文件放进 module	移到 `…/datasource/`
做成目录型资源	应为单文件 `name.datasource`，不是文件夹
多个 defaultDataSource=true	收敛为一个；否则行为依赖实现/列表顺序
脚本找不到库	`ByDSName` 用的是 name* 不是 id；检查拼写
DATASOURCENAME 为空/错	软件无默认库或未解析到
读写分离读旧数据	副本延迟或只读库未同步结构
KingBase/OceanBase 对象找不到	方言强制 schema（如 PUBLIC）；查对象所在 schema
改软件名后连接异常	DataSourceEnv 重建；核对数据源 parentId/applicationid 仍指向软件 id
poolsize/timeout 无效类型	样例用字符串数字；保持一致

手写包：默认库**必投递** *.init_default_datasource 并确认进 .done/（推荐 scripts/init_default_datasource.py）；亦可用设计器「测试数据库」复核。

12. 与其它技能边界¶

内容	本文	其它
`.datasource` 字段、dbType、默认库、JDBC/JNDI、读写分离、脚本按名	✓
软件元数据、activated、目录骨架、保存副作用概要	交汇	APPLICATION_SKILL
角色 / 菜单 / 模块路径	数据源不在其内	ROLE / MENU / MODULE_SKILL
表单 JsonTemplate、字段、activity	动态表落在默认库	FORM_SKILL
视图列/查询	查默认库	VIEW_SKILL
`TLK_` 列级/DDL 细表	概要	design/database-struct、dyna-form
数据模型 UI 步骤	概要选源	developer-manual data-model
报表 SQL 数据源脚本	按名/选源	报表手册 / iscript

生成业务包时：先软件 + 本文默认数据源 + 角色，再模块/表单/视图；跨库需求再加附加 .datasource 并在脚本/报表中按 name 引用。