erp/wiki/testing.md

测试环境指南

本项目在 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 脚本管理前后端服务：

.\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. 确保基础设施运行

# 检查 PostgreSQL 服务状态
Get-Service -Name "postgresql*"

# 如需启动
# PostgreSQL 通常自动启动，服务名 postgresql-x64-18

2. 启动后端（必须从 crates/erp-server 目录）

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. 启动前端

cd apps/web
pnpm install   # 首次需要安装依赖
pnpm dev       # 启动开发服务器（端口 5174，固定）

验证清单

后端验证

# 编译检查（无错误）
cargo check

# 全量测试（应全部通过）
cargo test --workspace

# Lint 检查（无警告）
cargo clippy -- -D warnings

# 格式检查
cargo fmt --check

前端验证

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 快速测试

# 登录获取 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>"

数据库管理

连接数据库

D:\postgreSQL\bin\psql.exe -U postgres -h localhost -d erp

常用查询

-- 列出所有表
\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

运行特定测试

# 运行单个 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 进程残留

# 使用 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 — 后端服务配置