@carfiedli/runtime-guardrail 0.1.19

package/README.fe.md

@@ -0,0 +1,256 @@
+# AI Guardrails 前端开发指南
+
+> 本文档面向参与 `frontend/` 目录开发的工程师，涵盖环境搭建、项目架构、开发规范、新增页面流程与部署说明。
+
+---
+
+## 目录
+
+- [1. 项目概述](#1-项目概述)
+- [2. 技术栈](#2-技术栈)
+- [3. 开发流程](#3-开发流程)
+- [4. 项目结构](#4-项目结构)
+- [5. 架构设计](#5-架构设计)
+- [6. 常见问题](#13-常见问题)
+
+---
+
+## 1. 项目概述
+
+**AI Guardrails Console** 是 AI 安全护栏管理控制台的前端项目，基于腾讯 **Tea 框架** 构建。提供安全态势总览、防护策略配置、日志审计等功能模块的管理界面。
+
+| 属性 | 值 |
+|------|-----|
+| 包名 | `@tencent/tea-app-runtime-guardrails` |
+| 框架 | Tea App（基于 React 16 + react-router-dom v5） |
+| UI 库 | `@tencent/tea-component ^2.8.5` |
+| 状态管理 | `zustand ^4.5.7` |
+| 构建工具 | `@tencent/tea-scripts ^2.1.27` |
+
+---
+
+## 2. 技术栈
+
+| 技术 | 版本 | 说明 |
+|------|------|------|
+| React | ^16.11.0 | UI 框架 |
+| TypeScript | ^3.8.2 | 类型系统 |
+| react-router-dom | ^5.2.0 | 客户端路由 |
+| @tencent/tea-component | ^2.8.5 | Tea UI 组件库 |
+| zustand | ^4.5.7 | 轻量级状态管理 |
+| history | ^4.9.0 | 浏览器历史管理 |
+| moment | ^2.24.0 | 日期时间处理 |
+| Less | — | CSS 预处理器 |
+
+---
+
+## 3. 开发流程
+
+### 3.1 前置条件
+
+- **Node.js**: 建议 v16+
+- **tea-cli**: Tea 框架命令行工具
+
+### 3.2 安装 tea-cli
+
+```bash
+npm i @tencent/tea-cli -g --registry=https://mirrors.tencent.com/npm/
+```
+使用 Tea 命令行工具前需要进行注册    
+[<token> 请点此获取](https://tea.tencent.com/developer)    
+获取后，执行： tea login Token    登录成功后，才能使用tea cli工具执行前端开发
+
+### 3.3 安装依赖
+
+```bash
+cd frontend
+npm install
+```
+
+> 项目配置了 `.npmrc`，npm 源指向 `https://mirrors.tencent.com/npm/`。
+
+### 3.4 启动开发服务器
+
+```bash
+# 在frontend/ 目录执行：
+npm run dev
+
+# 或在项目根目录执行 
+npm run fe
+```
+
+### 3.5 使用whistle代理线上静态文件
+
+代理规则：
+
+```bash
+/\/(runtime-guardrails)\.(\w{10})?\.(js|css)/  http://127.0.0.1:8322/$1.$3
+```
+此时，访问 https://ai-guard.woa.com/base/ 就能看到代理后的页面渲染效果
+
+
+### 3.6. 线上部署
+
+流水线地址： https://zhiyan.woa.com/qci/7038/pipeline/#/pipeline/detail/11655977/build/current
+
+
+## 4. 项目结构
+
+```
+frontend/
+├── tea.config.js              # Tea 构建配置（webpack 自定义）
+├── tsconfig.json              # TypeScript 配置
+├── package.json               # 依赖管理与脚本
+├── public/
+│   └── index.html             # HTML 模板
+│
+├── app/                       # 📦 框架层（别名 @tea/app）
+│   ├── app.tsx                # 核心 App 组件，路由渲染入口
+│   ├── index.ts               # 框架层导出入口
+│   ├── history-context.ts     # History Context + useHistory hook
+│   ├── types.ts               # 菜单/路由类型定义
+│   ├── components/
+│   │   ├── Layout.tsx         # 全局布局（Header + Sider + Body）
+│   │   ├── Menu.tsx           # 左侧导航菜单
+│   │   ├── UserMenu.tsx       # 顶部右侧用户菜单
+│   │   └── VersionBubble.tsx  # 右下角版本切换浮动气泡
+│   ├── hooks/
+│   │   └── useUserInfo.ts     # 用户信息消费 hook
+│   └── stores/
+│       └── useUserStore.ts    # 用户状态 Zustand store
+│
+├── src/                       # 📦 业务层（别名 @src/*）
+│   ├── app.ts                 # 业务入口（路由注册 + 样式导入）
+│   ├── app.less               # 全局样式
+│   ├── configs/
+│   │   └── menu.ts            # 左侧导航菜单配置
+│   ├── utils/
+│   │   ├── request.ts         # 通用请求方法 clawRequest
+│   │   └── utils.ts           # 工具函数（uuid）
+│   ├── components/            # 公共业务组件
+│   │   ├── ServiceContext/    # 全局 Service 选择上下文
+│   │   ├── BatchOperation/    # 批量操作组件 + Hook
+│   │   └── Skeleton/          # 骨架屏组件
+│   ├── routes/                # 业务路由/页面模块
+│   │   ├── dashboard/         # 安全态势总览
+│   │   ├── deploy-nodes/      # 部署节点管理
+│   │   ├── api-keys/          # API Keys 管理
+│   │   ├── installation/      # 安装方式
+│   │   ├── manual-review/     # 人工审核队列
+│   │   ├── llm-protection/    # LLM 推理防护
+│   │   ├── toolcall-protection/ # Tool Call 防护
+│   │   ├── skills-protection/ # Skills 防护
+│   │   ├── dlp-rules/         # DLP 规则
+│   │   ├── log-analysis/      # 日志分析
+│   │   ├── audit-logs/        # 审计日志
+│   │   └── system-settings/   # 系统设置
+│   ├── static/icons/          # SVG/PNG 图标资源
+│   └── types/
+│       └── assets.d.ts        # 静态资源类型声明
+│
+└── vanilla/                   # 原型版 HTML（通过 sync.sh 同步）
+```
+
+### 路径别名
+
+在 `tsconfig.json` 中配置了以下别名，import 时可直接使用：
+
+| 别名 | 对应路径 | 用途 |
+|------|---------|------|
+| `@tea/app` | `app/` | 框架层模块 |
+| `@tea/app/*` | `app/*` | 框架层子模块 |
+| `@src/*` | `src/*` | 业务层模块 |
+
+---
+
+## 5. 架构设计
+
+### 5.1 分层架构
+
+项目采用**双层架构**设计：
+
+```
+┌─────────────────────────────────────────────┐
+│  app/ — 框架层（Shell）                       │
+│  • 路由系统、布局、History、用户状态管理         │
+│  • 不含业务逻辑，仅提供基础设施                  │
+├─────────────────────────────────────────────┤
+│  src/ — 业务层                                │
+│  • 页面模块、业务组件、API 调用、样式             │
+│  • 调用 app.routes() 注册路由到框架层            │
+└─────────────────────────────────────────────┘
+```
+
+**数据流**：
+1. `src/app.ts` 导入所有路由组件和菜单配置
+2. 调用 `app.routes(routes, menu)` 注册到框架层
+3. 框架层 `app/app.tsx` 创建 Router、Layout 并渲染
+
+### 5.2 路由系统
+
+路由采用**扁平一级路由**设计，在 `src/app.ts` 中集中注册：
+
+```typescript
+// src/app.ts
+const routes = {
+  "/": Dashboard,
+  "/deploy-nodes": DeployNodes,
+  "/api-keys": ApiKeys,
+  // ...
+};
+app.routes(routes, menu);
+```
+
+**注意**：框架层强制只允许一级路由（有校验逻辑），不支持 `/a/b` 形式。如需模块内二级路由，请在页面组件内部使用 `react-router-dom` 的 `Switch/Route`。
+
+### 5.3 状态管理
+
+| 状态类型 | 方案 | 使用方式 |
+|---------|------|---------|
+| 全局用户信息 | Zustand store | `useUserStore()` / `useUserInfo()` |
+| Service 选择上下文 | React Context | `useServiceContext()` / `<ServiceSelector />` |
+| 页面局部状态 | React useState | 组件内自行管理 |
+
+### 5.4 ServiceContext 机制
+
+部分页面需要关联特定 Service（如防护策略配置类页面），通过 `withServiceContext` HOC 实现：
+
+```
+withServiceContext(MyPage)
+  └─> ServiceProvider         # 自动加载 service 列表
+       └─> ServiceGate        # loading → 骨架屏，error → 错误提示
+            └─> MyPage        # 正常渲染，通过 useServiceContext() 获取 serviceId
+```
+
+使用此模式的页面：`llm-protection`、`toolcall-protection`、`skills-protection`、`dlp-rules`、`system-settings`。
+
+---
+
+
+## 6. 常见问题
+
+### Q: 页面白屏，控制台无报错？
+
+检查路由是否在 `src/app.ts` 中注册，以及组件是否正确导出。框架层默认将未匹配路由重定向到 `/`。
+
+### Q: useServiceContext 报错 "must be used within a ServiceProvider"？
+
+确保页面通过 `withServiceContext` HOC 包装导出，否则无法使用 `useServiceContext()`。
+
+### Q: 如何调试 API 请求？
+
+`clawRequest` 默认发送 POST 请求，可在浏览器 Network 面板中查看。请求体中包含 `Action` 和 `RequestId` 字段。
+
+### Q: 本地开发时路由访问 404？
+
+开发环境的 basename 为 `/base`，请确保访问 `http://localhost:3000/base/...` 而非 `http://localhost:3000/...`。
+
+### Q: 新增的图标不显示？
+
+1. 确认 SVG/PNG 文件放在 `src/static/icons/` 目录下
+2. 确认 `src/types/assets.d.ts` 已声明对应的模块类型
+3. 使用 `import icon from "@src/static/icons/my-icon.svg"` 导入
+
+### Q: tea dev 报错 "Cannot read property 'endsWith' of undefined"？
+
+`tea.config.js` 中的 `TEA_PUBLIC_PATH` 环境变量未设置。请使用 `npm run dev`（已通过 `cross-env` 注入），或手动添加默认值。