@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.
Files changed (67) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +104 -0
  3. package/dist/bin/dazi-app.cjs +4 -0
  4. package/dist/bin/dazi-flow.cjs +4 -0
  5. package/dist/bin/dazi-onto.cjs +4 -0
  6. package/dist/bin/dazi.cjs +4 -0
  7. package/dist/bin/run-cli-bin.cjs +62 -0
  8. package/dist/clis/dazi-app.js +16697 -0
  9. package/dist/clis/dazi-flow.js +6093 -0
  10. package/dist/clis/dazi-onto.js +3948 -0
  11. package/dist/clis/dazi.js +5677 -0
  12. package/dist/docs/app/app-init.md +69 -0
  13. package/dist/docs/app/build-upload.md +77 -0
  14. package/dist/docs/app/release-guide.md +51 -0
  15. 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
  16. package/dist/docs/auth/auth-login.md +41 -0
  17. package/dist/docs/auth/token-management.md +42 -0
  18. package/dist/docs/data/cube-guide.md +23 -0
  19. package/dist/docs/data/data-spaces.md +30 -0
  20. package/dist/docs/data/table-preview.md +41 -0
  21. package/dist/docs/flow/flow-project-guide.md +505 -0
  22. package/dist/docs/flow/flows-guide.md +302 -0
  23. package/dist/docs/flow/node-code-guide.md +399 -0
  24. package/dist/docs/flow/plan-guide.md +59 -0
  25. package/dist/docs/flow/run-guide.md +98 -0
  26. package/dist/docs/flow/source-guide.md +44 -0
  27. package/dist/docs/flow/variables-guide.md +406 -0
  28. 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
  29. package/dist/docs/guides/cli-invocation.md +93 -0
  30. package/dist/docs/guides/cli-reference.md +98 -0
  31. package/dist/docs/guides/mcp-setup.md +89 -0
  32. package/dist/docs/guides/migrate-v2-v3.md +54 -0
  33. package/dist/docs/guides/quickstart.md +77 -0
  34. package/dist/docs/guides/troubleshooting.md +82 -0
  35. package/dist/docs/guides/workspace-v3.md +53 -0
  36. package/dist/docs/index.json +204 -0
  37. package/dist/docs/onto/action-guide.md +48 -0
  38. package/dist/docs/onto/dazi_script_sdk_reference.md +168 -0
  39. package/dist/docs/onto/dazi_script_seed_data_guide.md +155 -0
  40. package/dist/docs/onto/function-guide.md +68 -0
  41. package/dist/docs/onto/rule-guide.md +52 -0
  42. package/dist/docs/onto/space-management.md +46 -0
  43. 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
  44. 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
  45. 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
  46. package/dist/examples/index.json +36 -0
  47. package/dist/examples/onto/function/profit_fn_customer_segmentation.py +117 -0
  48. package/dist/examples/onto/function/profit_fn_mom_analysis.py +89 -0
  49. package/dist/examples/onto/function/profit_fn_top_products.py +89 -0
  50. package/dist/examples/onto/function/profit_fn_yoy_analysis.py +89 -0
  51. package/dist/examples/onto/setup/profit_ontology_init.py +388 -0
  52. package/dist/prompts/app/ui-design.md +48 -0
  53. package/dist/prompts/data/data-analysis.md +42 -0
  54. package/dist/prompts/data/sql-query.md +36 -0
  55. package/dist/prompts/flow/flow-design.md +77 -0
  56. package/dist/prompts/flow/plan-generate.md +61 -0
  57. package/dist/prompts/flow/run-debug.md +66 -0
  58. package/dist/prompts/flow/run-fix-loop.md +77 -0
  59. package/dist/prompts/general/ask-dazi.md +30 -0
  60. package/dist/prompts/general/code-review.md +31 -0
  61. package/dist/prompts/general/troubleshoot.md +41 -0
  62. package/dist/prompts/index.json +20 -0
  63. package/dist/prompts/onto/action-design.md +47 -0
  64. package/dist/prompts/onto/function-design.md +44 -0
  65. package/dist/prompts/onto/rule-seed.md +41 -0
  66. package/dist/prompts/onto/script-publish-run.md +146 -0
  67. 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
+ ```