DataNavo
by tangzhongwen
README.md
# DataNavo
DataNavo 通过 MCP 为其他 Agent 提供 BI 和企业数据分析能力,并提供支持单企业和多租户的 MySQL BI Web 应用。配置数据源并同步源表,在关系画布和表单中维护同源多表语义模型,用维度、指标、筛选和排序自动查询,以二维表格查看精确结果。
计划使用的官网域名为 `datanavo.dev`。
第一次使用请从[本地快速试用](docs/quickstart.md)开始。示例使用合成数据,覆盖安装、初始化、建模发布和外部 MCP 查询。
## 启动
需要 Node.js 24.7+、Python 3.12,以及可访问的 MySQL。首次安装:
```sh
npm ci
python3.12 -m venv .venv
.venv/bin/python -m pip install -r python/requirements.txt
npm run build
npm start
```
访问 http://127.0.0.1:3000 。无元数据库配置时显示部署配置页;启动终端会提示本次配置会话凭据文件的位置,在页面输入该文件内容。默认选中 SQLite,但不会自动创建数据库。首次建立新库时主动选择“初始化新的空库 / Schema”,测试后点击“保存并启用”并确认目标;元数据库与 Worker 就绪后,使用同一部署凭据完成产品初始化,选择单企业/多租户、首个企业及管理员;之后用用户名密码登录。本版账号密码不限制长度或强度,可留空;初始化、注册、改密与重置使用相同规则。普通用户由管理员分享租户可复用注册链接自行注册,用户管理没有直接新增账号。Ctrl+C 统一停止。
默认运行数据为 `data/`;正式部署将 `DATANAVO_DATA_DIR` 指向安装目录外的固定持久目录。SQLite、MySQL 均使用 MikroORM 和 JSON 文本,旧 JSONB 或其他不匹配结构明确拒绝,原数据不转换或清空。开发与验证使用独立数据目录。
`npm start` 启动前会比较 `dist/web` 与参与前端构建的源码(`web/`、`shared/`、设计系统组件、入口与构建配置):产物缺失或落后时自动运行 Vite 构建,因此改了前端后直接重启即可生效;产物新鲜时不做额外构建。这一步只做打包,完整校验(i18n、parser 生成、类型检查、后端构建)仍以 `npm run build` 为准;后端改动需先 `npm run build:server`,`npm start` 不会重建后端。
前端开发用 `npm run dev`,访问 Vite 显示的地址(默认 5173),`/api` 代理至 3000。入口先构建后端,修改后端后重新运行。直接访问 3000 时读到的是 `dist/web` 构建产物,由上述启动检查保证新鲜。`PORT` 可修改产品端口,开发代理需同时核对 `vite.config.ts`;`DATANAVO_PYTHON` 可指定 Python 可执行文件。
生产远程访问设置 `DATANAVO_PUBLIC_URL=https://应用域名`,用于可信 Origin、Secure Cookie 和注册/重置链接;不从转发头推断。回环 HTTP 仅供本地开发。会话绝对有效期 12 小时、空闲有效期 30 分钟;退出、改密、重置或停用后重新登录。页面、操作和模型权限来自当前有效角色,监控与全局配置仅部署管理员可见。实现与实际验证边界见[身份权限验证](docs/acceptance/identity-access-verification.md)。
## AI 助手、公共结果与 CLI
官方助手是可选启用的 DataNavo 查询与建模客户端。在“系统配置 → AI 助手”启用并配置模型服务后使用;默认关闭。关闭后不接受新对话运行,已有会话、结果和执行记录保留,核心 BI、对外 MCP 与 CLI 独立运行。
助手的查询、建模、业务指南和结果读取统一通过本服务 `/api/mcp`,自动使用当前用户的短期委托凭据,无需配置 PAT。每次调用仍核验当前角色、资源权限和接口能力。保留流式回答、会话历史、上下文压缩、运行取消与执行记录。选择 DeepSeek 时固定开启深度思考;不提供任意外连 MCP、stdio、个人外部 Key、通用附件、文件工作区、沙箱、Shell 或任意代码执行。模型服务的部署凭据仍由管理员配置。
卡片引用公共查询产物并经 MCP 取数。结果支持分页、CSV/JSONL 导出和下载;删除会话不删除公共产物,关闭助手也不删除任何数据。完整边界见[助手设计](docs/design/agent-runtime-design.md)。
公共 BI API 位于 `/api/bi/`,建模入口位于 `/api/bi/modeling/`。查询使用名称 DSL、固定内容与校验 token;产物默认最多五行预览,完整数据按需分页。写操作先保存 operationId,断线后核对原回执,不盲目重放。模型写入返回草稿与修订,随后校验;发布使用单草稿及预期修订。
核心 CLI 使用账户菜单签发的个人访问令牌(PAT),保留查询、建模、导出及资源管理命令:
```sh
npm run build:server
export DATANAVO_URL=http://127.0.0.1:3000
read -rs DATANAVO_TOKEN
export DATANAVO_TOKEN
npm run cli -- models list --json
npm run cli -- sources list-for-modeling --json
npm run cli -- query analyze --input /absolute/path/query-request.json --json
npm run cli -- artifact rows --artifact-id <artifactId> --offset 0 --limit 100 --json
npm run cli -- --help
```
CLI 不提供聊天工作区、附件或 Skill 命令。下载必须指定新的本地 `--output` 文件。PAT 的接口能力与用户当前业务权限取交集,服务仅保存摘要;默认有效期 30 天,可设置 1–90 天。
完成的公共结果与导出保存在 `query-artifacts/`,会话保存在 `agent/`,操作回执保存在 `operations/`,均按租户/用户隔离。默认单结果 100 万行/64 MiB,容量不足拒绝新写入。文件目录由单一宿主独占,不支持多节点共享。旧元数据库结构明确拒绝启动,不自动迁移或清空;请显式初始化独立新库。
## 外部 Agent 与 WorkBuddy 接入
通过 `/api/mcp` 提供无状态 Streamable HTTP MCP,使用核心个人 PAT。工具覆盖模型发现、目录、查询、结果分页、导出、取消、建模读写及校验发布。Agent 使用 `knowledge_browse`、`knowledge_search`、`knowledge_read` 或 MCP Resources 读取获准的模型、共享知识和指南。知识正文保存在本地内容目录,SQLite 归档包含所需正文。官方助手使用同一工具合同,采用服务器内部委托身份。
远程部署配置可信 `DATANAVO_PUBLIC_URL=https://应用域名`,拒绝不可信 Origin。当前不提供 OAuth、stdio 桥接或客户端市场自动安装。查询返回最多五行预览及 artifactId,更多结果使用 `artifact_rows`,完整内容未读完不能推断全局结论。
连接配置、工具清单、使用流程及能力要求见[接入指南](docs/external-mcp-guide.md)。本机 WorkBuddy 的配置入口和首次信任步骤见[WorkBuddy 接入](docs/external-mcp-guide.md#11-在-workbuddy-接入)。CLI 是独立可选客户端,可用 `npm run pack:cli` 生成安装包。
## 运行日志与排障
`npm start` 与 `npm run dev` 的产品后端默认同时向 stderr 和 `<dataDir>/logs` 保存 UTF-8 JSON Lines,最低级别为 info。每个 HTTP 响应携带服务端生成的 `X-Request-Id`,可按日志 `requestId` 找到终态,再由 `failureId` 关联安全根因。浏览器 API 错误保留 HTTP status 和请求编号。日志不会包含 SQL、绑定值、密码、请求正文或原始异常文案;debug 使用相同边界。Vite、npm 和构建工具输出不混入产品日志文件。
日志配置在启动时读取,变更后重启。`DATANAVO_LOG_LEVEL` 仅接受 debug、info、warn、error、fatal;`DATANAVO_LOG_OUTPUT` 接受默认 `both` 或仅终端的 `stderr`;`DATANAVO_LOG_DIR` 可指定绝对目录。默认单段上限 100 MiB,按大小或 UTC 日期轮转,滚动保留 7 天、合计最多 1 GiB 和 1024 段;先触发容量限制时保留时间会缩短。可通过 `DATANAVO_LOG_MAX_FILE_MIB`、`DATANAVO_LOG_RETENTION_DAYS`、`DATANAVO_LOG_MAX_TOTAL_MIB` 调整,范围及校验见[配置合同](docs/design/logging-persistence-design.md#2-配置合同)。非法配置安全非零退出;合法配置遇到文件故障时保留 stderr 并继续业务。POSIX 新日志目录为 `0700`,文件为 `0600`;已有目录不符合私有权限要求时停用文件输出。
已构建安装可直接查询,无需启动服务;缺少产物时先运行 `npm run build:server`。默认显示最后 200 条匹配记录,`--level` 为最低级别,其他筛选取 AND;时间必须含时区,区间为 `[since, until)`。使用绝对 `--dir` 可独立读取另一个部署目录:
```sh
npm run logs
npm run logs -- --lang en --follow --level warn
npm run logs -- --request-id root-demo
npm run logs -- --failure-id failure-demo --since 2026-10-23T00:00:00Z
npm --silent run logs -- --json --limit 500
```
目录只允许一个产品宿主写入,多实例须配置不同目录。正常停止回收 `.writer-lock`;SIGKILL、断电或锁操作中崩溃可能留下锁,后续实例保守停用文件输出。恢复前先停止所有使用该目录的实例并确认无写入者,再人工检查、移除 `.writer-lock` 并重启;保留全部 `.jsonl`,不自动按 PID 或超时抢锁。文件故障的有限恢复不会补写失败期间的记录。完整命令、故障和生命周期边界见[开发设计](docs/design/logging-persistence-design.md)。
正式部署仍应收集 stderr,覆盖文件故障和尽力输出的 fatal 事件,并限制访问、容量和保留期限;不要长期使用 `2>>app.log` 无限追加。Linux systemd 可让服务使用 `StandardError=journal`,由 journald 设置 `SystemMaxUse`、`SystemKeepFree` 和 `MaxRetentionSec`(例如 256M、1G、7day);用 `journalctl -u datanavo -o cat` 读取并过滤 JSON 事件。安装包同时保留 `dist/shared/error-catalog.json`、`dist/shared/public-messages.json`、`dist/shared/locales/`、`shared/error-catalog.json`、`shared/public-messages.json` 与 `python/`,Node/Python 从模块资源位置读取,不依赖启动时工作目录。缺省数据目录也相对安装根;显式相对 `DATANAVO_DATA_DIR` 仍相对启动 cwd,服务与 CLI 从不同目录启动时应使用绝对数据或日志目录。
单条日志不超过 16 KiB,每个 sink 的独立应用队列最多 1 MiB/1024 条;下游阻塞时优先丢弃 debug/info,恢复后报告累计损失。停止在既有总期限内为所有输出共同保留最多 1 秒刷新。日志不是数据库提交、资源已排空或断电持久化的证明;超时、响应中断及提交结果未知时先读取当前状态,不自动重放 SQL 或保存请求。基础接入证据见[日志与异常验证](docs/acceptance/logging-error-handling-verification.md),文件与本地查询的实际检查及未测边界见[持久化验证](docs/acceptance/logging-persistence-verification.md)。本轮在 macOS arm64、Node v26.12.0 验证,最低 Node 24、Linux/Windows、真实满盘及完整权限故障尚未验收。
## 元数据库配置
- 宿主管理配置位于 `DATANAVO_DATA_DIR/metadata-config/`。普通字段和 0600 凭据文件同代次保存,`active.json` 原子发布;配置会话只接受回环同源请求。元数据库未就绪时业务 API 返回 `503/METADATA_NOT_READY`。
- 正常重启只打开当前已有库;目标丢失或变空不会重建。修改连接前停止原服务,再以 `DATANAVO_METADATA_SETUP=1 npm start` 进入维护模式。切换库不会搬迁原数据。
- 设置 `DATANAVO_METADATA_CONFIG=/path/metadata.json` 时,部署文件为唯一且只读来源;秘密通过环境变量引用,错误不回退本地配置或 SQLite。首次自动部署先显式初始化,再启动产品。
```sh
npm run db:init -- --lang zh-CN --database /tmp/datanavo-check/metadata.sqlite
# MySQL 或外部插件使用部署文件;与 --database 互斥:
npm run db:init -- --config /path/metadata.json
```
CLI 只对明确目标初始化及核验,不发布当前配置、不启动业务。当前完整结构重复执行不写 DDL;空目标以外的未知、部分或旧结构拒绝。共同定义见 [entities.ts](server/metadata/entities.ts),运行时与外部插件说明见 [metadata README](server/metadata/README.md)。
MySQL 元数据库内置 `mysql2` 驱动,随 `npm ci` 和主程序交付。支持 MySQL 8.0.17+,使用 InnoDB、`utf8mb4_0900_bin`(NO PAD)、LONGTEXT 与 BIGINT;要求 InnoDB 页至少 16 KiB、`max_allowed_packet` 至少 32 MiB,以容纳完整索引和大 JSON。账号和专用 database 由管理员预先创建;初始化只创建应用表,不执行 CREATE DATABASE。元数据库连接与“数据源”页面的业务 MySQL 连接分别配置。
MySQL 部署文件示例:
```json
{
"plugin": "mysql", "mode": "fields",
"values": { "host": "db.internal", "port": 3306, "username": "datanavo", "database": "datanavo_metadata", "tls": "verify_identity" },
"secretRefs": { "password": { "env": "DATANAVO_METADATA_PASSWORD" } },
"runtime": { "poolMax": 4, "operationTimeoutMs": 5000 }
}
```
页面选择 MySQL 后使用同一声明式表单填写上述字段,端口默认 3306。TLS 支持 `disabled` 与系统 CA 的 `verify_identity`;自定义 CA 和客户端证书尚未支持。部署账号需要访问专用 database、读取实际结构目录、读写应用表及初始化时的建表权限。已有库缺失、为空或结构不匹配时按共同恢复规则拒绝,不重建、不自动迁移。
## 元数据库备份与恢复
部署管理员在“配置 → 元数据库备份”创建、查看、校验、下载和删除完整元数据库归档。首版支持 SQLite;MySQL 入口明确禁用。备份使用数据库原生完整快照,未来增删表或字段无需修改备份代码;创建期间暂停业务并排空写入,完成后恢复服务。
启动前设置 `DATANAVO_BACKUP_KEY_FILE=/secure/datanavo-backup.key`。该文件保存 **32 字节随机密钥的 64 位十六进制文本**,POSIX 权限设为 0600,并与备份分开保管。应用不会生成替代密钥;没有对应密钥就无法解密既有归档。加密 `.sdmeta` 归档保存在 `DATANAVO_DATA_DIR/metadata-backups/archives/`;用户账户、权限和库内凭据会随完整库保存,业务源库数据、Agent 密钥文件、聊天/公共产物及部署配置均不在包内。
恢复先校验归档,再由服务器创建独立的 `metadata-backups/restored/<operationId>/metadata.sqlite`。准备和启用分开确认;启用前必须匹配当前实际结构与领域存储合同,并补齐已知外部依赖。旧结构不匹配时拒绝,不自动迁移或覆盖当前库。启用会撤销旧会话、个人 PAT、注册及重置链接,保留账户密码与角色,随后重新登录。
源元数据库损坏时,以 `DATANAVO_METADATA_SETUP=1 npm start` 启动本机维护入口,使用部署维护会话读取既有归档;恢复不依赖源业务 Store。首版不接受 Web 上传或任意目标路径。使用外部只读 `DATANAVO_METADATA_CONFIG` 时,页面不会覆盖部署配置或自动启用。实现边界与实际验证见[备份设计](docs/design/metadata-backup-design.md#7-实施与验收)。
## 使用
1. **数据源**:选择已安装的 MySQL 连接器,填写稳定 ID、名称、连接、时区及密码。可先测试当前输入,保存时服务会重新探测连接,探测成功才保存。读取源库表清单,勾选表后同步完整结构。密码使用单个输入框;编辑时显示固定掩码,未修改则沿用已保存密码,输入后使用新密码。扩展数据库见[数据源驱动](#数据源驱动)。
2. **语义模型**:内容页默认展示只读关系画布,点表查看字段和计算列;点击“编辑模型”选择或新建草稿,新建成功后直接进入工作区。先创建空模型,再添加已同步整表;草稿工具栏也提供新建计算列。表节点只显示名称,每张表可自由拖动;未指定位置时自动排列并避开已有节点,拖动后的位置随“保存关系图”提交,重新打开后恢复布局。按住 Shift 拖向另一张表或点击“建立关系”,配置多对一方向、LEFT / INNER 和字段条件;图、维度和指标先加入本地完整草稿,再统一手动保存;发布后才对普通使用生效,内部标识由服务端签发,业务错误单独诊断。结构变化先查看差异并整体确认,再保存映射和比较基线;模型状态标识打开完整报告,可定位问题和重新校验。
3. **查询**:选择正常模型,添加维度/指标;日期维度展开后可同时勾选年、年季、年月、年月日、原值,各层独立成列并按完整组合分组,暂不生成小计行。配置统一筛选、排序和每页行数(默认 20 条)。完整有效配置自动查询;只维度返回去重组合,只有指标返回总计。来源歧义提示补选指标。高级 DSL 只读,查询页撤销支持配置、模型切换和清空。
模型关系区可添加 **SQL 查询表**,在共用编辑器中编写统一 SQL(含 `UNION / UNION ALL`)或 MySQL 原生查询。按“读取字段 → 应用字段变化 → 应用到模型 → 保存草稿”操作;字段名称、类型和 NULL 信息来自真实数据库且只读,同名保留 ID,删除/改名保留下游失效引用。未探查、过期和业务错误仍可保存/发布,普通查询继续要求模型通过当前完整校验。显式预览默认 20 行、最多 200 行,需要 `model.update` 与独立的 `model.sql.preview`,并按当前身份过滤该 SQL 节点的输出行。详细范围、实际检查和未测项见[SQL 查询表设计](docs/design/sql-query-tables-design.md)与[验证记录](docs/acceptance/sql-query-tables-verification.md)。
上下文计算先生成显式语义图,再按固定后端规则安排执行实例和 SQL。同一语句、快照及需求下,已证明相容的成员域、重复计算、同行标量和多输出归约可以共同生产;每个中间转换、条件保护与缺侧总化保持。实现范围及实际结果见[上下文查询优化](docs/design/context-query-optimization-design.md)和[验证记录](docs/acceptance/query-plan-optimization-verification.md#10-上下文查询通用计划优化2026-11-01)。
结果列按维度后接指标的选择顺序排列,表头为业务名称;NULL 显示为 `NULL`,Decimal 和整数用精确字符串。支持 SUM、AVG、COUNT、COUNT DISTINCT、MIN、MAX。结果支持后端分页,默认每页 20 条,每页上限 200;底部上一页/下一页浏览完整结果,修改数据配置回第一页,翻页可撤销。每页使用独立快照,不额外查询总数。保留上次结果时明确标示正在更新或已与当前配置不同,旧请求响应不能覆盖新配置。
查询顶部可保存完整草稿、另存为新资源,并进入资源管理。正式名称在租户内唯一,只折叠 ASCII 英文大小写;草稿和历史不占名,空输出或未选模型也可保存。字段顺序、筛选、排序、依赖参数实际值及展示设置一并保存,默认值也固定,NULL、空字符串与未填写分别恢复。最新正式查询跟随模型最新发布版,历史查询默认使用发布时正式依赖上下文;每次打开回到第1页,不恢复旧结果。结果未知按原 operationId 核对安全回执,不更换预期修订或载荷重试。详见[保存查询设计](docs/design/saved-queries-design.md)与[资源版本验证](docs/acceptance/resource-versioning-verification.md)。
元数据库保存数据源、原生目录、资源身份、草稿与正式版本、操作回执、内容检查、全局查询配置及身份权限。模型图、维度、指标和保存查询配置属于各自完整定义 JSON,不另存平行分表。结构格式错误拒绝保存,业务错误仍保存并单独诊断;pending / invalid 模型需先校验修复后查询。TLS 支持 disabled 与系统 CA 的 verify_identity;自定义 CA / 客户端证书尚未支持。数据源时区是全部日期维度的唯一配置。
元数据库的共同异步 Store、内置 SQLite/MySQL、声明式配置页与外部包加载已接入;设计与边界见[元数据库与插件开发设计](docs/design/metadata-storage-plugin-design.md),实际结果见[本次验证](docs/acceptance/metadata-storage-verification.md)。历史 JSONB 验证不替代本次文本存储验收。
数据源 ID 是应用身份,`connection.database` 是真实 MySQL 库;源表以 catalog / schema / table 保存,MySQL catalog 固定 def,执行使用已转义的 schema.table。源表同步不创建业务表,也不改写模型结构。详细操作和失败处理见[页面流程](docs/design/page-flows.md)。
列表和详情可删除数据源或模型;模型画布选中表后可删除表,关系编辑和维度/指标列表也提供删除。删除数据源保留依赖模型;删除模型清除其图、维度、指标及报告,保留引用该模型的已保存查询,重新打开时提示修复;删除表同时清除连接关系,维度与指标保留待修复。表和关系删除确认后仍需保存关系图。数据源删除后的模型可在“模型信息”中改绑;数据源、模型与保存查询标识删除后不可复用。删除边界及版本校验见[元数据方案](docs/design/metadata-model-design.md#73-实施顺序)。不匹配的旧元数据库会明确拒绝启动。按开发约定使用独立新库,不自动迁移或清空用户原数据。
计算列只属于模型表,不修改或物化源表。在表节点进入字段管理,使用标签或源码编辑统一/原生表达式、声明结果类型,再加入关系图草稿;参数页签维护模型级标量参数、可空和固定默认值。查询按所选字段的递归依赖显示参数名称和值,修改后 450ms 防抖重查并回到第一页,非法值暂停查询并保留上次结果。统一模式只接受登记函数与本表字段;原生模式只检查模板元素,普通 SQL 在实际执行时反馈错误。两种模式均不预验声明与真实结果是否一致。详细规则见[计算列设计](docs/design/calculated-columns-design.md)及[产品验证](docs/acceptance/calculated-columns-verification.md)。
## 数据源驱动
业务数据库通过安装完整连接器插件扩展,插件包含编译适配、Python 执行适配及固定版本驱动依赖。产品当前随包提供 MySQL 连接器(PyMySQL 1.1.1);其他数据库需要完整适配与对应数据库验收。
部署者在启动前安装插件和依赖,用 `DATANAVO_SOURCE_CONNECTORS` 指向绝对路径的插件目录清单;重启后,数据源表单只选择已安装的连接器。没有驱动上传、检查、准备环境、源级附件绑定、替换或回收 API。测试与保存使用选中连接器,保存成功才更新源配置和数据库事实。安装合同及示例见[连接器设计](docs/design/source-driver-design.md)。已有运行数据不会因退出上传功能被清理。
## 系统监控与配置
主导航“系统监控”查看查询执行与保存 SQL,“系统配置”管理全局 query 组。每项可独立恢复默认,修改先留草稿,保存后用于下一次新查询,离开前可选择继续编辑、放弃或保存。
默认关闭每次数据库探测,开启查询快照和列检查,遵循实际后端原生排序规则,NULL 位置用数据库默认。此模式下 MySQL 的普通字符串参数直接绑定,让筛选沿用字段的比较规则;金额、日期及显式 CAST 继续按其类型合同处理。SQL 默认不做额外类型转换;开启“严格 SQL 输入/输出类型”后,纯源库普通指标恢复输入/输出类型转换、SUM/AVG 的 38 位精度和 AVG 舍入。计算指标、计算列及显式类型声明仍遵循原有规则。数据源每次保存都会重新探测版本与大小写事实;失败保留旧连接与凭据。关闭查询探测且保存信息缺失时,重新保存数据源或开启探测;查询临时探测不修改源信息。
执行记录固定各组值与 revision,业务 SQL/全部和完整计划/实际轨迹独立筛选。重查保留原配置、SQL、参数并重新核验能力;需要新配置时发起新查询。混合执行允许文本跨后端:“数据库原生排序规则”开启时各阶段使用自身规则,接受分组、关联和排序等结果差异;关闭后使用共同 binary 规则;本地排序保留配置指定的 NULL 顺序。结构变化使用独立最新元数据库,不迁移或清空用户旧库。完整边界见[查询规范](docs/spec/query-spec.md#11-全局查询配置),实际验证见[本轮记录](docs/acceptance/system-configuration-verification.md)。
## 模型与保存查询版本
模型和保存查询独立维护草稿与正式历史。首次保存建立资源和草稿,普通使用只跟随最新发布版;有编辑权限即可发布。修改图、维度、指标和查询配置后手动保存,确认后发布。一个资源最多 1 个编辑中草稿,保留最新版及最多 10 个历史;满额后先手动清理。多人修改同一草稿时校验保存修订,冲突后重新读取。历史支持两方比较和整体恢复为草稿,不提供三方合并或选择性撤销发布。放弃的草稿保留一个自然月,删除立即生效。
新建、保存、发布、恢复及删除都返回操作回执。网络中断或结果未知时核对原 operationId,严格原请求重试不会重复提交;不得把没有收到响应当作保存失败。保存和发布允许未完成或有业务错误的内容,实际查询仍要求模型检查通过、当前权限和有效查询。模型预览可选择草稿/正式版本,历史保存查询默认使用发布时的正式依赖上下文。
完整行为与接口见[资源版本设计](docs/design/resource-versioning-design.md),实际检查及未测边界见[开发验证](docs/acceptance/resource-versioning-verification.md)。旧分表结构不能直接打开;按最新实体显式初始化独立新库,原库不迁移或清空。
## 资源目录与授权
一级“资源”入口按数据源、语义模型、保存查询、共享知识四个固定分类查找对象;模型与查询可在各自分类内创建嵌套文件夹、整理位置,原列表显示同一目录路径。选中资源查看摘要,明确打开后进入原工作区;选中保存查询本身不执行查询。模型内容可展开模型表、维度、普通指标、计算指标与关联知识,内容项与物理引用不复制策略。知识正文里的来源链接打开对应模型、指标或维度。只有查询权限时,可以在知识工作区核对当前获准的只读来源。
打开模型、指标或维度编辑器会按当前权限解析已有知识关联的标题。添加列表的分页不影响已有标题,加载失败时可重新读取。
租户管理员从“管理 → 资源授权”配置角色及类型动作,支持动态继承、整份独立策略、空策略、恢复继承、批量影响预览、同分类移动和按用户查看来源。角色页提供同一策略的反向入口。对象管理动作按树策略核验,创建同时核验功能资格、目标容器与创建后的编辑资格;创建人不隐式获权。查询在 SQL 简化后、方言输出前检查模型资格和实际数据/原生输出依赖,不再逐指标叠加 ACL。目录、分析、公共 BI 和 Agent 复用该规则;PAT 只限制接口能力,角色与资源树策略决定当前业务权限;凭据页不再选择资源范围。管理员 SQL 重放保留管理与执行环境检查,不重新检查任务资源或读取已删除模型。实际覆盖见[查询授权验证](docs/acceptance/query-resource-access-verification.md)。
源表/字段以连续身份登记,完整同步确认缺失后退役,同名再出现取得新身份。新增共同实体要求显式初始化独立新库,旧库不转换、不清空。合同见[资源树与授权设计](docs/design/resource-access-design.md),实际结果和未测项见[产品验证](docs/acceptance/resource-access-verification.md)。
## 独立 API 自动化测试
通过 `DATANAVO_API_CONFIG` 提供仓库外私有部署配置,再执行 `npm run test:api`。测试使用 Playwright APIRequestContext,不启动浏览器;默认 4 个 worker,同一文件内的用例也可并发,单次请求、完整收集和单案默认及最大均为两分钟;普通产品 API/Worker 请求的默认期限与配置上限同为两分钟。复用已有模型,以固定完整数据判断 `/api/queries` 结果,另有三个公共产物冒烟。业务数据生成与 MySQL 导入独立执行,凭据、大型数据与 JSON/HTML/JUnit 报告均保存在仓库外。
准备步骤、配置与目标覆盖见[测试模块说明](tests/integration/api/README.md)。已导入人工边界、TPC-H SF=0.01 与 TPC-DS SF=1;TPC-H 全部 22 条具备固定请求与完整预期,此前 API 全量实测为 10 通过/12 失败,完整清单 54 条为 40 通过/14 失败。历史失败原因、Q13 的合法表达限制和未测项见[TPC-H 验证](docs/acceptance/tpch-api-verification.md),初次导入证据见[首期验证](docs/acceptance/api-testing-verification.md)。计算 DSL 补齐轮的 Q11/Q17 直接 SQL 复验及剩余超时见[原独立验收](docs/acceptance/calculated-metrics-execution-verification.md#10-最终独立验收2026-10-31);后续多事实实现的 Q22 精确通过、Q9/Q20 共同维度拒绝见[多事实限定复验](docs/acceptance/multi-fact-query-verification.md#32-tpc-h限定复验)。这两轮均未重跑完整 API 清单。
第二期[查询专项](docs/design/api-testing-design.md#0-前置任务资源导入导出)已接入首批五个固定包、身份/授权与导入发布准备,三条准备试点和 PREP-01–09 的入口见[模块说明 §5](tests/integration/api/README.md#5-第二期固定资源与初始化)。其余查询专项待逐案实施。前置[资源导入导出](docs/design/resource-transfer-design.md)已接入“资源”页的“导出资源/导入资源”:选择正式、历史版本或已保存草稿,下载 `.sdresources.json`;导入时显式绑定目标源、物理表、主体/属性和复用对象,检查后将新资源原子写入草稿。SQL 结构在目标环境重新核实,导入不自动发布;未知结果按原 operationId 核对回执。目标源、秘密与授权独立准备。PAT 还需 `resource.export`/`resource.import` 接口能力。新增成功回执表要求显式初始化独立新库,旧库不迁移或清空;[实际检查与未测边界](docs/acceptance/resource-transfer-verification.md)单独记录。独立原型仍为[模拟预览](prototypes/module-design/README.md#f27-资源导入导出)。
## 合成数据示例与验证
[本地快速试用](docs/quickstart.md)使用下方付款记录夹具,自动创建模型并比对两道 MCP 查询的独立预期。本节其余命令用于开发回归和手动建模。
[examples/order-model.sql](examples/order-model.sql) 是用于建立订单示例模型的五表数据集,包含 16 位顾客、18 件商品、12 个分类、200 笔订单和 600 条明细。关联字段同名且统一使用 `BIGINT UNSIGNED`,不建外键;保留未下单顾客和未售出商品。订单仅保存运费,商品金额保留在明细中。文件末尾附记录数和数据自洽检查,导入已创建的独立空库:
```sh
mysql --default-character-set=utf8mb4 --host=127.0.0.1 --port=33385 --user=root -p datanavo_order_demo < examples/order-model.sql
```
[examples/fixture.sql](examples/fixture.sql) 使用完全合成的数据,建立独立 `datanavo_fixture` 测试库,覆盖重复业务 ID、NULL、精确小数、有符号 64 位整数、微秒及时间边界、聚合溢出及 205 组分页数据。普通指标不要求全局粒度或主键字段。
在自己的测试 MySQL 导入 fixture,并创建仅对测试库有 SELECT 权限的 reader,密码自行设置:
```sh
mysql --host=127.0.0.1 --port=33385 --user=root -p < examples/fixture.sql
```
在数据源表单填写真实测试连接和密码,读取、勾选并同步 fixture 表;在模型中添加整表、定义维度和六种普通指标,再查询。最新 JSON 示例为 [source.json](examples/source.json)、[model.json](examples/model.json)、[dimensions.json](examples/dimensions.json)、[metrics.json](examples/metrics.json) 与 [query.json](examples/query.json)。其中 query.json 是管理端 `/api/queries` 的已绑定 ID 载荷;公共 MCP/CLI 使用[名称作者 DSL](docs/spec/query-spec.md#2-dsl-和语义能力)。模型示例中的 sourceTableId 占位值须换成同步返回的源表 ID,不是可直接写入的物理表名;独立人工预期为 [examples/expected.json](examples/expected.json)。
```sh
npm run typecheck
npm test
npm run test:python
npm run test:metadata -- --plugin=sqlite
# MySQL 元数据库使用独立测试库和部署配置:
# DATANAVO_TEST_METADATA_CONFIG=/path/metadata-test.json npm run test:metadata -- --plugin=mysql
npm run build
# 已导入独立 fixture 并配置 reader 后:
DATANAVO_TEST_PASSWORD='测试账号密码' npm run test:integration
```
集成环境默认 `127.0.0.1:33385`,可用 `DATANAVO_TEST_HOST`、`DATANAVO_TEST_PORT` 调整。也支持 `DATANAVO_TEST_PASSWORD_FILE` 指向包含 `{"password":"..."}` 的本地 JSON,避免密码进入 shell 历史。`DATANAVO_TEST_ADMIN_SOCKET` 仅指向独立合成测试实例的本地 socket,供测试观察活动连接/只读事务及修改 `drift_values` 夹具验证结构漂移;不赋予产品查询账号额外权限,不指向业务实例。缺少密码或该观察入口时,相应用例明确跳过,不视为真实通过;元数据库使用独立临时目录,默认 `data/` 不写入测试配置。普通预览不创建结果文件。
维度、指标的可用范围由本人当前角色与资源树策略控制,查询检查简化后实际使用的数据/输出及隐藏条件、排序、时间和计算依赖;消费目录仅投影可用内容。PAT 入口只选择接口能力,不保存维度/指标或其他资源范围。授权与模型内容版本分离;已有不匹配的元数据库明确拒绝,不自动迁移或清空。当前执行与未测项见[查询资源验证](docs/acceptance/query-resource-access-verification.md),旧子对象授权方案的历史证据见[子对象权限产品验证](docs/acceptance/semantic-object-access-verification.md)。
## 实现边界
- React / Vite,Node HTTP / MikroORM 元数据库插件,TS 编译,Python / PyMySQL 唯一访问业务数据库;连接器统一原生类型映射,页面消费共享的草稿评估。查询、断言和计算列使用同一套统一 SQL AST。
- 查询编译统一为 SQL 计划、准备、授权和渲染阶段;单事实同粒度普通指标共用聚合,适用的简单计算指标在聚合后投影,保留类型、NULL 和中间转换。计算指标除法使用显式原生数值策略压缩 SQL,普通计算列精确合同不变。源库负责读取与基础缩减,透明根窗口与计算多事实组合按固定规则进入 DuckDB;单事实标量按自身依赖保留源数值运算,独立事实展示不改变它的数值位置。不满足 effects、类型、键语义或本地驱动源读取边界时明确拒绝,不隐式改为全源运算。透明同粒度路径已接入独立语义/执行计划,复杂上下文的完整阶段迁移仍待完成。本期没有能力驱动自动选址;适用范围、独立结果及性能证据见[查询计划优化验证](docs/acceptance/query-plan-optimization-verification.md)。
- 业务 SQL renderer 按本次连接返回的 MySQL 版本与 `lower_case_table_names` 检查名称,当前接受 8.0.21 及后续 8.0 补丁版本、8.4.x、9.7.x、26.7.x 和 26.10.x;其他版本明确拒绝。非 ASCII 结构化标识符的目标等价规则尚未实现,会报告不支持;Unicode 字符串值仍可使用。元数据库插件的版本要求另见其配置说明。
- 同源多表仅沿 many → one 使用 LEFT / INNER,禁止有向环和多路径;共享维度多事实已按[专项方案](docs/design/multi-fact-query-design.md)接入,各事实独立聚合后按实际完整维度组合并集对齐,所有输出/过滤/计算维度须对每个事实有效。开发专项与独立验收分项记录在[验证报告](docs/acceptance/multi-fact-query-verification.md);不扩展 DSL,不支持查询结果集二次加工。不检测实际目标唯一性,不为重复匹配自动去重指标。
- Worker 支持多个在途调用、独立查询连接/事务和有界预算;超时及断开按请求处理。故障自动重建 Worker,失败或结果未知的 SQL 不自动重跑。
- 执行核对真实结构、类型和 NULL 属性,在 UTC 会话只读快照执行数值断言和结果 SQL;业务表要求 InnoDB 基础表。有限预览在内存按 schema 校验,空结果保留列,清理错误不覆盖结果。
- 计算指标已接入 M0–M3 核心执行:标量、上下文/成员、六类嵌套归约、完整期间与归约交叉、嵌套期间及分层排名与窗口,支持必要的源 → Arrow → DuckDB 单向混合。设置中的“查询执行”提供简单本地记录、SQL/绑定/来源和完整包重查。复杂组合及未测边界见[执行验证](docs/acceptance/calculated-metrics-execution-verification.md);尚未提供通用独立 SQL 工作台和跨源查询;Agent、产物图表与导出按上文独立合同使用。登录、资源授权及模型/保存查询发布分别按对应合同实现。
2026-10-13 批次完成 TS 52/52、Python 28/28、真实集成 12/12(零跳过)、生产构建/启动及三个页面 1280/390 px 检查,环境、命令和未测边界见[三模块实现验证记录](docs/acceptance/workflows-verification.md)。TLS verify_identity、最低运行版本、其他平台、大图和真实 SQL 故障丢响应未测。2026-10-14 删除能力的 65 项单元、3 项 HTTP/SQLite 和产品页面检查见[删除复验](docs/acceptance/workflows-verification.md#35-删除能力复验2026-10-14)。AVG 与默认 20 条分页的 68 项 TS、30 项 Python、16 项真实集成及产品/原型检查见[本次验证](docs/acceptance/query-pagination-verification.md)。分项完成情况见[功能状态表](docs/implementation-status.md)。产品范围见[产品设计](docs/product/product-design.md),精确值与执行见[查询规范](docs/spec/query-spec.md),文档入口见[文档目录](docs/README.md#文档目录)。
## UI 设计与预览
[设计系统](prototypes/module-design/design-system/README.md)是唯一视觉规范,产品与方案 A 原型共享公共组件源码和视觉令牌;方案已确认,产品和原型的独立检查结果见[本轮验证 §3](docs/acceptance/workflows-verification.md#3-实际页面与公共原型)。
```sh
python3 prototypes/module-design/preview.py
```
- [设计系统评审页](http://127.0.0.1:4311/design-system/preview.html)
- [三模块方案 A 原型](http://127.0.0.1:4311/prototype/index.html)
- [元数据库备份原型(已确认)](http://127.0.0.1:4311/prototype/metadata-backup.html),结构变化自动进入完整备份、结构匹配后恢复到独立目标;[设计与实现](docs/design/metadata-backup-design.md),正式产品支持 SQLite,独立目标由服务器自动生成
- [AI 助手与 Agent 运行原型(已确认)](http://127.0.0.1:4311/prototype/agent-runtime.html),会话、五类卡片、附件与结果生命周期、部署配置及异常场景;原型仅合成演示,正式产品检查见[Agent 产品验证](docs/acceptance/agent-runtime-verification.md)
- [F25 资源树与资源授权原型(已授权接入)](http://127.0.0.1:4311/prototype/resource-access.html),资源优先、动态继承、独立策略、批量/移动与来源检查;[原型说明](prototypes/module-design/README.md#f25-资源树与资源授权),原型使用合成数据,产品配置阶段已接入,执行边界见专项验证
- [身份与国际化界面改版原型(已确认并接入)](http://127.0.0.1:4311/prototype/identity-redesign.html),角色分组权限与模型授权矩阵、用户/注册/账户流程及紧凑页头;正式页面与 F25 资源目录已分别接入
- [计算指标与调用解释原型](http://127.0.0.1:4311/prototype/calculated-metrics.html),完整交互原型;产品定义编辑与静态分析已接入,属性继续占位
- [系统监控与查询执行原型](http://127.0.0.1:4311/prototype/query-executions.html),详情默认业务 SQL,可切换全部步骤;记录与 SQL 重查均为合成演示
- [全局系统配置原型](http://127.0.0.1:4311/prototype/query-executions.html#configuration),六项查询策略(含默认关闭的严格 SQL 类型)、逐项恢复默认值与能力拒绝;原型已确认,正式产品已接入,原型仍仅用合成演示
- [元数据库配置原型](http://127.0.0.1:4311/prototype/metadata-storage.html)
表关系画布的自由拖动、缺省位置避让及坐标保存恢复检查见[位置复验](docs/acceptance/workflows-verification.md#34-表位置缺省复验2026-10-14)。
只需 Python 3,Ctrl+C 停止;端口占用可加 `--port 4312`,见[原型 README](prototypes/module-design/README.md)。原型不连接数据库,不能代替产品或持久化验收。功能与数据规则分别见[页面流程](docs/design/page-flows.md)和[元数据方案](docs/design/metadata-model-design.md)。
正式产品提供简体中文与 English,页头语言入口即时切换;首次访问跟随浏览器,不支持时回退中文。偏好只在当前浏览器同源存储并同步标签页,不进入服务器配置;语言切换保留草稿、编辑器及查询结果。业务名称、SQL、DSL 和精确值不翻译。`db:init`、`logs` 支持 `--lang zh-CN|en`,未指定时按 `LC_ALL → LC_MESSAGES → LANG → 中文` 解析,`C/POSIX` 为英文;JSON 日志保持机器合同。接口、插件与消息边界见[国际化设计](docs/design/internationalization-design.md),本次实际检查与未测项见[产品验证](docs/acceptance/internationalization-verification.md)。
## 开发约定
从 [AGENTS.md](AGENTS.md) 进入,开发、验证和提交遵循[开发流程](docs/development-workflow.md),目录与命名遵循[仓库约定](docs/repo-conventions.md),按任务选择[文档阅读路线](docs/README.md#阅读路线)。所有自维护文档和 README 暂时只维护一个简体中文版,见[文档约定](docs/README.md#文档约定)。
每次开发任务默认遵守[统一日志与异常处理规范](docs/spec/logging-error-handling-spec.md)及其完成门,无需重复提出。规范定义安全错误出口、错误分类、日志脱敏、请求关联和验收标准;实现与验收状态见[功能状态表 N13](docs/implementation-status.md#31-下一期演进方案)。
[语义查询引擎架构升级设计](docs/design/semantic-engine-design.md)记录已确认的职责边界、三个内部方法和提交后固定快照规则,以及首版范围和待讨论事项。首版本地模块已接入:宿主捕获数据,引擎协调模型校验、草稿分析和完整查询,运行时登记请求并负责实际收尾。接收后编辑或删除元数据不改变在途查询;新请求按最新状态检查。实际检查及未测边界见[引擎验证](docs/acceptance/semantic-engine-verification.md)。
[`@datanavo/unified-sql`](packages/unified-sql/README.md) 已作为同仓库 npm workspace 接入查询、数值断言、统一与原生计算列,包含 AST、统一 SQL parser、逻辑引用绑定、类型分析、MySQL renderer 和独立 transport。根 `npm run generate` 维护包内 Peggy 生成源码;`npm run build:sql` 单独构建该包,生产构建与测试入口会先构建它。接口与职责见[统一 SQL 设计](docs/design/unified-sql-design.md)。包默认树深度上限为 64;宿主对生成的完整计划设置 512,以容纳产品最多 64 层计算列依赖形成的派生查询。业务语句在物理绑定后显式调用集中简化,覆盖 R1–R7、必填 qualifier 与 OutputRef;规则与未测项见[简化器设计](docs/design/sql-simplifier-design.md)及[实现验证](docs/acceptance/sql-simplifier-verification.md)。[四项增强](docs/design/sql-simplifier-design.md#10-四项增强规则)已接入局部屏障及 CTE 删除/绕过/有界内联,全部规则共享无 SQL 输出的字节/绑定预算预检;不承诺数据库性能收益。
[计算列与 SQL 表达式编辑器设计](docs/design/calculated-columns-design.md)已按[确认原型](prototypes/module-design/README.md#f11-计算列模型参数与查询赋值已确认)接入正式产品:表级计算列、共用 CodeMirror 标签/源码编辑器、模型参数与查询赋值。统一 SQL 拒绝未登记函数,原生表达式保持不透明,用户属性已按[行权限设计](docs/design/row-access-design.md)接入可信定义与取值;计算指标定义编辑与静态分析单列下文,模型内完整查询另通过 SQL 查询表场景接入,通用独立 SQL 工作台仍不在范围内。实际自动化、MySQL 与页面检查及未测边界见[产品验证](docs/acceptance/calculated-columns-verification.md)。原型业务执行仍为合成演示。
[计算指标设计](docs/design/calculated-metrics-design.md)的文法与业务求值边界保持。产品“语义模型 → 指标”可编辑计算表达式、业务声明、只读分析,随后随模型完整草稿保存和发布;查询已开放 M1–M3 核心能力,草稿分析和直接 API 复用同一规划器按实际调用检查。精确小数常量和中间表达式使用统一 SQL 类型推导,适用于输出、重算及隐藏条件。本地 TIMESTAMP 的显式 RANGE 可混用 DATE/TIMESTAMP 端点,保留微秒;其他时间矩阵见执行验证。CASE 动态需求、完整根域窗口、成员身份和同快照读取继续生效;窗口依赖按完整根域分层,嵌套上下文逐层挂回;需要请求回传及未知原生捕获的组合按具体原因拒绝。范围与实际证据见[执行验证](docs/acceptance/calculated-metrics-execution-verification.md)和[功能状态 F12](docs/implementation-status.md#3-本期之外的能力),历史定义编辑验收单独保留。
[语义查询计划与 SQL 执行设计](docs/design/semantic-query-plan-design.md)已接入[实施路线](docs/design/calculated-metrics-implementation.md)的 M0–M3 核心范围。SQL 采用允许丢失的尽力记录,数值允许后端原生差异;业务计算全部使用 SQL,不进行业务值回灌。DuckDB 依赖锁定正式版 `2.0.0`。在“设置 → 查询执行”查看最近记录、固定输入、SQL/类型绑定、基本来源与实际事件;获授权的完整包可从头重查并关联新记录,不重新编译当前模型;要求部署管理员、`system.replay`、当前业务租户及源身份/修订匹配;不要求原模型或内容仍存在,也不重新核对任务资源权限。记录位于 `DATANAVO_DATA_DIR/query-executions/`,不保存密码,默认不自动清理,不能当作脱敏诊断日志分发;缺包/坏包或前提失配不可重查。历史严格精度探针不作为当前开放门,真实边界见执行验证。
[行权限、用户组与用户属性](docs/design/row-access-design.md)已接入正式产品:用户管理作用域下的“用户组”“用户属性”分别维护人员归集、定义与直接赋值;模型草稿的“行权限”按表编辑快捷/统一/原生条件,应用后仍需保存草稿并发布。匹配规则固定 OR,无匹配时全部可见;管理员同样参与匹配。查询使用所选模型版本规则和动作开始时的当前组/属性,历史 SQL 重放沿用原 SQL 与绑定。新增元数据结构需要显式建立独立新库,已有不匹配库不会自动转换或清空。实际验证和未测边界见[行权限产品验证](docs/acceptance/row-access-verification.md)。
## 开源许可证
项目自有代码采用 [Apache License 2.0](LICENSE),允许企业内部使用、修改、分发和商业使用,须遵守许可证中的声明保留等条件。第三方依赖、嵌入资源和已有第三方文件仍按各自许可证授权,根许可证不替代它们的条款。具体来源和许可证位置见[第三方声明](THIRD_PARTY_NOTICES.md)。后续开发与贡献遵守[开源开发与交付要求](docs/open-source-policy.md)。
当前内置元数据库为 SQLite 和 MySQL,业务数据源为 MySQL。达梦适配及 `dmdb` 依赖已移除;旧验收记录仅保留历史证据,不代表当前支持。独立 CLI 安装包包含同一许可证。
公开试用阶段的维护范围、贡献政策和报告方式见[维护与贡献](CONTRIBUTING.md)、[安全政策](SECURITY.md)。