Workspace 目录结构与工作机制¶

OBPM 设计态以文件系统为权威存储：设计定义（软件、模块、表单、视图、流程等）以 JAXB XML 落盘在 {myapps.storage.root}/workspace 下。设计器负责写盘与索引更新；运行时通过内存缓存读取，并监视 url.index 实现热加载。Designer 与 Runtime 共用同一 workspace，平台内没有独立的「发布副本」目录。

层次	实现位置
路径配置	`Environment`（`obpm-common/.../Environment.java`）
后缀常量	`ModelSuffix` / `ModelSuffixEx`
落盘 DAO	`AbstractFSDesignTimeDAO`（`obpm-core/.../dao/`）
索引与缓存	`DesignTimeSerializableCache`、`DesignTimeIndexCacheManager`
软件发现	`WorkspaceApplicationPoller`（每 5s 轮询，替换原 workspace 根 VFS 监听）
文件监视	`IndexFileMonitorListener`（每应用 `url.index`，Apache Commons VFS2）；`.sync` 见 §7.5
设计态服务	`DesignTimeServiceManager` → 各 `*DesignTimeServiceImpl`
启动	`InitDesigner`（设计器）、`InitRuntime`（运行时）等

按资源类型直接生成 XML 的细则见 docs/agent-skills-usage/skills/generate-*-file/SKILL.md；本文描述 结构与机制，不重复各资源字段表。

1. 配置与路径¶

1.1 核心配置¶

配置键	含义
`myapps.storage.root`	平台存储根目录

解析优先级（Environment.init / rootPath）：

启动参数 --myapps.storage.root=...
环境变量 myapps.storage.root 或 myapps_storage_root
classpath / 工作目录下的 application.yml|yaml|properties
默认尝试 {user.dir}/storage，再试 ../storage、../../storage

路径是否有效还会检查目录下是否存在 license5.x.zip（方法名 isLicenseExit，实为 license 文件存在性校验）。

1.2 派生路径¶

{myapps.storage.root}/
├── workspace/          # 设计态工作区（本文重点）
├── logs/               # 服务日志
├── fonts/              # 字体
├── uploads/            # 上传文件等
├── kms/                # KMS 文档（若启用）
├── models/             # 模型文件（若启用）
└── license5.x.zip      # 许可证

API：

Environment.getInstance().getStorageRootPath();   // {storage}
Environment.getInstance().getWorkspaceRootPath(); // {storage}/workspace

各模块 application.properties 常见默认：myapps.storage.root=C:\storage；run.bat 多通过 --myapps.storage.root=%WSPATH% 覆盖。

2. Workspace 目录结构¶

2.1 顶层¶

{myapps.storage.root}/workspace/
├── {软件名}.application/     # 展开式软件目录（可编辑）
├── version/                  # 版本快照（Versions）
├── .recycle/                 # 逻辑删除回收站
├── .tmp/                     # 应用市场导入等临时目录
└── .sync/                    # 同步任务投递目录（见 §7.5）

2.2 软件目录（应用级）¶

相对 workspace/{软件名}.application/：

相对路径	后缀 / 根元素	说明
`{软件名}.application`	`application`	软件元数据 XML
`url.index`	Properties	id → uri
`pid.index`	Properties	id → parentId
`datasource/*.datasource`	`dataSource`	数据源
`role/*.role`	`role`	角色
`module/{模块名}.module/`	`module`	一级模块（目录）
`menu/*.menu`	菜单	PC 菜单
`mobilemenu/*.mobilemenu`	移动菜单
`widget/`	`.widget` / `.widgetgroup`	首页小组件
`macro/*.macro`	脚本库
`valid/*.valid`	校验库
`style/*.style`	样式库
`task/*.task`	定时任务
`excelconfig/*.excelconfig`	Excel 导入配置
`mulitlang/*.mulitlang`	多语言（历史拼写 mulitlang）
`api/`	`.apigroup` / `.api`	API 中心
`links/*.link`	链接
`statelabel/`	状态标签
`bigscreen/`	大屏
`datamodel/`	数据模型
`extinterface/`	外部接口
`resources/`	静态资源（非 XML）
`static/`	静态页；运行时 `magic-static/{软件名}/`
`database/`	SQL 等附属
`README.md`	可选说明

后缀常量见 ModelSuffix；后缀 → Java 模型类见 ModelSuffixEx。

2.3 模块嵌套与模块内资源¶

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

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

模块内典型布局：

module/Leave.module/
├── Leave.module                 # 模块 XML
├── RequestForm.form             # 表单（文件）
├── RequestList.view             # 视图（文件）
├── LeaveFlow.flow/              # 流程（目录）
│   ├── LeaveFlow.flow
│   └── days.parameter
└── SubModule.module/            # 子模块
    └── SubForm.form

2.4 URI 约定¶

逻辑 URI 相对 workspace 根（不含 storage 前缀），由 FileSystemDesignTimeSerializable.getUri() / getPath() 计算。示例：

/LeaveOA.application/LeaveOA.application
/LeaveOA.application/datasource/main.datasource
/LeaveOA.application/module/Leave.module/RequestForm.form
/LeaveOA.application/module/Leave.module/LeaveFlow.flow/LeaveFlow.flow

绝对路径：Environment.getWorkspaceRootPath() + uri（见 AbstractFSDesignTimeDAO.getAbsolutePath）。

名称中的 / 落盘时会被替换为 =47，查询时再还原，避免误拆目录。

2.5 完整示例（LeaveOA）¶

C:\storage\workspace\
└── LeaveOA.application\
    ├── LeaveOA.application
    ├── url.index
    ├── pid.index
    ├── README.md
    ├── datasource\
    │   └── main.datasource
    ├── role\
    │   └── 管理员.role
    ├── module\
    │   └── Leave.module\
    │       ├── Leave.module
    │       ├── RequestForm.form
    │       ├── RequestList.view
    │       └── LeaveFlow.flow\
    │           ├── LeaveFlow.flow
    │           └── days.parameter
    ├── menu\
    ├── api\
    ├── resources\
    ├── static\
    └── database\

3. 索引与内存缓存¶

3.1 `url.index` / `pid.index`¶

每个展开式软件目录下各有一个 Properties 文件：

文件	内容
`url.index`	`资源id=/逻辑uri`
`pid.index`	`资源id=parentId`

新建软件时可先放空文件；首次经平台 save 后写入条目。DesignTimeSerializableCache.saveIndexToDisk 在每次设计态保存/删除后落盘。

3.2 `DesignTimeSerializableCache`¶

按 applicationId 维护 Caffeine 缓存（id → 设计态对象）
维护 INDEX_ID_URL / INDEX_ID_PID 与 appId↔name 映射

读取路径：

DesignTimeService.findById(appId, id)
  → DesignTimeSerializableCache.get
      → 命中：直接返回
      → 未命中：url.index 取 uri → 读 XML → JAXB → 回填缓存

3.3 重建索引 vs 热加载装入¶

API	行为	典型场景
`DesignTimeSerializableCache.initIndex`	仅从磁盘读 `url.index` / `pid.index` 装入属性映射；不清空 id→对象缓存	Runtime 启动、`url.index` 内容变更热加载
`DesignTimeIndexCacheManager.reloadCacheFromDisk`	`clear` + 扫盘重建对象缓存；不写回 index	内部供 `initCache` 使用；禁止在 `url.index` 变更监听中调用（会与 save 竞态）
`DesignTimeIndexCacheManager.initCache`	`reloadCacheFromDisk` 后再 `saveIndexToDisk`	设计器 `PUT /indexs/rebuild`

设计器 REST：PUT /indexs/rebuild（重建全部或指定软件）。手工改 XML 后若未走 API save，应重建索引或重启服务，否则 Runtime 热加载不会感知。

4. 生命周期总览¶

flowchart TD
    A[Environment.init] --> B["workspace = storageRoot/workspace"]
    B --> C{服务类型}
    C -->|Designer| D["InitDesigner: MODE_DESIGNER"]
    C -->|Runtime 等| E["InitRuntime: MODE_RUNTIME"]
    D --> F[扫描 .application]
    E --> F
    F --> G[DesignTimeSerializableCache.initIndex]
    E --> H["WorkspaceApplicationPoller.startOnce"]
    E --> I[initAllIndexFileMonitor]
    E --> S["默认创建并监听 .sync/"]
    S --> T["*.create_form_table → 同步动态表"]
    S --> U["*.init_default_datasource → DataSourceEnv + T_XXXX"]
    S --> V["*.clear_cache → 清缓存 + 重建数据源 + 附属全局清理"]
    J[设计器 API save] --> K[AbstractFSDesignTimeDAO.save]
    K --> L[JAXB XML 写盘]
    L --> M[Cache.put + saveIndexToDisk]
    M --> N[url.index 变更]
    N --> O[IndexFileMonitorListener.onUrlIndexChanged]
    O --> P["initIndex + 重建数据源（不清附属缓存）"]
    Q["activated=true + save"] --> R[DataSourceEnv + RT表 + 动态表]

5. 创建与导入¶

5.1 设计器 API 创建¶

POST /applications（ApplicationDesignTimeController）
ApplicationDesignTimeService.save → AbstractFSDesignTimeDAO.save
写入 {name}.application/{name}.application XML
创建空 pid.index、url.index，并随 save 更新索引
可选：Git 提交（JGitUtil.pushToGit，workspace 根为仓库）

5.2 手工 / Agent 落盘¶

按 generate-application-file 等技能写 XML 与目录骨架后：

调用 PUT /indexs/rebuild，或
重启 Designer / Runtime

否则内存索引与热加载链路不会包含新资源。

5.3 导入（应用市场 / Git）¶

应用市场或 Git 导入：clone 到 .tmp/，rename 到 workspace，再 initCache。

5.4 删除¶

VirtualFileSystemUtils.logicDelete：移入 workspace/.recycle/{时间戳}/...，并更新索引（非物理立即删除）。

6. 保存与更新（设计时写盘）¶

统一链路：

Controller → *DesignTimeServiceImpl → AbstractFSDesignTimeDAO.save(user, object)

6.1 `AbstractFSDesignTimeDAO.save` 步骤¶

名称/URI 合法性处理（含历史目录兼容、重命名）
JaxbUtils.convertToXml → VirtualFileSystemUtils.writeStringToFile
DesignTimeSerializableCache.put
DesignTimeSerializableCache.saveIndexToDisk（更新 url.index / pid.index）
JGitUtil.pushToGit（若已配置 Git）

6.2 特殊副作用¶

资源	副作用
软件 `activated=true`	初始化 `DataSourceEnv`、平台 RT 表、该软件下所有表单动态表（TLK_）；改名*会销毁并重建数据源连接
表单 save/update	`FormTableProcessBean` 创建/更新动态表
删除	逻辑删除至 `.recycle` + 索引更新

仅手写文件、不走平台 save API 时：**不会**自动同步动态表；依赖下次启动、导入或设计器保存触发。

也可通过向 workspace/.sync/ 投递触发文件（见 §7.5）：

*.create_form_table → 同步指定表单动态表（TLK_*）
*.init_default_datasource → 初始化默认库环境与平台 RT 静态表（T_XXXX）
*.clear_cache → 按 appId 清空设计时缓存、重建数据源、附属全局清理（不停 url.index 监听）

6.3 「发布」语义（平台内）¶

无独立 publish 管道。实际等价于：

动作	含义
`activated=true` + save	参与运行初始化；前台列表候选
Runtime 监视 `url.index`	设计器保存后无需重启即可加载新定义
企业域 `BIND_APPLICATIONS`	域绑定软件 id（数据库配置，不在 workspace 文件内）
角色 `status=1`	非 SYSTEM 软件前台可见还需用户拥有有效角色

前台可见条件概要：域绑定 ∩ activated ∩（SYSTEM 类型或拥有有效角色）。

7. 文件监视与热加载¶

url.index 与 .sync/ 底层仍用 Apache Commons VFS2 DefaultFileMonitor（setRecursive(false)）。软件目录的**发现与消失**改为定时轮询，不再挂 workspace 根目录的 VFS 创建监听。

7.1 各服务启动差异¶

服务	初始化	软件目录轮询	每应用 `url.index` 监视
Designer	`MODE_DESIGNER`	否	否
Runtime	`MODE_RUNTIME` + `initAllIndexFileMonitor`	是（`WorkspaceApplicationPoller.startOnce`）	是
Manager / Job	同类 Runtime	是	是
Report	注册报表回调；独立进程才 `startOnce`；lite 合包由 Runtime 启动轮询	见下	视实现

合包（obpm-lite）： Runtime 与 Report 共用同一 WorkspaceApplicationPoller；仅 Runtime startOnce，Report 只 register 回调。Report 独立进程则自行 startOnce。

要点：设计器不启动热重载 / 轮询；热加载发生在 Runtime（及 Manager/Job/Report）。

7.2 软件目录轮询（`WorkspaceApplicationPoller`）¶

每 **5 秒**扫描 workspace/*.application：

条件	回调	效果
描述文件 + `url.index` 均存在，且尚无该应用 index 监听	`CoreWorkspaceApplicationListener.onReady`	`initIndex` → `DataSourceEnv.initDataSource` → `initIndexFileMonitor`
已挂监听的应用目录消失，或 `url.index` 消失	`onRemoved`（与 `onUrlIndexDeleted` 对齐）	`destroyIndexFileMonitor` → `clear` 缓存 → 销毁数据源；不 `initDataSource`、不扫盘重建、不清附属全局缓存

规格：java/docs/superpowers/specs/2026-07-20-workspace-application-poller-design.md。

7.3 `url.index` 监听行为（`IndexFileMonitorListener`）¶

事件	方法	效果
内容变更	`onUrlIndexChanged`	`DesignTimeSerializableCache.initIndex`（只装入索引属性）；`destory`+`init` 数据源。不清附属全局缓存；不得 `clear` + `reloadCacheFromDisk`（与 save 竞态会导致 `getParent()` NPE）
删除	`onUrlIndexDeleted`	`destroyIndexFileMonitor`；`DesignTimeSerializableCache.clear`；销毁数据源；不 reload、不重建数据源、不清附属全局缓存

规格：java/docs/superpowers/specs/2026-07-20-url-index-deleted-cleanup-design.md。

三条清缓存路径对比：

路径	index	设计时对象缓存	数据源	附属全局清理	停 `url.index` 监听
`url.index` 变更	`initIndex`	不扫盘	重建	否	否
`url.index` 删除 / 轮询消失	清除映射	`clear`	仅销毁	否	是
`.sync/*.clear_cache`	`clear` 后 `initIndex`	`clear`（不扫盘重装）	重建	是	否

附属全局清理（仅 .clear_cache）：多语言 / 菜单 / 权限 / MyCache / 流程实例 / JS。

7.4 重要限制¶

热加载触发点是 url.index 变更，不是单个 XML 文件的修改。
设计器 API save 会写 index → Runtime 可热加载；变更路径只 initIndex，**保留**已有对象缓存中的 parent 等引用。
直接改 XML 而不更新 index → Runtime **不会**自动热加载；需 rebuild 索引或重启，或再经设计器 save 一次。
全量 initCache / reloadCacheFromDisk 仅用于显式重建索引，不要挂在 url.index 变更监听上。
需要强制丢弃脏对象缓存并清附属全局状态时，投递 .sync/*.clear_cache，不要依赖 url.index 监听。

7.5 `.sync` 同步任务目录¶

用于在**不走设计器 save API** 时（如 Agent / 手工落盘 XML）主动触发同步任务：表单动态表（*.create_form_table）、默认库环境与平台 RT 静态表（*.init_default_datasource）、按应用强制清缓存含附属全局清理（*.clear_cache）。*.create_form_table 规格见 docs/superpowers/specs/2026-07-16-sync-create-form-table-design.md（仓库内 java/docs/...）。

目录约定¶

项	约定
路径	`{myapps.storage.root}/workspace/.sync/`
子目录	`.done/`（成功归档）、`.failed/`（失败归档）
创建时机	Runtime 类服务启动 `initSyncMonitor` 时默认创建
监视	Runtime / Manager / Job 启动时监听；启动前先 drain 存量文件
Designer	不启用

触发文件：`*.create_form_table`¶

项	约定
文件名	`{任意前缀}.create_form_table`
文件内容	纯文本 `.form` 逻辑 URI（相对 workspace 根，一行；例：`/LeaveOA.application/module/Leave.module/RequestForm.form`）
投递方式	将文件放入 `workspace/.sync/`；不要求事先 rebuild 索引

处理流程¶

写入 .sync/{name}.create_form_table
  → 启动 drain 或 SyncMonitorListener.fileCreated
  → 读取 form URI → 读盘 JAXB 加载 Form（不查 url.index）
  → FormTableProcessBean.createOrUpdateDynaTable(form, form)
  → 成功 → .sync/.done/；失败 → .sync/.failed/

flowchart LR
    A["投放 *.create_form_table"] --> B[".sync 监视器"]
    B --> C["读取 form URI"]
    C --> D["读盘加载 Form"]
    D --> E["同步动态表任务"]
    E --> F["TLK_* 创建/更新"]
    F --> G[".done / .failed"]

与 §6.2 的关系：设计器 save 表单仍走现有 FormTableProcessBean 副作用；.sync 是面向**外部写盘**场景的补充触发通道，不替代 API save。Agent 落盘 .form 后的收尾步骤见 docs/agent-skills-usage/skills/generate-form-file/SKILL.md（「动态表同步触发」）。

触发文件：`*.init_default_datasource`¶

对应设计器 PUT /applications/{id}（activated=true）副作用中的 DataSourceEnv + 平台 RT 静态表（T_XXXX） 部分；**不**做全量表单 TLK_* 同步（单表仍用 *.create_form_table）。规格细节可与 *.create_form_table 同目录归档约定共用。

项	约定
文件名	`{任意前缀}.init_default_datasource`
文件内容	纯文本 `.datasource` 逻辑 URI（相对 workspace 根，一行；例：`/LeaveOA.application/datasource/main.datasource`）
投递方式	将文件放入 `workspace/.sync/`；不要求事先 rebuild 索引
适用条件	目标应为该软件默认库（`defaultDataSource=true`，或按软件默认库解析规则落到该项）；软件宜已 `activated=true`

处理流程¶

写入 .sync/{name}.init_default_datasource
  → 启动 drain 或 SyncMonitorListener.fileCreated
  → 读取 datasource URI → 读盘 JAXB 加载 DataSource（不查 url.index）
  → 校验/解析为软件默认库
  → DataSourceEnv 初始化该库连接/环境
  → AbstractApplicationInitDAO 初始化平台 RT 静态表（T_DOCUMENT、T_FLOWSTATERT 等 T_XXXX）
  → 成功 → .sync/.done/；失败 → .sync/.failed/

flowchart LR
    A["投放 *.init_default_datasource"] --> B[".sync 监视器"]
    B --> C["读取 datasource URI"]
    C --> D["读盘加载 DataSource"]
    D --> E["DataSourceEnv 初始化"]
    E --> F["AbstractApplicationInitDAO"]
    F --> G["T_XXXX 创建/对齐"]
    G --> H[".done / .failed"]

与 §6.2 / PUT 激活的关系：设计器将软件置 activated=true 并 save 时，仍走 ApplicationDesignTimeServiceImpl 既有副作用（含可选的全量动态表同步）；.sync 的本触发仅覆盖其中 默认库环境 + T_XXXX，供 Agent / 手工落盘 .datasource 后补齐 RT 表。静态表清单见 docs/design/database-struct.md（「静态表」）。

触发文件：`*.clear_cache`¶

用于在不删软件、不停 url.index 监听的前提下，强制清空某应用的设计时对象缓存、重建数据源，并执行**附属全局清理**（与 url.index 监听路径不同：后者不清附属缓存）。规格：java/docs/superpowers/specs/2026-07-20-sync-clear-cache-design.md。

项	约定
文件名	`{任意前缀}.clear_cache`
文件内容	纯文本 applicationId（一行；例：`sOZu9kthmxyP8qQfq0e`）
投递方式	将文件放入 `workspace/.sync/`
要做	`clear` → `initIndex` → 重建数据源 → 清多语言/菜单/权限/MyCache/流程实例/JS
不做	不停该应用 `url.index` 监听；不 `reloadCacheFromDisk` / `initCache`

处理流程¶

写入 .sync/{name}.clear_cache
  → 启动 drain 或 SyncMonitorListener.fileCreated
  → 读取 applicationId
  → DesignTimeSerializableCache.clear(applicationId)
  → 若有应用名：initIndex（恢复 index 映射，不扫盘装对象）
  → DataSourceEnv.destoryDataSource + initDataSource
  → 清多语言 / 菜单 / 权限 / MyCache / 流程实例 / JS
  → 成功 → .sync/.done/；失败 → .sync/.failed/

flowchart LR
    A["投放 *.clear_cache"] --> B[".sync 监视器"]
    B --> C["读取 appId"]
    C --> D["clear 设计时缓存"]
    D --> E["重建数据源"]
    E --> F["附属全局清理"]
    F --> G[".done / .failed"]

8. 运行时加载¶

启动（Runtime）：

DesignTimeIndexCacheManager.init(MODE_RUNTIME)：扫描 workspace，加载展开式 .application 目录；注册 CoreWorkspaceApplicationListener 并 WorkspaceApplicationPoller.startOnce
initAllIndexFileMonitor()：给已有软件挂 url.index 监视
对 activated=true 的软件：DataSourceEnv.initDataSource

运行期读定义与设计态共用 DesignTimeService + DesignTimeSerializableCache；业务数据在数据库动态表（如 TLK_*），不在 workspace XML 内。

9. 关键 API / REST 速查¶

9.1 Java¶

Environment.getInstance().getWorkspaceRootPath();

DesignTimeSerializableCache.initIndex(applicationId, applicationName);
DesignTimeSerializableCache.saveIndexToDisk(applicationId, applicationName);
DesignTimeSerializableCache.get(applicationId, id);
DesignTimeSerializableCache.clear(applicationId);

DesignTimeIndexCacheManager.getInstance().init(MODE_RUNTIME | MODE_DESIGNER);
DesignTimeIndexCacheManager.getInstance().initAllIndexFileMonitor();
DesignTimeIndexCacheManager.getInstance().initCache(applicationId, applicationName); // clear+扫盘+写回 index
DesignTimeIndexCacheManager.getInstance().destroyIndexFileMonitor(applicationId);
DesignTimeIndexCacheManager.getInstance().hasIndexFileMonitor(applicationId);
DesignTimeIndexCacheManager.fastFindId(xmlString);

WorkspaceApplicationPoller.getInstance().register(listener);
WorkspaceApplicationPoller.getInstance().startOnce();

AbstractFSDesignTimeDAO.save(user, object);
AbstractFSDesignTimeDAO.delete(user, applicationId, id);

9.2 设计器 REST（节选）¶

方法	路径	说明
POST	`/applications`	新建软件
PUT	`/applications/{id}`	更新软件（含 `activated`）
PUT	`/indexs/rebuild`	重建索引
GET	`/indexs/applications`	列举 workspace 中软件

10. 关键类索引¶

类	模块	职责
`Environment`	obpm-common	storage / workspace 路径
`ModelSuffix` / `ModelSuffixEx`	common / core	后缀与模型映射
`FileSystemDesignTimeSerializable`	obpm-common	URI/Path 基类
`VirtualFileSystemUtils`	obpm-common	VFS 读写、逻辑删除
`AbstractFSDesignTimeDAO`	obpm-core	XML 落盘、索引、Git
`DesignTimeSerializableCache`	obpm-core	内存缓存与 index 文件（`initIndex` / `saveIndexToDisk` / `clear`）
`DesignTimeIndexCacheManager`	obpm-core	扫描建索引、启监视器 / 轮询；`initCache` 全量重建
`WorkspaceApplicationPoller`	obpm-core	每 5s 发现/清理软件目录（替换原 workspace 根 VFS 监听）
`CoreWorkspaceApplicationListener`	obpm-core	轮询就绪：`initIndex` + 数据源 + 挂 `url.index` 监听；消失：对齐删除清理
`IndexFileMonitorListener`	obpm-core	`url.index` 变更=`initIndex`+重建数据源（无附属清理）；删除=停监听+清缓存+毁数据源
`SyncMonitorListener` / `CreateFormTableSyncHandler`	obpm-core	`.sync` 动态表同步触发（`*.create_form_table`）
`InitDefaultDataSourceSyncHandler`	obpm-core	`.sync` 默认库 + `T_XXXX` 初始化（`*.init_default_datasource`）
`ClearCacheSyncHandler`	obpm-core	`.sync` 按 appId 清缓存 + `initIndex` + 重建数据源 + 附属全局清理（`*.clear_cache`）
`AbstractApplicationInitDAO`	obpm-core	平台 RT 静态表（`T_XXXX`）DDL 定义与初始化
`DesignTimeServiceManager`	obpm-core	设计态服务工厂
`ApplicationDesignTimeServiceImpl`	obpm-core	软件保存与激活副作用
`FormDesignTimeServiceImpl`	obpm-core	表单保存与动态表
`InitDesigner` / `InitRuntime`	designer / runtime	启动入口
`ApplicationDesignTimeController`	obpm-designer	软件 CRUD / 重建索引
`JGitUtil`	obpm-core	workspace Git 提交

11. 运维与协作注意¶

Designer 与 Runtime 指向同一 myapps.storage.root，热加载才有意义。
手工改文件后务必 rebuild 索引（或走设计器保存），否则 Runtime 不可见。
软件 name 即目录名，全 workspace 唯一；激活态改名会重建数据源与动态表，慎改。
域绑定、用户角色在 运行库，不在 workspace 文件里。
.recycle 为逻辑删除落点；清理前确认无需恢复。
Git：workspace 根可作为版本库，每次 save 可自动 commit；协作流程需团队自行约定分支策略。
.sync/ 用于投递同步任务：*.create_form_table（动态表）、*.init_default_datasource（默认库 DataSourceEnv + T_XXXX）、*.clear_cache（按 appId 清设计时缓存 + 重建数据源 + 附属全局清理）；成功进 .done/，失败进 .failed/；勿把手写业务 XML 直接放进该目录。
Runtime 侧软件目录靠轮询发现；url.index 变更热加载只做 initIndex + 重建数据源（**不清**附属缓存），不要在监听里做 clear+扫盘重建；强制全清走 .clear_cache。

12. 相关文档¶

文档	内容
`docs/agent-skills-usage/skills/generate-application-file/SKILL.md`	软件/数据源/角色目录与字段
`docs/agent-skills-usage/skills/generate-*-file/SKILL.md`	表单、视图、流程等资源写法
`docs/design/dyna-form.md` 等	运行时表单/视图等设计方案
`docs/design/database-struct.md`	平台 RT 静态表（`T_XXXX`）清单
`java/docs/superpowers/specs/2026-07-20-workspace-application-poller-design.md`	软件目录 5s 轮询发现/清理
`java/docs/superpowers/specs/2026-07-20-url-index-deleted-cleanup-design.md`	`url.index` 变更=`initIndex`+数据源；删除清理；均无附属清理
`java/docs/superpowers/specs/2026-07-20-sync-clear-cache-design.md`	`.sync` `*.clear_cache` 清缓存 + 重建数据源 + 附属全局清理
`CLAUDE.md`	仓库级概览（含 workspace 一句说明）

Workspace 目录结构与工作机制¶

1. 配置与路径¶

1.1 核心配置¶

1.2 派生路径¶

2. Workspace 目录结构¶

2.1 顶层¶

2.2 软件目录（应用级）¶

2.3 模块嵌套与模块内资源¶

2.4 URI 约定¶

2.5 完整示例（LeaveOA）¶

3. 索引与内存缓存¶

3.1 url.index / pid.index¶

3.2 DesignTimeSerializableCache¶

3.3 重建索引 vs 热加载装入¶

4. 生命周期总览¶

5. 创建与导入¶

5.1 设计器 API 创建¶

5.2 手工 / Agent 落盘¶

5.3 导入（应用市场 / Git）¶

5.4 删除¶

6. 保存与更新（设计时写盘）¶

6.1 AbstractFSDesignTimeDAO.save 步骤¶

6.2 特殊副作用¶

6.3 「发布」语义（平台内）¶

7. 文件监视与热加载¶

7.1 各服务启动差异¶

7.2 软件目录轮询（WorkspaceApplicationPoller）¶

7.3 url.index 监听行为（IndexFileMonitorListener）¶

7.4 重要限制¶

7.5 .sync 同步任务目录¶

目录约定¶

触发文件：*.create_form_table¶

处理流程¶

触发文件：*.init_default_datasource¶

处理流程¶

触发文件：*.clear_cache¶

处理流程¶

8. 运行时加载¶

9. 关键 API / REST 速查¶

9.1 Java¶

9.2 设计器 REST（节选）¶

10. 关键类索引¶

11. 运维与协作注意¶

12. 相关文档¶

3.1 `url.index` / `pid.index`¶

3.2 `DesignTimeSerializableCache`¶

6.1 `AbstractFSDesignTimeDAO.save` 步骤¶

7.2 软件目录轮询（`WorkspaceApplicationPoller`）¶

7.3 `url.index` 监听行为（`IndexFileMonitorListener`）¶

7.5 `.sync` 同步任务目录¶

触发文件：`*.create_form_table`¶

触发文件：`*.init_default_datasource`¶

触发文件：`*.clear_cache`¶