@dazitech/cli 3.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +104 -0
- package/dist/bin/dazi-app.cjs +4 -0
- package/dist/bin/dazi-flow.cjs +4 -0
- package/dist/bin/dazi-onto.cjs +4 -0
- package/dist/bin/dazi.cjs +4 -0
- package/dist/bin/run-cli-bin.cjs +62 -0
- package/dist/clis/dazi-app.js +16697 -0
- package/dist/clis/dazi-flow.js +6093 -0
- package/dist/clis/dazi-onto.js +3948 -0
- package/dist/clis/dazi.js +5677 -0
- package/dist/docs/app/app-init.md +69 -0
- package/dist/docs/app/build-upload.md +77 -0
- package/dist/docs/app/release-guide.md +51 -0
- package/dist/docs/app//344/270/273/350/246/201/350/264/242/345/212/241/346/214/207/346/240/207/345/244/215/346/235/202/346/212/245/350/241/250/345/274/200/345/217/221/345/256/236/350/267/265.md +261 -0
- package/dist/docs/auth/auth-login.md +41 -0
- package/dist/docs/auth/token-management.md +42 -0
- package/dist/docs/data/cube-guide.md +23 -0
- package/dist/docs/data/data-spaces.md +30 -0
- package/dist/docs/data/table-preview.md +41 -0
- package/dist/docs/flow/flow-project-guide.md +505 -0
- package/dist/docs/flow/flows-guide.md +302 -0
- package/dist/docs/flow/node-code-guide.md +399 -0
- package/dist/docs/flow/plan-guide.md +59 -0
- package/dist/docs/flow/run-guide.md +98 -0
- package/dist/docs/flow/source-guide.md +44 -0
- package/dist/docs/flow/variables-guide.md +406 -0
- package/dist/docs/flow//346/265/201/347/250/213/345/274/200/345/217/221/346/234/200/344/275/263/345/256/236/350/267/265-VS-flow0/346/241/210/344/276/213.md +344 -0
- package/dist/docs/guides/cli-invocation.md +93 -0
- package/dist/docs/guides/cli-reference.md +98 -0
- package/dist/docs/guides/mcp-setup.md +89 -0
- package/dist/docs/guides/migrate-v2-v3.md +54 -0
- package/dist/docs/guides/quickstart.md +77 -0
- package/dist/docs/guides/troubleshooting.md +82 -0
- package/dist/docs/guides/workspace-v3.md +53 -0
- package/dist/docs/index.json +204 -0
- package/dist/docs/onto/action-guide.md +48 -0
- package/dist/docs/onto/dazi_script_sdk_reference.md +168 -0
- package/dist/docs/onto/dazi_script_seed_data_guide.md +155 -0
- package/dist/docs/onto/function-guide.md +68 -0
- package/dist/docs/onto/rule-guide.md +52 -0
- package/dist/docs/onto/space-management.md +46 -0
- package/dist/docs/onto//346/234/254/344/275/223/350/204/232/346/234/254/347/274/226/345/206/231/346/214/207/345/215/227.md +145 -0
- package/dist/docs/onto//346/234/254/344/275/223/350/247/204/345/210/222/346/214/207/345/215/227.md +131 -0
- package/dist/docs/onto//350/247/204/345/210/222/347/244/272/344/276/213_/345/210/251/346/266/246/345/210/206/346/236/220/346/234/254/344/275/223/346/226/271/346/241/210.md +541 -0
- package/dist/examples/index.json +36 -0
- package/dist/examples/onto/function/profit_fn_customer_segmentation.py +117 -0
- package/dist/examples/onto/function/profit_fn_mom_analysis.py +89 -0
- package/dist/examples/onto/function/profit_fn_top_products.py +89 -0
- package/dist/examples/onto/function/profit_fn_yoy_analysis.py +89 -0
- package/dist/examples/onto/setup/profit_ontology_init.py +388 -0
- package/dist/prompts/app/ui-design.md +48 -0
- package/dist/prompts/data/data-analysis.md +42 -0
- package/dist/prompts/data/sql-query.md +36 -0
- package/dist/prompts/flow/flow-design.md +77 -0
- package/dist/prompts/flow/plan-generate.md +61 -0
- package/dist/prompts/flow/run-debug.md +66 -0
- package/dist/prompts/flow/run-fix-loop.md +77 -0
- package/dist/prompts/general/ask-dazi.md +30 -0
- package/dist/prompts/general/code-review.md +31 -0
- package/dist/prompts/general/troubleshoot.md +41 -0
- package/dist/prompts/index.json +20 -0
- package/dist/prompts/onto/action-design.md +47 -0
- package/dist/prompts/onto/function-design.md +44 -0
- package/dist/prompts/onto/rule-seed.md +41 -0
- package/dist/prompts/onto/script-publish-run.md +146 -0
- package/package.json +27 -0
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
# 应用初始化
|
|
2
|
+
|
|
3
|
+
**文档 ID**: `app/app-init`
|
|
4
|
+
**适用**:搭子 v3 · 应用项目 `项目/app_<名称>/`
|
|
5
|
+
|
|
6
|
+
## 推荐:扩展创建
|
|
7
|
+
|
|
8
|
+
| 场景 | 操作 |
|
|
9
|
+
|------|------|
|
|
10
|
+
| 新建 monorepo + 首个组件 | 侧栏 **新建项目** → **应用项目** → **新建应用项目** |
|
|
11
|
+
| 已有项目加组件 | **新建项目** → **在已有项目下新建组件**,或 `dazi.app.component.new` |
|
|
12
|
+
|
|
13
|
+
生成目录:`项目/app_<名称>/apps/<app_id>/`(含 `manifest.json`、`src/`、`drap-assets/` 等)。
|
|
14
|
+
|
|
15
|
+
## CLI:从模板创建
|
|
16
|
+
|
|
17
|
+
**推荐**:在 **`dazi-work` 根目录**执行 `.\scripts\dazi.ps1 app …`(脚本会自动设置 `DAZI_BUNDLED_DIR`,避免「未找到 bundled CLI」):
|
|
18
|
+
|
|
19
|
+
```powershell
|
|
20
|
+
cd D:\path\to\dazi-work
|
|
21
|
+
|
|
22
|
+
# 从模板创建(--dir 相对 dazi-work 根)
|
|
23
|
+
.\scripts\dazi.ps1 app init <template-id> --space <space-id> --dir 项目/app_<名>/apps/<app-id>
|
|
24
|
+
|
|
25
|
+
# 查看可用模板(含平台「转为应用模板」的动态模板)
|
|
26
|
+
.\scripts\dazi.ps1 app templates list --remote
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
**可选**:在**应用项目根**(`项目/app_<名称>/`,含 `sdk/`、`templates/`)使用 `pnpm run dazi-app -- …`。若报「未找到 bundled CLI」,需将 `DAZI_BUNDLED_DIR` 指向扩展或 `tools/dazi-clis` 下的 `bundled/clis`,或改用上方 `.\scripts\dazi.ps1 app`。
|
|
30
|
+
|
|
31
|
+
`template-id` 对应 `templates/app-template-*` 目录短名(如 `alarm-center` → `app-template-alarm-center`)。
|
|
32
|
+
|
|
33
|
+
## 创建后目录结构
|
|
34
|
+
|
|
35
|
+
```text
|
|
36
|
+
项目/app_<名称>/
|
|
37
|
+
├── sdk/、templates/、cli/
|
|
38
|
+
└── apps/<app-id>/
|
|
39
|
+
├── manifest.json # 权威声明(upload 后进 Registry DB)
|
|
40
|
+
├── src/
|
|
41
|
+
├── drap-assets/
|
|
42
|
+
├── package.json
|
|
43
|
+
└── AGENTS.md
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
## 清单要点
|
|
47
|
+
|
|
48
|
+
`manifest.json` 定义应用与平台的绑定关系,常用字段:
|
|
49
|
+
|
|
50
|
+
| 字段 | 说明 |
|
|
51
|
+
|------|------|
|
|
52
|
+
| `appId` | Registry 全局唯一 ID |
|
|
53
|
+
| `permissions` | 至少 `dataspace:<spaceId>` |
|
|
54
|
+
| `data_sources[]` | 数据集 key + kind |
|
|
55
|
+
| `mount` | `page` 或 `chat_result` |
|
|
56
|
+
|
|
57
|
+
扩展 **配置 manifest 数据源**(`dazi.app.editDataSources`)可图形化编辑 `data_sources`。
|
|
58
|
+
|
|
59
|
+
## 验证清单
|
|
60
|
+
|
|
61
|
+
```powershell
|
|
62
|
+
# 在 dazi-work 根
|
|
63
|
+
.\scripts\dazi.ps1 app manifest validate --cwd 项目/app_<名>/apps/<app-id> --scan-src
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
## 相关文档
|
|
67
|
+
|
|
68
|
+
- [build-upload](./build-upload.md)
|
|
69
|
+
- 应用项目内 [quickstart](../../bundled/templates/runtime-apps-project/docs/quickstart.md)(复制到工作区后的 monorepo)
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
# 应用构建与上传
|
|
2
|
+
|
|
3
|
+
**文档 ID**: `app/build-upload`
|
|
4
|
+
**适用**:搭子 v3 · DRAP 应用项目位于 `项目/app_<名称>/apps/<app_id>/`
|
|
5
|
+
|
|
6
|
+
## 工作目录
|
|
7
|
+
|
|
8
|
+
| 操作 | 目录 |
|
|
9
|
+
|------|------|
|
|
10
|
+
| `.\scripts\dazi.ps1 app …`(init、upload、release 等) | **`dazi-work` 根**;路径用 `--cwd 项目/app_<名>/apps/<app_id>`(相对工作区根) |
|
|
11
|
+
| `pnpm run dazi-app`(可选) | **应用项目根**(含 `sdk/`、`templates/`);需正确设置 `DAZI_BUNDLED_DIR`,否则易报「未找到 bundled CLI」 |
|
|
12
|
+
| `pnpm run dev` / `build` | **应用组件目录** `apps/<app_id>/` |
|
|
13
|
+
| 扩展「构建并发布」 | 在侧栏选中**应用组件**节点,无需手填路径 |
|
|
14
|
+
|
|
15
|
+
发布前确认扩展登录与 **发布目标 API**(`dazi.serverUrl` / `~/.dazi/auth.json`)一致。
|
|
16
|
+
|
|
17
|
+
## 开发
|
|
18
|
+
|
|
19
|
+
在 `apps/<app_id>/`:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
pnpm run dev
|
|
23
|
+
# 或(在 dazi-work 根):.\scripts\dazi.ps1 app dev --cwd 项目/app_<名>/apps/<app_id>
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## 构建
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
pnpm run build
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
输出到 `dist/`(由 `dazi.app.buildOutputDir` 配置)。
|
|
33
|
+
|
|
34
|
+
## 上传
|
|
35
|
+
|
|
36
|
+
在 **`dazi-work` 根**执行(`--cwd` 为相对工作区根的应用组件目录):
|
|
37
|
+
|
|
38
|
+
```powershell
|
|
39
|
+
cd D:\path\to\dazi-work
|
|
40
|
+
|
|
41
|
+
# 上传到指定空间
|
|
42
|
+
.\scripts\dazi.ps1 app upload --cwd 项目/app_<名>/apps/<app_id> --space <space-id>
|
|
43
|
+
|
|
44
|
+
# 上传并立即激活
|
|
45
|
+
.\scripts\dazi.ps1 app upload --cwd 项目/app_<名>/apps/<app_id> --space <space-id> --activate
|
|
46
|
+
|
|
47
|
+
# 带更新日志
|
|
48
|
+
.\scripts\dazi.ps1 app upload --cwd 项目/app_<名>/apps/<app_id> --space <space-id> --changelog "修复了 #123 问题"
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
等价写法(须在应用项目根且已配置 `DAZI_BUNDLED_DIR`):`pnpm run dazi-app -- upload --cwd apps/<app_id> --space <space-id>`。
|
|
52
|
+
|
|
53
|
+
浏览器验收:`<主站>/runtime-apps/<app_id>`(地址见应用项目内 `docs/env.md` 或扩展设置 `dazi.serverUrl`)。
|
|
54
|
+
|
|
55
|
+
## 本地预览(上传前)
|
|
56
|
+
|
|
57
|
+
```powershell
|
|
58
|
+
.\scripts\dazi.ps1 app preview all --cwd 项目/app_<名>/apps/<app_id>
|
|
59
|
+
.\scripts\dazi.ps1 app preview sql --cwd 项目/app_<名>/apps/<app_id>
|
|
60
|
+
.\scripts\dazi.ps1 app preview script --cwd 项目/app_<名>/apps/<app_id>
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## 相关文档
|
|
64
|
+
|
|
65
|
+
- [app-init](./app-init.md)
|
|
66
|
+
- [release-guide](./release-guide.md)
|
|
67
|
+
- [§331 多项目架构](../../docs/331-应用项目多项目与组件重构.md)
|
|
68
|
+
|
|
69
|
+
## 收尾与发版检查
|
|
70
|
+
|
|
71
|
+
在扩展仓 `dazi-vscode` 根目录执行:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
pnpm run build
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
该命令会执行 `copy:bundled`,并在复制 `runtime-apps` 骨架后自动修正文档路径(模板 README/FAQ),确保新建应用项目拿到的是最新说明。
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
# 应用发布管理
|
|
2
|
+
|
|
3
|
+
**文档 ID**: `app/release-guide`
|
|
4
|
+
**适用**:在 **`dazi-work` 根**通过 `.\scripts\dazi.ps1 app …` 管理发布;`--cwd` 指向 `项目/app_<名>/apps/<app_id>/`。
|
|
5
|
+
|
|
6
|
+
场景实践:[主要财务指标复杂报表开发实践](./主要财务指标复杂报表开发实践.md)(模板 `financial-indicators-complex-report`)。
|
|
7
|
+
|
|
8
|
+
```powershell
|
|
9
|
+
cd D:\path\to\dazi-work
|
|
10
|
+
|
|
11
|
+
# 查看某应用的发布版本
|
|
12
|
+
.\scripts\dazi.ps1 app release list <app-id> --cwd 项目/app_<名>/apps/<app-id>
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
扩展 **构建并发布** 会调用同一套 API;发布目标由 `dazi.serverUrl` / `~/.dazi/auth.json` 决定(见 §333)。
|
|
16
|
+
|
|
17
|
+
## 查看发布版本
|
|
18
|
+
|
|
19
|
+
```powershell
|
|
20
|
+
.\scripts\dazi.ps1 app release list <app-id> --cwd 项目/app_<名>/apps/<app-id>
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## 激活指定版本
|
|
24
|
+
|
|
25
|
+
```powershell
|
|
26
|
+
.\scripts\dazi.ps1 app release activate <app-id> --semver 1.2.0 --cwd 项目/app_<名>/apps/<app-id>
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## 撤回版本
|
|
30
|
+
|
|
31
|
+
```powershell
|
|
32
|
+
.\scripts\dazi.ps1 app release revoke <app-id> --semver 1.2.0 --cwd 项目/app_<名>/apps/<app-id>
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## 版本号规范
|
|
36
|
+
|
|
37
|
+
遵循 semver:`MAJOR.MINOR.PATCH`
|
|
38
|
+
|
|
39
|
+
- **MAJOR**:不兼容的 API 变更
|
|
40
|
+
- **MINOR**:向下兼容的功能新增
|
|
41
|
+
- **PATCH**:向下兼容的问题修正
|
|
42
|
+
|
|
43
|
+
## 资源管理
|
|
44
|
+
|
|
45
|
+
```powershell
|
|
46
|
+
.\scripts\dazi.ps1 app asset list --cwd 项目/app_<名>/apps/<app-id>
|
|
47
|
+
.\scripts\dazi.ps1 app asset new-sql --cwd 项目/app_<名>/apps/<app-id>
|
|
48
|
+
.\scripts\dazi.ps1 app asset new-script --cwd 项目/app_<名>/apps/<app-id>
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
> **说明**:亦可在应用项目根使用 `pnpm run dazi-app -- release list …` 等等价命令,但需先配置 `DAZI_BUNDLED_DIR`;推荐统一使用 `.\scripts\dazi.ps1 app`。
|
|
@@ -0,0 +1,261 @@
|
|
|
1
|
+
# 主要财务指标复杂报表 · 开发实践
|
|
2
|
+
|
|
3
|
+
> **适用模板**:`financial-indicators-complex-report`(`app-template-financial-indicators-complex-report`)
|
|
4
|
+
> **参考实现**:`complex-report-003`(主要财务指标表,28 行 × 36 列)
|
|
5
|
+
> **设计稿示例**:`单一分析表2026.xlsx`(文件上传管理 / `managed_file_id`)
|
|
6
|
+
|
|
7
|
+
本文说明如何从 Excel 设计稿开发并发布**中国式复杂报表(财务指标宽表)**,供业务项目与 AI 辅助开发参考。
|
|
8
|
+
|
|
9
|
+
---
|
|
10
|
+
|
|
11
|
+
## 1. 适用场景
|
|
12
|
+
|
|
13
|
+
| 项 | 说明 |
|
|
14
|
+
|----|------|
|
|
15
|
+
| 报表形态 | 多级表头 + 宽表(年度列 + 分月列) |
|
|
16
|
+
| 典型列 | 类别、指标名称、2017–2022 年、2021/2022/2023 分月 |
|
|
17
|
+
| 交互 | 表头固定、左侧两列冻结、类别纵向合并、条件行样式 |
|
|
18
|
+
| 组件 | `@dazi/app-sdk-ui` → `ComplexReport` |
|
|
19
|
+
| 布局 | RLIR(`报表布局.json`)→ `manifest.report_design.layout_snapshot` |
|
|
20
|
+
| 数据 | 开发 `static`;上线 `sql_template` / `ontology_function` |
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## 2. 从模板创建应用
|
|
25
|
+
|
|
26
|
+
### 2.1 命令行(推荐)
|
|
27
|
+
|
|
28
|
+
在 **`dazi-work` 根**使用 `.\scripts\dazi.ps1 app`(自动解析 bundled CLI,最稳):
|
|
29
|
+
|
|
30
|
+
```powershell
|
|
31
|
+
cd D:\path\to\dazi-work
|
|
32
|
+
|
|
33
|
+
# 初始化应用(将 my-fin-report-001、app_<名> 换成你的路径)
|
|
34
|
+
.\scripts\dazi.ps1 app init financial-indicators-complex-report `
|
|
35
|
+
--space space__0519 `
|
|
36
|
+
--dir 项目/app_<名>/apps/my-fin-report-001
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
若已在应用项目根 `项目/app_<名>/` 且已配置 `DAZI_BUNDLED_DIR`,也可用:`pnpm run dazi-app -- init … --app-id my-fin-report-001 --dir apps/my-fin-report-001`。
|
|
40
|
+
|
|
41
|
+
### 2.2 VS Code
|
|
42
|
+
|
|
43
|
+
1. 打开 DRAP 应用工作区(`runtime-apps-project`)
|
|
44
|
+
2. 选择模板 **「主要财务指标复杂报表」**(`financial-indicators-complex-report`)
|
|
45
|
+
3. 执行 **App: 从模板创建应用**
|
|
46
|
+
|
|
47
|
+
初始化后目录包含:
|
|
48
|
+
|
|
49
|
+
- `src/fixtures/generated/reportLayout.json` — 示例 RLIR(仅叶子列)
|
|
50
|
+
- `src/fixtures/generated/reportRows.json` — 28 行样例
|
|
51
|
+
- `src/fixtures/reportLayout.ts` — `normalizeReportLayout()`
|
|
52
|
+
- `src/pages/MainPage.tsx` — 标准页面
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## 3. 端到端流程
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
Excel 上传(主站 · 文件上传管理)
|
|
60
|
+
↓ 原生摘录 + 规则/AI 报表布局解析
|
|
61
|
+
报表布局.json(RLIR)+ 表结构.json
|
|
62
|
+
↓ VS Code「拉取到本地资源」
|
|
63
|
+
工作区 资源/files/{文件名}_{file_id}/
|
|
64
|
+
↓「绑定复杂报表设计稿」
|
|
65
|
+
manifest.report_design(managed_file_id + binding)
|
|
66
|
+
↓ 同步 fixtures / AI 改页面
|
|
67
|
+
src/fixtures/generated/*.json
|
|
68
|
+
↓ 本地验收
|
|
69
|
+
pnpm run dev
|
|
70
|
+
↓ 发布
|
|
71
|
+
pnpm run build → .\scripts\dazi.ps1 app upload --activate(在 dazi-work 根,带 --cwd)
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
VS Code 分步说明见应用内 `.ai/implement-from-managed-file.md`。
|
|
75
|
+
|
|
76
|
+
---
|
|
77
|
+
|
|
78
|
+
## 4. RLIR 关键规范(必读)
|
|
79
|
+
|
|
80
|
+
### 4.1 过滤 `leaf: false` 父列
|
|
81
|
+
|
|
82
|
+
平台生成的 `columns` 中,分月分组父列(如 `col_2021_monthly`)可能 `leaf: false`。
|
|
83
|
+
**若原样传入 `ComplexReport`,会出现「2021年(分月)」错位、1 月表头异常。**
|
|
84
|
+
|
|
85
|
+
模板已在 `normalizeReportLayout()` 中处理:
|
|
86
|
+
|
|
87
|
+
```typescript
|
|
88
|
+
const columns = (layout.columns ?? []).filter((c) => c.leaf !== false);
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
同步更新 `wideTable.totalFields` / `defaultVisibleColumns` 为**叶子列数**(本例 36,不是含父列的 39)。
|
|
92
|
+
|
|
93
|
+
### 4.2 更新 Excel 后同步 fixtures
|
|
94
|
+
|
|
95
|
+
```powershell
|
|
96
|
+
# 将工作区 bundle 中的 报表布局.json 同步到应用(路径按实际工作区调整)
|
|
97
|
+
node -e "
|
|
98
|
+
const fs = require('fs');
|
|
99
|
+
const src = JSON.parse(fs.readFileSync('资源/files/单一分析表2026.xlsx_575878bb/报表布局.json','utf8'));
|
|
100
|
+
const leafCols = src.columns.filter(c => c.leaf !== false);
|
|
101
|
+
const out = {
|
|
102
|
+
title: src.title, summary: src.summary, columns: leafCols,
|
|
103
|
+
columnGroups: src.columnGroups,
|
|
104
|
+
wideTable: { ...src.wideTable, totalFields: leafCols.length, defaultVisibleColumns: leafCols.length }
|
|
105
|
+
};
|
|
106
|
+
fs.writeFileSync('apps/my-fin-report-001/src/fixtures/generated/reportLayout.json', JSON.stringify(out, null, 2));
|
|
107
|
+
"
|
|
108
|
+
```
|
|
109
|
+
|
|
110
|
+
发布前执行 **App: 写入 layout 快照**,将 RLIR 写入 `manifest.report_design.layout_snapshot`。
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## 5. 页面接入
|
|
115
|
+
|
|
116
|
+
### 5.1 MainPage 标准写法
|
|
117
|
+
|
|
118
|
+
```tsx
|
|
119
|
+
const layout = useMemo(() => {
|
|
120
|
+
const snap = manifest?.report_design?.layout_snapshot;
|
|
121
|
+
return normalizeReportLayout(snap ?? financialReportLayout);
|
|
122
|
+
}, [manifest]);
|
|
123
|
+
|
|
124
|
+
const ds = useReportDataset({ visibleFields, wideTable: layout.wideTable });
|
|
125
|
+
|
|
126
|
+
<ComplexReport
|
|
127
|
+
layout={layout}
|
|
128
|
+
dataset={ds.data}
|
|
129
|
+
maxHeight={640}
|
|
130
|
+
onVisibleFieldsChange={handleVisibleFieldsChange}
|
|
131
|
+
pagination={{ page: ds.page, pageSize: ds.pageSize, onPageChange: ds.setPage }}
|
|
132
|
+
/>
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
`handleVisibleFieldsChange` 须 `useCallback`,并用 `join("\0")` 比较列集合,避免无意义重渲染。
|
|
136
|
+
|
|
137
|
+
### 5.2 业务规则(模板默认)
|
|
138
|
+
|
|
139
|
+
| 规则 | 配置 |
|
|
140
|
+
|------|------|
|
|
141
|
+
| 类别合并 | `category` 列 `rowMerge: true` |
|
|
142
|
+
| 利润总额加粗 | `features.rowEmphasis` → 指标含「利润总额」 |
|
|
143
|
+
| 万元产值综合能耗标红 | `features.rowDanger` → 指标含「万元产值综合能耗」 |
|
|
144
|
+
| 数值格式 | 除类别/指标外 `format: "number"` |
|
|
145
|
+
|
|
146
|
+
### 5.3 应用级样式
|
|
147
|
+
|
|
148
|
+
`src/styles/template.css` 冻结「类别」「指标名称」两列(`position: sticky`),横向滚动时保持可读。
|
|
149
|
+
|
|
150
|
+
---
|
|
151
|
+
|
|
152
|
+
## 6. 数据与 manifest
|
|
153
|
+
|
|
154
|
+
### 6.1 开发阶段
|
|
155
|
+
|
|
156
|
+
| 文件 | 用途 |
|
|
157
|
+
|------|------|
|
|
158
|
+
| `generated/reportRows.json` | 静态样例行 |
|
|
159
|
+
| `datasets.ts` | 包装为 `report_data` |
|
|
160
|
+
| `manifest.data_sources` | `kind: static` |
|
|
161
|
+
|
|
162
|
+
建议 `refresh.on_mount: false`,由宿主首次注入 + 本地投影,避免重复请求。
|
|
163
|
+
|
|
164
|
+
### 6.2 上线阶段
|
|
165
|
+
|
|
166
|
+
```json
|
|
167
|
+
{
|
|
168
|
+
"report_design": {
|
|
169
|
+
"managed_file_id": "<文件上传管理 UUID>",
|
|
170
|
+
"display_name": "单一分析表2026.xlsx",
|
|
171
|
+
"layout_source": "publish_snapshot",
|
|
172
|
+
"layout_snapshot": { "...RLIR..." },
|
|
173
|
+
"binding": {
|
|
174
|
+
"wideTable": { "pageSize": 200, "maxColumnsPerRequest": 36 }
|
|
175
|
+
}
|
|
176
|
+
},
|
|
177
|
+
"data_sources": [
|
|
178
|
+
{ "key": "report_data", "kind": "sql_template", "template_id": "..." }
|
|
179
|
+
]
|
|
180
|
+
}
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
SQL / 资产放在 `drap-assets/`,勿把 Excel 放进 `drap-assets/report-design/`。
|
|
184
|
+
|
|
185
|
+
---
|
|
186
|
+
|
|
187
|
+
## 7. 性能与稳定性
|
|
188
|
+
|
|
189
|
+
### 7.1 禁止 `fetch-data-sources` 死循环
|
|
190
|
+
|
|
191
|
+
**现象**:页面闪烁,Network 大量 `POST .../fetch-data-sources`,最终 `ERR_INSUFFICIENT_RESOURCES`。
|
|
192
|
+
|
|
193
|
+
**原因**:旧版 `useReportDataset` 依赖不稳定的 `useDataset()` 返回对象;`static` 带 `project_columns` 等 overrides 仍走动态接口。
|
|
194
|
+
|
|
195
|
+
**要求**(当前 SDK 已修复,发布时需同步主站与子应用构建):
|
|
196
|
+
|
|
197
|
+
1. `static` 仅在子应用/宿主本地做列投影与分页
|
|
198
|
+
2. `useReportDataset` / `useDataset` 勿因 loading 状态每帧 refetch
|
|
199
|
+
3. `ComplexReport` 的 `onVisibleFieldsChange` 仅在实际列变化时回调
|
|
200
|
+
4. `index.tsx` 复用 `createRoot`,避免重复 mount
|
|
201
|
+
|
|
202
|
+
### 7.2 micro-app 重复 createRoot
|
|
203
|
+
|
|
204
|
+
若控制台出现 `createRoot() on a container that has already been passed to createRoot()`,检查 `lifecycle.mount` 是否复用已有 `Root`。
|
|
205
|
+
|
|
206
|
+
---
|
|
207
|
+
|
|
208
|
+
## 8. 常见问题
|
|
209
|
+
|
|
210
|
+
| 现象 | 原因 | 处理 |
|
|
211
|
+
|------|------|------|
|
|
212
|
+
| 分月表头错位 | `leaf:false` 父列未过滤 | `normalizeReportLayout` |
|
|
213
|
+
| 类别未合并 | 未配置 `rowMerge` | `category` 列开启 |
|
|
214
|
+
| 行样式无效 | `features` 未写入 layout | manifest 或 normalize 补全 |
|
|
215
|
+
| 页面狂刷接口 | refetch 循环 / 未部署 SDK 补丁 | 见 §7.1,重建并发布 |
|
|
216
|
+
| 运行时无数据 | 未绑定设计稿或未写快照 | 绑定 + 发布快照 |
|
|
217
|
+
|
|
218
|
+
---
|
|
219
|
+
|
|
220
|
+
## 9. 发布检查清单
|
|
221
|
+
|
|
222
|
+
- [ ] 管理端完成报表布局解析,本地已拉取 `报表布局.json`
|
|
223
|
+
- [ ] `normalizeReportLayout` 过滤 `leaf:false`
|
|
224
|
+
- [ ] `generated/reportLayout.json` / `reportRows.json` 与最新 Excel 一致
|
|
225
|
+
- [ ] `manifest.report_design` 含 `managed_file_id` 与 `layout_snapshot`
|
|
226
|
+
- [ ] `pnpm run dev` 验收:表头、合并、冻结列、行样式、无接口风暴
|
|
227
|
+
- [ ] `pnpm run build`
|
|
228
|
+
- [ ] `.\scripts\dazi.ps1 app manifest validate --scan-src`(`--cwd` 指向组件目录)
|
|
229
|
+
- [ ] `.\scripts\dazi.ps1 app upload --activate`(在 dazi-work 根)
|
|
230
|
+
- [ ] 主站 frontend 已部署(含 static 本地投影)
|
|
231
|
+
|
|
232
|
+
---
|
|
233
|
+
|
|
234
|
+
## 10. 常用命令
|
|
235
|
+
|
|
236
|
+
```powershell
|
|
237
|
+
# 本地开发:进入应用组件目录
|
|
238
|
+
cd D:\path\to\dazi-work\项目\app_<名>\apps\my-fin-report-001
|
|
239
|
+
pnpm run dev
|
|
240
|
+
pnpm run build
|
|
241
|
+
|
|
242
|
+
# 校验与发布:在 dazi-work 根
|
|
243
|
+
cd D:\path\to\dazi-work
|
|
244
|
+
.\scripts\dazi.ps1 app manifest validate --cwd 项目/app_<名>/apps/my-fin-report-001 --scan-src
|
|
245
|
+
.\scripts\dazi.ps1 app upload --cwd 项目/app_<名>/apps/my-fin-report-001 --space space__0519 --activate
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
---
|
|
249
|
+
|
|
250
|
+
## 11. 相关文档
|
|
251
|
+
|
|
252
|
+
| 文档 | 说明 |
|
|
253
|
+
|------|------|
|
|
254
|
+
| [337-中国式复杂报表开发方案.md](../337-中国式复杂报表开发方案.md) | 平台架构与 Phase 规划 |
|
|
255
|
+
| [问题和分析/复杂报表记录.md](../问题和分析/复杂报表记录.md) | 线上问题排查记录 |
|
|
256
|
+
| `dazi-vscode/docs/app/release-guide.md` | 应用发布总览 |
|
|
257
|
+
| 模板 `README.md` | `runtime-apps/templates/app-template-financial-indicators-complex-report/` |
|
|
258
|
+
|
|
259
|
+
---
|
|
260
|
+
|
|
261
|
+
*文档版本:2026-05-31 · 基于 complex-report-003 实践整理,对应模板 financial-indicators-complex-report*
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# 认证登录
|
|
2
|
+
|
|
3
|
+
**文档 ID**: `auth/auth-login`
|
|
4
|
+
|
|
5
|
+
## 登录方式
|
|
6
|
+
|
|
7
|
+
### Token 登录(推荐 CI/CD)
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
.\scripts\dazi.ps1 auth set-token --token "eyJ..."
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Token 存储在 `~/.dazi/auth.json`,可在多个项目间共享。
|
|
14
|
+
|
|
15
|
+
### 用户名密码登录
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
.\scripts\dazi.ps1 auth login --username your@email.com --password yourpassword
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
### 验证登录状态
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
.\scripts\dazi.ps1 auth whoami
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## 多环境支持
|
|
28
|
+
|
|
29
|
+
通过环境变量切换服务器:
|
|
30
|
+
|
|
31
|
+
```powershell
|
|
32
|
+
$env:DAZI_BASE_URL = "https://staging.dazi.tech"
|
|
33
|
+
.\scripts\dazi.ps1 auth whoami
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
或在 `.env` 文件中配置:
|
|
37
|
+
|
|
38
|
+
```
|
|
39
|
+
DAZI_BASE_URL=https://your-dazi-server.com
|
|
40
|
+
DAZI_AGENT_API_TOKEN=eyJ...
|
|
41
|
+
```
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# Token 管理
|
|
2
|
+
|
|
3
|
+
**文档 ID**: `auth/token-management`
|
|
4
|
+
|
|
5
|
+
## Token 存储
|
|
6
|
+
|
|
7
|
+
Token 存储在 `~/.dazi/auth.json`,格式:
|
|
8
|
+
|
|
9
|
+
```json
|
|
10
|
+
{
|
|
11
|
+
"token": "eyJ...",
|
|
12
|
+
"serverUrl": "https://your-dazi.example.com",
|
|
13
|
+
"username": "user@example.com",
|
|
14
|
+
"savedAt": "2026-01-01T00:00:00.000Z"
|
|
15
|
+
}
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
## 迁移旧版 Token
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
# 预览
|
|
22
|
+
.\scripts\dazi.ps1 auth migrate --dry-run
|
|
23
|
+
|
|
24
|
+
# 执行(从 ~/.dazi-app/auth.json 迁移)
|
|
25
|
+
.\scripts\dazi.ps1 auth migrate
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Token 刷新
|
|
29
|
+
|
|
30
|
+
Token 过期后重新登录,旧 Token 自动覆盖:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
.\scripts\dazi.ps1 auth login
|
|
34
|
+
# 或
|
|
35
|
+
.\scripts\dazi.ps1 auth set-token --token "<new-token>"
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
## 清除 Token
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
.\scripts\dazi.ps1 auth logout
|
|
42
|
+
```
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# 数据集(Cube)管理
|
|
2
|
+
|
|
3
|
+
**文档 ID**: `data/cube-guide`
|
|
4
|
+
|
|
5
|
+
## 什么是 Cube
|
|
6
|
+
|
|
7
|
+
Cube 是预聚合的数据集,基于数据表或视图构建,支持快速查询和分析。
|
|
8
|
+
|
|
9
|
+
## 列出 Cube
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
.\scripts\dazi.ps1 data cube list --space <space-id>
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## 查看 Cube 详情
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
.\scripts\dazi.ps1 data cube info <cube-id> --space <space-id>
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
## 在扩展中使用
|
|
22
|
+
|
|
23
|
+
在侧栏「🗂 数据资源」→ 空间 → 数据集,点击 Cube 打开详情 Webview。
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# 数据空间管理
|
|
2
|
+
|
|
3
|
+
**文档 ID**: `data/data-spaces`
|
|
4
|
+
|
|
5
|
+
## 列出数据空间
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
.\scripts\dazi.ps1 data space list
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## 创建数据空间
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
.\scripts\dazi.ps1 data space create --name "财务数据" --category-id finance
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## 刷新数据空间
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
.\scripts\dazi.ps1 data space refresh <space-id>
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## 扩展侧栏
|
|
24
|
+
|
|
25
|
+
在 VS Code 侧栏「🗂 数据资源」节点下,按空间分组展示:
|
|
26
|
+
- 数据表(Tables)
|
|
27
|
+
- 数据集(Cubes)
|
|
28
|
+
- 数据源(Sources)
|
|
29
|
+
|
|
30
|
+
点击数据表可打开预览 Webview,显示表结构和前 10 行数据。
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
# 数据表预览
|
|
2
|
+
|
|
3
|
+
**文档 ID**: `data/table-preview`
|
|
4
|
+
|
|
5
|
+
## 列出数据表
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
.\scripts\dazi.ps1 data table list --space <space-id>
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## 查看表结构
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
.\scripts\dazi.ps1 data table schema <table-id> --space <space-id>
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## 采样数据
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
.\scripts\dazi.ps1 data table sample <table-id> --space <space-id> --rows 10
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
## 在扩展中预览
|
|
24
|
+
|
|
25
|
+
在侧栏「🗂 数据资源」→ 空间 → 数据表,点击表名打开预览 Webview:
|
|
26
|
+
|
|
27
|
+
- **Schema 标签页**:列名、类型、是否可空
|
|
28
|
+
- **预览标签页**:前 10 行数据
|
|
29
|
+
|
|
30
|
+
## 文件管理
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
# 列出平台文件
|
|
34
|
+
.\scripts\dazi.ps1 data file list --space <space-id>
|
|
35
|
+
|
|
36
|
+
# 上传本地文件
|
|
37
|
+
.\scripts\dazi.ps1 data file upload ./data.csv --space <space-id>
|
|
38
|
+
|
|
39
|
+
# 下载文件
|
|
40
|
+
.\scripts\dazi.ps1 data file pull remote/path.csv --space <space-id>
|
|
41
|
+
```
|