Files
eip4-web/docs/P4脚手架报告.md
zhengwr b3486c093e feat: P4-3 eip4-web 前端渲染宿主脚手架(amis 6.13.0 本地化/登录JWT/待办/双闸渲染闸)
- 脚手架: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>
2026-06-11 16:13:17 +08:00

11 KiB
Raw Permalink Blame History

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(架构设计第七节)

七、遗留清单

  1. 设计器二开(amis-editor):P4 后半。装配点:新增路由 /designer,引 amis-editor (评估 npm 包混合:editor 走 npm + 运行时渲染仍走本地 SDK);产出 schema 经校验闸后落库/下发。
  2. 生产期 schema 接口:GET /api/page/schema/{templateId}(本期已设计契约,P5 后端落地); 前端经 VITE_SCHEMA_SOURCE=backend 一行切换,无须改业务代码。
  3. 153 视图重写组件装配点:外包交付物集成。装配方式:amis 自定义渲染器注册 (amisRequire 暴露的 Renderer 注册 API),schema 用 type: 引用自定义组件; 建议在 src/components/custom-renderers/ 下集中注册,AmisRenderer 初始化时挂载。
  4. 主题:本期用 amis 默认 cxd 主题(sdk.css)。如需暗色/品牌主题,切 dark.css 或定制 (本地 SDK 已含 cxd/dark/ang/antd 多套主题 css)。
  5. 待办→业务页映射表:本期点击待办跳 /page/{businessTable} 占位; 生产需「业务表 → templateId」映射(可由后端随待办条目下发或前端配置表)。
  6. 依赖安全: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 演示数据(项目管理组/审批归档组),使表格出多行。