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>
This commit is contained in:
2026-06-11 16:13:17 +08:00
parent c51f37e228
commit b3486c093e
140 changed files with 88352 additions and 12 deletions

BIN
docs/01-login.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 17 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 42 KiB

BIN
docs/03-render-role.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 27 KiB

BIN
docs/04-todo-degraded.png Normal file

Binary file not shown.

After

Width:  |  Height:  |  Size: 40 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 17 KiB

185
docs/P4脚手架报告.md Normal file
View File

@@ -0,0 +1,185 @@
# 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 演示数据(项目管理组/审批归档组),使表格出多行。