Samples 运行与测试
本页介绍 macula-samples 单仓项目的运行与测试。以下命令均从仓库根目录开始，前端命令另在 Admin 目录执行。
启动前准备
确认 Macula Cloud IAM、Gateway、System 已运行，并登记 BFF 应用与管理端 OAuth Client。复制并编辑仓库根目录的 deploy/.env，然后启动 Samples 本地基础设施：
cp deploy/.env.example deploy/.env
./deploy/scripts/compose.sh config
./deploy/scripts/compose.sh up
该模式启动 MySQL、Redis、Nacos 和初始化任务，应用在 IDE 中以 local profile 运行。Java 服务不会自动加载 .env，需要覆盖的值在 IDE 中设置。
应用启动顺序
- Service1、Basic、OpenAPI、Thirdparty。
- Admin BFF。
- Samples Gateway。
- Admin 管理端。
Parent 和 API 契约模块不单独启动。Service1 通过 Flyway 管理数据库迁移。
cd macula-samples-admin
npm ci
npm run dev
浏览器访问 http://127.0.0.1:5800。Vite 的 /api 默认代理到 http://127.0.0.1:6000，登录请求直接访问外部 IAM。
后端测试
在 macula-samples 仓库根目录执行，并显式选择环境：
# Service1 及其接口契约
mvn -pl macula-samples-api,macula-samples-api/macula-samples-service1-api,macula-samples-service1 -am test -Plocal
# 全量后端测试
mvn test -Plocal
优先缩小到改动模块和所需依赖。连接 MySQL、Redis、Nacos 或 Macula Cloud 的检查需要对应环境，不将环境缺失当作业务代码失败。
管理端检查
在 Admin 目录执行：
npm run test:unit
npm run build
npm run test:e2e:ci
npm run lint 含自动修复，会修改文件，应在确认工作区状态后执行。E2E 是否使用模拟接口或真实后端，应以用例运行条件为准。
联调检查点
- Gateway 能通过 IAM introspection 验证客户端 Token。
- BFF、Service 等资源服务器能取得 Samples Gateway 的 JWK，验证内部 JWT。
- BFF 的 Cloud endpoint 指向正确的 Macula Cloud 网关，用户与菜单能按登记应用返回。
- Nacos 服务名、Gateway 路由、Feign 目标与接口契约一致。