核心概念

这一页解决的是**"东西该放哪、谁看得见谁"**的问题。平台里绝大多数"看不懂"和"改出 bug"， 根源都是把下面几组概念混在了一起。

用法：每一节先给结论，再给可核验的落点（真实路径、类名或命令）。 本工作区没有验证过的内容一律标注"未验证"，不做推测；口径有分歧时以 wujies-platform/AGENTS.md 为准（它是约束与已知坑的权威清单）。

一、三个仓库，先认清目录名复制标题链接

三个仓库没有共同的 git 根，各自分支、各自提交。

wujies-admin 这一个名字指三处不同地方复制标题链接

记法：路径里出现 src/plugins/**、src/views/**、app-market-dist/** → 说的是 plus-ui/； 出现 src/main/resources/**、wujies-admin.jar、-pl wujies-admin → 说的是 wujies-platform/wujies-admin/。

二、一个应用 = 一个自包含工程复制标题链接

结论复制标题链接

平台里没有为应用单独拆出的契约模块，平台源码也不引用应用的类。每个应用是一个自包含的工程：

由此得到三条硬事实：

• wujies-platform/wujies-modules/ 下的模块全是平台自己的，没有应用契约模块；
• 平台对 cn.wujies.<app>.* 的 Java 引用为 0，只允许出现在注释里；
• 新增业务模块不需要改平台一行，只写插件。

怎么自己核验（本工作区实测）复制标题链接

第一条命令列出平台模块清单（不应出现任何应用自己的模块）， 第二条检查平台源码有没有真的 import 应用包：

Get-ChildItem .\wujies-platform\wujies-modules -Directory | Select-Object -ExpandProperty Name

Get-ChildItem .\wujies-platform -Recurse -Include *.java |
    Select-String -Pattern 'cn\.wujies\.(gallery|exam|im|pay|quote|social|mall|member|enterprise|hello|finance)\.'

实测：第一条命令的输出是 wujies-app-market、wujies-plugin-probe、wujies-system、wujies-workflow 四个模块，没有任何应用自己的模块。第二条的命中全部落在注释、日志文案与测试断言字符串里； 唯一带真实 import 的命中在 wujies-platform/docs/removed/ 下 —— 那是已移出 reactor 的存档源码。

一个真实插件的目录（wujies-quote，本工作区实测）复制标题链接

wujies/wujies-plugins/wujies-quote/
├── app.json                                应用清单（菜单树、产物路径、依赖）
├── pom.xml                                 parent = cn.wujies.plugins:wujies-plugins-parent
├── migrations/01-create-quote-tables.sql   建表脚本，安装/升级时执行
└── src/main/
    ├── java/cn/wujies/quote/
    │   ├── controller/                     QuoteController、QuotePriceController
    │   ├── domain/                         实体；bo/ 与 vo/ 在其下
    │   ├── mapper/                         QuoteMapper、QuoteItemMapper、QuotePriceMapper
    │   ├── service/、service/impl/         接口与实现
    │   ├── fallback/QuoteServiceLocator    给宿主用的定位器
    │   └── portal/                         门户端（C 端）接口
    └── resources/mapper/quote/             QuoteMapper.xml 等 3 个映射文件

两条命名约定：

• 包名 = cn.wujies.<app>.*，应用编码就是包名的第二段；
• 插件模块的 artifactId 是 wujies-<app>-plugin（如 wujies-quote-plugin），jar 也按这个名字产出。

定时任务同样随应用走（包落在 cn.wujies.<app>.task 下），例如 wujies/wujies-plugins/wujies-member/src/main/java/cn/wujies/member/task/MemberPointsExpireTask.java。

三、Mapper XML：随插件 jar 走，由代码注册复制标题链接

这一条最容易被教反，单独讲。先看结论：

代码位置： wujies-platform/wujies-modules/wujies-app-market/src/main/java/cn/wujies/appmarket/plugin/PluginMapperRegistrar.java； 同包的 PluginRuntimeManager 负责把 Mapper bean 注册进宿主（registerMapperBeans）。

接口怎么被认出来复制标题链接

Mapper bean 注册在宿主 beanFactory，而不是插件自己的子上下文 —— 因为兄弟插件也要按类型注入它 （例如 mall 注入 member 的 MemberMapper）。只在宿主注册一份，插件子上下文里不再注册。

排错对照复制标题链接

这些细节与实测记录见 wujies-platform/AGENTS.md §2.2、docs/开发问题与解决方案.md §2。

四、两种上下文：宿主 / 插件复制标题链接

插件子上下文以宿主为 parent，所以 插件能注入宿主，宿主不能注入插件。 这条 Spring 的父子关系是单向的，也是很多"为什么注入不进来"的答案。

宿主侧要拿插件服务，只有两条路：

插件之间怎么互相调用（依赖兄弟插件构件、需要共享的事件类必须放平台等）， 见 必须遵守的不变量。

五、三种数据：目录 / 安装实例 / 迁移记录复制标题链接

关键点：目录表已经配置成"不按租户隔离"（见 wujies-platform/wujies-admin/src/main/resources/application.yml 的 security.tenant.excludes）， 而安装实例表带 tenant_id、由多租户插件自动隔离。所以：

• 想把目录集中到一台服务器、其它部署远程读 → 可行，而且不需要传租户参数；
• 想集中安装实例 → 不要做，那是每个部署自己的运行状态。

远程读目录还有一个静默坑：空串参数不是"没传"。拼 ?audience= 时服务端拿到的是空字符串而不是 null，而可见范围判断是 audience != null → 会去匹配 FIND_IN_SET('', audience) → 一条都查不出来。 跨进程传参时，可选参数要整条丢掉，不要拼空值。

六、另外三组容易混的复制标题链接

6.1 官方版 / 用户版（app-market.edition）复制标题链接

同一套代码扮演两个角色，刻意不做 fork：

详见 目录中心化与版本形态。

6.2 落位 / 加载复制标题链接

"安装应用"其实是两件事，本项目刻意把它们拆开：

顺序上保证 落位 → 变更表结构 → 切换代码。反过来的话，新代码在启动时机读一个还没建的列就会炸。 详见 应用生命周期。

6.3 菜单 key / menu_id复制标题链接

菜单以 menu_key 为身份，menu_id 只是数据库主键。

• 安装/升级时按 menu_key 幂等 upsert，同名 key 复用既有 menu_id —— 否则租户已经分配好的权限会在升级后全部失效；
• 新版本里被移除的菜单标记为 obsolete，调用方应"停用"而不是"删除"；
• 因此永远不要手写 INSERT INTO sys_menu，菜单只能通过应用清单声明。

详见 菜单与权限。

相关阅读复制标题链接

• 必须遵守的不变量
• 应用生命周期
• 目录中心化与版本形态
• 数据模型
• 菜单与权限
• 数据库迁移
• 术语表