first commit

docs/UNI_API_REPLACEMENT_MATRIX.md

@@ -0,0 +1,136 @@
+# uni-app API 替换矩阵
+
+## 文档状态
+
+- 状态：阶段 0 盘点产物
+- 日期：2026-05-25
+- 来源：`rg` 扫描 `src`，排除 `src/uni_modules`
+- 目标：为 Vue3 Web 改造建立 uni 运行时替换账本
+
+## 扫描摘要
+
+高频 `uni.*` 使用统计：
+
+| API | 次数 | 主要风险 |
+| --- | ---: | --- |
+| `uni.showToast` | 74 | 用户反馈入口分散 |
+| `uni.navigateTo` | 26 | 路由跳转分散 |
+| `uni.$emit` | 26 | 跨组件事件耦合 |
+| `uni.hideLoading` | 19 | loading 状态分散 |
+| `uni.$on` | 13 | 事件监听生命周期需重建 |
+| `uni.createSelectorQuery` | 12 | DOM 测量方式不同 |
+| `uni.navigateBack` | 9 | 返回逻辑需路由服务承接 |
+| `uni.$off` | 9 | 事件清理需统一 |
+| `uni.connectSocket` | 8 | 聊天实时链路高风险 |
+| `uni.showModal` | 7 | Modal 交互需统一 |
+| `uni.showLoading` | 6 | loading 交互需统一 |
+| `uni.getSystemInfoSync` | 6 | 系统信息和安全区需 Web 替代 |
+| `uni.hideKeyboard` | 5 | 键盘行为 Web 不等价 |
+| `uni.request` | 4 | 请求层需替换 |
+| `uni.getLocation/openLocation` | 6 | 浏览器定位和地图打开需授权/降级 |
+| `uni.requestPayment` | 2 | 支付方案需重新确认 |
+| `uni.login` | 2 | 微信登录不能直接迁移 |
+| `uni.chooseImage` | 2 | 图片选择上传需 Web 化 |
+| `uni.saveImageToPhotosAlbum` | 2 | 浏览器保存相册不可等价 |
+
+微信原生 `wx.*` 使用：
+
+| API | 次数 | 文件 |
+| --- | ---: | --- |
+| `wx.getPrivacySetting` | 1 | `src/components/Privacy/index.vue` |
+| `wx.openPrivacyContract` | 1 | `src/components/Privacy/index.vue` |
+
+uni 页面生命周期使用集中在：
+
+- `src/App.vue`
+- `src/pages/index/index.vue`
+- `src/pages/login/index.vue`
+- `src/pages/goods/index.vue`
+- `src/pages/goods/album/index.vue`
+- `src/pages-booking/index.vue`
+- `src/pages-order/order/detail.vue`
+- `src/pages/ChatMain/ChatMainList/index.vue`
+- `src/pages/ChatMain/ChatLongAnswer/index.vue`
+- `src/pages/ChatMain/NoticeMessage/detail.vue`
+- `src/pages-bridge/UploadImage.vue`
+- `src/components/Privacy/index.vue`
+
+## 替换矩阵
+
+| 分类 | 当前 API/能力 | 代表文件 | Web 替代方案 | 目标封装 | 阶段 | 风险 |
+| --- | --- | --- | --- | --- | --- | --- |
+| 路由 | `uni.navigateTo`、`uni.navigateBack`、`uni.reLaunch` | `src/router/index.js`、`src/hooks/useGoLogin.js`、多页面 | Vue Router `push/back/replace` | `services/router` | 2 | 中 |
+| 请求 | `uni.request` | `src/request/base/request.js`、`src/request/api/AgentChatStream.js` | Axios 或 `fetch` | `services/http`、`services/stream` | 2/4 | 高 |
+| 上传 | `uni.uploadFile` | `src/request/api/UpdateFile.js` | `FormData` + `fetch/axios` | `services/http/upload` | 2/7 | 中 |
+| 下载 | `uni.downloadFile` | `src/pages/webview/bridge.js` | `fetch blob` + object URL | `services/browser/download` | 7 | 中 |
+| 存储 | `uni.setStorageSync`、`uni.getStorageSync`、`uni.removeStorageSync` | `src/constant/token.js` | `localStorage/sessionStorage` | `services/storage` | 2/3 | 低 |
+| 事件 | `uni.$emit`、`uni.$on`、`uni.$off` | 聊天、发现、登录、通知 | `mitt` typed event bus | `services/event-bus` | 2 | 中 |
+| 反馈 | `uni.showToast`、`uni.showModal`、`uni.showLoading`、`uni.hideLoading` | 多页面和组件 | 统一 Toast/Modal/Loading 组件 | `services/feedback` | 2 | 低 |
+| 生命周期 | `onLoad`、`onShow`、`onHide`、`onUnload`、`onReady` | 页面组件 | Vue `onMounted/onUnmounted` + Router hooks | 页面组合式函数 | 4-7 | 中 |
+| 应用启动 | `onLaunch`、`uni.onNetworkStatusChange`、`uni.getNetworkType` | `src/App.vue` | App bootstrap + `online/offline` 事件 | `app/bootstrap` | 2/3 | 中 |
+| 系统信息 | `uni.getSystemInfoSync`、`uni.getWindowInfo` | 导航栏、登录、卡片 | `window.innerWidth`、CSS env、ResizeObserver | `services/browser/viewport` | 2/8 | 中 |
+| DOM 测量 | `uni.createSelectorQuery` | Tabs、发现 tabs、长回答 | DOM API、`getBoundingClientRect`、ResizeObserver | 局部 composable | 5/6 | 中 |
+| 键盘 | `uni.onKeyboardHeightChange`、`uni.hideKeyboard` | `src/pages/ChatMain/ChatInputArea/index.vue` | VisualViewport API、blur、CSS 视口适配 | `features/chat/composables` | 4 | 高 |
+| WebSocket | `uni.connectSocket` | `src/utils/WebSocketManager.js` | 浏览器原生 `WebSocket` | `services/websocket` | 4 | 高 |
+| 流式响应 | `enableChunked`、`uni.arrayBufferToBase64` | `src/request/api/AgentChatStream.js` | `fetch + ReadableStream`、TextDecoder、SSE parser | `services/stream` | 4 | 高 |
+| 登录 | `uni.login` | `src/manager/LoginManager.js` | 微信 Web 授权、H5 登录或后端 token 方案 | `services/auth` | 3 | 高 |
+| 支付 | `uni.requestPayment` | `src/pages-booking/index.vue`、`FooterSection` | 微信 JS-SDK/H5 支付/后端支付跳转 | `features/payment` | 6 | 高 |
+| 图片选择 | `uni.chooseImage` | `CreateServiceOrder`、`webview/bridge.js` | `<input type="file">` | `services/browser/file-picker` | 7 | 中 |
+| 保存图片 | `uni.saveImageToPhotosAlbum` | `Qrcode`、`webview/bridge.js` | 下载链接、长按保存提示 | `services/browser/download` | 7 | 中 |
+| 图片预览 | `uni.previewImage` | 图片组件 | 弹窗预览组件 | `components/ImagePreview` | 5/6 | 低 |
+| Canvas | `uni.createCanvasContext`、`uni.canvasToTempFilePath`、`uni.upx2px` | `src/components/Qrcode` | 浏览器 Canvas、二维码库 | `components/Qrcode` | 6/7 | 中 |
+| 定位地图 | `uni.getLocation`、`uni.openLocation` | `LocationCard`、`LocationInfo`、`Discovery` | Geolocation API、地图 URL/SDK | `services/browser/location` | 5/6 | 中 |
+| 电话 | `uni.makePhoneCall` | `LocationCard`、订单卡片 | `tel:` 链接 | `services/browser/phone` | 6/7 | 低 |
+| 小程序隐私 | `wx.getPrivacySetting`、`wx.openPrivacyContract`、`uni.getPrivacySetting` | `src/components/Privacy/index.vue` | Web 隐私协议弹窗/链接 | `features/auth/privacy` | 3/7 | 中 |
+| 分享 | `uni.showShareMenu`、`utils/share.js` | `src/main.js`、`src/utils/share.js` | Web Share API 或自定义分享 | `services/browser/share` | 7 | 中 |
+| 更新 | `uni.getUpdateManager` | `src/utils/UpdateManager.js` | Web 无等价；PWA 时另做 | 待定 | 9 | 低 |
+
+## 模板标签替换摘要
+
+高频 uni/小程序标签：
+
+| 标签 | 次数 | Web 替代 |
+| --- | ---: | --- |
+| `<view>` | 997 | `div` 或布局组件 |
+| `<text>` | 292 | `span`、`p` |
+| `<image>` | 65 | `img` 或图片组件 |
+| `<button>` | 20 | `button` |
+| `<scroll-view>` | 18 | `div` + CSS overflow |
+| `<input>` | 9 | `input` |
+| `<uni-popup>` | 7 | Modal/Drawer 组件 |
+| `<swiper>`、`<swiper-item>` | 6 | 轮播组件或 CSS scroll snap |
+| `<textarea>` | 3 | `textarea` |
+| `<z-paging>` | 3 | 列表分页/虚拟列表组件 |
+| `<zero-markdown-view>` | 3 | Markdown 渲染库 |
+| `<canvas>` | 2 | 浏览器 `canvas` |
+
+替换策略：
+
+1. 迁移页面时同步替换标签，不做全仓机械替换。
+2. 高频基础标签可在早期建立轻量基础组件，但不要复刻 uni 组件完整语义。
+3. `scroll-view`、`swiper`、`canvas`、`web-view` 必须按业务场景单独验证。
+
+## 约束规则
+
+- 新 Web 代码不得直接调用 `uni.*` 或 `wx.*`。
+- 新业务页面不得直接散落 `fetch`、`localStorage`、`window.location` 等浏览器 API；必须通过服务封装进入。
+- 新路由跳转优先使用 route name 或 `routerService`，避免字符串拼接旧路径。
+- 事件名可以沿用 `src/constant/constant.js`，但事件 payload 应在 TypeScript 中补类型。
+- 小程序专属能力先保留旧项目，Web 端必须有明确替代、降级或暂不支持说明。
+
+## 第一批替换任务建议
+
+1. `services/storage` 替代 token storage。
+2. `services/event-bus` 替代登录、聊天、发现联动事件。
+3. `services/router` 替代跳转语义。
+4. `services/feedback` 替代 toast/loading/modal。
+5. `services/http` 替代普通 API 请求。
+6. `services/websocket` 和 `services/stream` 单独做聊天链路原型。
+
+## 验收清单
+
+- [ ] 新 Web 工程中没有新增 `uni.*` 或 `wx.*` 调用。
+- [ ] 所有平台能力都有唯一封装入口。
+- [ ] 聊天 WebSocket 和流式响应先做原型验证。
+- [ ] 支付、登录、隐私协议有目标平台方案确认。
+- [ ] 页面迁移时每个 `scroll-view`、`swiper`、`canvas` 都有对应验收项。