.module 文件 Schema¶

位置：/{应用}.application/module/{模块名}.module/{模块名}.module（子模块嵌套于父模块目录）　|　XML 根：module　|　与技能对齐：generate-module-file 机制背景见 [[design/table-schema/overview]]。

1. 用途与落盘¶

模块 = 应用内的**资源容器**（表单/视图/流程/报表/图表 + 子模块），本身几乎无业务逻辑。JAXB XML，根元素小写 module，id 为**根属性**。目录名 = 元数据文件名 = <name>。

/{应用}.application/module/{模块}.module/{模块}.module            # 顶层模块
/{应用}.application/module/{父模块}.module/{子模块}.module/{子模块}.module  # 子模块

路径硬规则（Module.getPath()）：

parent 类型	路径形态
Application	`/{app}.application/module/{name}.module`
Module	`/{父模块路径}/{name}.module`（不再插 `/module/`）

2. 属性表¶

属性	XML 形态	类型	默认	说明
`id`	根属性	string	须生成	`__` + 短 UUID
`name`	子元素	string	—	必填；目录名与文件名
`parentId`	子元素	string	—	文件系统父：顶层=应用 id；子模块=上级模块 id
`superior`	子元素	string	`""`	逻辑上级模块 id；顶层留空；子模块=上级模块 id（与 parentId 同值）
`orderNo`	子元素	int	0	同级排序（升序）
`description`	子元素 CDATA	string	空
`remark`	子元素 CDATA	string	可省略

不进 XML：applicationid（靠路径归属）、uri（运行时推导）。

name 含 / % \ 时落盘替换为 =47/=37/=92，读取还原；尽量勿用这些字符。

3. XML 示例¶

顶层模块：

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<module id="__MpEzTToulqZtNEFisw6">
  <name>事件模块</name>
  <parentId>__l7pzNG6dR2wuVJ1kOGV</parentId>
  <description><![CDATA[售后事件]]></description>
  <orderNo>0</orderNo>
  <superior></superior>
</module>

子模块：superior = parentId = 上级模块 id。

4. 模块内可挂资源¶

后缀	含义	子项 `parentId`
`module`	子模块	父模块 id（+ `superior`）
`form`	表单	本模块 id
`view`	视图	本模块 id
`flow`	流程	本模块 id
`report`	套打/报表模板	本模块 id
`chart`	统计图	本模块 id

非模块资源（勿塞进 .module 目录）：menu/mobilemenu/role/datasource/style/macro/valid/task/widget/statelabel/api 等落应用目录对应 group。

5. 校验规则（设计态）¶

name 空 → 「模块名称不能为空」
同级（相同 parentId）重名 → 「同级模块名称已存在」
name 与上级模块同名 → 「名称不可以跟上级相同」
删除模块 = 按 uri 逻辑删除**整个目录树**（含子资源）
重命名须同步：目录名 + 元数据文件名 + XML <name>

6. 相关¶

资源	文档
所属软件	[[application-file]]
表单/视图/流程	[[form-file]] / [[view-file]] / [[flow-file]]
生成操作指南	`agent-skills-usage/skills/generate-module-file/SKILL.md`