iap-ui

v1.0.3

Published

7 days ago

云启千行

0High
0Medium
0Low

tiankazma1201

sunday2026

云启千行 vue vue.js component components ui framework

iap-web 项目内部交接文档

1. 文档目的

本文档面向团队内部成员，用于帮助新同学、维护同学和协作同学快速理解 iap-web 的工程定位、目录分工、开发方式、构建发布路径和常见问题处理方式。

本文档目标是回答下面这些实际问题：

这个仓库到底是做什么的
日常开发应该从哪里进入
改某一类需求时应该优先看哪些目录
这个项目怎么构建、怎么发布、怎么排查问题
哪些地方是历史包袱，修改时要特别谨慎

2. 项目定位

iap-web 不是单一业务系统前端，而是一个综合型前端平台工程，主要由 4 部分组成：

通用 UI 组件库
平台设计态前端
平台运行态前端
后台框架与工程构建体系

从代码结构上，可以把它理解成：

src
  -> 通用组件、公共样式、指令、工具

examples
  -> 组件文档与本地演示站

fbp
  -> 平台业务主体
  -> design: 设计态
  -> runtime: 运行态
  -> frame: 后台框架
  -> screen: 大屏

build / tools / scripts
  -> 工程配置、打包、样式产出、部署

一句话描述：

这是一个以 Vue 2 组件库为基础，同时承载低代码平台设计、运行和管理能力的多入口前端工程。

3. 技术栈与工程特征

核心技术

Vue 2.6.14
Vue Router 3.x
Vuex 3.x
Element UI 2.15.8
Webpack 3.11.0
Webpack Dev Server 2.11.3
Gulp
Less + Sass

典型工程特征

多入口页面工程，不是单页面 SPA
组件库和业务平台代码共仓
构建链路偏老，存在历史演进痕迹
样式采用 Less 变量主题体系
平台请求链路与鉴权逻辑耦合较深

当前维护判断

接手时请默认按照“稳定维护型老工程”心态处理，不建议直接做大范围工程升级。尤其是以下组合需要谨慎：

Vue 2 + Webpack 3
Babel 老配置
ESLint 与 TSLint 并存
iap-ui / qhui / fbp / iap-web 多命名共存

4. 目录职责划分

iap-web
├── src/
├── fbp/
├── examples/
├── build/
├── tools/
├── ai-proxy/
├── test/
├── build.sh
├── deploy.sh
├── package.json
└── vue.config.js

4.1 `src/`：通用组件与基础能力

这是组件库主体目录，也是大部分 UI 能力的来源。

关键子目录：

src/components/
- 通用组件主体，当前一级目录约 70 个
- 包含表单、布局、表格、树、弹窗、上传、时间选择、列表、分页等
src/views/
- 平台型视图组件
- 当前主要包括 frame、side-menu、user-select
src/directives/
- 全局指令
- 包括 watermark、clickoutside、transfer-dom
src/theme-variable/
- 样式与主题系统核心目录
src/locale/
- 国际化语言包
src/utils/
- 通用工具函数
src/index.js
- 组件库统一导出与安装入口

4.2 `fbp/`：平台业务主体

这是平台能力主目录，接手业务需求时通常都会落在这里。

`fbp/design/`

设计态模块，主要包含：

应用设计
表单设计
列表设计
模型设计
打印设计
大屏设计
设计器相关 store 和组件

`fbp/runtime/`

运行态模块，主要包含：

card 页面
list 页面
view 页面
dashboard 页面
login 页面
文件查看
workflow 运行页面

`fbp/frame/`

后台框架模块，主要包含：

登录
菜单
用户
组织
岗位
角色
通知
计划
日志
安全策略
工作流相关管理能力

`fbp/screen/`

大屏模块，主要用于大屏设计与预览。

`fbp/api/`

统一请求封装与拦截器逻辑。

`fbp/config/`

环境变量与部署路径配置。

4.3 `examples/`：组件文档与联调入口

这里不是临时测试目录，而是组件演示站和文档站。

主要职责：

作为组件开发的可视化联调入口
展示组件 demo
挂载 Markdown 文档内容

4.4 `build/`：构建中枢

build/ 是整个项目的构建核心，包含：

Webpack 公共配置
开发环境打包配置
生产环境打包配置
组件库产物配置
多语言包构建配置
样式构建脚本

4.5 `ai-proxy/`：主题 AI 代理服务

这是一个独立的小型 Node 服务，主要作用是：

代理主题 AI 相关请求
解决浏览器直连第三方模型接口时的跨域问题

5. 模块分工建议

从代码结构上，团队内部建议按下面方式分工理解：

组件与基础样式维护
- 重点关注 src/components/、src/theme-variable/
平台运行态维护
- 重点关注 fbp/runtime/、fbp/api/
后台框架维护
- 重点关注 fbp/frame/
设计器维护
- 重点关注 fbp/design/
大屏维护
- 重点关注 fbp/screen/
工程与发布维护
- 重点关注 build/、build.sh、deploy.sh

6. 新同学接手路径

第一天建议完成的事

先读 package.json
再读 src/index.js
再看 build/webpack.base.config.js
看 build/webpack.dev.config.js
看 build/webpack.prod.config.js
看 fbp/config/dev.env.js
看 fbp/config/prod.env.js
看 fbp/api/index.js
看 fbp/api/interceptors.js
运行一次本地开发环境

第一周建议建立的理解

知道 src 和 fbp 的边界
知道常用本地入口地址
知道构建产物在哪里
知道改组件和改平台页面的入口差异
知道请求链路和环境配置在哪

7. 本地开发说明

7.1 安装依赖

优先使用：

npm install -f

如果出现依赖兼容问题，可尝试：

npm install --legacy-peer-deps

7.2 启动开发环境

npm run dev

本地常用访问地址：

开发中心：http://localhost:8081/frame.html
运行框架：http://localhost:8081/main.html
运行时：http://localhost:8081/runtime.html
登录入口：http://localhost:8081/main.html#/login

7.3 关键入口文件

examples/main.js
- 组件演示站入口
fbp/dev.js
- 设计态入口
fbp/runtime.js
- 运行态入口
fbp/frame.js
- 后台框架入口

8. 常见需求改动对照

这一节用于帮助接手同学快速判断“改哪里”。

8.1 改通用组件

优先查看：

src/components/<组件名>/
src/theme-variable/
对应 demo/
examples/

典型场景：

输入框、按钮、选择器、表格、树、分页、对话框等通用能力修改

8.2 改组件样式或主题

优先查看：

src/theme-variable/variables/
src/theme-variable/common/
src/theme-variable/input/
src/theme-variable/interactive/
src/theme-variable/components/

8.3 改运行态页面

优先查看：

fbp/runtime/
fbp/api/
fbp/config/
必要时联动 src/components/

典型场景：

运行表单
运行列表
dashboard 展示
文件查看
运行态流程页面

8.4 改后台框架能力

优先查看：

fbp/frame/
fbp/api/
src/views/
src/theme-variable/components/frame/

典型场景：

登录页
主框架页
菜单
用户组织角色
消息通知

8.5 改设计器

优先查看：

fbp/design/
fbp/design/store/
fbp/design/designer/
fbp/design/dashboard/

典型场景：

表单设计
列表设计
模型设计
打印设计
大屏设计

8.6 改请求逻辑或接口适配

优先查看：

fbp/api/index.js
fbp/api/interceptors.js
fbp/config/*.env.js

9. 构建与产物说明

9.1 常用构建命令

页面构建

npm run build
npm run build:win
npm run build:iap
npm run build:nocode
npm run build:nocode-base

说明：

这几类构建的区别主要来自 BUILD_ENV
不同环境会影响接口前缀、根路径和运行时入口地址

组件库构建

npm run dist
npm run dist:style
npm run dist:dev
npm run dist:prod
npm run dist:locale
npm run mini

9.2 构建产物位置

`dist/`

组件库产物，典型内容：

fbp.js
fbp.min.js
qhui.core.min.js
styles/qhui.css
styles/qhui.min.css
locale/*

`examples/dist/`

页面构建产物，典型内容：

index.html
dev.html
runtime.html
frame.html
main.html
screen.html
print.html
对应 JS 资源与 vendor.bundle.js

9.3 构建配置重点

建议重点了解这些文件：

build/webpack.base.config.js
build/webpack.dev.config.js
build/webpack.prod.config.js
build/webpack.dist.dev.config.js
build/webpack.dist.prod.config.js
build/webpack.dist.locale.config.js
build/webpack.dist.mini.config.js
build/build-style.js

10. 环境配置说明

10.1 开发环境

fbp/config/dev.env.js 中当前关键变量：

PATH = "/iap-service/"
ROOT = "http://localhost:8081/"
FORM_ROOT = "http://localhost:8081/runtime.html#/"

10.2 生产环境

fbp/config/prod.env.js 根据 BUILD_ENV 切换：

win
iap
nocode
nocode-base

影响范围：

前端根路径
接口路径
运行态入口
移动端入口

10.3 环境问题排查建议

如果出现以下问题，优先检查 fbp/config/：

页面打开后资源路径不对
接口地址不对
登录跳转地址不对
运行态页面地址不对

11. 请求链路说明

统一请求封装位于：

fbp/api/index.js
fbp/api/interceptors.js

当前拦截器主要职责：

统一设置 baseURL
登录超时处理与跳转
错误提示
请求体加密
附带 ResourceId
白名单接口豁免鉴权
非白名单接口补 Authorization

修改这部分时要注意

不要只看前端表现，要确认是否影响网关和后端协议
修改请求头或加密逻辑前，要先确认是否有其他页面共享
如果登录态跳转异常，先看这里，再看路由层

12. 样式与主题说明

样式主目录是 src/theme-variable/，采用 Less 变量驱动。

可按下面方式理解：

variables/
- 通用颜色、尺寸、主题变量
common/
- 通用组件样式
input/
- 输入类组件样式
interactive/
- 按钮、提示、弹层、工具栏等
components/
- 平台级组件样式
nav/
- 菜单、分页、锚点等导航类样式
icon/
- 图标字体

样式问题排查建议

如果遇到：

组件功能正常但样式异常
某些主题变量未生效
构建后样式缺失

优先检查：

src/theme-variable/index.less
对应组件 less 文件是否已引入
build/build-style.js

13. 文档与 Demo 体系

项目文档采用“组件 demo + Markdown loader”模式。

关键点：

组件目录通常自带 demo/
demo/*.md 负责文档内容
demo/index.vue 负责汇总展示
tools/mdloader/ 把 Markdown 转成 Vue 组件

团队建议

如果修改了组件交互或参数，建议同步更新：

demo
API 文档
示例截图或说明

避免组件行为已经变化，但内部文档还是旧的。

14. AI 代理服务说明

ai-proxy/ 是主题 AI 功能配套服务。

启动方式

cd ai-proxy
npm install
npm start

默认服务地址：

http://localhost:3780

当前接口：

POST /ai/theme/generate
POST /ai/theme/chat

15. 发布与部署说明

15.1 本地构建脚本

build.sh 主要流程：

清理旧产物
安装依赖
执行组件库构建
执行页面构建
拷贝输出目录

15.2 部署脚本

deploy.sh 主要流程：

检查 Docker 与 Git
git pull
使用容器安装依赖
执行 npm run build:iap
将构建产物部署到 /opt/icd/html/web
旧版本目录存在时自动备份

15.3 发版前建议检查项

发版前建议至少确认：

本地依赖安装正常
npm run build:iap 能跑通
关键入口页可正常访问
登录页与运行态跳转正常
样式产物正常
接口前缀未被误改
构建产物路径符合部署环境预期

16. 常见问题与处理建议

16.1 为什么项目里既有 `iap-ui` 又有 `fbp`？

因为项目经历过多阶段演进：

iap-ui 更偏组件库命名
fbp 更偏平台能力命名

目前二者共存在同一仓库中。

16.2 为什么看起来既像组件库又像业务平台？

因为这个项目本身就是“组件库 + 平台业务”复合工程，不能按普通组件库或普通后台项目的思路单独理解。

16.3 为什么 `vue.config.js` 很简单，但工程仍然复杂？

因为主构建链路实际在 build/ 目录的 Webpack 配置中，vue.config.js 当前只承担少量辅助作用。

16.4 为什么测试命令可能不稳定？

package.json 中保留了 karma 单测脚本，但本地项目当前没有看到完整的 test/unit/ 目录，说明测试链路大概率处于历史遗留状态。

16.5 为什么构建对 Node 版本敏感？

因为当前工程构建链路较老，而仓库里又已经兼容了较新的 Node 场景。代码中已经出现针对 build:iap 的特殊兼容处理，因此后续变更构建插件时要特别谨慎。

17. AI 与 .iap Skills

仓库内已经预留 .iap/skills/ 目录，用来放面向 AI / 智能体的项目内技能。

当前已补充：

.iap/mcp.json
- 项目内通用 MCP 配置声明
- 使用 mcpServers 结构声明 figma MCP，便于不同 AI 工具接入时复用
.iap/mcpServers/figma.json
- 项目内按目录拆分的 MCP Server 配置
- 便于不同工具按服务粒度读取或组装
.iap/config.toml
- 项目内 MCP 配置
- 已启用 figma MCP
.iap/skills/blocks-page-builder/SKILL.md
- 用于基于区块模板和现有组件库组件创建平台页面
- 适合 fbp/frame、fbp/runtime、fbp/design 中的新页面或重构页面
.iap/skills/iap-web-development/SKILL.md
- 用于在这个仓库内进行通用开发、排查、重构和模块归类
- 适合作为 AI / 智能体进入项目时的第一层开发技能
.iap/skills/blocks-page-generator/SKILL.md
- 用于根据页面需求直接生成页面代码
- 负责模块落点、区块模板选择、组件拼装和联动代码生成
.iap/skills/blocks-page-alignment/SKILL.md
- 用于把现有存量页面和 block 模版对齐
- 重点约束“替换页面骨架但不改业务逻辑”，适合菜单管理、组织管理、设置页等老页面改造

这个 skill 的核心约束是：

优先使用 src/components/blocks/ 里的组合块
优先使用现有 iap-ui 组件，不臆造新组件
页面交互按现有 blocks 约定处理
- 树联动：BlockTree @on-select-change
- 表格联动：gridProps.onSelectRow
- Grid 数据加载：this.$refs.xxx.loadData({ Rows })

如果后续继续扩展 AI 页面生成能力，建议优先在 .iap/skills/ 下新增或迭代 skill，而不是把大量 AI 操作说明散落在业务目录里。

17.1 本地开发代理覆盖

开发环境默认配置为：

fbp/config/dev.env.js
- PATH: '"/iap-service/"'
build/webpack.dev.config.js
- 代理目标默认走 http://10.110.124.141:30080

为避免联调本地后端时误改默认配置并提交到仓库，当前工程已支持本地覆盖文件：

默认配置入口
- build/dev.config.js
本地覆盖示例
- build/dev.local.example.js
本地实际覆盖文件
- build/dev.local.js
- 该文件已加入 .gitignore

如果需要联调本地后端，可在本地创建 build/dev.local.js：

'use strict'

module.exports = {
  apiPath: '"/"',
  proxyTarget: 'http://localhost:8086',
}

如果没有该文件，工程会始终使用仓库默认配置。

18. 风险提示

以下内容属于高风险修改区，改动前建议先评估影响范围：

build/ 下的 Webpack 配置
fbp/config/ 下的环境配置
fbp/api/interceptors.js
src/index.js
src/theme-variable/index.less
登录态、跳转逻辑、请求加密逻辑

修改这些内容前建议先做的事

明确影响的是组件库、运行态还是后台框架
确认是否存在多入口共享逻辑
确认是否影响发布脚本和部署路径
尽量先做小步验证，再扩大修改范围

19. 后续建议补充项

如果团队后续继续维护这份文档，建议继续补齐：

实际模块负责人
需求提交流程
发版责任人
回滚流程
常见线上故障案例
关键接口清单
页面入口与路由对照表

20. 总结

对于团队内部来说，最重要的不是记住每个目录细节，而是先建立这三个认知：

src 是通用底座，fbp 是平台主体。
这是多入口平台工程，不是普通 Vue 单页项目。
这个项目可维护，但不适合激进升级，优先保证稳定交付。

如果你是新接手同学，建议先跑通本地环境，再按“组件库 -> 构建链路 -> 平台模块”的顺序逐层理解，效率会最高。

21.项目扩展

21.1 单点登录

# redirect参数: 单点登录成功后要跳转的页面
# 示例
http://域名:端口号/web/main.html#/login?redirect=/web/main.html#/flowRender

# 同域下可省略域名和端口号
# 示例
/web/main.html#/login?redirect=/web/main.html#/flowRender

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

iap-web 项目内部交接文档

1. 文档目的

2. 项目定位

3. 技术栈与工程特征

核心技术

典型工程特征

当前维护判断

4. 目录职责划分

4.1 src/：通用组件与基础能力

4.2 fbp/：平台业务主体

fbp/design/

fbp/runtime/

fbp/frame/

fbp/screen/

fbp/api/

fbp/config/

4.3 examples/：组件文档与联调入口

4.4 build/：构建中枢

4.5 ai-proxy/：主题 AI 代理服务

5. 模块分工建议

6. 新同学接手路径

第一天建议完成的事

第一周建议建立的理解

7. 本地开发说明

7.1 安装依赖

7.2 启动开发环境

7.3 关键入口文件

8. 常见需求改动对照

8.1 改通用组件

8.2 改组件样式或主题

8.3 改运行态页面

8.4 改后台框架能力

8.5 改设计器

8.6 改请求逻辑或接口适配

9. 构建与产物说明

9.1 常用构建命令

页面构建

组件库构建

9.2 构建产物位置

dist/

examples/dist/

9.3 构建配置重点

10. 环境配置说明

10.1 开发环境

10.2 生产环境

10.3 环境问题排查建议

11. 请求链路说明

修改这部分时要注意

12. 样式与主题说明

样式问题排查建议

13. 文档与 Demo 体系

团队建议

14. AI 代理服务说明

启动方式

相关联配置

15. 发布与部署说明

15.1 本地构建脚本

15.2 部署脚本

15.3 发版前建议检查项

16. 常见问题与处理建议

16.1 为什么项目里既有 iap-ui 又有 fbp？

16.2 为什么看起来既像组件库又像业务平台？

16.3 为什么 vue.config.js 很简单，但工程仍然复杂？

16.4 为什么测试命令可能不稳定？

16.5 为什么构建对 Node 版本敏感？

17. AI 与 .iap Skills

17.1 本地开发代理覆盖

18. 风险提示

修改这些内容前建议先做的事

19. 后续建议补充项

20. 总结

21.项目扩展

21.1 单点登录

4.1 `src/`：通用组件与基础能力

4.2 `fbp/`：平台业务主体

`fbp/design/`

`fbp/runtime/`

`fbp/frame/`

`fbp/screen/`

`fbp/api/`

`fbp/config/`

4.3 `examples/`：组件文档与联调入口

4.4 `build/`：构建中枢

4.5 `ai-proxy/`：主题 AI 代理服务

`dist/`

`examples/dist/`

16.1 为什么项目里既有 `iap-ui` 又有 `fbp`？

16.3 为什么 `vue.config.js` 很简单，但工程仍然复杂？