- 脚手架:React 18 + Vite 5 + TS;amis 6.13.0 本地 SDK(public/sdk-local,不依赖 CDN,
照 PoC amis-local.html 范式 amisRequire('amis/embed'))
- 登录页:POST /api/auth/login + JWT 存储(内存+localStorage 折中,XSS 权衡见 README/token.ts)
- 页面渲染 /page/:templateId:取转换后 schema 渲染;开发期静态 mock(public/schemas/ 放
角色维护/通知管理归档/用户组管理 3 个真实转换产物,均过官方 schema.json 校验闸);
生产期 schema 接口契约已设计(VITE_SCHEMA_SOURCE 切换)
- 待办页 /todo:GET /api/todo + 503 熔断降级展示
- amis fetcher 适配:复用宿主 axios 注入 Bearer,对接 /api/entity amis CRUD 格式
- axios 拦截器:Bearer 注入 + 401 清会话跳登录
- 联调验证(playwright 无头):登录跳转→渲染用户组(本地库 3 行)→角色维护(真实产物)→
待办 503 降级→401 跳登录(prod 严格链 8090),5 张截图留 docs/
- 工程化:npm run build → dist/(应用 208KB/gzip 71KB + 本地 SDK 61MB,Nginx 可托管);
README/报告/gitignore
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
11 KiB
P4-3 eip4-web 前端渲染宿主脚手架 实测报告
日期:2026-06-11 | 仓库:
eip4-web(独立 git 仓库,整仓归本任务) 任务:搭建 React 18 + Vite + TS 脚手架;amis 6.13.0 本地化渲染宿主;登录/JWT;页面渲染路由; 待办聚合页;amis fetcher 适配后端;无头浏览器联调验证;Nginx 可托管构建产物。 环境:Node v22.22.3 | 后端 JDK 17(openjdk@17)| 本地 PG 15(localhost:5433/eip4m0) 五条既定约定全部遵守(见 §六)。
一、技术栈结论
| 层 | 选型 | 决策理由 |
|---|---|---|
| 框架 | React 18.3 + Vite 5.4 + TypeScript 5.6 | 主流稳妥,不引重型框架(Next/Umi 等);Vite 启动 ~100ms,构建 ~500ms |
| 路由 | react-router-dom 6.28 | 登录守卫(RequireAuth)+ 页面路由 /page/:templateId + 待办 /todo |
| HTTP | axios 1.7 | 请求拦截器注入 Bearer;响应 401 拦截器清会话 + 跳登录 |
| 渲染 | amis 6.13.0 本地 SDK(非 npm 包) | 见下方选型决策 |
amis 渲染:本地 SDK vs npm 包(决策)
选本地 SDK(public/sdk-local/,amisRequire('amis/embed') 模式):
- 约定驱动:本期约定「amis 锁 6.13.0 本地化部署,不依赖 CDN」,SDK 产物来自 C5 构建预演
(eip4-poc 的
sdk-local/,整套渲染器含图表/富文本/office 预览已离线构建)。 - 同源复用:与 PoC 已验证的
amis-local.html范式一致,且与转换器/双闸校验同源—— 转换器产出的 schema 在 PoC 已用同一 SDK 渲染验证过,前端宿主复用零适配风险。 - npm 包形态的代价:
amis+amis-core+ 按需thirds虽利于 tree-shaking,但需自行解决 6.13 本地化(locale)、可选渲染器装配、与本期锁定版本的对齐,引入不确定性,违背「最小可用」。 - 代价接受:本地 SDK 体积大(61 MB,全渲染器),但它是静态资源由 Nginx 托管 + 浏览器缓存, 非应用包(应用包仅 208 KB);首屏按需加载,体积不进 JS bundle。
结论:本期用本地 SDK,产物不依赖 CDN,符合约定。设计器二开(P4 后半)若需 amis-editor, 再评估 npm 包混合方案(editor 走 npm + 运行时渲染走本地 SDK)。
二、页面与契约
2.1 页面/路由
| 路由 | 页面 | 职责 |
|---|---|---|
/login |
LoginPage | POST /api/auth/login → 存 JWT → 跳转(回跳来源路径) |
/page/:templateId |
PageRenderPage | 取 schema → AmisRenderer 用本地 SDK 渲染(双闸渲染闸承接点) |
/todo |
TodoPage | GET /api/todo 列表 + 点击进业务页占位;503 降级展示 |
/、* |
重定向 | 默认进 /page/usergroup-manage;未登录守卫跳 /login |
2.2 后端契约清单
| 用途 | 方法 路径 | 响应/语义 | 契约来源 | 前端承接 |
|---|---|---|---|---|
| 登录签发 JWT | POST /api/auth/login |
{success,token,userId,account,name,roles,...} |
P2认证实测报告.md | src/api/auth.ts |
| 实体 amis CRUD | GET /api/entity/{t}/list |
amis 格式 {status:0,msg,data:{items,total}} |
EntityController(PoC 已 amis 格式) | AmisRenderer 自定义 fetcher |
| 待办聚合 | GET /api/todo |
列表;引擎不可达 → 503 FLOW_SERVICE_UNAVAILABLE |
P3网关实测报告.md | src/api/todo.ts(503 降级) |
| 页面 schema(生产) | GET /api/page/schema/{templateId} |
200 返回 amis 页面 schema(后端校验闸通过后下发) | 本期设计契约(P5 落地) | src/api/schema.ts(VITE_SCHEMA_SOURCE=backend) |
生产期 schema 接口契约(本期设计,后端 P5 实现):
GET /api/page/schema/{templateId} → 200 直接返回 amis 页面 schema(顶层 type:'page'),
由后端在官方 schema.json「校验闸」通过后下发;404 模板不存在;503 转换器不可用;鉴权带 Bearer。
开发期用静态 mock(public/schemas/)替代,前端经 VITE_SCHEMA_SOURCE 一行切换,生产无须改业务代码。
2.3 静态 schema(开发期 mock,真实转换产物)
3 个文件均为 eip4-poc 转换器对客户库(192.168.20.68:5435 eip3)真实模板的转换产物,
经 /api/poc/amis-schema 取得,并经 /api/poc/amis-validate(官方 schema.json 校验闸)验证:
| 文件 | 来源模板 | 实体表 | 校验闸 | 本地可联调 |
|---|---|---|---|---|
usergroup-manage.json |
用户组管理 | SYS_USERGROUP | ✅ schemaValid=true,0 错误 | ✅(本地已注册+有数据) |
role-maintain.json |
角色维护 | SYS_ROLE | ✅ schemaValid=true,0 错误 | 结构渲染(本地无该元数据) |
notice-archive.json |
通知管理归档 | OA_NOTICEMANAGE | ✅ schemaValid=true,0 错误 | 结构渲染(实体在客户库) |
选「用户组管理」作本地端到端联调主目标:其实体 SYS_USERGROUP 在 eip4m0 已由 bootstrap 注册且有数据。
2.4 amis fetcher 适配(关键)
AmisRenderer 用 amis.embed(container, schema, {}, { fetcher }) 注入自定义 fetcher:
复用宿主 axios(已带 Bearer 注入 + 401 跳登录拦截),amis 内置请求全部走该 fetcher。
后端 /api/entity 已是 amis CRUD 格式 {status:0,msg,data:{items,total}},响应无须再适配。
联调网络抓包证实:amis 发出的实体请求头含 authorization: Bearer ... + accept: application/json
(axios 默认头),证明走的是注入 fetcher 而非 amis 原生 fetch。
三、联调验证证据(无头浏览器 playwright)
后端三态并起:platform-app local(8084,连 eip4m0)+ prod 严格链(8090,验 401)+ PoC(8085,取 schema)。 flowable-service 未起(验证待办 503 降级)。
| # | 验证场景 | 方法 | 结果 | 截图 |
|---|---|---|---|---|
| 1 | 登录页渲染 | 导航 /login | ✅ 表单出 DOM,预填 alice | docs/01-login.png |
| 2 | 登录成功跳转 | 点登录(alice/123456) | ✅ 跳 /page/usergroup-manage |
— |
| 3 | 渲染「用户组管理」 | amis 本地 SDK 渲染 | ✅ 查询区(名称/说明+搜索)+ 表格 3 行真实数据(系统管理员组/项目管理组/审批归档组),数据来自本地库 SYS_USERGROUP | docs/02-render-usergroup.png |
| 4 | 渲染「角色维护」(真实转换产物) | 导航 + amis 渲染 | ✅ 查询区(角色名称/描述)+ 表格列;数据空态(SYS_ROLE 本地未注册,后端 status:1,amis 正确展示「暂无数据」) | docs/03-render-role.png |
| 5 | 待办 503 降级 | /todo(flowable 未起) | ✅ 网关返回 503 FLOW_SERVICE_UNAVAILABLE,页面降级展示橙色提示「工作流引擎暂不可达」,不崩 |
docs/04-todo-degraded.png |
| 6 | 401 流程 | 篡改令牌签名 → 重载 → amis fetcher 调 /api/entity(prod 8090 严格链) | ✅ 后端 401 → http 拦截器清会话 + 自动跳 /login(URL 变 /login) |
docs/05-401-redirect-login.png |
补充 curl 验证(prod 8090 严格链,印证 401 真实性):
| 场景 | HTTP |
|---|---|
无令牌访问 /api/entity/SYS_USERGROUP/list |
401 |
| 伪造令牌访问 | 401 |
| 正确登录 | 200 |
| 有效令牌访问实体 | 200(渲染 3 行) |
注:local profile(8084)为 permitAll 测试通道,伪造令牌不被拒(P2 报告设计); 故 401 流程在 prod 严格链(8090)上验证,顺带验证了「8090 备用端口 + 前端 VITE_BACKEND_TARGET 切换」。
src/ lsp/tsc 诊断:0 错误 0 警告(14 文件)。
四、构建产物(Nginx 托管形态)
npm run build(tsc -b && vite build)→ dist/,BUILD SUCCESS:
| 产物 | 大小 | 说明 |
|---|---|---|
dist/assets/*.js(应用包) |
208 KB(gzip ~71 KB) | React+路由+axios+业务,不含 amis SDK |
dist/index.html |
906 B | 引本地 SDK(/sdk-local/sdk.js 等)+ 应用入口 |
dist/sdk-local/ |
61 MB | amis 6.13.0 本地 SDK,原样拷贝,不参与打包、不依赖 CDN |
dist/schemas/ |
12 KB | 开发期静态 schema(生产改走后端接口) |
| dist 总计 | 62 MB | Nginx 直接托管;SPA 回退 + /api 反代 |
源码规模:src/ 14 文件 720 行。
五、双闸「渲染闸」在前端侧的承接设计
双闸 = 校验闸(官方 schema.json,draft-07 机器校验)+ 渲染闸(真实 SDK 运行时渲染冒烟)。
- 校验闸:在后端/转换器侧完成(
/api/poc/amis-validate或生产期 schema 接口下发前)。 本期 3 个 mock schema 均已过校验闸(schemaValid=true,0 错误),前端只消费已过闸的 schema。 - 渲染闸(前端承接):
AmisRenderer用 amis 真实 6.13.0 SDK 渲染 = 运行时渲染冒烟。- schema 能渲出查询区+表格 DOM = 渲染闸通过(联调场景 3/4 证实)。
- 渲染异常会暴露在 amis 错误边界与 console,即为渲染闸失败信号。
- 生产期闭环建议:后端 schema 接口在校验闸通过后下发;前端渲染闸由 CI 用 playwright 对每个转换产物跑「渲染冒烟断言」(DOM 出现关键结构)→ 与后端校验闸合成完整双闸自动化。
六、五条既定约定遵守核对
| 约定 | 遵守 |
|---|---|
| amis 锁 6.13.0 本地化,不依赖 CDN(来源 C5 构建预演) | ✅ public/sdk-local/ 拷自 eip4-poc;index.html 引本地 /sdk-local/*,无任何 CDN |
渲染宿主参照 PoC amis-local.html |
✅ amisRequire('amis/embed') + 本地 sdk.css/helper.css/iconfont.css,同范式 |
| 页面 schema 双闸,缺一不可 | ✅ 校验闸(3 schema 过校验)+ 渲染闸(前端真实 SDK 渲染);承接设计见 §五 |
| 设计器排 P4 后半 | ✅ 本期未做设计器,装配点见 §七遗留 |
| 渲染层备选方案指针 | ✅ README 记 lowcode-engine / ProComponents(架构设计第七节) |
七、遗留清单
- 设计器二开(amis-editor):P4 后半。装配点:新增路由
/designer,引 amis-editor (评估 npm 包混合:editor 走 npm + 运行时渲染仍走本地 SDK);产出 schema 经校验闸后落库/下发。 - 生产期 schema 接口:
GET /api/page/schema/{templateId}(本期已设计契约,P5 后端落地); 前端经VITE_SCHEMA_SOURCE=backend一行切换,无须改业务代码。 - 153 视图重写组件装配点:外包交付物集成。装配方式:amis 自定义渲染器注册
(
amisRequire暴露的Renderer注册 API),schema 用type:引用自定义组件; 建议在src/components/custom-renderers/下集中注册,AmisRenderer初始化时挂载。 - 主题:本期用 amis 默认
cxd主题(sdk.css)。如需暗色/品牌主题,切dark.css或定制 (本地 SDK 已含 cxd/dark/ang/antd 多套主题 css)。 - 待办→业务页映射表:本期点击待办跳
/page/{businessTable}占位; 生产需「业务表 → templateId」映射(可由后端随待办条目下发或前端配置表)。 - 依赖安全:
npm audit报 6 项(传递依赖,vite/esbuild 链),本期不阻断脚手架; 生产前npm audit fix或锁版本评估。
附:本地库自举(联调前置)
eip4m0 初始为空库,联调前依次灌入(顺序敏感):
bootstrap-sys.sql → bootstrap-privilege.sql → bootstrap-auth.sql (platform-parity)
bootstrap-datastatus.sql (platform-flow-gateway)
注:privilege/auth 尾部 EIP4PT_* 业务实体重分区报错可忽略(那些实体由 ParityCli --seed 动态建, 本地未种子化,不影响登录与 SYS_USERGROUP/SYS_USER 路径)。 本期另插 2 行 SYS_USERGROUP 演示数据(项目管理组/审批归档组),使表格出多行。