@chenhui996/gg-cli 1.0.3 → 1.0.4

package/dist/template/operations-tem/.editorconfig

@@ -0,0 +1,16 @@
+# EditorConfig is awesome: https://EditorConfig.org
+
+# top-most EditorConfig file
+root = true
+
+# Unix-style newlines with a newline ending every file
+[*]
+end_of_line = lf
+insert_final_newline = true
+charset = utf-8
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false

package/dist/template/operations-tem/.env.development

@@ -0,0 +1,4 @@
+# 开发环境配置
+VITE_ENV=development
+VITE_API_BASE_URL=/api
+VITE_APP_TITLE=Operations Template (Dev)

package/dist/template/operations-tem/.env.production

@@ -0,0 +1,4 @@
+# 生产环境配置
+VITE_ENV=production
+VITE_API_BASE_URL=https://api.example.com
+VITE_APP_TITLE=Operations Template

package/dist/template/operations-tem/.env.test

@@ -0,0 +1,4 @@
+# 测试环境配置
+VITE_ENV=test
+VITE_API_BASE_URL=https://test-api.example.com
+VITE_APP_TITLE=Operations Template (Test)

package/dist/template/operations-tem/.prettierignore

@@ -0,0 +1,34 @@
+# 忽略格式化的目录和文件
+node_modules
+dist
+build
+coverage
+
+# 忽略特定类型的文件
+*.png
+*.jpg
+*.jpeg
+*.gif
+*.svg
+*.ico
+*.eot
+*.ttf
+*.woff
+*.woff2
+*.mp4
+*.webm
+*.ogg
+*.mp3
+*.wav
+*.flac
+*.aac
+
+# 忽略锁定文件
+package-lock.json
+yarn.lock
+pnpm-lock.yaml
+
+# 其他忽略
+.DS_Store
+.idea
+.vscode

package/dist/template/operations-tem/.prettierrc

@@ -0,0 +1,14 @@
+{
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": true,
+  "quoteProps": "as-needed",
+  "jsxSingleQuote": false,
+  "trailingComma": "all",
+  "bracketSpacing": true,
+  "bracketSameLine": false,
+  "arrowParens": "always",
+  "endOfLine": "lf"
+}

package/dist/template/operations-tem/README.md

@@ -3,15 +3,16 @@
 基于 React 19 + TypeScript + Vite 8 + Ant Design 6 的现代化后台管理系统模版。
 本模版专为快速构建企业级中后台应用而设计，集成了最佳实践的工程化配置、清晰的架构分层和美观的 UI 设计。
 
-## ✨ 特性
+## ✨ 特性与架构
 
 - **最新技术栈**: 采用 React 19、Vite 8、TypeScript 5 等前沿技术。
-- **UI 设计**: 集成 Ant Design 6，配合 Less 预处理器，深度还原 Figma 设计稿风格。
-- **函数式编程**: 全面采用 React Hooks 和函数式组件，代码简洁、易维护。
-- **状态管理**: 使用 Zustand 5 进行轻量级全局状态管理。
-- **路由管理**: 基于 React Router 7.x 的 Data API 路由模式。
+- **UI 设计**: 集成 Ant Design 6，配合 Less 预处理器，深度还原企业级设计规范。
+- **状态管理**: 使用 Zustand 5 进行轻量级全局状态管理，告别繁琐的 Redux 样板代码。
+- **路由管理**: 基于 React Router 7.x 的 Data API 路由模式，支持更细粒度的路由控制。
 - **网络请求**: 封装 Axios 1.x，统一处理拦截器、错误码和 TypeScript 类型定义。
-- **工程化**: 配置 ESLint 9、Prettier 规范代码风格。
+- **工程化与规范**: 配置 ESLint 9 (逻辑检查) 与 Prettier (代码格式化)，并集成 EditorConfig 统一跨编辑器基础风格。
+- **多环境支持**: 完善的 `.env` 环境隔离机制，清晰区分开发 (dev)、测试 (test) 和生产 (prod) 环境。
+- **生产构建优化**: 内置产物分类、第三方依赖 (Vendor) 手动分包策略、自动剔除 Console 等生产级优化。
 
 ## 📦 目录结构
 
@@ -63,13 +64,58 @@ npm run dev
 
 浏览器访问 `http://localhost:5173` 即可看到效果。
 
-### 4. 构建生产环境
+### 3. 构建生产环境
 
 ```bash
+# 构建测试环境
+npm run build:test
+
+# 构建生产环境
+npm run build:prod
+# 或
 npm run build
 ```
 
-## 🛠 开发指南
+## 🛠 开发与构建指南
+
+### 1. 环境变量配置
+
+项目根目录包含三个环境配置文件，利用 Vite 的 `import.meta.env` 进行读取，且内置了完整的 TypeScript 类型提示：
+- `.env.development`：本地开发环境 (运行 `npm run dev` 时加载)
+- `.env.test`：测试环境 (运行 `npm run build:test` 时加载)
+- `.env.production`：生产环境 (运行 `npm run build:prod` 时加载)
+
+> 💡 **注意**：在代码中可以通过 `import.meta.env.VITE_XXX` 访问环境变量。为了安全，所有暴露给前端的自定义环境变量必须以 `VITE_` 开头。
+
+### 2. 代码检查与格式化
+
+```bash
+# 运行 ESLint 逻辑检查
+npm run lint
+
+# 运行 Prettier 格式化代码 (将会自动格式化 src 目录下的文件)
+npm run format
+```
+
+### 3. 生产环境构建与优化
+
+本项目针对生产环境 (`build:prod`) 做了深度优化，确保上线的资源体积最小、加载最快：
+- **静态资源 Hash 分类**：JS、CSS、图片等资源分别打包到不同的文件夹，并打上 Hash 戳，完美配合服务器的强缓存策略。
+- **手动分包 (Manual Chunks)**：将体积巨大且变动极少的第三方依赖（如 `react` 核心库、`antd` 组件库、`echarts` 图表库）单独拆分。这样即便你修改了业务代码，用户依然能命中第三方库的浏览器缓存。
+- **代码净化**：自动剔除代码中的 `console` 和 `debugger` 语句，提升性能并保护代码安全。
+
+### 4. 构建产物分析 (打包体积分析)
+
+如果你想了解每个包（Chunk）的体积大小，排查是否引入了臃肿的依赖，可以运行分析脚本：
+
+```bash
+npm run analyze
+```
+该命令会自动执行生产环境构建，并在打包结束后，于浏览器中弹出一个 **交互式的可视化树状图** (`dist/stats.html`)，让你对所有产物的原始大小和 Gzip 压缩大小一目了然。
+
+---
+
+## 💻 业务开发指南
 
 ### 1. 新增页面
 
@@ -134,13 +180,4 @@ const { name, setName } = useUserStore();
 - **布局**: 左侧固定侧边栏 (`240px`) + 顶部通栏
 - **图标**: 使用 `@ant-design/icons`
 
-## 🤝 贡献指南
-
-1. Fork 本仓库
-2. 新建 feature 分支
-3. 提交代码并 Push
-4. 发起 Pull Request
-
 ---
-
-© 2024 Operations Template. All Rights Reserved.

package/dist/template/operations-tem/docs/Git/345/274/200/345/217/221/350/247/204/350/214/203.md

@@ -0,0 +1,105 @@
+# Git 开发规范
+
+为了保证团队协作的高效性、代码历史的可追溯性以及发布流程的稳定性，特制定本 Git 开发规范。团队成员需严格遵守本规范进行代码的分支管理和提交。
+
+## 1. 分支管理模型
+
+我们采用基于 Git Flow 思想的轻量级分支管理模型。
+
+### 1.1 长期分支
+- **`main` (或 `master`)**: 主分支。
+  - 只能包含稳定、已发布或即将发布到生产环境的代码。
+  - **严禁直接在 `main` 分支上进行开发提交**。
+  - 所有合并到 `main` 的代码必须经过 Code Review 和充分测试。
+- **`develop`**: 开发主分支。
+  - 包含下一个版本将要发布的所有最新代码。
+  - 从 `main` 分支拉取，功能分支合并回此分支。
+  - 部署到**开发/测试环境**的基础分支。
+
+### 1.2 临时分支
+临时分支用完即删，保持分支列表整洁。
+
+- **`feature/*` (功能分支)**:
+  - 命名规范：`feature/功能名称` 或 `feature/需求ID-功能名称` (如：`feature/login-page`, `feature/JIRA-123-user-profile`)。
+  - 从 `develop` 分支拉取。
+  - 开发完成后合并回 `develop` 分支。
+- **`bugfix/*` (缺陷修复分支)**:
+  - 命名规范：`bugfix/问题描述` 或 `bugfix/缺陷ID-问题描述` (如：`bugfix/login-crash`, `bugfix/JIRA-456-table-render-error`)。
+  - 用于修复日常测试中发现的非紧急 Bug。
+  - 从 `develop` 分支拉取，修复后合并回 `develop`。
+- **`hotfix/*` (线上紧急修复分支)**:
+  - 命名规范：`hotfix/问题描述` 或 `hotfix/缺陷ID` (如：`hotfix/payment-failure`)。
+  - **仅用于修复生产环境的严重 Bug**。
+  - 必须从 `main` 分支拉取！
+  - 修复测试通过后，**必须同时合并回 `main` 和 `develop` 分支**，并在 `main` 上打上新版本 Tag。
+
+## 2. Commit 提交规范
+
+我们遵循 [Angular Commit 规范](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines)，使用标准化的格式来记录每一次提交，以便自动生成 Changelog 并快速定位问题。
+
+### 2.1 Commit Message 格式
+```text
+<type>(<scope>): <subject>
+// 空一行
+<body>
+// 空一行
+<footer>
+```
+
+### 2.2 Type (必填)
+说明本次提交的类型，只允许使用以下标识：
+- `feat`: 新增功能 (Feature)
+- `fix`: 修复 Bug
+- `docs`: 仅修改文档 (Documentation)
+- `style`: 仅仅修改了空格、格式缩进、逗号等等，不改变代码逻辑 (不涉及逻辑的格式修改)
+- `refactor`: 代码重构，没有加新功能或者修复 bug
+- `perf`: 优化相关，比如提升性能、体验
+- `test`: 增加测试，包括单元测试、集成测试等
+- `build`: 影响构建系统或外部依赖的更改（如：webpack, npm）
+- `ci`: 对 CI 配置文件和脚本的更改
+- `chore`: 构建过程或辅助工具的变动
+- `revert`: 回滚到上一个版本
+
+### 2.3 Scope (选填)
+用于说明本次 Commit 影响的范围，比如数据层、控制层、视图层等等，视项目不同而不同。例如在前端项目中，可以是具体的页面或组件名：`auth`, `table-component`, `router` 等。
+
+### 2.4 Subject (必填)
+本次提交的简短描述，不超过 50 个字符。
+- 以动词开头，使用第一人称现在时，比如 `change`，而不是 `changed` 或 `changes`。
+- 首字母小写。
+- 结尾不加句号 (`.`)。
+
+### 2.5 Body (选填)
+对本次提交的详细描述，可以分成多行。说明代码变更的动机，以及与之前行为的对比。
+
+### 2.6 Footer (选填)
+- **不兼容变动 (Breaking Changes)**：如果当前代码与上一个版本不兼容，则 Footer 部分以 `BREAKING CHANGE:` 开头，后面是对变动的描述、以及变动理由和迁移方法。
+- **关闭 Issue/缺陷**：如果当前 commit 针对某个 issue/需求，那么可以在 Footer 部分关闭这个 issue。如：`Closes #123`, `Fixes JIRA-456`。
+
+### 2.7 Commit 示例
+```text
+feat(user): 新增用户登录页面的记住密码功能
+
+增加了本地 storage 的存储逻辑，在用户勾选记住密码时，加密保存 token。
+
+Closes #89
+```
+
+```text
+fix(table): 修复数据为空时分页器仍然显示的问题
+```
+
+## 3. 工作流与 Code Review 规范
+
+1. **同步最新代码**：每天开发前，或在拉取新分支前，务必先 `git pull --rebase origin develop`，确保基于最新代码开发。
+2. **小步提交**：鼓励频繁提交本地代码（遵循 Commit 规范），避免将几天的巨大工作量堆积在一次 Commit 中。
+3. **合并前 Rebase**：在将功能分支合并回 `develop` 之前，如果 `develop` 已经有了新的提交，建议在自己的分支上先执行 `git rebase develop`，解决冲突后再发起 Merge Request / Pull Request。这有助于保持线性的提交历史。
+4. **Code Review (CR)**：
+   - 合并代码到 `develop` 或 `main` 必须通过发起 PR/MR 的方式，**禁止直接 Push**。
+   - 至少需要一位其他开发人员 Review 通过 (Approve) 后才能合并。
+   - CR 重点关注：代码是否符合规范、是否有潜在 Bug、性能是否达标、是否包含敏感信息（如明文密码、密钥）。
+
+## 4. 辅助工具推荐
+强烈建议在项目中集成以下工具以保证规范的落地：
+- **`husky` + `lint-staged`**：在提交前自动进行 ESLint / Prettier 检查。
+- **`commitlint` + `commitizen`**：在 `git commit` 时强制校验 Commit Message 是否符合规范。

package/dist/template/operations-tem/docs/React/345/274/200/345/217/221/350/247/204/350/214/203.md

@@ -0,0 +1,81 @@
+# React 开发规范
+
+本文档规定了团队内 React 项目的开发规范和最佳实践，旨在提高代码的可读性、可维护性和团队协作效率。
+
+## 1. 组件开发规范
+
+### 1.1 组件定义
+- **统一使用函数组件 (Function Component)**：放弃 Class 组件，全面拥抱 React Hooks。
+- **使用 `React.FC` 定义类型**：结合 TypeScript，明确组件类型。
+- **使用 `Props`**：不直接在函数参数处解构 props，而是通过解构赋值在函数内部获取 props。
+
+```tsx
+// ✅ 推荐做法
+import React from 'react';
+
+interface UserCardProps {
+  name: string;
+  age?: number;
+}
+
+export const UserCard: React.FC<UserCardProps> = (props) => {
+  const { name, age = 18 } = props;
+
+  return (
+    <div>
+      <p>Name: {name}</p>
+      <p>Age: {age}</p>
+    </div>
+  );
+};
+```
+
+### 1.2 命名规范
+- **组件文件命名**：使用 **PascalCase (大驼峰)** 命名（如 `UserProfile.tsx`）。如果组件是一个目录，使用 **pascal-case（kebab-case）**，入口文件使用 `index.tsx`。
+- **组件内部变量/函数命名**：使用 **camelCase (小驼峰)** 命名。
+- **事件处理函数命名**：
+  - 传递给组件的 props 命名为 `onXxx`（如 `onClick`）。
+  - 组件内部的处理函数命名为 `handleXxx`（如 `handleClick`）。
+
+### 1.3 组件结构与拆分
+- **单一职责原则**：一个组件只做一件事情。如果组件逻辑变得复杂，应拆分为更小的子组件。
+- **UI 与逻辑分离**：尽量保持 UI 组件 (Presentational Component) 的纯粹性，将复杂的业务逻辑、数据获取抽离到自定义 Hook 或容器组件 (Container Component) 中。
+
+## 2. Hooks 使用规范
+
+### 2.1 基础 Hooks
+- **`useState`**：用于管理组件内部的简单状态。对于复杂状态，考虑使用 `useReducer` 或全局状态管理库 (如 Zustand)。
+- **`useEffect`**：
+  - 必须明确声明依赖数组 (Dependency Array)。
+  - 避免在 `useEffect` 中执行过多不相关的逻辑，按功能拆分为多个 `useEffect`。
+  - 注意清理副作用 (如定时器、事件监听器)。
+
+### 2.2 性能优化 Hooks
+- **谨慎使用 `useMemo` 和 `useCallback`**：仅在遇到真正的性能瓶颈或需要传递稳定的引用给子组件时使用。过度使用会增加内存开销。
+- 由于项目引入了 React Compiler (React 19)，编译器会自动进行大部分的 Memoization 优化，手动使用这些 Hook 的场景将大幅减少。
+
+### 2.3 自定义 Hooks
+- **命名规范**：必须以 `use` 开头（如 `useFetchUser`）。
+- **返回值**：通常返回一个数组 `[value, setValue]` 或一个对象 `{ data, loading, error }`，根据实际场景决定。
+
+## 3. 状态管理规范
+
+- **局部状态**：优先使用组件内部的 `useState` 或 `useReducer`。
+- **全局状态**：使用 Zustand 5 进行轻量级的全局状态管理。
+  - 按业务模块划分 Store (如 `useUserStore`, `useAppStore`)。
+  - 避免将所有状态都放入全局 Store，只共享真正需要跨组件通信的状态。
+
+## 4. 样式开发规范
+
+- **预处理器**：统一使用 Less。
+- **样式隔离**：
+  - 优先使用 CSS Modules (命名为 `xxx.module.less`)，避免全局样式污染。
+  - 配合 classnames 库进行类名的条件拼接。
+- **命名约定**：Less 文件中的类名使用 **kebab-case (短横线命名法)**，如 `.user-profile-container`。
+
+## 5. 代码质量与格式化
+
+- 必须遵守项目配置的 ESLint 和 Prettier 规则。
+- 在提交代码前，确保没有 ESLint 警告或错误。
+- 避免使用 `any`，尽可能提供准确的 TypeScript 类型定义。
+- 不要保留未使用的变量或导入 (`no-unused-vars`)。

package/dist/template/operations-tem/docs/TypeScript/345/274/200/345/217/221/350/247/204/350/214/203.md

@@ -0,0 +1,119 @@
+# TypeScript 开发规范
+
+本文档旨在统一团队内 TypeScript 的使用方式，提升代码的健壮性和可维护性，减少运行时错误。
+
+## 1. 基础规范
+
+### 1.1 命名规范
+- **接口 (Interface) 和 类型别名 (Type Alias)**：
+  - 使用 **PascalCase (大驼峰)** 命名。
+  - 不要使用 `I` 或 `T` 作为前缀（如 `interface IUser` ❌，应为 `interface User` ✅）。
+- **枚举 (Enum)**：
+  - 使用 **PascalCase** 命名枚举及其成员。
+  - 推荐使用字符串枚举以提高调试时的可读性。
+
+```typescript
+// ✅ 推荐做法
+enum UserRole {
+  Admin = 'ADMIN',
+  Editor = 'EDITOR',
+  Viewer = 'VIEWER',
+}
+```
+
+### 1.2 `interface` vs `type`
+- **优先使用 `interface`**：在定义对象或组件 Props 的形状时，默认使用 `interface`。
+- **使用 `type` 的场景**：当需要使用联合类型 (Union Types)、交叉类型 (Intersection Types) 或映射类型 (Mapped Types) 等高级特性时，才使用 `type`。
+
+```typescript
+// ✅ 推荐做法
+interface User {
+  id: string;
+  name: string;
+}
+
+type ID = string | number; // 联合类型必须用 type
+```
+
+## 2. 组件与 Props 规范
+
+### 2.1 Props 定义
+- **必须为每个组件定义 Props 接口**：命名约定为 `[ComponentName]Props`。
+- **明确可选属性**：使用 `?` 标记可选属性，并为其提供合理的默认值。
+- **避免内联类型定义**：不要在函数签名中直接写出庞大的类型对象。
+
+```tsx
+// ✅ 推荐做法
+interface ButtonProps {
+  label: string;
+  onClick: () => void;
+  disabled?: boolean; // 明确可选
+}
+
+export const Button: React.FC<ButtonProps> = (props) => {
+  const { label, onClick, disabled = false } = props;
+  // ...
+};
+```
+
+### 2.2 事件处理类型
+- 优先使用 React 内置的事件类型（如 `React.MouseEvent<HTMLButtonElement>`、`React.ChangeEvent<HTMLInputElement>`），避免使用 `any`。
+
+```tsx
+// ✅ 推荐做法
+const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+  console.log(e.target.value);
+};
+```
+
+## 3. 函数与变量规范
+
+### 3.1 函数返回类型
+- **推荐显式声明函数的返回类型**：虽然 TS 具有强大的类型推导能力，但在定义公共函数、API 接口函数或复杂业务逻辑时，显式声明返回类型有助于提早发现错误并提高代码可读性。
+
+```typescript
+// ✅ 推荐做法
+function calculateTotal(price: number, quantity: number): number {
+  return price * quantity;
+}
+```
+
+### 3.2 变量类型推导
+- **让 TS 自动推导简单类型**：对于初始化时就明确赋值的简单变量，不要显式声明类型。
+
+```typescript
+// ❌ 不推荐
+const age: number = 25;
+const name: string = 'Alice';
+
+// ✅ 推荐做法 (自动推导)
+const age = 25;
+const name = 'Alice';
+```
+
+## 4. 高级类型与断言
+
+### 4.1 类型断言
+- **尽量避免使用类型断言 (`as Type` 或 `<Type>`)**。
+- 如果必须使用，说明 TS 编译器无法推断出正确的类型。请先考虑是否可以通过更好的类型定义或类型守卫来解决。
+
+### 4.2 工具类型 (Utility Types)
+- 熟练掌握并使用 TS 内置的工具类型，如 `Partial<T>`, `Required<T>`, `Readonly<T>`, `Pick<T, K>`, `Omit<T, K>`。
+- 这有助于减少重复代码，保持类型定义的 DRY 原则。
+
+```typescript
+// ✅ 推荐做法
+interface User {
+  id: string;
+  name: string;
+  email: string;
+}
+
+// 只更新部分用户信息
+type UpdateUserDto = Partial<Omit<User, 'id'>>;
+```
+
+## 5. API 请求类型规范
+
+- **统一的响应体接口**：在封装请求库时，定义统一的响应体泛型接口 (如 `ApiResponse<T>`)。
+- **为所有 API 接口定义请求和返回类型**：在 `src/api/` 目录下，每个接口必须明确入参和出参的类型。

package/dist/template/operations-tem/docs//345/211/215/347/253/257/346/227/245/345/277/227/344/270/216/347/233/221/346/216/247/345/237/213/347/202/271/350/247/204/350/214/203.md

@@ -0,0 +1,136 @@
+# 前端日志与监控埋点规范
+
+传统的 `console.log` 只能输出在用户的浏览器控制台，一旦代码发布到生产环境，前端就变成了“黑盒”。为了解决“生产环境瞎子”问题，提升前端应用的可观测性（Observability），特制定本前端日志与监控埋点规范。
+
+前端日志不写入本地文件，而是通过 HTTP/Beacon 上报至监控中心（如 Sentry, 阿里云 ARMS, 或自建日志服务）。
+
+## 1. 前端日志的分类
+
+前端日志主要分为三大类，每类的采集方式和关注点均不同：
+
+1. **异常日志 (Error Logs)**：对应后端的 ERROR 级别。记录 JS 报错、接口请求失败、静态资源加载失败。
+2. **行为埋点日志 (Behavior Logs)**：对应后端的 INFO/TRACE 级别。记录用户的核心操作路径，用于业务分析和故障复现（用户点击流）。
+3. **性能日志 (Performance Logs)**：记录页面白屏时间、首屏渲染时间、接口耗时等 Web Vitals 指标。
+
+---
+
+## 2. 核心字段规范 (Context)
+
+无论上报哪种日志，前端必须在日志的 Context（上下文）中携带以下基础信息，以便和后端链路打通，并精确定位用户环境：
+
+| 字段名 | 类型 | 说明 | 获取方式示例 |
+| --- | --- | --- | --- |
+| `traceId` | String | **全链路追踪 ID**，前后端必须一致 | 从后端的 API 响应 Header 或 HTML Meta 中获取 |
+| `userId` | String | 当前登录操作员 ID | 从 Redux/Zustand Store 或 Token 解析 |
+| `env` | String | 当前环境标识 (dev/test/prod) | `import.meta.env.MODE` |
+| `app_name` | String | 前端应用名称 | 如：`operations-admin-web` |
+| `page_url` | String | 发生事件/报错的当前页面 URL | `window.location.href` |
+| `user_agent` | String | 用户的浏览器、操作系统信息 | `navigator.userAgent` |
+| `network` | String | 用户的网络环境 (4G/WiFi等) | `navigator.connection.effectiveType` (可选) |
+
+---
+
+## 3. 异常日志规范 (Error Logging)
+
+### 3.1 自动捕获
+在项目入口文件（如 `main.tsx`）中，必须全局挂载异常捕获钩子，将错误上报至监控平台：
+
+```typescript
+// 捕获常规 JS 运行时错误
+window.addEventListener('error', (event) => {
+  logService.error('JS_RUNTIME_ERROR', {
+    message: event.message,
+    filename: event.filename,
+    lineno: event.lineno,
+    colno: event.colno,
+    stack: event.error?.stack,
+  });
+});
+
+// 捕获 Promise 未处理的 rejection (如 async/await 报错未 catch)
+window.addEventListener('unhandledrejection', (event) => {
+  logService.error('PROMISE_UNHANDLED_REJECTION', {
+    reason: event.reason,
+  });
+});
+```
+
+### 3.2 React 组件树异常捕获
+必须在根路由或核心组件外层包裹 `ErrorBoundary`（错误边界组件），防止单一组件报错导致整个页面白屏崩溃，并在钩子中上报。
+
+```tsx
+import React, { ErrorInfo } from 'react';
+
+class GlobalErrorBoundary extends React.Component<any, { hasError: boolean }> {
+  state = { hasError: false };
+
+  static getDerivedStateFromError(error: Error) {
+    return { hasError: true };
+  }
+
+  componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+    // 关键：在这里将 React 渲染报错上报
+    logService.error('REACT_RENDER_ERROR', {
+      error: error.toString(),
+      componentStack: errorInfo.componentStack,
+    });
+  }
+
+  render() {
+    if (this.state.hasError) {
+      return <h1>抱歉，页面加载出错，请刷新重试。</h1>;
+    }
+    return this.props.children;
+  }
+}
+```
+
+### 3.3 HTTP 接口异常上报
+在 Axios 的全局响应拦截器 (`response interceptor`) 中，如果 HTTP 状态码非 200，或业务状态码报错，必须上报。
+**关键规范**：接口报错上报时，必须携带请求的 URL、参数、响应体以及**最关键的 `traceId`**。
+
+---
+
+## 4. 行为埋点规范 (Behavior Logging)
+
+业务埋点不仅为了产品分析转化率，更是为了在用户报障时，能还原出**“用户点了什么导致了报错” (Breadcrumbs)**。
+
+### 4.1 埋点触发时机
+- **PV 埋点 (Page View)**：路由切换完成时上报。
+- **点击埋点 (Click Event)**：用户点击核心按钮（如：提交订单、确认支付、删除数据）时上报。
+- **曝光埋点 (Impression)**：核心区块（如：广告位、重要弹窗）进入可视区域时上报。
+
+### 4.2 埋点命名与数据规范
+- **事件 ID (EventId)**：统一采用 `动作_对象` 格式的大写蛇形命名。如 `CLICK_SUBMIT_ORDER_BTN`, `VIEW_LOGIN_PAGE`。
+- **严禁携带大字段**：不要把整个接口返回的 List 或 Base64 图片塞入埋点上报中。
+
+```typescript
+// ✅ 推荐的做法：只记录关键标识
+logService.track('CLICK_DELETE_USER', {
+  targetUserId: '8848',
+  sourcePage: '/users/list'
+});
+```
+
+---
+
+## 5. 数据脱敏规范 (Data Masking)
+
+**与后端规范完全一致，前端在拼接日志和埋点 Context 时，严禁将明文敏感数据上报至公网监控服务中！**
+
+如果用户的输入或接口返回包含了以下字段，在调用 `logService.send()` 之前必须进行掩码处理：
+- 手机号 (`phone`, `mobile`) -> 保留前3后4，中间替换为 `****`
+- 身份证号 (`idCard`) -> 保留前6后4，中间替换为 `********`
+- 密码 (`password`, `pwd`) -> 直接替换为常量 `[REDACTED]` 或根本不上报
+- 银行卡号 (`bankCard`) -> 仅保留后4位
+
+*(前端脱敏通常采用在封装的底层日志 SDK 拦截器中，遍历对象 Key，通过正则统一替换)*
+
+---
+
+## 6. 日志发送策略
+
+由于前端日志通过公网发送，不能影响用户的正常业务网络请求。
+
+- **优先使用 `navigator.sendBeacon`**：这是一种浏览器原生提供的异步发送数据的方法，即使页面被卸载或关闭，数据也能可靠发出，且不会阻塞主线程。
+- **节流与批量上报**：对于高频触发的事件（如滚动、性能指标收集），必须在本地收集放入队列，定时（如每 5 秒）或定量（如满 10 条）批量合并发送一次 HTTP 请求。