From be2f43c6243f5ea6494941506e8529b5e349ab0c Mon Sep 17 00:00:00 2001 From: iven Date: Sat, 18 Apr 2026 20:35:32 +0800 Subject: [PATCH] =?UTF-8?q?docs(wiki):=20=E6=9B=B4=E6=96=B0=20testing.md?= =?UTF-8?q?=20=E5=B7=B2=E7=9F=A5=E9=97=AE=E9=A2=98=E8=A1=A8=20=E2=80=94=20?= =?UTF-8?q?=E6=96=B0=E5=A2=9E=204=20=E6=9D=A1=E5=AE=A1=E8=AE=A1=E4=BF=AE?= =?UTF-8?q?=E5=A4=8D=E8=AE=B0=E5=BD=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- wiki/testing.md | 147 +++++++++++++++++++++++++++++++++++------------- 1 file changed, 109 insertions(+), 38 deletions(-) diff --git a/wiki/testing.md b/wiki/testing.md index de07fa1..85aad6c 100644 --- a/wiki/testing.md +++ b/wiki/testing.md @@ -1,6 +1,6 @@ # 测试环境指南 -> 本项目在 **Windows** 环境下开发，使用 PowerShell 脚本一键启动。不使用 Docker，数据库和缓存直接通过原生安装运行。 +> 本项目在 **Windows** 环境下开发，使用 PowerShell 脚本一键启动。不使用 Docker，数据库直接通过原生安装运行。 ## 环境要求 @@ -9,54 +9,58 @@ | Rust | stable (1.93+) | 后端编译 | | Node.js | 20+ | 前端工具链 | | pnpm | 9+ | 前端包管理 | -| PostgreSQL | 16+ | 主数据库 | -| Redis | 7+ | 缓存 + 会话 | +| PostgreSQL | 16+ (当前 18) | 主数据库 | +| Redis | 7+ (云端实例) | 缓存 + 限流 | -## 服务连接信息 +## 服务连接信息（实际配置） | 服务 | 地址 | 用途 | |------|------|------| -| PostgreSQL | `postgres://erp:erp_dev_2024@localhost:5432/erp` | 主数据库 | -| Redis | `redis://localhost:6379` | 缓存 + 会话 | +| 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 # 启动后端 + 前端（自动清理旧进程） .\dev.ps1 -Status # 查看端口状态 .\dev.ps1 -Restart # 重启所有服务 .\dev.ps1 -Stop # 停止所有服务 ``` 脚本会自动： -1. 清理端口占用 +1. 清理端口 5174-5189 范围内所有残留进程 2. 编译并启动 Rust 后端 (`cargo run -p erp-server`) -3. 安装前端依赖并启动 Vite 开发服务器 (`pnpm dev`) +3. 安装前端依赖并启动 Vite 开发服务器 (`pnpm dev -- --strictPort`) ## 手动启动 -### 1. 启动基础设施 - -确保 PostgreSQL 和 Redis 服务已在 Windows 上运行： +### 1. 确保基础设施运行 ```powershell # 检查 PostgreSQL 服务状态 Get-Service -Name "postgresql*" -# 检查 Redis 是否运行（如果作为 Windows 服务安装） -Get-Service -Name "Redis" -ErrorAction SilentlyContinue - -# 或通过命令行启动 Redis -redis-server +# 如需启动 +# PostgreSQL 通常自动启动，服务名 postgresql-x64-18 ``` -### 2. 启动后端 +### 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 ``` @@ -67,7 +71,7 @@ cargo run -p erp-server ```powershell cd apps/web pnpm install # 首次需要安装依赖 -pnpm dev # 启动开发服务器 +pnpm dev # 启动开发服务器（端口 5174，固定） ``` ## 验证清单 @@ -111,24 +115,48 @@ pnpm tsc -b | `http://localhost:3000/api/docs/openapi.json` | GET | OpenAPI 文档 | | `http://localhost:5174` | GET | 前端页面 | -### 登录信息 +### API 快速测试 -- 用户名: `admin` -- 密码: `Admin@2026` +```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 " + +# 列出插件 +curl -s http://localhost:3000/api/v1/admin/plugins \ + -H "Authorization: Bearer " +``` ## 数据库管理 ### 连接数据库 ```bash -psql -U erp -d erp -h localhost +D:\postgreSQL\bin\psql.exe -U postgres -h localhost -d erp ``` -### 查看表结构 +### 常用查询 ```sql -\dt -- 列出所有表 -\d table_name -- 查看表结构 +-- 列出所有表 +\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; ``` ### 迁移 @@ -158,32 +186,75 @@ 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: 端口被占用 +### Q: 端口被占用 / 多个 Vite 进程残留 ```powershell -# 查看占用端口的进程 -Get-NetTCPConnection -LocalPort 3000 -State Listen - -# 终止进程 -Stop-Process -Id -Force - -# 或使用 dev.ps1 自动清理 +# 使用 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 服务正在运行 -2. 检查 `crates/erp-server/config/default.toml` 中的连接字符串 -3. 确认 `erp` 数据库已创建 +1. 确认 PostgreSQL 服务正在运行: `Get-Service -Name "postgresql*"` +2. 使用正确连接串: `postgres://postgres:123123@localhost:5432/erp` +3. psql 路径: `D:\postgreSQL\bin\psql.exe` ### Q: 首次启动很慢 -首次 `cargo run` 需要编译整个 workspace，后续增量编译会很快。 +首次 `cargo run` 需要编译整个 workspace（特别是 wasmtime），后续增量编译会很快。 + +### Q: Redis 未安装 + +Redis 已配置为云端实例（`129.204.154.246:6379`）。限流中间件使用固定窗口计数器，登录接口限制 60 秒内 5 次请求。如 Redis 不可达，自动降级为 fail-open（放行所有请求）。 ## 关联模块