265 lines
7.7 KiB
Markdown
265 lines
7.7 KiB
Markdown
# 测试环境指南
|
||
|
||
> 本项目在 **Windows** 环境下开发，使用 PowerShell 脚本一键启动。不使用 Docker，数据库直接通过原生安装运行。
|
||
|
||
## 环境要求
|
||
|
||
| 工具 | 最低版本 | 用途 |
|
||
|------|---------|------|
|
||
| Rust | stable (1.93+) | 后端编译 |
|
||
| Node.js | 20+ | 前端工具链 |
|
||
| pnpm | 9+ | 前端包管理 |
|
||
| PostgreSQL | 16+ (当前 18) | 主数据库 |
|
||
| Redis | 7+ (云端实例) | 缓存 + 限流 |
|
||
|
||
## 服务连接信息（实际配置）
|
||
|
||
| 服务 | 地址 | 用途 |
|
||
|------|------|------|
|
||
| PostgreSQL | `postgres://postgres:123123@localhost:5432/erp` | 主数据库 |
|
||
| Redis | `redis://:redis_KBCYJk@129.204.154.246:6379` (云端) | 缓存 + 限流 |
|
||
| 后端 API | `http://localhost:3000/api/v1` | Axum 服务 |
|
||
| 前端 SPA | `http://localhost:5174` | Vite 开发服务器 |
|
||
|
||
### 登录信息
|
||
|
||
- 用户名: `admin`
|
||
- 密码: `Admin@2026`
|
||
|
||
## 一键启动（推荐）
|
||
|
||
使用 PowerShell 脚本管理前后端服务：
|
||
|
||
```powershell
|
||
.\dev.ps1 # 启动后端 + 前端（自动清理旧进程）
|
||
.\dev.ps1 -Status # 查看端口状态
|
||
.\dev.ps1 -Restart # 重启所有服务
|
||
.\dev.ps1 -Stop # 停止所有服务
|
||
```
|
||
|
||
脚本会自动：
|
||
1. 清理端口 5174-5189 范围内所有残留进程
|
||
2. 编译并启动 Rust 后端 (`cargo run -p erp-server`)
|
||
3. 安装前端依赖并启动 Vite 开发服务器 (`pnpm dev -- --strictPort`)
|
||
|
||
## 手动启动
|
||
|
||
### 1. 确保基础设施运行
|
||
|
||
```powershell
|
||
# 检查 PostgreSQL 服务状态
|
||
Get-Service -Name "postgresql*"
|
||
|
||
# 如需启动
|
||
# PostgreSQL 通常自动启动，服务名 postgresql-x64-18
|
||
```
|
||
|
||
### 2. 启动后端（必须从 crates/erp-server 目录）
|
||
|
||
```powershell
|
||
cd crates/erp-server
|
||
$env:ERP__DATABASE__URL = "postgres://postgres:123123@localhost:5432/erp"
|
||
$env:ERP__JWT__SECRET = "dev-secret-key-change-in-prod"
|
||
$env:ERP__AUTH__SUPER_ADMIN_PASSWORD = "Admin@2026"
|
||
cargo run -p erp-server
|
||
```
|
||
|
||
首次运行会自动执行数据库迁移。
|
||
|
||
### 3. 启动前端
|
||
|
||
```powershell
|
||
cd apps/web
|
||
pnpm install # 首次需要安装依赖
|
||
pnpm dev # 启动开发服务器（端口 5174，固定）
|
||
```
|
||
|
||
## 验证清单
|
||
|
||
### 后端验证
|
||
|
||
```bash
|
||
# 编译检查（无错误）
|
||
cargo check
|
||
|
||
# 全量测试（应全部通过）
|
||
cargo test --workspace
|
||
|
||
# Lint 检查（无警告）
|
||
cargo clippy -- -D warnings
|
||
|
||
# 格式检查
|
||
cargo fmt --check
|
||
```
|
||
|
||
### 前端验证
|
||
|
||
```bash
|
||
cd apps/web
|
||
|
||
# 安装依赖
|
||
pnpm install
|
||
|
||
# TypeScript 编译 + 生产构建
|
||
pnpm build
|
||
|
||
# 类型检查
|
||
pnpm tsc -b
|
||
```
|
||
|
||
### 功能验证
|
||
|
||
| 端点 | 方法 | 说明 |
|
||
|------|------|------|
|
||
| `http://localhost:3000/api/v1/health` | GET | 健康检查 |
|
||
| `http://localhost:3000/api/docs/openapi.json` | GET | OpenAPI 文档 |
|
||
| `http://localhost:5174` | GET | 前端页面 |
|
||
|
||
### API 快速测试
|
||
|
||
```bash
|
||
# 登录获取 Token
|
||
curl -s http://localhost:3000/api/v1/auth/login \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"username":"admin","password":"Admin@2026"}'
|
||
|
||
# 列出用户（需要 Token）
|
||
curl -s http://localhost:3000/api/v1/users \
|
||
-H "Authorization: Bearer <token>"
|
||
|
||
# 列出插件
|
||
curl -s http://localhost:3000/api/v1/admin/plugins \
|
||
-H "Authorization: Bearer <token>"
|
||
```
|
||
|
||
## 数据库管理
|
||
|
||
### 连接数据库
|
||
|
||
```bash
|
||
D:\postgreSQL\bin\psql.exe -U postgres -h localhost -d erp
|
||
```
|
||
|
||
### 常用查询
|
||
|
||
```sql
|
||
-- 列出所有表
|
||
\dt
|
||
|
||
-- 查看迁移记录
|
||
SELECT version FROM seaql_migrations ORDER BY version;
|
||
|
||
-- 查看插件权限
|
||
SELECT code, name FROM permissions WHERE deleted_at IS NULL ORDER BY code;
|
||
|
||
-- 查看 admin 角色的权限
|
||
SELECT p.code FROM role_permissions rp
|
||
JOIN permissions p ON rp.permission_id = p.id
|
||
JOIN roles r ON rp.role_id = r.id
|
||
WHERE r.code = 'admin' AND rp.deleted_at IS NULL AND p.deleted_at IS NULL;
|
||
```
|
||
|
||
### 迁移
|
||
|
||
迁移在 `crates/erp-server/migration/src/` 目录下。后端启动时自动执行。
|
||
|
||
## 测试详情
|
||
|
||
### 测试分布
|
||
|
||
| Crate | 测试数 | 说明 |
|
||
|-------|--------|------|
|
||
| erp-auth | 8 | 密码哈希、TTL 解析 |
|
||
| erp-core | 6 | RBAC 权限检查 |
|
||
| erp-workflow | 16 | BPMN 解析、表达式求值 |
|
||
| erp-plugin-prototype | 6 | WASM 插件集成测试 |
|
||
| **总计** | **36** | |
|
||
|
||
### 运行特定测试
|
||
|
||
```bash
|
||
# 运行单个 crate 的测试
|
||
cargo test -p erp-auth
|
||
|
||
# 运行匹配名称的测试
|
||
cargo test -p erp-core -- require_permission
|
||
|
||
# 运行插件集成测试
|
||
cargo test -p erp-plugin-prototype
|
||
|
||
# 集成测试（需要 Docker/PostgreSQL）
|
||
cargo test -p erp-server --test integration
|
||
```
|
||
|
||
## 已知问题（2026-04-18 审计）
|
||
|
||
| 问题 | 严重度 | 状态 |
|
||
|------|--------|------|
|
||
| CRM 插件权限未分配给 admin 角色 → 数据页面 403 | P0 | ✅ 已修复 |
|
||
| CRM 插件权限码与实体名不匹配（`tag.manage` vs `customer_tag`）→ 标签/关系/图谱 403 | P0 | ✅ 已修复（迁移 m20260419_000038） |
|
||
| CRM 插件 WASM 二进制错误（存储了测试插件而非 CRM 插件） | P0 | ✅ 已修复 |
|
||
| 首页统计卡片永久 loading | P0 | ✅ 已修复 |
|
||
| `roles/permissions` 路由被 UUID 解析拦截 | P1 | ✅ 已修复 |
|
||
| 统计概览 `tagColor` undefined crash（`getEntityPalette` 负数索引） | P1 | ✅ 已修复 |
|
||
| 销售漏斗/看板 filter 请求 500（CRM customer 表缺少 generated columns） | P1 | ✅ 已修复（手动 ALTER TABLE 补齐 `_f_level`/`_f_status`/`_f_customer_type`/`_f_industry`/`_f_region` + 索引） |
|
||
| `build_scope_sql` 参数索引硬编码 `$100` 导致 SQL 参数错位 | P1 | ✅ 已修复（动态 `values.len()+1`） |
|
||
| `AppError::Internal` 无日志输出，500 错误静默 | P1 | ✅ 已修复（添加 `tracing::error` 日志） |
|
||
| antd 6 废弃 API 警告（`valueStyle`/`Spin tip`/`trailColor`） | P2 | ✅ 已修复 |
|
||
| display_name 存储 XSS HTML | P1 | 待修复 |
|
||
| 页面刷新时 4 个 401 错误（过期 token 未主动刷新） | P2 | ✅ 已修复（proactive token refresh） |
|
||
| 插件列表重复请求（无并发去重） | P2 | ✅ 已修复（fetchPlugins promise 去重） |
|
||
| TS 编译错误：未使用变量 | P3 | ✅ 已修复 |
|
||
| antd vendor chunk 2.9MB（gzip 后约 400KB） | P3 | 待优化 |
|
||
| antd `setScaleParam` 强制回流 64ms | P3 | antd 内部问题，无法直接修复 |
|
||
|
||
详见 `docs/audit-2026-04-18.md`。
|
||
|
||
### 前端审计摘要（2026-04-18 Lighthouse + 性能）
|
||
|
||
| 指标 | 得分 |
|
||
|------|------|
|
||
| Accessibility | 100 |
|
||
| SEO | 100 |
|
||
| Best Practices | 100 |
|
||
| LCP | 840ms |
|
||
| CLS | 0.02 |
|
||
| TTFB | 4ms |
|
||
|
||
**已实施的优化：**
|
||
- API client proactive token refresh（请求前 30s 检查过期，提前刷新避免 401）
|
||
- plugin store 请求去重（promise 复用，防止并发重复调用）
|
||
- 生产构建中 StrictMode 双重渲染导致的重复请求不会出现
|
||
|
||
## 常见问题
|
||
|
||
### Q: 端口被占用 / 多个 Vite 进程残留
|
||
|
||
```powershell
|
||
# 使用 dev.ps1 自动清理
|
||
.\dev.ps1 -Stop
|
||
|
||
# 手动清理 Vite 残留进程（端口 5174-5189）
|
||
Get-NetTCPConnection -State Listen | Where-Object { $_.LocalPort -ge 5174 -and $_.LocalPort -le 5189 } | ForEach-Object { Stop-Process -Id $_.OwningProcess -Force }
|
||
```
|
||
|
||
### Q: 数据库连接失败
|
||
|
||
1. 确认 PostgreSQL 服务正在运行: `Get-Service -Name "postgresql*"`
|
||
2. 使用正确连接串: `postgres://postgres:123123@localhost:5432/erp`
|
||
3. psql 路径: `D:\postgreSQL\bin\psql.exe`
|
||
|
||
### Q: 首次启动很慢
|
||
|
||
首次 `cargo run` 需要编译整个 workspace（特别是 wasmtime），后续增量编译会很快。
|
||
|
||
### Q: Redis 未安装
|
||
|
||
Redis 已配置为云端实例（`129.204.154.246:6379`）。限流中间件使用固定窗口计数器，登录接口限制 60 秒内 5 次请求。如 Redis 不可达，自动降级为 fail-open（放行所有请求）。
|
||
|
||
## 关联模块
|
||
|
||
- [[infrastructure]] — 基础设施配置详情
|
||
- [[database]] — 数据库迁移和表结构
|
||
- [[frontend]] — 前端技术栈和配置
|
||
- [[erp-server]] — 后端服务配置
|