feat: 2026-09 全面治理与审查修复

.all-contributorsrc

@@ -1,6 +1,6 @@
 {
-  "projectName": "JerryHub-dev/umi-react-admin",
-  "projectOwner": "JerryHub-dev",
+  "projectName": "umi-react-admin",
+  "projectOwner": "Jerry-CodeHub",
   "repoType": "github",
   "repoHost": "https://github.com",
   "files": ["README.md"],

.claude/CLAUDE.md

@@ -4,17 +4,16 @@
 
 ## 项目概述
 
-umi-react-admin 是一个基于 Umi Max 的企业级 React 后台管理系统模板，包含丰富的功能组件展示，如日历、富文本编辑、地图（Cesium/高德/OpenLayers）、低代码设计器等。
+umi-react-admin 是一个基于 Umi Max 的企业级 React 后台管理系统模板，包含丰富的功能组件展示，如日历、富文本编辑、地图（Cesium/高德/OpenLayers）、播放器、签名等。
 
 ## 技术栈
 
 - **框架**: Umi Max 4.x + React 18 + TypeScript 5.x
 - **UI**: Ant Design 5 + Ant Design Pro Components
 - **样式**: Tailwind CSS 3 + Less
-- **状态管理**: Valtio (Umi Max 内置)
-- **表单/低代码**: Formily 2 + Designable
+- **状态管理**: Umi initialState（全局用户与主题）+ 组件内 state（未启用 valtio）
 - **地图**: Cesium.js、OpenLayers 9、高德地图
-- **图表**: Ant Design Charts、D3.js
+- **图表**: Ant Design Charts (plots)、D3.js
 - **包管理器**: pnpm
 
 ## 常用命令
@@ -25,6 +24,10 @@ pnpm start            # 启动开发服务器 (端口 8000)
 pnpm build            # 生产构建
 pnpm build:github     # GitHub Pages 构建
 pnpm preview          # 构建并预览 (端口 8001)
+pnpm check            # typecheck + 严格 lint + vitest（提交前必跑）
+pnpm test             # vitest 单测（test:watch 监听 / test:coverage 覆盖率）
+pnpm size             # 构建并执行体积预算门禁（size-budget.json）
+pnpm analyze          # 构建并生成 bundle 组成分析
 pnpm format           # Prettier 格式化代码
 ```
 
@@ -33,10 +36,9 @@ pnpm format           # Prettier 格式化代码
 ```
 src/
 ├── pages/            # 页面组件（路由对应）
-├── components/       # 可复用组件
+├── components/       # 可复用组件（ErrorBoundary、CesiumViewer）
 ├── layouts/          # 布局组件
-├── models/           # 全局数据模型 (hooks)
-├── services/         # API 服务层
+├── services/         # API 服务层（auth + demo 数据层，模式判定见 services/demo/mode.ts）
 ├── utils/            # 工具函数
 ├── locales/          # 国际化文件 (zh-CN, en-US)
 ├── constants/        # 常量定义
@@ -70,6 +72,7 @@ config/
 - React 组件: PascalCase (`Home.tsx`)
 - 工具函数: camelCase (`format.ts`)
 - 组件目录: PascalCase (`FullCalendar/index.tsx`)
+- 样式辅助文件: Xxx.style.ts（styled-components 样式常量）
 
 ## Git 工作流
 
@@ -91,6 +94,15 @@ config/
 - 需要设置环境变量 `CESIUM_ION_TOKEN`
 - Cesium 资源在构建时自动复制到 dist/Cesium/
 - 全局变量 `CESIUM_BASE_URL` 指向 `/Cesium`
+- 新页面用 `@/components/CesiumViewer` 的 `createDemoViewer` 与 `CesiumInitError`；不要隐藏 credit 署名区（ion 条款要求）
+
+### 易踩坑（均有真实事故）
+
+- **mock 目录只放接口定义**：umi 会 require mock 下所有 ts/js，测试文件放进去会让 dev 全站 500、preview 启动失败（`scripts/mock-loadable.test.ts` 兜底）
+- **polyfill 只引 `core-js/stable`**（config.ts `polyfill.imports`）：默认的 esnext 提案 polyfill 会强制覆盖原生实现（曾导致 pdfjs 报 onPull 错误）
+- **演示数据层两种模式**：dev 走 umi mock；生产构建且未配 `UMI_APP_API_BASE` 时走前端本地实现（鉴权与表格）。`max preview` 自带 mock，验证纯静态行为要用真正的静态服务器
+- **public 资源路径一律经 `PUBLIC_PATH` 拼接**：GitHub Pages 部署在 `/umi-react-admin/` 子路径
+- **首页图表数据**由 `node scripts/generate-chart-data.mjs` 确定性生成，不要引入来源不明的第三方数据
 
 ### 国际化
 
@@ -106,6 +118,6 @@ config/
 
 ## 部署
 
-- **GitHub Pages**: `pnpm build:github` + GitHub Actions
-- **Docker**: 使用根目录 Dockerfile
-- **Vercel**: 支持自动部署 (vercel.json)
+- **GitHub Pages**: `pnpm build:github` + GitHub Actions（部署前复制 404.html 做 SPA 回退）
+- **Docker**: 根目录 Dockerfile + `nginx/`（仅带哈希文件长缓存，.mjs 需显式声明类型）
+- **Vercel**: 支持自动部署 (vercel.json，含 SPA rewrite)

.dockerignore

@@ -0,0 +1,27 @@
+node_modules
+.git
+.github
+.claude
+.kilo
+.idea
+.vscode
+.husky
+dist
+coverage
+docs
+.pnpm-store
+LsDocs
+
+# 本地秘钥绝不进镜像（构建 token 走 build-arg）
+.env*
+
+# umi 本地生成物（含宿主机绝对路径，构建时会重新生成）
+src/.umi
+src/.umi-production
+src/.umi-test
+.mfsu
+.swc
+
+# 本地报告与临时文件
+*.log
+.DS_Store

.env.example

@@ -1,3 +1,12 @@
 # Cesium Ion Token
 # 从 https://ion.cesium.com/ 获取你的 token
 CESIUM_ION_TOKEN=your_cesium_ion_token_here
+
+# 可选：真实后端 API 地址（配置后 request 走该 baseURL，替换演示 mock）
+# UMI_APP_API_BASE=https://api.example.com
+
+# 可选：TinyMCE Cloud API Key（不配置则编辑器以无 key 模式加载）
+# TINYMCE_API_KEY=
+
+# 可选：Clarity 统计项目 ID（模板默认不含任何统计脚本，配置后按你自己的项目上报）
+# CLARITY_ID=

.eslintignore

@@ -2,3 +2,9 @@ public/Cesium/
 public/js/turf.min.js
 public/js/html2canvas.min.js
 public/js/CesiumNavigation.umd.js
+dist/
+src/.umi/
+src/.umi-production/
+.claude/
+.kilo/
+coverage/

.eslintrc.js

@@ -1,5 +1,6 @@
 module.exports = {
   extends: require.resolve('@umijs/max/eslint'),
+  plugins: ['jsx-a11y'],
   rules: {
     // 禁止使用 console.log，但允许 warn 和 error
     'no-console': ['warn', { allow: ['warn', 'error'] }],
@@ -17,5 +18,17 @@ module.exports = {
     eqeqeq: ['warn', 'always'],
     // 禁止在 return、throw、continue 和 break 语句后出现不可达代码
     'no-unreachable': 'warn',
+    // a11y 最小集（阶段5）：图片必有 alt、aria 属性合法，不启用大规模规则避免存量误报
+    'jsx-a11y/alt-text': 'error',
+    'jsx-a11y/aria-props': 'error',
+    'jsx-a11y/role-supports-aria-props': 'error',
+    'jsx-a11y/anchor-is-valid': 'warn',
   },
+  overrides: [
+    {
+      // 构建与门禁脚本是命令行工具，向终端输出是本职
+      files: ['scripts/**/*.{js,mjs,cjs,ts}'],
+      rules: { 'no-console': 'off' },
+    },
+  ],
 };

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,18 @@
+---
+name: 功能建议
+about: 为模板提议新功能或改进
+title: '[feature] '
+labels: enhancement
+---
+
+## 背景
+
+<!-- 你遇到的问题或场景 -->
+
+## 期望
+
+<!-- 希望模板提供什么 -->
+
+## 替代方案
+
+<!-- 考虑过的其他做法 -->

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,14 @@
+## 变更说明
+
+<!-- 这个 PR 做了什么、为什么 -->
+
+## 自查清单
+
+- [ ] `pnpm check` 通过（typecheck + 严格 lint + vitest）
+- [ ] 涉及构建/体积的改动已跑 `pnpm size`（预算门禁）
+- [ ] 新增 public 资源已在 THIRD-PARTY-NOTICES.md 登记来源与许可
+- [ ] 框架层页面文案已接 intl（如涉及）
+
+## 截图 / 演示
+
+<!-- UI 变更请附截图 -->

.github/workflows/ci.yml

@@ -0,0 +1,75 @@
+name: CI
+
+# PR 时执行质量门禁（也可在 Actions 页手动触发）；master 的部署由 deploy.yml 负责。
+# 不监听分支 push：同分支 push 与 PR 会双触发，被并发取消的那次会以 cancelled 留在 PR 检查列表里
+on:
+  pull_request:
+  workflow_dispatch:
+
+# 同一 PR 的新提交取消仍在运行的旧运行
+concurrency:
+  group: ci-${{ github.head_ref || github.ref_name }}
+  cancel-in-progress: true
+
+# 注：actions 使用次版本钉住的标签；后续可升级为 commit SHA 钉固（供应链加固 TODO）
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7.0.1
+
+      - name: Setup pnpm（读 packageManager 字段）
+        uses: pnpm/action-setup@v6.1.0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v7.0.0
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Quality gates（typecheck + 严格 lint + vitest，含 mock 可加载性）
+        run: pnpm check
+
+      - name: Dependency audit（非阻断观察期）
+        # 两段式策略（决策 D7/D30）：先建立可见性，high 存量清零后转强制阻断
+        run: pnpm audit --registry=https://registry.npmjs.org/ || true
+
+  build:
+    needs: check
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # 两条产线都冒烟：主产线（Vercel/Docker）与 GitHub Pages 子路径产线
+        script: [build, 'build:github']
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7.0.1
+
+      - name: Setup pnpm（读 packageManager 字段）
+        uses: pnpm/action-setup@v6.1.0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v7.0.0
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build smoke（${{ matrix.script }}，无需任何 secrets）
+        run: pnpm run ${{ matrix.script }}
+
+      - name: 体积预算与样式覆盖门禁
+        if: matrix.script == 'build'
+        run: node scripts/check-bundle-size.mjs
+
+      - name: 产物 JWT 泄露扫描
+        # 补审计 security-6 的盲区：曾发生 token 经 define 注入构建产物并部署到 gh-pages。
+        # CI 构建不注入 secret，产物里除 Cesium 自带的公开默认 token 外出现任何 JWT 都判失败
+        run: node scripts/check-dist-secrets.mjs

.github/workflows/deploy.yml

@@ -5,23 +5,25 @@ on:
     branches:
       - master
 
+concurrency:
+  group: gh-pages-deploy
+  cancel-in-progress: true
+
 jobs:
   build-and-deploy:
     runs-on: ubuntu-latest
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v7.0.1
 
-      - name: Setup pnpm
-        uses: pnpm/action-setup@v4
-        with:
-          version: 9
+      - name: Setup pnpm（读 packageManager 字段）
+        uses: pnpm/action-setup@v6.1.0
 
       - name: Setup Node.js
-        uses: actions/setup-node@v4
+        uses: actions/setup-node@v7.0.0
         with:
-          node-version: '18'
+          node-version-file: .nvmrc
           cache: pnpm
 
       - name: Install dependencies
@@ -39,10 +41,20 @@ jobs:
       - name: Build
         env:
           CESIUM_ION_TOKEN: ${{ secrets.CESIUM_ION_TOKEN }}
+          # 可选：为演示站开启 Clarity 统计时配置（模板默认不含任何统计脚本）
+          CLARITY_ID: ${{ secrets.CLARITY_ID }}
         run: pnpm run build:github
 
+      - name: SPA fallback（子路由直链/刷新不 404）
+        # GitHub Pages 对不存在的路径返回站点根的 404.html；复制入口页即可让前端路由接管
+        run: cp dist/index.html dist/404.html
+
       - name: Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v3
+        uses: peaceiris/actions-gh-pages@v4.1.0
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
           publish_dir: ./dist
+          # 孤儿化部署：gh-pages 历史不累积（曾达 71 个提交/33MiB），
+          # 且旧产物（含已泄露未轮换的历史 token）不再被新克隆拉取。
+          # 注意：开启后首次部署将重建整棵部署树。
+          force_orphan: true

.gitignore

@@ -1,5 +1,8 @@
 /node_modules
-/.env.local
+# 本地环境变量（umi 会加载 .env、.env.local 等），只提交模板 .env.example
+/.env
+/.env.*
+!/.env.example
 /.umirc.local.ts
 /config/config.local.ts
 /src/.umi
@@ -15,3 +18,14 @@
 # OS and editor artifacts
 .DS_Store
 .idea/
+
+# 本地 AI 工具 worktree 产物
+.claude/worktrees/
+.kilo/
+
+# 内部审计/修复方案文档（不随仓库分发）
+docs/audit-report-*.md
+docs/remediation-plan-*.md
+
+# 测试覆盖率产物
+coverage/

.husky/pre-commit

@@ -1,5 +1,5 @@
 #!/usr/bin/env sh
 . "$(dirname -- "$0")/_/husky.sh"
 
-# npx --no-install lint-staged --quiet
-pnpm lint-staged
+pnpm lint-staged
+pnpm typecheck

.lintstagedrc

@@ -1,6 +1,6 @@
 {
   "*.{md,json}": ["prettier --cache --write"],
-  "*.{js,jsx}": ["max lint --fix --eslint-only", "prettier --cache --write"],
+  "*.{js,jsx,mjs,cjs}": ["eslint --fix --max-warnings=0", "prettier --cache --write"],
   "*.{css,less}": ["max lint --fix --stylelint-only", "prettier --cache --write"],
-  "*.ts?(x)": ["max lint --fix --eslint-only", "prettier --cache --parser=typescript --write"]
+  "*.ts?(x)": ["eslint --fix --max-warnings=0", "prettier --cache --parser=typescript --write"]
 }

.npmrc

@@ -1,4 +1,7 @@
-registry=https://registry.npmmirror.com/
+# 仓库不指定 registry（CI、Docker 与全球贡献者默认走 npm 官方源）。
+# 国内开发者请在自己的 ~/.npmrc 配置镜像，例如：registry=https://registry.npmmirror.com/
+# 注意镜像源不支持 audit 通道，安全审计需显式走官方源：
+#   pnpm audit --registry=https://registry.npmjs.org/
 
 # 将依赖提升至node_modules根目录。
 shamefully-hoist=true
@@ -9,5 +12,6 @@ auto-install-peers=true
 # 如果您不希望pnpm在对等依赖问题上失败
 strict-peer-dependencies=false
 
-# CI 环境不使用 frozen-lockfile（解决 Vercel 部署问题）
-frozen-lockfile=false
+# 锁文件纪律：不在 .npmrc 全局关闭 frozen-lockfile。
+# CI/GitHub Actions 已显式 --frozen-lockfile，Vercel 由 vercel.json 的 installCommand 锁定，
+# pnpm 在 CI 环境也会自动启用 frozen 模式；本地开发保持默认以便更新锁文件。

.nvmrc

@@ -0,0 +1 @@
+22.19.0