asai-vue-host 0.2.58 → 0.2.59

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +110 -184
  2. package/dist/components/index.d.ts +7 -0
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,184 +1,110 @@
1
- # asai-vue-host — 应用宿主框架（核心）
2
-
3
- ## 概述
4
-
5
- `asai-vue-host` 是 AsaiWeb CMS 的**核心应用宿主框架**，提供应用加载、模块管理、路由分发、WebSocket 通信和数据库响应的能力。它是整个前端架构的运行容器。
6
-
7
- ## 功能
8
-
9
- - 🚀 **应用启动**：管理完整应用加载流程
10
- - 📦 **模块管理**：动态加载和卸载功能模块
11
- - 🧭 **路由分发**：基于 Hash 路由的页面分发
12
- - 🔌 **WebSocket 通信**：WebSocket 连接管理与事件系统
13
- - 💾 **数据库响应**：IndexedDB / 本地数据响应式提供
14
- - 🎯 **功能注入**：通过 `provide` 提供全局数据和方法
15
- - ⏳ **加载状态管理**：多种加载动画组件
16
- - 🚨 **错误处理**：404 页面、加载错误页面
17
-
18
- ## 文件结构
19
-
20
- ```
21
- asai-vue-host/
22
- ├── src/
23
- │ └── components/
24
- │ ├── index.ts # 插件安装入口（install 方法）
25
- │ ├── asengine/
26
- │ │ └── provide/
27
- │ │ ├── providedb.ts # 数据库响应式数据 Provide
28
- │ │ ├── providedbwork.ts # 数据库工作线程 Provide
29
- │ │ ├── providefn.ts # 功能函数 Provide
30
- │ │ └── providews.ts # WebSocket 数据 Provide
31
- │ └── asui/
32
- │ ├── app/
33
- │ │ ├── AsaiWebItemIndex.vue # 应用入口页面
34
- │ │ ├── AsaiWebItemDefault.vue # 默认页面
35
- │ │ ├── AsaiWebModule.vue # 模块容器
36
- │ │ ├── AsaiWebModuleDefault.vue # 默认模块
37
- │ │ ├── AsaiWebModuleIndex.vue # 模块索引页
38
- │ │ ├── AsaiWebServer.vue # 服务器页面
39
- │ │ └── AsaiComponent.vue # 通用组件容器
40
- │ ├── common/
41
- │ │ ├── AsPageBusy.vue # 页面繁忙状态
42
- │ │ ├── AsPageBusyGif.vue # GIF 加载动画
43
- │ │ ├── AsReset.vue # 重置组件
44
- │ │ ├── MenuShowFix.vue # 菜单显示修复
45
- │ │ ├── RouterMap.vue # 路由映射组件
46
- │ │ ├── AsPageBusy/
47
- │ │ │ ├── AsLoadingA3d.vue # 3D 加载动画
48
- │ │ │ └── AsLoadingCircle.vue# 圆形加载动画
49
- │ │ └── _comps/
50
- │ │ └── Asai404.vue # 404 页面
51
- │ └── page/
52
- │ ├── PageErr.vue # 错误页面
53
- │ ├── PageLoadErr.vue # 加载错误
54
- │ ├── PageLoadServer.vue # 服务器加载
55
- │ ├── PageLoadUserToken.vue # 用户 Token 加载
56
- │ ├── PageLoadUserTokenOnline.vue # 在线 Token 加载
57
- │ └── PageLoadWs.vue # WebSocket 加载
58
- └── README.md
59
- ```
60
-
61
- ## 安装方式
62
-
63
- ```typescript
64
- import AsaiVueHost from 'asai-vue-host';
65
-
66
- app.use(AsaiVueHost, {
67
- loadts: (options) => { /* 加载 TypeScript 模块 */ },
68
- loadvue: (options) => { /* 加载 Vue 组件 */ },
69
- loadfn: (path) => { /* 加载函数 */ },
70
- });
71
- ```
72
-
73
- ## Provide 系统
74
-
75
- 插件通过 Vue 的 `provide/inject` 机制注入以下全局功能：
76
-
77
- | Provide Key | 说明 |
78
- |-------------|------|
79
- | `$engineasai` | 主引擎上下文 |
80
- | `providedb` | 数据库响应式数据 |
81
- | `providews` | WebSocket 数据 |
82
- | `providefn` | 功能函数 |
83
- | `providedbwork` | 数据库工作线程 |
84
-
85
- ## 核心组件
86
-
87
- ### 应用组件
88
-
89
- | 组件 | 说明 |
90
- |------|------|
91
- | `AsaiWebServer` | 服务器连接管理 |
92
- | `AsaiWebModule` | 模块容器，管理子页面 |
93
- | `AsaiWebModuleIndex` | 模块首页索引 |
94
- | `AsaiWebModuleDefault` | 默认模块视图 |
95
- | `AsaiWebItemIndex` | 应用主入口页面 |
96
- | `AsaiWebItemDefault` | 应用默认页面 |
97
- | `AsaiComponent` | 动态组件渲染容器 |
98
-
99
- ### 公共组件
100
-
101
- | 组件 | 说明 |
102
- |------|------|
103
- | `AsPageBusy` | 页面繁忙/加载中状态 |
104
- | `AsPageBusyGif` | GIF 格式加载动画 |
105
- | `AsLoadingA3d` | 3D 风格加载动画 |
106
- | `AsLoadingCircle` | 圆形旋转加载动画 |
107
- | `AsReset` | 数据重置组件 |
108
- | `MenuShowFix` | 菜单显示修正 |
109
- | `RouterMap` | Hash 路由映射 |
110
- | `Asai404` | 404 页面 |
111
-
112
- ### 页面组件
113
-
114
- | 组件 | 说明 |
115
- |------|------|
116
- | `PageErr` | 通用错误页面 |
117
- | `PageLoadErr` | 加载失败页面 |
118
- | `PageLoadServer` | 服务器加载页面 |
119
- | `PageLoadUserToken` | 用户认证 Token 加载 |
120
- | `PageLoadUserTokenOnline` | 在线用户 Token 加载 |
121
- | `PageLoadWs` | WebSocket 连接加载 |
122
-
123
- ## 技术细节
124
-
125
- - **插件安装模式**：通过 Vue 插件系统集成，使用 `install(app, opt)` 模式
126
- - **自动扫描加载**：使用 `import.meta.glob` 自动发现并注册组件
127
- - **模块化注入**：通过 `$engineasai` 注入点集中管理
128
- - **异步加载**：组件使用动态导入，按需加载减少首屏体积
129
- - **加载动画**：提供 CSS3 动画和 GIF 动画两种方案
130
-
131
- ## 代码优化分析
132
-
133
- ### 已做优化
134
- - ✅ 插件化架构：使用 Vue 插件 `install(app, opt)` 模式，可组合安装
135
- - ✅ 自动扫描加载：`import.meta.glob` 自动发现注册组件
136
- - ✅ 模块化注入：不同功能使用独立 key（`$engineasai`），避免命名冲突
137
- - ✅ Provide/Inject 模式：全局数据解耦，组件按需注入
138
- - ✅ 提供多种加载动画（CSS3 动画 + GIF），降级方案
139
-
140
- ### 可优化点
141
-
142
- #### 1. Provide 数据为简单 reactive 对象
143
- ```typescript
144
- // providedb.ts
145
- export default reactive({
146
- providedb: { data: {} }
147
- });
148
- // providews.ts
149
- export default reactive({
150
- providews: { data: { rooms: {}, wssys: {} } }
151
- });
152
- ```
153
- **问题**：三个 provide 都使用 `reactive` 包裹但在对象中嵌套对象。Vue3 的 `reactive` 是深度的，嵌套对象的属性变更也会触发更新。但数据变更后，如果 inject 方直接替换内部对象（如 `providedb.data = newData`），可能会丢失响应性。
154
-
155
- **建议**：使用 `readonly` 包装 inject 数据，或明确提供数据修改方法。
156
-
157
- #### 2. 组件扫描使用 eager: false（lazy 模式）
158
- ```typescript
159
- files: (import.meta as any).glob(['./asui/*/*.vue'])
160
- ```
161
- **问题**：lazy 模式（非 eager）意味着组件只在首次渲染时异步加载。对于核心宿主组件（如 `AsaiWebModule`、`AsaiWebItemIndex`），它们是首屏必需组件，懒加载可能导致白屏闪烁。
162
-
163
- **建议**：对核心组件使用 eager 加载，次要组件使用 lazy。
164
-
165
- #### 3. PageLoadUserToken 等页面组件未定义Props
166
- 一些页面加载组件（如 `PageLoadWs`、`PageLoadErr`）没有明确的 Props 定义。建议添加 Props 接口，至少支持错误信息、重试函数等。
167
-
168
- #### 4. 错误页面没有重试机制
169
- `PageErr` 和 `PageLoadErr` 只显示错误信息，没有"重试"按钮。建议添加 `retry` 属性和 `@retry` 事件。
170
-
171
- #### 5. "asany" 类型过多
172
- 整个插件的 TypeScript 大量使用 `any` 类型，失去类型检查的意义。建议：
173
- - 定义核心类型接口（如 `AsaiContext`、`ModuleConfig`、`AppRoute`）
174
- - 将 `$fn`、`$global`、`$model` 等全局对象的类型定义为接口
175
-
176
- #### 6. Index.ts 中的 `opt.loadts` 和 `opt.loadvue` 缺少类型定义
177
- `install(app, opt)` 的 `opt` 参数没有 TypeScript 接口，调用方不知需传入哪些方法。建议：
178
- ```typescript
179
- interface HostPluginOptions {
180
- loadts: (opts: { app: any; key: string; eager: boolean; files: Record<string, any> }) => void;
181
- loadvue: (opts: { loadfn: any; app: any; eager: boolean; files: Record<string, any> }) => void;
182
- loadfn: (path: string) => any;
183
- }
184
- ```
1
+ # asai-vue-host — 应用宿主框架（核心）
2
+
3
+ ## 包信息
4
+
5
+ | 建议 npm 名 | 入口文件 | $fn / 注入键 | 类型 |
6
+ |------------|---------|-------------|------|
7
+ | `@estun/asai-vue-host` | `src/components/index.ts` | `$engineasai`（provide/inject） | Host |
8
+
9
+ ## 概述
10
+
11
+ `asai-vue-host` 是 AsaiWeb CMS 的**核心应用宿主框架**，提供应用加载、模块管理、Hash 路由分发、WebSocket 通信和数据库响应式 Provide。是整个前端架构的运行容器。
12
+
13
+ ## 集成方式
14
+
15
+ ```typescript
16
+ // monorepo — webclient/src/utils/index.ts
17
+ import AsaiVueHost from '../plugs/asai-vue-host/src/components/index';
18
+ // import '/node_modules/asai-vue-host/dist/asai-vue-host.css';
19
+ // npm
20
+ // import AsaiVueHost from '@estun/asai-vue-host';
21
+
22
+ installModules.forEach((module) => module.install(app, lib));
23
+ ```
24
+
25
+ ## 独立性约束
26
+
27
+ - **禁止** cross-import 其它 `plugs/*`。
28
+ - 通过 `LibInit` 传入的 `loadts` / `loadvue` / `loadfn` 与宿主 app 耦合，不反向依赖 Feature 插件。
29
+
30
+ ## 主要 API / 导出
31
+
32
+ | 导出 | 说明 |
33
+ |------|------|
34
+ | `install(app, opt)` | Vue 插件安装入口 |
35
+ | Provide `$engineasai` | 主引擎 composable 与工具 |
36
+ | `providedb` / `providews` / `providefn` / `providedbwork` | 全局 Provide 键 |
37
+ | 全局组件 | `asui/*/*.vue` 懒加载注册（AsaiWebModule、PageLoad* 等） |
38
+
39
+ ## 性能说明
40
+
41
+ - TS 模块（`asengine`）**eager** 加载；Vue 组件 **lazy**（`eager: false`），首次渲染拉 chunk。
42
+ - 核心首屏组件若出现白屏闪烁，可在业务侧对关键组件单独 eager。
43
+
44
+ ## peerDependencies 建议
45
+
46
+ ```json
47
+ {
48
+ "peerDependencies": {
49
+ "vue": "^3.4.0",
50
+ "vue-router": "^4.0.0"
51
+ }
52
+ }
53
+ ```
54
+
55
+ ---
56
+
57
+ ## 功能
58
+
59
+ - 应用启动、模块管理、Hash 路由分发
60
+ - WebSocket 连接管理与事件系统
61
+ - IndexedDB / 本地数据响应式 Provide
62
+ - 加载状态与错误页面（404、PageLoadErr 等）
63
+
64
+ ## 文件结构
65
+
66
+ ```
67
+ asai-vue-host/
68
+ ├── src/components/
69
+ │ ├── index.ts # install 入口
70
+ │ ├── asengine/provide/ # providedb / providews / providefn
71
+ │ └── asui/ # app / common / page 组件
72
+ └── README.md
73
+ ```
74
+
75
+ ## 安装方式
76
+
77
+ ```typescript
78
+ app.use(AsaiVueHost, {
79
+ loadts: (options) => { /* 加载 TypeScript 模块 */ },
80
+ loadvue: (options) => { /* 加载 Vue 组件 */ },
81
+ loadfn: (path) => { /* 加载函数 */ },
82
+ });
83
+ ```
84
+
85
+ ## Provide 系统
86
+
87
+ | Provide Key | 说明 |
88
+ |-------------|------|
89
+ | `$engineasai` | 主引擎上下文 |
90
+ | `providedb` | 数据库响应式数据 |
91
+ | `providews` | WebSocket 数据 |
92
+ | `providefn` | 功能函数 |
93
+ | `providedbwork` | 数据库工作线程 |
94
+
95
+ ## 核心组件
96
+
97
+ | 组件 | 说明 |
98
+ |------|------|
99
+ | `AsaiWebServer` | 服务器连接管理 |
100
+ | `AsaiWebModule` | 模块容器 |
101
+ | `AsaiWebItemIndex` | 应用主入口 |
102
+ | `AsPageBusy` / `AsLoadingCircle` | 加载动画 |
103
+ | `PageLoadWs` / `PageLoadErr` | 连接/错误页 |
104
+ | `Asai404` | 404 页面 |
105
+
106
+ ## 技术细节
107
+
108
+ - Vue 插件 `install(app, opt)` 模式
109
+ - `import.meta.glob` 自动发现并注册组件
110
+ - 异步组件按需加载减少首屏体积
package/dist/components/index.d.ts CHANGED
@@ -1,3 +1,10 @@
1
+ /**
2
+ * asai-vue-host — 宿主核心框架插件
3
+ *
4
+ * 通过 LibInit 在 main.ts → utils/index.ts 中 app.use() 安装。
5
+ * - loadts: 注入 $engineasai（asengine 工具与 use*.ts）
6
+ * - loadvue: 懒加载 asui 子目录下的 .vue 全局组件
7
+ */
1
8
  declare const _default: {
2
9
  install(app: any, opt: any): void;
3
10
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "asai-vue-host",
3
- "version": "0.2.58",
3
+ "version": "0.2.59",
4
4
  "description": "asai for you",
5
5
  "author": "Asai",
6
6
  "license": "ISC",