chore: 初始化仓库基线（AGENTS.md、git 规范、敏感文件排除）

故障排查处理记录（微信小程序）.md

@@ -0,0 +1,110 @@
+# 故障排查处理记录（微信小程序）
+
+## 一、tabBar 图标格式错误
+
+**现象**：微信开发者工具调试器报错：
+```
+dist/app.json: ["tabBar"]["list"][0]["iconPath"] 文件格式错误，仅支持 .png、.jpg、.jpeg 格式
+```
+所有 5 组 tabBar 图标（共 10 个）均报此错误。
+
+**原因**：`app.config.ts` 中 tabBar 图标引用的是 `.svg` 文件，微信小程序 tabBar 图标仅支持 PNG/JPG/JPEG 格式，不支持 SVG。
+
+**处理**：
+1. 使用 `sharp` 库将 `src/assets/tabbar/` 下 10 个 SVG 文件转换为 81×81 像素的 PNG：
+   ```bash
+   npm install sharp --no-save --legacy-peer-deps
+   node convert-icons.js  # 遍历 tabbar 目录，sharp(svgBuffer).resize(81,81).png().toFile()
+   ```
+2. 修改 `src/app.config.ts`，将 5 组 tabBar 的 `iconPath` 和 `selectedIconPath` 从 `.svg` 改为 `.png`。
+3. 重新编译 `npm run build:weapp`。
+
+**涉及文件**：
+- `miniapp/src/assets/tabbar/*.png` -- 新生成的 PNG 图标（10 个）
+- `miniapp/src/app.config.ts` -- tabBar 图标路径改为 .png
+
+---
+
+## 二、WebSocket 连接崩溃：onOpen is not a function
+
+**现象**：微信开发者工具调试器报错：
+```
+[WS] 连接请求已发送
+TypeError: this.socket.onOpen is not a function
+    at n.value (app-service.js:7176)
+```
+WebSocket 连接后立即崩溃，页面白屏。
+
+**原因**：`ws.ts` 中使用 `Taro.connectSocket()` 返回值（SocketTask）的 `onOpen`/`onMessage`/`onClose`/`onError` 方法注册回调，但在 Taro 4.x 微信小程序环境中，`connectSocket()` 返回的对象不可靠，不一定包含这些方法。
+
+**处理**：改用 Taro 全局回调 API，不再依赖 SocketTask 实例方法：
+- `Taro.onSocketOpen(cb)` 替代 `socket.onOpen(cb)`
+- `Taro.onSocketMessage(cb)` 替代 `socket.onMessage(cb)`
+- `Taro.onSocketClose(cb)` 替代 `socket.onClose(cb)`
+- `Taro.onSocketError(cb)` 替代 `socket.onError(cb)`
+- `Taro.sendSocketMessage({ data })` 替代 `socket.send({ data })`
+- `Taro.closeSocket()` 替代 `socket.close({})`
+- 连接状态用 `this.connected` 布尔值跟踪，替代 `this.socket` 引用
+
+**涉及文件**：
+- `miniapp/src/utils/ws.ts` -- 整个 WebSocketManager 类重写为全局 API 方式
+
+---
+
+## 三、API 请求连接被拒绝：ERR_CONNECTION_REFUSED
+
+**现象**：微信开发者工具调试器报错：
+```
+[Request] GET /rooms 异常: {errMsg: "request:fail net::ERR_CONNECTION_REFUSED", errno: 7}
+[Request] GET /devices 异常: {errMsg: "request:fail net::ERR_CONNECTION_REFUSED", errno: 7}
+```
+所有 API 请求均失败。
+
+**原因**：`config.ts` 中默认 API 地址为 `http://localhost:3000/api/v1`，但后端服务运行在物理机 `100.83.103.1:3000`，Windows 本地没有服务在 3000 端口监听。
+
+**处理**：修改 `miniapp/src/api/config.ts`，将默认 API 地址和 WebSocket fallback 地址从 `localhost:3000` 改为 `100.83.103.1:3000`：
+```typescript
+const DEFAULT_API_BASE_URL = isH5 ? '/api/v1' : 'http://100.83.103.1:3000/api/v1';
+// ...
+return `ws://100.83.103.1:3000/ws?token=${token}`;
+```
+
+**涉及文件**：
+- `miniapp/src/api/config.ts` -- 默认地址改为 100.83.103.1:3000
+
+---
+
+## 四、WebSocket 域名校验失败：url not in domain list
+
+**现象**：微信开发者工具调试器报错：
+```
+[WS] 连接错误: {errMsg: "fail:url not in domain list"}
+[WS] 连接已关闭
+```
+HTTP 请求正常（返回 401），但 WebSocket 连接被拒绝。
+
+**原因**：微信开发者工具缓存了旧的域名校验状态，即使已在"详情 -> 本地设置"中勾选了"不校验合法域名"，WebSocket 连接仍被拦截。
+
+**处理**：微信开发者工具菜单 -> 清缓存 -> 全部清除 -> 关闭工具重新打开 -> 重新编译。
+
+**注意事项**：
+- 微信开发者工具版本：2.01.2510290 win32-x64
+- `project.config.json` 中已有 `"urlCheck": false`，但缓存导致未生效
+- 清缓存后域名校验恢复正常，WebSocket 连接成功
+
+---
+
+## 五、401 未授权：token 过期
+
+**现象**：微信开发者工具调试器报错：
+```
+[Request] 401 未授权，清除登录状态
+```
+小程序自动跳回登录页。
+
+**原因**：之前登录获取的 token 已过期，后端返回 401，`request.ts` 中的 401 拦截器清除 Storage 中的 token/refreshToken/user 并 `reLaunch` 到登录页。
+
+**处理**：重新登录（admin / silk@123）获取新 token 即可。
+
+**涉及文件**：
+- `miniapp/src/api/request.ts` -- 401 拦截逻辑（清除登录状态 + 跳转登录页）