xls2ddl/aidocs/singletree.md

树形数据管理模块技术文档

概述

本模块用于根据数据库表结构和配置文件，自动生成基于树形控件（Tree）的前端 UI 配置及后端 CRUD 接口代码。适用于快速构建具有父子层级关系的数据管理系统。

该工具支持通过 .xlsx 或其他格式描述的数据模型生成完整的树形界面与操作逻辑，包括：

• 树形展示界面 (index.ui)
• 获取节点数据接口
• 新增、更新、删除节点接口

---

依赖说明

外部依赖

import os
import sys
import codecs
import json

内部模块依赖

模块路径	功能
appPublic.dictObject	提供 DictObject 类，将字典转换为可点式访问的对象
appPublic.folderUtils	文件夹操作工具：listFile, _mkdir
appPublic.myTE	自定义模板引擎 MyTemplateEngine，支持 Jinja2 风格语法
xlsxData.xlsxFactory	从 Excel 文件中读取数据模型
xls2crud.build_dbdesc	构建数据库描述对象
xls2crud.field_list	提取字段列表
xls2crud.subtable2toolbar	将子表信息转为工具栏按钮配置
xls2crud.filter_backslash	过滤字符串中的多余反斜杠
tmpls.*_tmpl	各类模板字符串（新增、更新、删除、获取数据等）

---

模板定义

ui_tmpl - 树形组件 UI 配置模板

此模板用于生成 index.ui 文件，定义前端 Tree 组件的配置项。

参数说明

字段名	类型	是否必需	描述
widgettype	string	是	固定为 "Tree"
title	string	否	页面标题；若未提供则使用 summary[0].title
description	string	否	页面描述
toolbar	array	否	工具栏按钮配置（JSON 格式输出）
editable	object	否	编辑功能开关及 URL 配置
add_url	string	否	新增接口地址，默认为 ./new_{tblname}.dspy
update_url	string	否	更新接口地址，默认为 ./update_{tblname}.dspy
delete_url	string	否	删除接口地址，默认为 ./delete_{tblname}.dspy
checkField	string	否	可选复选框字段
parentField	string	是	父节点字段名（如 parent_id）
idField	string	是	主键字段名
textField	string	是	显示文本字段名
typeField	string	否	节点类型字段
params	object	否	请求附加参数
newdata_params	object	否	新增时携带参数
node_typeicons	object	否	不同类型节点图标映射
dataurl	string	否	获取节点数据接口地址，默认为 ./get_{tblname}.dspy
binds	object	否	数据绑定配置（JSON 格式输出，缩进4格）

注意：模板中使用 {%- raw -%} 和 {%- endraw %} 包裹动态路径表达式以防止被提前渲染。

---

get_nodes_tmpl - 获取树节点数据脚本模板

生成用于查询树节点的 Python 异步脚本（.dspy），支持父子层级过滤。

SQL 查询逻辑

SELECT * FROM {tblname}
WHERE {parentField} = ${id}$   -- 当前节点的子节点
   OR {parentField} IS NULL    -- 根节点
ORDER BY {textField}

上下文变量

• params_kw: 前端传入参数字典
• db: 使用 DBPools() 获取数据库连接池
• dbname: 通过 get_module_dbname(modulename) 获取模块对应数据库名

返回结果为查询到的记录列表。

---

核心函数说明

gen_tree_ui(d, pat)

生成树形 UI 配置文件 index.ui

参数

• d (dict/DictObject): 渲染上下文数据
• pat (str): 输出目录路径

行为

1. 使用 MyTemplateEngine 渲染 ui_tmpl
2. 写入 pat/index.ui 文件
3. 调用 filter_backslash 清理反斜杠

---

gen_get_nodedata(d, pat)

生成获取节点数据的 .dspy 脚本

输出文件

get_{tblname}.dspy

示例输出

ns = params_kw.copy()
sql = '''select * from my_table where 1 = 1'''
id = ns.get('parent_id')
if id:
    sql += " and parent_id = ${id}$"
else:
    sql += " and parent_id is null"
sql += " order by name "
...

---

gen_new_nodedata(d, pat)

生成新增节点接口脚本

输出文件

new_{tblname}.dspy

调用 data_new_tmpl 模板进行渲染。

---

gen_update_nodedata(d, pat)

生成更新节点接口脚本

输出文件

update_{tblname}.dspy

调用 data_update_tmpl 模板进行渲染。

---

gen_delete_nodedata(d, pat)

生成删除节点接口脚本

输出文件

delete_{tblname}.dspy

调用 data_delete_tmpl 模板进行渲染。

---

build_tree_ui(tree_data, dbdesc)

主入口函数：根据树配置和数据库结构生成全部文件

参数

• tree_data: 包含 output_dir, tblname, params 的对象
• dbdesc: 数据库结构描述字典（由 build_dbdesc 生成）

流程

1. 创建输出目录
2. 提取当前表结构并封装为 DictObject
3. 添加额外参数（如 title、toolbar 等）
4. 调用 subtable2toolbar(tbldesc) 自动生成工具栏
5. 计算可编辑字段列表（排除 edit_exclouded_fields、idField、parentField）
6. 依次调用各 gen_* 函数生成所有文件

---

main(dbdesc, outdir, modulename, fn)

解析输入 JSON/XLSX 配置文件并执行生成流程

参数

• dbdesc: 数据库描述对象
• outdir: 输出目录
• modulename: 模块名称（用于确定数据库）
• fn: 输入配置文件路径（JSON 或 XLSX）

⚠️ 注意：函数重复定义两次，应保留一个。

---

命令行运行方式

python tree_generator.py <model_path> <outpath> <modelname> <tree_desc_file> [...]

参数说明

参数	说明
model_path	数据模型路径（通常是 .xlsx 文件或模型目录）
outpath	输出代码的目标目录
modelname	模块名（用于查找数据库配置）
tree_desc_file...	一个或多个树形结构定义文件（JSON 或 XLSX）

示例

python tree_generator.py ./models/db.xlsx ./output/admin usermgr ./trees/org_tree.json

---

配置文件结构示例（JSON）

{
  "tblname": "org_dept",
  "output_dir": "./output/admin/org",
  "title": "组织架构管理",
  "description": "管理部门与人员的树形结构",
  "parentField": "parent_id",
  "idField": "id",
  "textField": "dept_name",
  "typeField": "dept_type",
  "notitle": false,
  "editable": true,
  "new_data_url": "/api/org/add",
  "update_data_url": "/api/org/edit",
  "delete_data_url": "/api/org/remove",
  "get_data_url": "/api/org/nodes",
  "params": {
    "status": "active"
  },
  "newdata_params": {
    "autoCreateCode": true
  },
  "node_typeicons": {
    "company": "icon-company",
    "department": "icon-dept"
  },
  "edit_exclouded_fields": ["created_time", "updated_by"]
}

---

输出文件结构

在指定 output_dir 下生成以下文件：

output_dir/
├── index.ui                    # 树形界面配置
├── get_<tblname>.dspy          # 获取节点数据
├── new_<tblname>.dspy          # 新增节点
├── update_<tblname>.dspy       # 更新节点
└── delete_<tblname>.dspy       # 删除节点

---

扩展建议

1. 增加校验机制：对必填字段（如 idField, parentField）做存在性检查
2. 支持更多控件类型：可通过 widgettype 扩展为 TreeGrid、Cascade 等
3. 国际化支持：在模板中加入 i18n 支持
4. 权限控制注入：可在 .dspy 脚本中自动添加权限判断逻辑

---

版权与维护

• 项目：通用 CRUD 代码生成器子模块
• 维护者：未知（原始作者）
• 修改建议：请提交 PR 或 issue 至项目仓库

---

✅ 文档版本：v1.0
📅 最后更新：2025-04-05