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

186 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 演示数据(项目管理组/审批归档组),使表格出多行。