# 多数据源声明（SQLite / MySQL 云库）

本文说明技能如何向匠厂宿主**声明**业务数据库，以及技能 CLI / Action 如何与宿主读写**同一物理库**。

**产品定位：** 默认仍是本地 SQLite（`{skill_slug}.db`）。需要多用户共享、集中运维或云库时，可显式声明 **MySQL**。UI / API 契约不变；`_jiangchang_*` 展示元数据仍写在同一逻辑库中。

**宿主版本：** 匠厂 Host **≥ 6.9.28** 才支持 `data-sources.json` 与 MySQL 连接器。

**完整参考实现：** [`process-work-order`](https://git.jc2009.com/client-commons/process-work-order) @ v1.0.2（工单管理 + MySQL 云库试点）。

---

## 何时用哪种后端

| 场景 | 推荐 |
|------|------|
| 单机、离线、小数据量、便携部署 | **SQLite**（默认，不配声明文件亦可） |
| 多用户共享、运维集中管库、与外部系统共库 | **MySQL 云库**（显式 opt-in） |

**硬规则：一个 `sourceId` 对应一个物理库。** 禁止双写、禁止 SQLite 与 MySQL 同步镜像。

---

## 文件位置

均在**用户数据目录**（不是安装包目录）：

```
{JIANGCHANG_DATA_ROOT}/{JIANGCHANG_USER_ID}/{skill_slug}/
├── data-sources.json      # 声明式数据源（可选；见下）
├── .env                   # MYSQL_DSN 等连接配置
└── {skill_slug}.db        # SQLite 模式下的本地库文件
```

安装/升级时，若用户目录尚无 `data-sources.json` 且技能包内有 `assets/data-sources.example.json`，宿主会**复制一次**示例（不覆盖已有文件）。

模板默认示例为 **SQLite 显式声明**（与自动扫描 `{skill_slug}.db` 等价）。改走 MySQL 时，请参照 `assets/examples/data-sources.mysql.example.json` 手工替换用户目录中的 `data-sources.json`，并在 `.env` 配置 DSN。

若不需要声明式接入，可删除用户目录中的 `data-sources.json`，宿主恢复自动扫描 `.db` 文件。

---

## `data-sources.json` 格式

根对象：

| 字段 | 类型 | 说明 |
|------|------|------|
| `version` | `1` | 固定为 1 |
| `sources` | 数组 | 至少一条数据源 |

每条 `sources[]`：

| 字段 | 必填 | 说明 |
|------|------|------|
| `id` | 是 | 英文标识，如 `primary` |
| `kind` | 是 | `sqlite` 或 `mysql` |
| `displayName` | 否 | 侧栏展示名；多库时建议填写 |
| `path` | sqlite 必填 | 相对技能数据目录的路径；可用 `{skillSlug}` 占位 |
| `connectionEnv` | mysql 必填 | `.env` 中 DSN 的环境变量名，如 `MYSQL_DSN` |

### SQLite 示例（模板默认）

见 [`../assets/data-sources.example.json`](../assets/data-sources.example.json)。

### MySQL 示例

见 [`../assets/examples/data-sources.mysql.example.json`](../assets/examples/data-sources.mysql.example.json)。

---

## `.env` 与 DSN

MySQL 连接串写在用户 `.env`（或进程环境变量），**不要**写进 `data-sources.json`：

```env
# MySQL 云库连接（不配则走本地 SQLite）
MYSQL_DSN=mysql://user:password@192.168.0.20:3306/your_database
```

格式：`mysql://` 或 `mysql2://`，须含库名。注释写法须符合 [`../development/CONFIG.md`](../development/CONFIG.md)（配置管理会展示给用户）。

技能 Python 侧：`scripts/db/backend.py` 读取同一 `MYSQL_DSN`；有值则 `resolve_backend()` 为 `mysql`，否则 `sqlite`。

---

## 技能代码职责

### 宿主 UI（数据管理）

宿主读取用户目录 `data-sources.json` + `.env`，经 Host 内置连接器访问库。**不依赖**技能 `connection.py`。

### CLI / Action / `init-db`

**必须**与宿主使用同一后端策略，否则会出现「UI 看云库、CLI 写本地 `.db`」的分裂。

模板已提供：

| 模块 | 作用 |
|------|------|
| `scripts/db/backend.py` | `resolve_backend()`、`parse_mysql_dsn()` |
| `scripts/db/cursor_compat.py` | 统一 `?` 占位符与 `executescript` |
| `scripts/db/connection.py` | `get_conn()` 双分支；`init_db()` 幂等建 `_jiangchang_*` |

业务表 DDL / 迁移仍在技能自己的 `schema` / `init_db()` 中按 `conn.backend` 分支处理（见工单参考实现）。

可选：`describe_active_store()` 用于 health / 排障，输出当前连的是 sqlite 还是 mysql。

---

## MySQL 当前限制（Host）

- 不支持 `tableAdmin`（建表/改表 UI）
- 不支持 `cellPresentation`
- 元数据与 CRUD 与 SQLite 路径一致

表结构变更仍由技能 `init-db` / 迁移脚本负责。

---

## 开发 Checklist（云库）

复制新业务技能并选择 MySQL 时：

1. Host ≥ 6.9.28
2. 用户目录放置 `data-sources.json`（mysql 源 + `connectionEnv`）
3. `.env` 配置 `MYSQL_DSN`（或你在 json 里声明的 env 名）
4. `requirements.txt` 含 `PyMySQL>=1.1.0`（模板已声明）
5. 业务 DDL 同时支持 sqlite / mysql 分支（或仅部署 mysql）
6. **抽测**：数据管理 UI 与 CLI（如 list / create）读写同一库
7. 见 [`../development/CHECKLIST.md`](../development/CHECKLIST.md) A6-16

---

## 与 SCHEMA / ACTIONS 的关系

- [`SCHEMA.md`](SCHEMA.md)：`_jiangchang_*` 契约适用于**已注册数据源**上的表，不限于本地文件。
- [`ACTIONS.md`](ACTIONS.md)：无 `replaces` 时宿主直写**已注册数据源**（默认本地 SQLite）。
- [`CLI.md`](CLI.md)：`init-db` 对当前 active backend 幂等初始化元数据。