@mingfuyun/star-allinone 0.4.0 → 0.4.1

package/examples/AGENTS.md

@@ -10,7 +10,7 @@ Peer React is **18.3.1**. The npm package does not export a table.
 
 - Lists: `import MFProTable from '@/components/CommonTable/MFProTable'`. There is no `MFTablePro`. Never import a table from `@mingfuyun/star-allinone`.
 - Overlays: `import { CustomDrawer, BaseModal, HocModal } from '@mingfuyun/star-allinone'`. Do not add or keep `src/components/CustomDrawer` (or local BaseModal / HocModal).
-- Package runtime exports only: `Cron`, `CustomDrawer`, `BaseModal`, `HocModal`, `ErrorBoundary`.
+- Package runtime exports: `Cron`, `CustomDrawer`, `BaseModal`, `HocModal`, `ErrorBoundary`, plus tracking helpers `createTracking`, `getTrackData`, and `TRACKING_REPORT_URLS` from `0.4.0`.
 - Pages: `import Service from '@/services'`. Do not call axios or `src/services/request.tsx` from pages.
 
 Props for `MFProTable` are in `.agents/skills/shared-project-conventions/references/mfprotable.md` after skills sync.
@@ -24,6 +24,7 @@ User-facing shared entries only:
 - Project health: `pnpm exec star-allinone doctor`.
 - Review and commit: `$shared-review-and-submit`. Wait for confirmation.
 - Test publish: `$shared-publish-test` after explicit pipeline confirmation.
+- Tracking: `$shared-tracking`. Load the SDK from OSS. Do not commit `tracking-sdk.global.min.js`.
 
 ## Hard rules
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mingfuyun/star-allinone",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "星系运维前端能力包",
   "main": "dist/index.js",
   "bin": {

package/skills/README.md

@@ -36,7 +36,7 @@ Cursor / Codex 的常驻说明只放仓库根 `AGENTS.md`（模板见 `examples/
 
 ## npm 包的职责
 
-`@mingfuyun/star-allinone` 只发布 **4 个用户入口**。其余是入口的 `references/` 或无 `SKILL.md` 的共享文件：
+`@mingfuyun/star-allinone` 发布下面这些用户入口。其余是入口的 `references/` 或无 `SKILL.md` 的共享文件：
 
 ```text
 @mingfuyun/star-allinone/
@@ -46,6 +46,7 @@ Cursor / Codex 的常驻说明只放仓库根 `AGENTS.md`（模板见 `examples/
         ├── design-to-page/          # 页面；标准列表内部跑 gen page
         ├── review-and-submit/       # 审查并提交；步骤在 references/
         ├── publish-test/            # 测发
+        ├── tracking/                # 埋点接入
         ├── project-conventions/     # architecture / component-contract / mfprotable / review-checklist / quality-checklist
         └── i-have-adhd/             # 用户输出格式
 ```
@@ -126,6 +127,7 @@ git commit -m "chore(skill): 更新公共 skill"
 | `shared-design-to-page` | 页面：标准列表内部 `gen page`，其余按设计稿实现 |
 | `shared-review-and-submit` | 审查并提交 |
 | `shared-publish-test` | 测发 |
+| `shared-tracking` | 埋点：升级能力包、加载 OSS 脚本、初始化、失败上报、按钮 `data-track` |
 
 ## 公共规则写在哪里
 
@@ -135,6 +137,7 @@ git commit -m "chore(skill): 更新公共 skill"
 | `shared-design-to-page` | SKILL + `page-conventions.md`、`overlays.md`、`list-page-template.md` | 页面分层、标准列表 CLI、弹层合同 |
 | `shared-review-and-submit` | SKILL + `impact-analysis.md`、`verify.md`、`ai-review.md`、`commit.md` | 影响分析 → 验证 → 确认后提交 |
 | `shared-publish-test` | SKILL + `scripts/publish-current-branch.sh` | 云效测发；只读 `publishPipelineId` |
+| `shared-tracking` | SKILL | 埋点接入：能力包版本、配置文件、脚本、初始化、失败上报、按钮 |
 | （非入口）`shared-project-conventions` | `architecture.md`、`mfprotable.md`、`component-contract.md`、`review-checklist.md`、`quality-checklist.md` | 架构、导入合同、质量清单 |
 | （非入口）`shared-i-have-adhd` | `i-have-adhd.md` | 用户输出格式 |
 

package/skills/shared/tracking/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: {{sharedSkillName}}
+description: User-facing. Connect a galaxy admin app to the shared tracking SDK. Use when the user asks to add tracking, 埋点, data-track, api_request failure reports, or window.__tracker. Requires @mingfuyun/star-allinone 0.4.0 or newer.
+---
+
+# 埋点接入
+
+把星系管理端接到统一埋点。运行时在 `@mingfuyun/star-allinone` 的 `createTracking`。SDK 脚本只从 OSS 加载，不要放进业务仓库，也不要打进 webpack。
+
+先确认埋点平台已登记本项目的 `appId`。测试用 `test-<project>`，生产用 `<project>`。不一致时只改配置，不改包。
+
+## 1. 更新能力包
+
+依赖至少 `0.4.0`。这一版才有 `createTracking`、`TRACKING_REPORT_URLS`，以及 `CustomDrawer` 的 `cancelTrack` / `okTrack`。
+
+```bash
+pnpm add @mingfuyun/star-allinone@^0.4.0
+pnpm exec star-allinone skills sync
+```
+
+`package.json` 里写成 `"@mingfuyun/star-allinone": "^0.4.0"`。不要把 SDK 文件拷进 `public/`。
+
+## 2. 添加的文件
+
+只新增一个配置文件：`src/utils/tracking/index.ts`。
+
+它负责 appId、用户标识、入队规则、路由中文名。队列、创建和销毁 tracker 都调用包，不要在业务项目再写一套。
+
+```ts
+import { TRACKING_REPORT_URLS, createTracking } from '@mingfuyun/star-allinone';
+
+type TrackingUser = {
+  email?: string;
+  username?: string;
+};
+
+const tracking = createTracking<TrackingUser>({
+  getConfig: () =>
+    ENV === 'test' || ENV === 'prod'
+      ? {
+          appId: ENV === 'prod' ? '<project>' : 'test-<project>',
+          reportUrl: TRACKING_REPORT_URLS[ENV],
+        }
+      : undefined,
+  getUserId: (user) =>
+    user?.email
+      ? `u_${user.email}${user.username ? `_${user.username}` : ''}`
+      : undefined,
+  shouldQueue: ({ ready, pathname }) => !ready || pathname === '/',
+  getRouteName: (pathname) => undefined,
+  normalizePathname: (pathname) => pathname,
+});
+
+export const markTrackingReady = tracking.markReady;
+export const syncTrackingRoute = tracking.syncRoute;
+export const reportApiTracking = tracking.reportApi;
+export const getTrackData = tracking.getTrackData;
+```
+
+按项目改这四项：
+
+- `getConfig`：没有 `test` / `prod` 时返回 `undefined`，不要创建 tracker。`ENV` 不是全局时，改成该项目自己的环境变量。
+- `getUserId`：星链是 `u_{email}` 或 `u_{email}_{username}`。别的项目用自己的稳定用户字段，格式保持 `u_` 前缀。不要放 token。
+- `shouldQueue`：用户或路由还没就绪时入队。单应用在 `/` 或未就绪时入队。多应用还要在离开可埋点路径时清空队列，给 `createTracking` 传 `shouldClearQueue`。
+- `getRouteName` / `normalizePathname`：用本项目路由表把 path 变成中文名。有 `publicPath` 时先去掉前缀再查路由。没有路由名时 `getTrackData` 仍可用，名称里会少页面名。
+
+## 3. 要改的文件
+
+### 加载脚本
+
+在 HTML 或 Umi `headScripts` 里插入普通 script。地址固定为：
+
+`https://statics-mf.cjjd10.com/STAR_STATIC/LIBS/tracking-sdk.global.min.js`
+
+Umi 不要把本地 `public` 文件写进 `headScripts.src`。Vite 会把它当成源码导入然后报错。用内联脚本创建标签：
+
+```js
+(function () {
+  var script = document.createElement('script');
+  script.src = 'https://statics-mf.cjjd10.com/STAR_STATIC/LIBS/tracking-sdk.global.min.js';
+  document.head.appendChild(script);
+})();
+```
+
+不要改已有的性能上报脚本。
+
+### 初始化
+
+Umi：
+
+- `src/app.tsx` 的 `getInitialState` 成功和失败都调用 `markTrackingReady(user)`。失败时传空用户，页面仍要能打开。
+- 增加 `onRouteChange`，调用 `syncTrackingRoute(location.pathname)`。
+
+其他框架在用户信息就绪后调用 `markTrackingReady`，路由变化时调用 `syncTrackingRoute`。不要在业务组件里 `createTracker`。
+
+同一 `appId` 和用户会复用 `window.__tracker`。异常由包吞掉，不能影响页面。
+
+### 接口失败
+
+在项目自己的请求封装里，业务 `code` 非 0 或 HTTP 失败时调用 `reportApiTracking`。成功不报。字段：去掉 query 的 `url`、大写 `method`、`duration`、`success: false`、`status`、`errorMessage`。保留原来的 `message.error`。页面不要直接调 axios。
+
+### 按钮
+
+`getTrackData(action, name, { key, name })` 生成 `data-track` JSON。`id` 用下划线，展示名用 `-` 连接。
+
+- 提交类按钮加 `data-track={getTrackData(...)}`。
+- `CustomDrawer` 默认底部用 `cancelTrack` 和 `okTrack`，不要为了埋点整段替换 `footer`。自定义 `footer` 时，把 `data-track` 写在自己的按钮上。
+- 项目里的 `MFProTable`：工具栏按钮透传 `track`；查询按钮用 `filter_query` / `查询`，重置按钮用 `filter_reset` / `重置`。ProTable 重置按钮的 key 是 `rest`。
+- 不加复制、列设置。搜索栏里除查询和重置以外的按钮，除非用户点名，否则不加。
+
+## 不要做的事
+
+- 不要把 `tracking-sdk.global.min.js` 提交到业务仓库。
+- 不要把 SDK 打进业务 bundle，也不要从源码 `import` 它。
+- 不要在包外重写队列。上限 50 条、失败补报已经在 `createTracking` 里。
+- 不要上报成功请求。
+- 不要为了埋点改用户接口或请求错误提示。
+
+## 验证
+
+`pnpm typecheck`。浏览器里确认：
+
+1. 页面请求了 OSS 上的脚本，并且出现 `window.TrackingSDK`。
+2. 进入业务页、初始状态完成后存在 `window.__tracker`。`/` 上可以还没有。
+3. 一次失败请求发出事件名 `api_request`。
+4. 查询、重置和主要提交按钮带 `data-track`。
+
+`appId` 与平台不一致时，只改 `src/utils/tracking/index.ts`。