748 lines
20 KiB
Markdown
748 lines
20 KiB
Markdown
# AR10 XApp Removable Packaging Specification
|
||
|
||
> **版本**：V1.2
|
||
> **日期**：2026-09-18
|
||
> **性质**：规范性文件（normative）
|
||
> **适用对象**：`xapp`，即一级业务包
|
||
> **关联文档**：
|
||
> - `AR05_工作台架构约定.md`
|
||
> - `AR09_对象命名规范.md`
|
||
> - `AR11_技能专员连接器可删除封装规范.md`
|
||
|
||
## 1. 目标
|
||
|
||
本文定义 `xapp` 的封装方式，目标是让一个 `xapp` 在工程上达到如下删除标准：
|
||
|
||
1. 删除一个后端目录
|
||
2. 删除一个前端目录
|
||
3. 删除一条注册项
|
||
4. 不需要全仓手工搜改业务代码
|
||
5. 重新构建后不出现编译错误
|
||
6. 运行卸载脚本后，不残留该 `xapp` 自有表、路由、菜单、任务、通知、前端状态
|
||
|
||
本文中的“可删除”指：
|
||
|
||
- 删一个目录 + 删一条注册项 + 跑一次卸载 = 安全移除一个 `xapp`
|
||
|
||
严格意义上，“删一个文件就彻底删除”只适用于插件二进制或代码生成包；在当前单仓工程内，合理目标应为“删一个目录”。
|
||
|
||
## 2. 范围与非目标
|
||
|
||
### 2.1 本文覆盖
|
||
|
||
本文覆盖 `xapp` 的以下封装维度：
|
||
|
||
1. manifest
|
||
2. registry
|
||
3. 前后端路由注册
|
||
4. provider 暴露
|
||
5. 数据边界
|
||
6. schema 与 seed
|
||
7. 卸载协议
|
||
8. 定义条目所有权
|
||
9. 共享引用降级协议
|
||
10. 守卫与验收标准
|
||
|
||
### 2.2 本文不覆盖
|
||
|
||
本文不讨论以下内容的具体业务实现：
|
||
|
||
1. 某个 `xapp` 内部页面应该长什么样
|
||
2. 某个 `xapp` 的领域模型如何详细设计
|
||
3. 某个 `xapp` 的 UI 风格如何命名
|
||
|
||
这些属于对象内部实现，不属于封装边界规范本身。
|
||
|
||
## 3. 当前问题
|
||
|
||
当前仓库已经存在 `xapp_definition`、前端 `/xapps/...` 路由以及若干 `XAppShell`，但多数业务 `xapp` 仍停留在“入口像 xapp，底层仍是平台散装模块”的阶段。典型表现如下：
|
||
|
||
1. 平台总路由中仍手写某个 `xapp` 的业务路由
|
||
2. 平台总导航中仍手写某个 `xapp` 的菜单
|
||
3. 平台层 API 直接查询某个 `xapp` 的表
|
||
4. `xapp` 的核心对象仍放在通用 `model` 包，而非 `xapp` 自己的域包
|
||
5. 持久化模型直接兼任 API DTO 和领域对象
|
||
6. 统计、画像、后台管理直接耦合业务表，而不是通过 provider 聚合
|
||
7. `xapp` 的任务、通知、缓存、前端状态未形成 own 命名空间
|
||
8. `xapp_definition`、目录条目、seed 定义记录等定义层资源尚未进入卸载协议
|
||
9. 历史任务、收藏、通知历史等共享引用在对象删除后的处理策略未定义
|
||
|
||
这意味着当前不少 `xapp` 仍停留在“挂了 xapp 皮肤的并行模块”阶段，尚未达到可插拔业务包标准。
|
||
|
||
## 4. 定义
|
||
|
||
### 4.1 什么是 xapp
|
||
|
||
在本项目中，`xapp` 的定义是：
|
||
|
||
1. 一个可注册的一级业务包
|
||
2. 一个有 manifest 的对象
|
||
3. 一个有自有 schema 的领域边界
|
||
4. 一个只通过 contract 暴露能力的模块
|
||
5. 一个可以通过“删目录 + 删注册 + 跑卸载”安全移除的工程单元
|
||
|
||
### 4.2 什么不是 xapp
|
||
|
||
以下对象不应按 `xapp` 方式建模：
|
||
|
||
1. 单个技能
|
||
2. 单个专员
|
||
3. 单个连接器
|
||
4. 一张单页配置页
|
||
5. 一个普通 store 或 API 文件
|
||
|
||
这些对象的封装规则见 `AR11`。
|
||
|
||
## 5. 封装目标
|
||
|
||
每个 `xapp` 必须完整拥有以下六类内容：
|
||
|
||
1. Manifest
|
||
2. Frontend shell
|
||
3. Backend module
|
||
4. Domain model / repo / service
|
||
5. Owned schema
|
||
6. Integration adapters
|
||
|
||
平台层只负责：
|
||
|
||
1. 注册 `xapp`
|
||
2. 聚合 `xapp` 暴露的能力
|
||
3. 为 `xapp` 提供公共底座能力
|
||
|
||
平台层不负责：
|
||
|
||
1. 直接进入 `xapp` 内部目录取对象
|
||
2. 直接查询 `xapp` 自有表
|
||
3. 直接 hardcode 某个 `xapp` 的页面、菜单、统计、通知
|
||
4. 直接依赖 `xapp` 内部 repo / service / views
|
||
|
||
## 6. 依赖方向
|
||
|
||
`xapp` 封装能否成立，核心不在于目录是否漂亮，而在于依赖方向是否单一。
|
||
|
||
正确依赖方向应为：
|
||
|
||
```text
|
||
platform core
|
||
-> xapps/core/contracts
|
||
-> xapps/core/registry
|
||
-> xapp manifest
|
||
-> xapp module install / register
|
||
|
||
xapp internal
|
||
-> xapp domain / repo / service / dto / schema
|
||
```
|
||
|
||
错误依赖方向包括：
|
||
|
||
1. `platform api -> xapp repo`
|
||
2. `platform stats -> xapp table`
|
||
3. `platform nav -> xapp views path literal`
|
||
4. `platform seed -> xapp domain object`
|
||
|
||
一句话：**平台层可以认识“这个 xapp 存在”，但不能认识“这个 xapp 里面具体有什么文件”。**
|
||
|
||
## 7. 推荐目录结构
|
||
|
||
### 7.1 后端
|
||
|
||
```text
|
||
backend-go/internal/xapps/
|
||
core/
|
||
contracts.go
|
||
manifest.go
|
||
registry.go
|
||
uninstall.go
|
||
apps/
|
||
internal_exam/
|
||
manifest.go
|
||
module.go
|
||
api/
|
||
student.go
|
||
admin.go
|
||
domain/
|
||
paper.go
|
||
record.go
|
||
mistake.go
|
||
repo/
|
||
paper_repo.go
|
||
record_repo.go
|
||
mistake_repo.go
|
||
service/
|
||
exam_service.go
|
||
stats_service.go
|
||
dto/
|
||
request.go
|
||
response.go
|
||
schema/
|
||
migrations.go
|
||
uninstall.go
|
||
assets/
|
||
tests/
|
||
internal_training/
|
||
manifest.go
|
||
module.go
|
||
api/
|
||
domain/
|
||
repo/
|
||
service/
|
||
dto/
|
||
schema/
|
||
assets/
|
||
tests/
|
||
```
|
||
|
||
### 7.2 前端
|
||
|
||
```text
|
||
frontend/src/xapps/
|
||
core/
|
||
contracts.js
|
||
registry.js
|
||
installer.js
|
||
uninstall.js
|
||
apps/
|
||
internal-exam/
|
||
manifest.js
|
||
routes.js
|
||
nav.js
|
||
providers.js
|
||
api/
|
||
store/
|
||
views/
|
||
components/
|
||
assets/
|
||
internal-training/
|
||
manifest.js
|
||
routes.js
|
||
nav.js
|
||
providers.js
|
||
api/
|
||
store/
|
||
views/
|
||
components/
|
||
assets/
|
||
```
|
||
|
||
## 8. 核心硬规则
|
||
|
||
### 8.0 一对象一目录是最终形态
|
||
|
||
对 `xapp` 而言，最终封装形态必须满足：
|
||
|
||
1. 一个 `xapp` 对应一个后端目录
|
||
2. 一个 `xapp` 对应一个前端目录
|
||
3. 该 `xapp` 的业务定义、路由定义、provider 定义、schema 定义都落在自己的目录中
|
||
|
||
因此：
|
||
|
||
1. **允许中心化注册**
|
||
2. **不允许中心化定义**
|
||
|
||
这里的“中心化注册”指：
|
||
|
||
1. registry 统一列出有哪些 `xapp manifest`
|
||
2. installer 统一执行 install / uninstall
|
||
3. platform core 统一聚合 provider
|
||
|
||
这里的“中心化定义”指：
|
||
|
||
1. 在一个平台公共文件里手写多个 `xapp` 的业务路由
|
||
2. 在一个平台公共文件里手写多个 `xapp` 的菜单项
|
||
3. 在一个平台公共文件里手写多个 `xapp` 的 schema / provider / page path
|
||
|
||
前者是允许的，后者不是最终封装形态。
|
||
|
||
### 8.0.1 允许中心化 / 禁止中心化
|
||
|
||
| 类型 | 是否允许 | 说明 |
|
||
|---|---|---|
|
||
| `xapps/core/registry` 集中列出 manifest | 允许 | 该文件承担注册中心职责 |
|
||
| `xapps/core/installer` 统一安装路由和导航 | 允许 | 这是装配层 |
|
||
| 平台总路由手写 `internal-exam` 业务路径 | 禁止 | 这是业务定义泄漏 |
|
||
| 平台总导航手写 `internal-training` 菜单细节 | 禁止 | 这是业务定义泄漏 |
|
||
| 平台公共文件集中维护多个 `xapp` 的 page path / provider key / table 名 | 禁止 | 这会破坏目录级删除 |
|
||
|
||
### 8.1 平台层不能直接 import xapp 内部实现
|
||
|
||
平台层只能依赖：
|
||
|
||
1. `xapps/core/registry`
|
||
2. `manifest`
|
||
3. `contracts/interface`
|
||
|
||
平台层不能依赖：
|
||
|
||
1. `internal_exam/domain/*`
|
||
2. `internal_exam/repo/*`
|
||
3. `internal_exam/service/*`
|
||
4. `internal_exam/views/*`
|
||
5. 任何其他 `xapp` 内部文件
|
||
|
||
这条规则的目的，是保证删除某个 `xapp` 目录后，不会炸掉全局依赖图。
|
||
|
||
### 8.2 路由必须由 xapp 自己注册
|
||
|
||
总路由不得手写某个 `xapp` 的业务路径，例如：
|
||
|
||
1. `/api/exam/*`
|
||
2. `/xapps/internal-exam/*`
|
||
3. `/courses/*`
|
||
4. `/products/*`
|
||
|
||
正确做法：
|
||
|
||
1. 平台加载 `xapp registry`
|
||
2. `xapp` 在 `module.go` / `manifest.js` 中自注册前后端路由
|
||
|
||
后端示意：
|
||
|
||
```go
|
||
xappRegistry.Register(internalexam.Manifest)
|
||
```
|
||
|
||
前端示意：
|
||
|
||
```js
|
||
xappRegistry.register(internalExamManifest)
|
||
```
|
||
|
||
### 8.3 数据表必须归属到 xapp 命名空间
|
||
|
||
为了实现“删目录即可删表”，表名必须体现归属。
|
||
|
||
不推荐：
|
||
|
||
1. `exam_paper`
|
||
2. `exam_record`
|
||
3. `mistake_record`
|
||
4. `learning_progress`
|
||
|
||
推荐：
|
||
|
||
1. `xapp_exam_paper`
|
||
2. `xapp_exam_record`
|
||
3. `xapp_exam_mistake`
|
||
4. `xapp_training_progress`
|
||
|
||
如果某张表是平台共享能力，而不是某个 `xapp` 私有数据，则应放入 shared 域，不允许伪装成 `xapp` 私有对象。
|
||
|
||
### 8.4 核心对象不能继续停留在通用 model 总包
|
||
|
||
`xapp` 私有业务对象必须放入自己的域目录，例如：
|
||
|
||
```text
|
||
internal/xapps/apps/internal_exam/domain/
|
||
```
|
||
|
||
平台 `internal/model` 中只保留：
|
||
|
||
1. 平台公共对象
|
||
2. 跨 `xapp` 共享对象
|
||
3. 公共底座对象
|
||
|
||
### 8.5 持久化模型不能直接充当 API DTO
|
||
|
||
必须分层：
|
||
|
||
1. `domain`：领域对象
|
||
2. `repo entity`：持久化对象
|
||
3. `dto request/response`：接口契约
|
||
|
||
禁止继续使用如下模式：
|
||
|
||
1. `ShouldBindJSON(&model.ExamPaper{})`
|
||
2. API 直接返回 ORM entity
|
||
3. 统计逻辑直接依赖表字段细节
|
||
|
||
### 8.6 统计、画像、后台管理只能通过 provider 聚合
|
||
|
||
平台层不得直接查询某个 `xapp` 的私有表来构建：
|
||
|
||
1. 首页统计
|
||
2. 学员画像
|
||
3. 部门统计
|
||
4. 后台管理报表
|
||
|
||
应改为由 `xapp` 对外暴露 provider：
|
||
|
||
```go
|
||
type XAppStatsProvider interface {
|
||
BuildAdminStats(ctx context.Context) (any, error)
|
||
}
|
||
|
||
type XAppProfileProvider interface {
|
||
BuildUserProfile(ctx context.Context, userID uint) (any, error)
|
||
}
|
||
```
|
||
|
||
平台只聚合 provider 输出，不碰 `xapp` 内部表结构。
|
||
|
||
### 8.7 菜单、通知、任务、前端状态必须归 xapp 自己管理
|
||
|
||
不得把以下内容散落在平台全局文件中：
|
||
|
||
1. 导航项
|
||
2. 页面路由 path 判断
|
||
3. 通知跳转链接
|
||
4. 定时任务
|
||
5. seed 数据入口
|
||
6. localStorage key
|
||
7. 前端 layout 的特殊 case
|
||
|
||
这些都必须由 `xapp manifest` 暴露。
|
||
|
||
### 8.8 定义条目也属于 xapp 的 own boundary
|
||
|
||
`xapp` 的封装边界不仅包括代码、路由、表和缓存，也包括“定义层资源”。
|
||
|
||
定义层资源至少包括：
|
||
|
||
1. `xapp_definition` 中属于该 `xapp` 的定义记录
|
||
2. 对象目录、市场目录、对象中心中的条目
|
||
3. seed 自动生成的对象定义记录
|
||
4. 前端目录页、治理页中依赖定义中心生成的条目
|
||
|
||
如果一个 `xapp` 删除后，这些定义条目仍然残留，那么：
|
||
|
||
1. 用户仍可能看到僵尸入口
|
||
2. 后台仍可能显示无效定义
|
||
3. 平台仍可能尝试按已删除对象做跳转或查询
|
||
|
||
因此，定义条目必须被视为 `owned resource`，纳入 manifest 和卸载协议。
|
||
|
||
## 9. Manifest 与 Registry 设计
|
||
|
||
## 9.1 后端 manifest
|
||
|
||
```go
|
||
type XAppManifest interface {
|
||
Key() string
|
||
Meta() XAppMeta
|
||
RegisterRoutes(r gin.IRouter)
|
||
RegisterProviders(reg ProviderRegistry)
|
||
RegisterMigrations(reg MigrationRegistry)
|
||
RegisterSeeds(reg SeedRegistry)
|
||
RegisterJobs(reg JobRegistry)
|
||
RegisterNotifications(reg NotificationRegistry)
|
||
OwnedTables() []string
|
||
OwnedStorageKeys() []string
|
||
OwnedJobKeys() []string
|
||
OwnedNotificationKeys() []string
|
||
OwnedDefinitionKeys() []string
|
||
OwnedCatalogEntries() []string
|
||
SharedReferencePolicy() SharedReferencePolicy
|
||
}
|
||
```
|
||
|
||
后端 manifest 至少负责：
|
||
|
||
1. 路由注册
|
||
2. provider 注册
|
||
3. migration 注册
|
||
4. seed 注册
|
||
5. job 注册
|
||
6. 通知注册
|
||
7. 定义条目归属声明
|
||
8. 共享引用处理策略声明
|
||
|
||
### 9.2 前端 manifest
|
||
|
||
```js
|
||
export default {
|
||
key: 'internal-exam',
|
||
label: '内部考试APP',
|
||
baseRoute: '/xapps/internal-exam',
|
||
install({ navRegistry, routeRegistry, providerRegistry, storeRegistry }) {},
|
||
uninstallMeta: {
|
||
ownedStorageKeys: ['xapp:internal-exam:*'],
|
||
ownedRouteNames: ['InternalExam*'],
|
||
ownedNavKeys: ['xapp.internal-exam.*'],
|
||
ownedDefinitionKeys: ['xapp.internal-exam.definition'],
|
||
ownedCatalogEntries: ['catalog.xapp.internal-exam'],
|
||
},
|
||
}
|
||
```
|
||
|
||
前端 manifest 至少负责：
|
||
|
||
1. 页面路由注册
|
||
2. 菜单注册
|
||
3. store 注册
|
||
4. provider 注册
|
||
5. 前端状态资源声明
|
||
6. 前端定义条目资源声明
|
||
|
||
### 9.3 Registry 的职责
|
||
|
||
registry 只做两件事：
|
||
|
||
1. 收集 manifest
|
||
2. 统一安装 / 卸载 / 枚举
|
||
|
||
registry 不应承担：
|
||
|
||
1. 业务逻辑
|
||
2. repo 查询
|
||
3. 页面渲染
|
||
4. 领域对象转换
|
||
|
||
## 10. 卸载协议
|
||
|
||
“可删除”不是只删代码，还必须定义资源清理协议。
|
||
|
||
### 10.1 卸载输入
|
||
|
||
卸载协议至少应支持以下输入：
|
||
|
||
1. `xapp key`
|
||
2. `dry_run`
|
||
3. `drop_tables`
|
||
4. `clear_storage`
|
||
5. `clear_jobs`
|
||
6. `clear_notifications`
|
||
|
||
### 10.2 卸载输出
|
||
|
||
卸载结果至少应返回：
|
||
|
||
1. 实际清理的表
|
||
2. 实际清理的 job key
|
||
3. 实际清理的 notification key
|
||
4. 实际清理的 storage key
|
||
5. 未清理成功的残留项
|
||
6. 实际清理的定义条目
|
||
7. 被共享引用阻塞或降级处理的项
|
||
|
||
### 10.3 卸载原则
|
||
|
||
卸载必须遵守以下原则：
|
||
|
||
1. 只清理 manifest 声明过的 owned 资源
|
||
2. 默认支持 `dry_run`
|
||
3. 禁止越权删除共享资源
|
||
4. 共享表必须由 shared 域自己维护，不得被 xapp 卸载误删
|
||
|
||
### 10.4 定义条目清理协议
|
||
|
||
卸载 `xapp` 时，必须同时清理或冻结以下定义层资源：
|
||
|
||
1. `xapp_definition` 中的定义记录
|
||
2. 对象目录或市场目录中的条目
|
||
3. seed 自动生成的默认定义条目
|
||
|
||
允许的处理方式包括：
|
||
|
||
1. 直接删除
|
||
2. 标记为 tombstone
|
||
3. 标记为 disabled 且不再对用户可见
|
||
|
||
但无论采用哪种方式，都必须保证：
|
||
|
||
1. 平台不会再把它当成可安装、可进入、可查询的有效 `xapp`
|
||
2. 前后端目录与导航中不再出现死入口
|
||
|
||
### 10.5 Shared Reference Policy
|
||
|
||
`xapp` 删除时，除 own resource 外，还必须处理共享域对它的历史引用。
|
||
|
||
典型共享引用包括：
|
||
|
||
1. 历史任务记录
|
||
2. 项目绑定关系
|
||
3. 收藏 / 最近使用
|
||
4. 通知历史
|
||
5. 审计日志
|
||
6. 历史发布版本
|
||
|
||
规范允许以下四类处理策略：
|
||
|
||
1. `block_uninstall`：仍存在强引用时禁止卸载
|
||
2. `convert_to_tombstone`：转为“对象已移除”墓碑态
|
||
3. `detach_reference`：解除引用但保留历史记录
|
||
4. `readonly_history`：保留只读历史，不允许继续进入对象
|
||
|
||
`xapp manifest` 必须声明自己的共享引用处理策略，平台卸载器必须在 `dry_run` 结果中明确报告：
|
||
|
||
1. 哪些引用会被阻塞
|
||
2. 哪些引用会被降级
|
||
3. 哪些引用会被直接解除
|
||
|
||
### 10.6 Dry-run Gate 与执行守卫
|
||
|
||
卸载协议不仅要能执行，还必须能被平台守卫。
|
||
|
||
至少应具备以下守卫：
|
||
|
||
1. uninstall `dry_run` 报告
|
||
2. owned resource audit
|
||
3. 定义条目完整性检查
|
||
4. 共享引用阻塞检查
|
||
5. CI 中的封装边界检查
|
||
|
||
## 11. Owned 资源矩阵
|
||
|
||
一个 `xapp` 的 own boundary 至少应覆盖以下资源：
|
||
|
||
| 资源类型 | 是否必须声明 | 典型例子 |
|
||
|---|---|---|
|
||
| 后端目录 | 必须 | `backend-go/internal/xapps/apps/internal_exam/` |
|
||
| 前端目录 | 必须 | `frontend/src/xapps/apps/internal-exam/` |
|
||
| 后端路由 | 必须 | `/api/xapps/internal-exam/*` |
|
||
| 前端路由 | 必须 | `/xapps/internal-exam/*` |
|
||
| owned tables | 必须 | `xapp_exam_record` |
|
||
| owned storage keys | 必须 | `xapp:internal-exam:*` |
|
||
| definition keys | 必须 | `xapp.internal-exam.definition` |
|
||
| catalog entries | 必须 | `catalog.xapp.internal-exam` |
|
||
| provider keys | 必须 | `xapp.internal-exam.stats` |
|
||
| job keys | 视需要 | `xapp.internal-exam.daily-sync` |
|
||
| notification keys | 视需要 | `xapp.internal-exam.record-published` |
|
||
| nav keys | 必须 | `xapp.internal-exam.entry` |
|
||
|
||
## 12. 当前培训 / 考试域的拆分建议
|
||
|
||
## 12.1 应进入 `internal_exam` xapp 的内容
|
||
|
||
应归入：
|
||
|
||
1. 考试配置
|
||
2. 考试记录
|
||
3. 错题本
|
||
4. 发证逻辑
|
||
5. 学员考试流程
|
||
6. 考试统计 provider
|
||
7. 考试后台管理接口
|
||
8. 考试前端 views / api / store
|
||
|
||
当前对象对应：
|
||
|
||
1. `ExamPaper`
|
||
2. `ExamRecord`
|
||
3. `MistakeRecord`
|
||
|
||
## 12.2 应进入 `internal_training` xapp 的内容
|
||
|
||
应归入：
|
||
|
||
1. 课程
|
||
2. 产品知识
|
||
3. 公司介绍
|
||
4. 培训入口
|
||
5. 培训前端 views / api / store
|
||
6. 培训进度统计 provider
|
||
|
||
## 12.3 `LearningProgress` 的边界
|
||
|
||
`LearningProgress` 当前记录的是：
|
||
|
||
1. `company`
|
||
2. `product`
|
||
3. `course`
|
||
|
||
因此它不应进入 `internal_exam`。
|
||
|
||
它有两种合理归属：
|
||
|
||
1. 归入 `internal_training`
|
||
2. 归入 shared learning 域
|
||
|
||
选择标准如下：
|
||
|
||
1. 如果未来只有培训 `xapp` 使用，则归 `internal_training`
|
||
2. 如果未来知识库、认证、课程中心等多个 `xapp` 都会消费，则归 shared learning
|
||
|
||
## 13. 迁移顺序
|
||
|
||
推荐按以下顺序实施，避免边搬边炸：
|
||
|
||
1. 先建立 `xapps/core/contracts`
|
||
2. 建立 registry
|
||
3. 让 `exam / training` 先改为 manifest 注册
|
||
4. 将平台直查表的逻辑改为 provider 调用
|
||
5. 再搬迁 `domain / repo / service`
|
||
6. 再把 DTO 与持久化对象分层
|
||
7. 最后再改表名命名空间
|
||
8. 最后补卸载脚本
|
||
|
||
这个顺序的核心原因是：
|
||
|
||
1. 先修正依赖方向
|
||
2. 再修正代码落点
|
||
3. 再修正对象边界
|
||
4. 最后修正资源所有权
|
||
|
||
## 14. 判定红线
|
||
|
||
如果一个 `xapp` 还存在以下任意一条，则不算完成封装：
|
||
|
||
1. 总路由中仍手写它的业务路径
|
||
2. 总导航中仍手写它的业务菜单
|
||
3. 平台 `api/*.go` 仍直接查询它的私有表
|
||
4. 平台 `model` 总包仍承载它的核心业务对象
|
||
5. 别的模块还能直接 import 它的内部包
|
||
6. 数据表名未进入它 own 的命名空间
|
||
7. 统计、画像、后台管理未通过 provider 输出
|
||
8. 前端主 layout 仍有针对它的硬编码 path 判断
|
||
9. 卸载协议无法枚举它的 owned 资源
|
||
10. 删除目录后仍需手工搜索多处散装注册点
|
||
11. 一个公共定义文件里仍集中维护多个 `xapp` 的业务路由、菜单、provider、schema 或 path
|
||
12. `xapp_definition`、目录条目或 seed 定义记录未进入 own boundary
|
||
13. 历史任务、收藏、通知历史等共享引用没有明确降级策略
|
||
14. 缺少 `dry_run`、边界检查或资源审计守卫
|
||
|
||
### 14.1 迁移期兼容层的限制
|
||
|
||
本规范允许迁移期存在少量兼容层，但必须满足以下条件：
|
||
|
||
1. 兼容层只能做转发、注册、兼容映射
|
||
2. 兼容层不得继续承载多个 `xapp` 的业务定义
|
||
3. 兼容层必须有明确退场目标，不能成为长期正式结构
|
||
|
||
换句话说：
|
||
|
||
1. `registry` 可以中心化
|
||
2. `compat adapter` 可以暂存
|
||
3. `definition hub` 不允许长期存在
|
||
|
||
### 14.2 Enforcement / Guard
|
||
|
||
为了防止封装边界回退，平台至少应建立以下自动守卫：
|
||
|
||
1. import boundary lint：禁止平台层直接 import `xapp` 内部实现
|
||
2. registry completeness check：已注册对象必须能完整枚举 own 资源
|
||
3. owned resource audit：检查 manifest 声明和实际资源是否一致
|
||
4. uninstall dry-run gate：卸载前必须可生成风险报告
|
||
5. CI fail 条件：若出现未声明资源、未处理共享引用或越权依赖，则直接失败
|
||
|
||
## 15. 验收清单
|
||
|
||
一个 `xapp` 只有满足以下条件，才算达到“整包可删除”：
|
||
|
||
1. 删除 `backend-go/internal/xapps/apps/<xapp>/`
|
||
2. 删除 `frontend/src/xapps/apps/<xapp>/`
|
||
3. 删除 registry 里的注册项
|
||
4. 后端构建通过
|
||
5. 前端构建通过
|
||
6. 没有平台层 import 残留
|
||
7. 没有平台级 hardcoded path 残留
|
||
8. 运行卸载脚本后，该 `xapp` 的 owned tables 被清理
|
||
9. 前端导航、页面、缓存、localStorage 全部消失
|
||
10. 平台统计只少这一个 `xapp` 的 provider 结果，不出现空指针或编译错误
|
||
11. job / notification / provider key 不残留
|
||
12. 共享域不被误删
|
||
13. `xapp_definition`、目录条目、seed 定义条目不会残留死入口
|
||
14. `dry_run` 报告能正确列出 shared reference 的阻塞与降级结果
|
||
|
||
## 16. 最终标准
|
||
|
||
`xapp` 的最终定义应为：
|
||
|
||
1. 一个可注册的业务包
|
||
2. 一个有 manifest 的对象
|
||
3. 一个有自有 schema 的领域边界
|
||
4. 一个只通过 contract 暴露能力的模块
|
||
5. 一个可以通过“删目录 + 删注册 + 跑卸载”安全移除的工程单元
|
||
|
||
只有达到这个标准，`xapp` 才能成为真正的一级对象。
|