zcw-shared 1.29.0 → 1.31.0

package/README.md

@@ -71,11 +71,16 @@ playground/            # 测试和验证环境
 #### 规则 1：不直接导入第三方库
 
 ```typescript
-// ❌ 错误：直接导入 Vue
+// ❌ 错误：直接导入 Vue 运行时函数
 import { ref, watch } from 'vue'
 
-// ✅ 正确：从 references 导入类型
+// ✅ 正确：只能使用 import type 导入 Vue 类型
+import type { Ref } from 'vue'
+
+// ❌ 错误：不能从 references 导入 Vue 类型
 import type { Ref } from '../../references/vue.d'
+
+// 注意：Vue 类型只能从 'vue' 包直接导入，因为 Vue 的类型系统过于复杂，难以在 references 中完整定义
 ```
 
 #### 规则 2：只传入实际使用的函数，不传入整个模块
@@ -121,7 +126,7 @@ export function myFunction(deps: MyFunctionDeps) {
 }
 ```
 
-#### 规则 4：类型定义在 references 中，使用 typeof 或索引访问提取
+#### 规则 4：类型定义在 references 中，使用 typeof 或索引访问提取（Vue 类型除外）
 
 ```typescript
 // ❌ 错误：在函数中定义类型
@@ -139,6 +144,24 @@ export interface MyFunctionDeps {
 }
 ```
 
+**Vue 类型特殊规则：**
+
+Vue 的类型系统过于复杂，难以在 `references/` 中完整定义，因此 Vue 类型只能从 `'vue'` 包直接导入：
+
+```typescript
+// ✅ 正确：Vue 类型只能从 'vue' 包直接导入
+import type { Ref, Component, VNode } from 'vue'
+
+export interface MyFunctionDeps {
+  ref: <T>(value: T) => Ref<T>
+  component: Component
+  node: VNode
+}
+
+// ❌ 错误：不能从 references 导入 Vue 类型
+import type { Ref } from '../../references/vue.d'  // Vue 没有 references 文件
+```
+
 #### 规则 5：每个函数维护自己完整的依赖，不要分散
 
 ```typescript
@@ -169,9 +192,13 @@ export function myFunction(path: string, deps: MyFunctionDeps) {
 
 不仅是 Node.js 和浏览器 API，第三方 SDK 对象（Vue、微信、UniApp 等）也要遵循同样的规则。
 
+**Vue 特殊说明：**
+- Vue 类型只能通过 `import type {} from 'vue'` 导入，不能从 `references/` 导入
+- Vue 运行时函数仍然需要通过依赖注入传入，不能直接导入
+
 ```typescript
 // ❌ 错误：传入整个 Vue 运行时
-import type { VueRuntime } from '../../references/vue.d'
+import type { VueRuntime } from 'vue'
 
 export interface DynamicMountOptions {
   vue: VueRuntime  // 包含很多未使用的方法
@@ -182,8 +209,8 @@ export function dynamicMount(options: DynamicMountOptions) {
   options.vue.render(...)
 }
 
-// ✅ 正确：只传入使用的函数
-import type { VueRuntime } from '../../references/vue.d'
+// ✅ 正确：只传入使用的函数，类型从 'vue' 导入
+import type { VueRuntime } from 'vue'
 
 export interface DynamicMountDeps {
   createVNode: VueRuntime['createVNode']
@@ -279,6 +306,11 @@ export async function buildProject(
 
 **references/** 目录定义环境API的抽象类型（接口、类型别名等），所有基础类型都应在此定义：
 
+**注意：Vue 类型例外**
+- Vue 的类型系统过于复杂，难以在 `references/` 中完整定义
+- Vue 类型只能从 `'vue'` 包直接导入，使用 `import type {} from 'vue'`
+- Vue 运行时函数仍然需要通过依赖注入传入，不能直接导入
+
 ```typescript
 // references/node.d.ts
 export interface FileSystem {
@@ -314,13 +346,6 @@ export interface Document {
   head: HTMLElement
 }
 
-// references/vue.d.ts
-export interface Ref<T = any> {
-  value: T
-}
-
-export type InjectionKey<T> = symbol
-
 // references/timer.d.ts
 export declare const setTimeout: (callback: (...args: any[]) => void, ms?: number, ...args: any[]) => any
 export declare const clearTimeout: (timeoutId: any) => void
@@ -372,9 +397,9 @@ const result = await buildProject(options, {
 
 // 浏览器 Vue 环境
 import { ref, shallowRef, watch } from 'vue'
-import { useAsyncState } from 'shared/hooks/useAsyncState'
+import { useAsyncState } from 'shared/vue-hooks/state/useAsyncState'
 
-// 传入 Vue 运行时函数和浏览器 API
+// 传入 Vue 运行时函数和浏览器 API（注意：运行时函数通过依赖注入传入，类型通过 import type 导入）
 const { state, isLoading } = useAsyncState(
   async () => fetch('/api/data').then(r => r.json()),
   { 
@@ -382,7 +407,7 @@ const { state, isLoading } = useAsyncState(
     delay: 1000
   },
   {
-    vue: { ref, shallowRef, watch },  // Vue Composition API 函数
+    vue: { ref, shallowRef, watch },  // Vue Composition API 运行时函数
     host: { setTimeout }               // 浏览器定时器
   }
 )
@@ -703,19 +728,15 @@ export function newFunction(
 **Vue Hooks 开发模板：**
 
 ```typescript
-// src/hooks/useNewHook.ts
-import type { Ref } from '../../references/vue.d'
+// src/vue-hooks/useNewHook.ts
+// ✅ Vue 类型只能从 'vue' 直接导入
+import type { Ref } from 'vue'
 import type { setTimeout } from '../../references/timer.d'
-
-export interface VueCompositionAPI {
-  ref: <T>(value: T) => Ref<T>
-  watch: (source: any, callback: () => void, options?: any) => void
-  onMounted: (fn: () => void) => void
-  onUnmounted: (fn: () => void) => void
-}
+import type { VueCompositionAPI } from '../../types/vue.d'
 
 export interface NewHookEnvironment {
-  vue: VueCompositionAPI
+  /** Vue Composition API 运行时函数（通过依赖注入传入） */
+  vue: Pick<Required<VueCompositionAPI>, 'ref' | 'watch' | 'onMounted' | 'onUnmounted'>
   host: {
     setTimeout: typeof setTimeout
     clearTimeout: typeof clearTimeout
@@ -750,13 +771,15 @@ export function useNewHook<T>(
 在提交代码前，请确保：
 
 #### ✅ 依赖注入检查
-- [ ] 没有直接 `import` 第三方库（如 `vue`、`react`）
+- [ ] 没有直接 `import` 第三方库的运行时函数（如 `import { ref } from 'vue'`）
+- [ ] Vue 类型只能使用 `import type {} from 'vue'` 导入，不能从 `references/` 导入
 - [ ] 没有直接使用全局对象（`window`、`document`、`global`、`process`）
 - [ ] 所有环境依赖都通过 `deps` 或 `env` 参数传入
 - [ ] 使用 `deps.` 前缀访问依赖，没有解构
 
 #### ✅ 类型定义检查
-- [ ] 类型从 `references/` 导入，使用 `import type`
+- [ ] 类型从 `references/` 导入，使用 `import type`（Vue 类型除外）
+- [ ] Vue 类型只能从 `'vue'` 包直接导入，使用 `import type {} from 'vue'`
 - [ ] 依赖接口命名为 `{FunctionName}Deps` 或 `{HookName}Environment`
 - [ ] 使用 `Interface['method']` 或 `typeof` 提取类型
 - [ ] 每个依赖都有清晰的 JSDoc 注释
@@ -816,10 +839,11 @@ npm run publish:major  # 主要版本
 
 ### 依赖管理
 
-1. **不导入第三方库**：不直接 `import { ref } from 'vue'`，而是通过 `env` 对象传入
-2. **不依赖全局对象**：不直接使用 `window`、`document`、`global`
-3. **接口命名规范**：`{FunctionName}Deps`，例如 `BuildProjectDeps`、`ModifyManifestDeps`
-4. **使用 deps. 前缀**：所有依赖访问都使用 `deps.methodName()`，不解构
+1. **不导入第三方库运行时函数**：不直接 `import { ref } from 'vue'`，而是通过 `env` 对象传入
+2. **Vue 类型特殊规则**：Vue 类型只能使用 `import type {} from 'vue'` 导入，不能从 `references/` 导入
+3. **不依赖全局对象**：不直接使用 `window`、`document`、`global`
+4. **接口命名规范**：`{FunctionName}Deps`，例如 `BuildProjectDeps`、`ModifyManifestDeps`
+5. **使用 deps. 前缀**：所有依赖访问都使用 `deps.methodName()`，不解构
 
 ### 测试要求
 
@@ -833,12 +857,13 @@ npm run publish:major  # 主要版本
 在编写新函数或修改现有函数时，快速检查以下要点：
 
 **✅ 6大核心规则：**
-1. ❌ 不直接导入第三方库 → ✅ 从 `references/` 导入类型
-2. ❌ 不传入整个模块对象 → ✅ 只传入实际使用的函数
-3. ❌ 不解构 deps 对象 → ✅ 使用 `deps.` 前缀访问
-4. ❌ 不重复定义类型 → ✅ 使用 `Interface['method']` 提取
-5. ❌ 不分散依赖到多个参数 → ✅ 统一的 `Deps` 接口
-6. ❌ 第三方 SDK 也不能整个传入 → ✅ Vue、Wx 等也要拆分
+1. ❌ 不直接导入第三方库运行时函数 → ✅ 从 `references/` 导入类型（Vue 类型除外）
+2. ❌ Vue 类型不能从 `references/` 导入 → ✅ 只能使用 `import type {} from 'vue'`
+3. ❌ 不传入整个模块对象 → ✅ 只传入实际使用的函数
+4. ❌ 不解构 deps 对象 → ✅ 使用 `deps.` 前缀访问
+5. ❌ 不重复定义类型 → ✅ 使用 `Interface['method']` 提取
+6. ❌ 不分散依赖到多个参数 → ✅ 统一的 `Deps` 接口
+7. ❌ 第三方 SDK 也不能整个传入 → ✅ Vue、Wx 等也要拆分
 
 **✅ 命名规范：**
 - 函数依赖接口：`{FunctionName}Deps`
@@ -853,23 +878,28 @@ npm run publish:major  # 主要版本
 
 ### 常见错误和解决方案
 
-#### ❌ 错误 1：直接导入第三方库
+#### ❌ 错误 1：直接导入第三方库运行时函数
 ```typescript
-import { ref, watch } from 'vue'  // ❌ 错误
+import { ref, watch } from 'vue'  // ❌ 错误：导入了运行时函数
 ```
 **解决方案：**
 ```typescript
-import type { Ref } from '../../references/vue.d'  // ✅ 正确
+// ✅ 正确：Vue 类型只能从 'vue' 直接导入
+import type { Ref } from 'vue'
+import type { VueCompositionAPI } from '../../types/vue.d'
 
-export interface VueCompositionAPI {
-  ref: <T>(value: T) => Ref<T>
-  watch: (source: any, callback: () => void) => void
+export interface UseMyHookEnvironment {
+  vue: Pick<Required<VueCompositionAPI>, 'ref' | 'watch'>
 }
 
-export function useMyHook(env: { vue: VueCompositionAPI }) {
-  const state = env.vue.ref(0)
+export function useMyHook(env: UseMyHookEnvironment) {
+  const state = env.vue.ref(0)  // 运行时函数通过依赖注入传入
   env.vue.watch(state, () => {})
 }
+
+// 使用时：
+// import { ref, watch } from 'vue'
+// const result = useMyHook({ vue: { ref, watch } })
 ```
 
 #### ❌ 错误 2：传入整个模块对象
@@ -942,7 +972,8 @@ export function myFunction(deps: MyFunctionDeps) {
 
 #### ❌ 错误 6：传入整个第三方 SDK 对象
 ```typescript
-import type { VueRuntime } from '../../references/vue.d'
+// ❌ 错误：Vue 类型可以从 'vue' 导入，但不能传入整个运行时对象
+import type { VueRuntime } from 'vue'
 import type { Wx } from '../../references/wechat.d'
 
 export interface MyFunctionDeps {
@@ -957,11 +988,12 @@ export function myFunction(deps: MyFunctionDeps) {
 ```
 **解决方案：**
 ```typescript
-import type { VueRuntime } from '../../references/vue.d'
+// ✅ 正确：Vue 类型从 'vue' 导入，运行时函数通过依赖注入传入
+import type { VueRuntime } from 'vue'
 import type { Wx } from '../../references/wechat.d'
 
 export interface MyFunctionDeps {
-  createVNode: VueRuntime['createVNode']        // ✅ 正确
+  createVNode: VueRuntime['createVNode']        // ✅ 正确：只传入使用的函数
   downloadFile: Wx['downloadFile']              // ✅ 正确
   USER_DATA_PATH: Wx['env']['USER_DATA_PATH']  // ✅ 嵌套属性也要精确提取
 }
@@ -974,12 +1006,12 @@ export function myFunction(deps: MyFunctionDeps) {
 ```
 
 **常见第三方 SDK 对象拆分：**
-- `VueRuntime` → 只传入 `createVNode`, `render` 等实际使用的方法
-- `Wx` (微信) → 只传入 `downloadFile`, `request` 等实际使用的方法
-- `UniApp` → 只传入 `getCurrentPages` 等实际使用的方法
-- `CryptoJS` → 只传入 `MD5`, `SHA256` 等实际使用的方法
-- `CloudBaseManager` → 只传入 `init` 等实际使用的方法
-- `Sharp` (图像处理) → 已经是函数，直接作为依赖
+- `VueRuntime` → 只传入 `createVNode`, `render` 等实际使用的方法（类型用 `import type {} from 'vue'` 导入）
+- `Wx` (微信) → 只传入 `downloadFile`, `request` 等实际使用的方法（类型从 `references/wechat.d` 导入）
+- `UniApp` → 只传入 `getCurrentPages` 等实际使用的方法（类型从 `references/uniapp.d` 导入）
+- `CryptoJS` → 只传入 `MD5`, `SHA256` 等实际使用的方法（类型从 `references/crypto-js.d` 导入）
+- `CloudBaseManager` → 只传入 `init` 等实际使用的方法（类型从 `references/tencent-cloud.d` 导入）
+- `Sharp` (图像处理) → 已经是函数，直接作为依赖（类型从 `references/sharp.d` 导入）
 
 ### 文档规范
 

package/dist/functions/platform/tencent-cloud/deploy.tcb.d.ts

@@ -0,0 +1,13 @@
+import type { DeployOptions, DeployResult, SecretType } from '../../../../types/tencent-cloud.d';
+import type { TencentCloudSecret, CloudBaseManager } from '../../../../references/tencent-cloud.d';
+import type { FileSystem } from '../../../../references/node.d';
+import type { Console } from '../../../../references/console.d';
+export interface DeployTCBDeps {
+    existsSync: FileSystem['existsSync'];
+    init: CloudBaseManager['init'];
+    log: Console['log'];
+    error: Console['error'];
+    getSecret: (type: SecretType) => TencentCloudSecret | null;
+}
+export declare function deployToTCB(options: DeployOptions, deps: DeployTCBDeps): Promise<DeployResult>;
+export default deployToTCB;

package/dist/functions/platform/tencent-cloud/deploy.tcb.js

@@ -0,0 +1,46 @@
+export async function deployToTCB(options, deps) {
+    const { localPath, cloudPath = '/', envId, secretType, showProgress = true } = options;
+    try {
+        if (!deps.existsSync(localPath)) {
+            return {
+                success: false,
+                error: `本地路径不存在: ${localPath}`
+            };
+        }
+        const secret = deps.getSecret(secretType);
+        if (!secret || !secret.secretId || !secret.secretKey) {
+            return {
+                success: false,
+                error: `无效的密钥类型: ${secretType}`
+            };
+        }
+        const app = deps.init({
+            secretId: secret.secretId,
+            secretKey: secret.secretKey,
+            envId
+        });
+        const hosting = app.hosting;
+        await hosting.uploadFiles({
+            localPath,
+            cloudPath,
+            onProgress: showProgress ? (progressData) => {
+                deps.log(`上传进度: ${progressData.percent}%`);
+            } : undefined
+        });
+        deps.log('文件上传成功');
+        return {
+            success: true,
+            message: '部署成功'
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        deps.error('部署失败:', error);
+        return {
+            success: false,
+            error: `部署失败: ${errorMessage}`
+        };
+    }
+}
+export default deployToTCB;
+//# sourceMappingURL=deploy.tcb.js.map

package/dist/functions/platform/tencent-cloud/deploy.tcb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy.tcb.js","sourceRoot":"","sources":["../../../../src/functions/platform/tencent-cloud/deploy.tcb.ts"],"names":[],"mappings":"AAuDA,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,OAAsB,EACtB,IAAmB;IAEnB,MAAM,EACJ,SAAS,EACT,SAAS,GAAG,GAAG,EACf,KAAK,EACL,UAAU,EACV,YAAY,GAAG,IAAI,EACpB,GAAG,OAAO,CAAA;IAEX,IAAI,CAAC;QAEH,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;YAChC,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,YAAY,SAAS,EAAE;aAC/B,CAAA;QACH,CAAC;QAGD,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAA;QACzC,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC;YACrD,OAAO;gBACL,OAAO,EAAE,KAAK;gBACd,KAAK,EAAE,YAAY,UAAU,EAAE;aAChC,CAAA;QACH,CAAC;QAGD,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC;YACpB,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,KAAK;SACN,CAAC,CAAA;QAGF,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAA;QAG3B,MAAM,OAAO,CAAC,WAAW,CAAC;YACxB,SAAS;YACT,SAAS;YACT,UAAU,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC,YAAgC,EAAE,EAAE;gBAC7D,IAAI,CAAC,GAAG,CAAC,SAAS,YAAY,CAAC,OAAO,GAAG,CAAC,CAAA;YAC5C,CAAC,CAAC,CAAC,CAAC,SAAS;SACf,CAAC,CAAA;QAGF,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;QAClB,OAAO;YACL,OAAO,EAAE,IAAI;YACb,OAAO,EAAE,MAAM;SAChB,CAAA;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QAC3E,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;QAC1B,OAAO;YACL,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,SAAS,YAAY,EAAE;SAC/B,CAAA;IACH,CAAC;AACH,CAAC;AAQD,eAAe,WAAW,CAAA"}

package/dist/functions/platform/tencent-cloud/getSecret.d.ts

@@ -0,0 +1,4 @@
+import type { TencentCloudSecret } from '../../../../references/tencent-cloud.d';
+import type { SecretType } from '../../../../types/tencent-cloud.d';
+export declare function getSecret(type: SecretType): TencentCloudSecret;
+export default getSecret;

package/dist/functions/platform/tencent-cloud/getSecret.js

@@ -0,0 +1,19 @@
+const secretMap = {
+    personal: {
+        secretId: 'AKIDKVQ5VjiQu73j9IBnFRN2QYQ2MQEl22mI',
+        secretKey: 'IL7cqoWy94lDsGSXP9gxzkGXcSFrDJ8h',
+    },
+    individual: {
+        secretId: 'AKID2A6oIZcT5TcWBetteARULxKSM1ResARl',
+        secretKey: 'INFtISN3VmocDZgYBZicIitpWyEG4f2B',
+    },
+    enterprise: {
+        secretId: 'AKIDRhqpgKn46uVvACzd7ORGTbaLtHSSEn8H',
+        secretKey: '95tV4Ql02wpY5QaaOzTlrjOr8OQFsHUW',
+    },
+};
+export function getSecret(type) {
+    return secretMap[type];
+}
+export default getSecret;
+//# sourceMappingURL=getSecret.js.map

package/dist/functions/platform/tencent-cloud/getSecret.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getSecret.js","sourceRoot":"","sources":["../../../../src/functions/platform/tencent-cloud/getSecret.ts"],"names":[],"mappings":"AAIA,MAAM,SAAS,GAA2C;IACxD,QAAQ,EAAE;QAER,QAAQ,EAAE,sCAAsC;QAChD,SAAS,EAAE,kCAAkC;KAC9C;IACD,UAAU,EAAE;QAEV,QAAQ,EAAE,sCAAsC;QAChD,SAAS,EAAE,kCAAkC;KAC9C;IACD,UAAU,EAAE;QAEV,QAAQ,EAAE,sCAAsC;QAChD,SAAS,EAAE,kCAAkC;KAC9C;CACF,CAAA;AAoCD,MAAM,UAAU,SAAS,CAAC,IAAgB;IACxC,OAAO,SAAS,CAAC,IAAI,CAAC,CAAA;AACxB,CAAC;AAKD,eAAe,SAAS,CAAA"}

package/dist/functions/platform/uniapp/app-plus/buildAndroidApp.d.ts

@@ -0,0 +1,27 @@
+import type { UniAppAndroidBuildOptions, UniAppAndroidBuildResult } from '../../../../../types/uniapp-android-build.d';
+import type { FileSystem, Path, ChildProcess } from '../../../../../references/node.d';
+import type { XMLParserConstructor, XMLSerializerConstructor } from '../../../../../references/xml.d';
+import type { JSON5Parser } from '../../../../../references/json5.d';
+import type { XPath } from '../../../../../references/xpath.d';
+import type { setTimeout } from '../../../../../references/timer.d';
+export interface BuildAndroidAppDeps {
+    existsSync: FileSystem['existsSync'];
+    readFileSync: FileSystem['readFileSync'];
+    writeFileSync: FileSystem['writeFileSync'];
+    copyFileSync: FileSystem['copyFileSync'];
+    mkdirSync: FileSystem['mkdirSync'];
+    readdirSync: FileSystem['readdirSync'];
+    statSync: FileSystem['statSync'];
+    cp: FileSystem['promises']['cp'];
+    join: Path['join'];
+    dirname: Path['dirname'];
+    basename: Path['basename'];
+    exec: ChildProcess['exec'];
+    platform: string;
+    parse: JSON5Parser['parse'];
+    xmlParser: XMLParserConstructor;
+    xmlSerializer: XMLSerializerConstructor;
+    xpath: XPath;
+    setTimeout: typeof setTimeout;
+}
+export declare function buildAndroidApp(options: UniAppAndroidBuildOptions, deps: BuildAndroidAppDeps): Promise<UniAppAndroidBuildResult>;