feat(health): 添加 erp-health 健康管理模块骨架

新建 erp-health 原生 Rust crate，覆盖设计规格中定义的 5 大业务域： - 16 个 SeaORM Entity（患者/家属/标签/医生/健康档案/体征/化验单/预约/排班/随访/咨询等） - 16 表数据库迁移（含索引、外键、默认值、可回滚） - 40+ API 路由骨架（患者管理/健康数据/预约排班/随访/咨询/医生管理） - 12 个权限声明（health.patient/health-data/appointment/follow-up/consultation/doctor 各 .list/.manage） - DTO / Service / Handler / Event 四层架构，Service 使用 todo!() 占位 - erp-server 集成：模块注册 + AppState FromRef 桥接 + 路由挂载同步更新 CLAUDE.md 项目进度、wiki 知识库、设计规格文档。
2026-04-23 19:59:22 +08:00
parent 5ac8e18d74
commit ca50d32f6e
61 changed files with 6853 additions and 1208 deletions
--- a/wiki/testing.md
+++ b/wiki/testing.md
@@ -1,119 +1,49 @@
-# 测试环境指南
+---
+title: 测试与验证
+updated: 2026-04-23
+status: stable
+tags: [testing, verification]
+---

-> 本项目在 **Windows** 环境下开发，使用 PowerShell 脚本一键启动。不使用 Docker，数据库直接通过原生安装运行。
+# 测试与验证

-## 环境要求
+> 从 [[index]] 导航。关联: [[infrastructure]] [[database]] [[frontend]] [[erp-server]]

-| 工具 | 最低版本 | 用途 |
-|------|---------|------|
-| Rust | stable (1.93+) | 后端编译 |
-| Node.js | 20+ | 前端工具链 |
-| pnpm | 9+ | 前端包管理 |
-| PostgreSQL | 16+ (当前 18) | 主数据库 |
-| Redis | 7+ (云端实例) | 缓存 + 限流 |
+## 1. 设计决策

-## 服务连接信息（实际配置）
+- **真实数据库优先** — 集成测试用真实 PostgreSQL，不用内存模拟
+- **分层验证** — 编译检查 → 单元测试 → 功能验证 → 生产构建
+- **环境配置统一由 [[infrastructure]] 管理** — 连接信息、启动命令、登录凭据见该页

-| 服务 | 地址 | 用途 |
-|------|------|------|
-| 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 开发服务器 |
+## 2. 关键文件 + 验证清单

-### 登录信息
+### 测试分布

- 用户名: `admin`
- 密码: `Admin@2026`
+| Crate | 测试数 | 覆盖 |
+|-------|--------|------|
+| erp-auth | 8 | 密码哈希、TTL 解析 |
+| erp-core | 6 | RBAC 权限检查 |
+| erp-workflow | 16 | BPMN 解析、表达式求值 |
+| erp-plugin-prototype | 6 | WASM 插件集成 |
+| **总计** | **36** | |

-## 一键启动（推荐）
-
-使用 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
+cargo check                    # 编译无错误
+cargo test --workspace         # 全量测试
+cargo clippy -- -D warnings    # Lint 无警告
+cargo fmt --check              # 格式检查
+cd apps/web && pnpm build      # 前端生产构建
 ```

-### 前端验证
+### 功能验证端点

-```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 | 前端页面 |
+| 端点 | 说明 |
+|------|------|
+| `http://localhost:3000/api/v1/health` | 健康检查 |
+| `http://localhost:3000/api/docs/openapi.json` | OpenAPI 文档 |
+| `http://localhost:5174` | 前端页面 |

 ### API 快速测试

@@ -122,143 +52,57 @@ pnpm tsc -b
 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>"
 ```

-## 数据库管理
+### 前端性能基准（2026-04-18 Lighthouse）

-### 连接数据库
+Accessibility / SEO / Best Practices 均 100，LCP 840ms，CLS 0.02
+
+## 3. 代码逻辑
+
+### 集成契约
+
+| 方向 | 模块 | 触发时机 |
+|------|------|---------|
+| 依赖 ← | [[infrastructure]] | 环境准备、连接信息 |
+| 验证 → | [[erp-server]] | 健康检查、API 测试 |
+| 验证 → | [[frontend]] | 生产构建 |
+
+⚡ **不变量**: 功能验证需要后端服务运行中，编译检查必须先于测试通过
+
+### 数据库常用查询

 ```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;
+SELECT version FROM seaql_migrations ORDER BY version;  -- 迁移记录
+SELECT code, name FROM permissions WHERE deleted_at IS NULL ORDER BY code;  -- 插件权限
 ```

-### 迁移
+## 4. 活跃问题 + 陷阱

-迁移在 `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 内部问题，无法直接修复 |
+| antd vendor chunk 2.9MB (gzip ~400KB) | P3 | 待优化 |

-详见 `docs/audit-2026-04-18.md`。
+### 历史教训

-### 前端审计摘要（2026-04-18 Lighthouse + 性能）
+- CRM 权限码与实体名不一致 → 403（详见 [[wasm-plugin]] 权限命名铁律）
+- `AppError::Internal` 无日志 → 500 静默（已加 `tracing::error`）
+- `build_scope_sql` 参数索引硬编码 → SQL 参数错位（已动态化）

-| 指标 | 得分 |
+⚠️ 首次 `cargo run` 需编译整个 workspace（含 wasmtime），后续增量快
+⚠️ Redis 不可达时限流自动降级为 fail-open
+
+## 5. 变更记录
+
+| 日期 | 变更 |
 |------|------|
-| 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]] — 后端服务配置
+| 2026-04-23 | 重构为 5 节结构，去除与 infrastructure.md 重复 |
+| 2026-04-18 | Lighthouse 审计 + 性能优化 |