166 lines
8.0 KiB
Markdown
166 lines
8.0 KiB
Markdown
# abacus-static-framework — 架构文档（ARCHITECTURE）
|
||
|
||
> 模块、依赖、契约、目录布局的**唯一权威**（本仓库视角）。新增/重命名/移动模块或调整依赖方向，必须先改本文，再改代码（同一个 commit）。
|
||
> 上游：`PRD.md`（行为）。前后端共享约束见工作区 `docs/`（`../../../../docs/coding-standards.md`、`../../../../docs/architecture.md`），本文不复制其正文。
|
||
|
||
## 0. 阅读指引
|
||
|
||
本文描述前端底座的模块划分与依赖方向；§2 模块清单与 §6 目录一一对应，§3.2 是跨模块接口契约（写代码必须遵守）。新会话先读 §2 + §6 定位任务归属，再动手。
|
||
|
||
## 1. 领域模型（Domain Model）
|
||
|
||
### 1.1 实体
|
||
|
||
前端无持久化实体；领域概念即运行时状态：
|
||
|
||
| 实体 | 字段 | 关系 | 持久化？ |
|
||
|---|---|---|---|
|
||
| 用户会话（userStore） | access_token/refresh_token/expires_dt/user_type | 全局单例 | 否（localStorage） |
|
||
| 菜单/路由（permissionStore） | routes（过滤后）、menuTree | 依赖后端菜单接口 | 否（内存） |
|
||
| 应用设置（settingsStore） | backendServices、loginType、loginAddress | 来自 window.frameBaseConfig | 否（运行时注入） |
|
||
|
||
### 1.2 派生概念（非持久化）
|
||
|
||
- `backendServices` 别名→真实服务名映射（`window.frameBaseConfig` 注入）。
|
||
- 当前路由上下文（`currentRouter()`）用于组装 commonParam（menuName/moduleId/moduleName）。
|
||
|
||
### 1.3 不变量（任何模块都必须维护）
|
||
|
||
- I1. `src/framework/**` 只读：业务代码不得 import 后修改框架文件；框架变更只能由框架负责人进行。
|
||
- I2. 业务请求一律经 `framework/utils/request.ts`，禁止裸 `axios`/`fetch`。
|
||
- I3. 服务别名首段必须是 `settingsStore.backendServices` 中已注册的键。
|
||
|
||
## 2. 模块清单
|
||
|
||
按依赖层级从低到高排列。
|
||
|
||
### Layer 0 — framework/utils（基础设施）
|
||
```
|
||
## 模块名：framework/utils
|
||
- 职责：请求管线（request.ts）、标准工具（standard/*：vxe、dataHandleUtil、globalHandle、security、baiduMap）
|
||
- 不负责：业务逻辑、页面状态
|
||
- 输入：各业务模块的请求配置
|
||
- 输出：统一响应体解包后的数据 / Blob；标准工具函数
|
||
- 关键类型/接口：request(config) -> Promise<data>；gridDefaultProps(opts)；useQueryParamsHandle(...)
|
||
- 持有状态：token 刷新队列（模块内闭包）、settingsStore 引用
|
||
```
|
||
|
||
### Layer 0 — framework/components/standard（视觉基座）
|
||
```
|
||
## 模块名：framework/components/standard
|
||
- 职责：标准 UI 组件（AbForm/AbQueryForm/AbSection/ClickCopy/FilePreviewDialog/ImportExcel/LogShow/RealTimeSearchSelect/SensitiveText/Text/BottomFloat）
|
||
- 不负责：业务特有布局（业务自建 components）
|
||
- 输入：props/插槽
|
||
- 输出：统一风格组件
|
||
- 持有状态：无（受控组件）
|
||
```
|
||
|
||
### Layer 1 — framework/store（有状态服务）
|
||
```
|
||
## 模块名：framework/store
|
||
- 职责：全局 Pinia 状态（settings：backendServices/loginType；permission：菜单生成与过滤；user：token/业务域）
|
||
- 不负责：页面级状态（业务自建 store）
|
||
- 输入：window.frameBaseConfig、后端菜单接口
|
||
- 输出：状态与 actions
|
||
- 持有状态：是
|
||
```
|
||
|
||
### Layer 2 — framework/router + hooks + directives（路由与通用逻辑）
|
||
```
|
||
## 模块名：framework/router + hooks + directives
|
||
- 职责：静态路由与动态路由装配支持；useVxeTableHandle 等通用组合式函数；v-debounce/v-throttle 指令
|
||
- 不负责：业务菜单路由（subsystem/router/dynamicRouter.ts）
|
||
- 输入：permissionStore 过滤后的路由
|
||
- 输出：可用路由表、表格查询联动能力
|
||
- 持有状态：路由表（由 permissionStore 维护）
|
||
```
|
||
|
||
### Layer 3 — subsystem（业务可写区）
|
||
```
|
||
## 模块名：subsystem
|
||
- 职责：业务子系统（api 封装、dynamicRouter 菜单路由、views 页面、extend 扩展、自建 components/hooks/store/styles/types/utils）
|
||
- 不负责：框架能力（一律复用 framework）
|
||
- 输入：后端接口、用户操作
|
||
- 输出：业务页面与接口调用
|
||
- 持有状态：业务自身状态（自建 store）
|
||
```
|
||
|
||
## 3. 依赖图（DAG）
|
||
|
||
```mermaid
|
||
graph TD
|
||
subsystem --> framework_utils[framework/utils]
|
||
subsystem --> framework_components[framework/components/standard]
|
||
subsystem --> framework_hooks[framework/hooks]
|
||
subsystem --> framework_router[framework/router]
|
||
framework_router --> framework_store[framework/store]
|
||
framework_hooks --> framework_utils
|
||
framework_hooks --> framework_components
|
||
framework_store --> framework_utils
|
||
framework_utils --> framework_store
|
||
```
|
||
|
||
### 3.1 依赖方向规则
|
||
|
||
- 高层依赖低层；业务（subsystem）依赖框架（framework），框架各层按上图单向；**反向依赖一律禁止**（如 framework 不得 import subsystem）。
|
||
- 例外：`framework/utils/request.ts` 依赖 `framework/store`（settingsStore）获取别名映射——两者同属 framework 层，允许。
|
||
|
||
### 3.2 跨模块接口契约（写代码时必须遵守的签名）
|
||
|
||
```
|
||
// module: framework/utils/request
|
||
// request(config: {url, method, params|data, headers?, custom?}) -> Promise<data> // status===200 已解包 data；ArrayBuffer 返回整个 response
|
||
// url 首段 = 服务别名（I3），自动携带 token/commonParam（I2）
|
||
|
||
// module: framework/utils/standard/vxe
|
||
// gridDefaultProps(opts: {params, rowConfig, pagerConfig, proxyConfig, columns}) -> VxeGridProps
|
||
|
||
// module: framework/hooks/useVxeTableHandle
|
||
// useQueryParamsHandle(params, page, sorts, filters) -> query params // 分页契约 {data,total}，见共享规范 §6.4
|
||
// useTableQueryReload(...) / useInVxeGridSearch(...)
|
||
```
|
||
|
||
## 4. 持久化与边界
|
||
|
||
- 无后端式持久化；前端持久化仅 token（localStorage，由 userStore 管理）。
|
||
- 外部边界：所有 HTTP 请求必须经 request.ts；开发期经 vite proxy；运行时经 Nginx 反代；`window.frameBaseConfig` 由宿主页面注入（含 backendServices）。
|
||
|
||
## 5. 测试边界
|
||
|
||
- 无自动化单测（PRD 已声明）；每页面人工冒烟（列表/查询/新增/编辑/导出）。
|
||
- 真机/真环境必验：多数据源路由、Kafka 消费、XXL-JOB 调度、Nacos 配置拉取、真实数据库迁移（属后端，但前端联调需一并验证）。
|
||
|
||
## 6. 目录结构（与 §2 模块清单一一对应）
|
||
|
||
```
|
||
src/
|
||
├── framework/ # Layer 0~2（只读共享）
|
||
│ ├── api/ components/ hooks/ layout/ router/ store/ styles/ types/ utils/ views/ directives/
|
||
│ └── utils/request.ts # 请求管线（契约见 §3.2）
|
||
├── subsystem/ # Layer 3（业务可写区）
|
||
│ ├── api/<服务别名>/ # 按 Controller 分 ts（如 sms/{index,applog,abnormal,config}.ts）
|
||
│ ├── router/dynamicRouter.ts # 菜单路由唯一注册点
|
||
│ ├── views/<一级菜单>/<二级菜单>/index.vue
|
||
│ ├── extend/ # 框架扩展钩子
|
||
│ └── (自建) components/ hooks/ store/ styles/ types/ utils/
|
||
├── permission.ts # 全局路由守卫（生成/过滤动态路由）
|
||
└── main.ts # 入口
|
||
```
|
||
|
||
## 7. 自检（架构健康度三问）
|
||
|
||
1. 出 bug 了，能否 30 秒内指出是 framework 还是 subsystem、哪个子目录的责任？
|
||
2. 替换 UI 库/表格库，改动能否控制在 framework/components 与 utils/standard 内 + 适配层？
|
||
3. 加新业务页面，能否立刻说出落在 `subsystem/views/<一级>/<二级>/` 哪个位置？
|
||
|
||
## 8. 待办与已知技术负债
|
||
|
||
- 前端 README 引用的 `docs/` 文档中心已补齐（`../../../../docs/`）。
|
||
- 旧框架兼容入口 `externalOldERPIndex`（data.js）仅在需要兼容历史模块时配置。
|
||
|
||
## 9. 文档变更协议
|
||
|
||
- 加/删模块或改依赖方向 → 改本文 §2 + §3，同一 commit。
|
||
- 改对外签名（request/gridDefaultProps 等）→ 先改 §3.2，再改代码。
|
||
- 与 `PRD.md` 冲突 → 以 `PRD.md` 为准，回改本文；与共享 `docs/coding-standards.md` 冲突 → 以 docs/ 为准并回改本文。
|