1.3 业务规范

在企业级后台系统中，业务逻辑往往复杂、层级多、交互密集。为了保证系统的可维护性与团队协作效率，我们需要在开发过程中遵循统一的业务实现规范。

本规范主要围绕应用结构设计和用户交互控制展开，帮助团队在开发过程中形成一致的编码习惯和设计思路。

一、应用结构

1. 分层架构设计

UI 层（View）

负责页面展示和用户交互，由 Vue/React 组件构成；

• 页面组件存放在 views/*，对应具体路由；
• 通用组件存放在 components/*，如表格、按钮、表单控件等；

逻辑层（ViewModel / Controller）

处理数据转换、状态管理、业务流程；

• 使用 Pinia（Vue）或 Zustand（React）进行全局状态管理；
• 避免多个组件之间直接共享状态，通过统一的状态中心通信；

服务层（Service）

封装 API 请求、本地存储、缓存处理；

• 所有网络请求统一调用封装后的 service 方法；
• 支持拦截器统一处理错误、加载状态、权限问题；

模型层（Model）

定义接口类型、数据结构；

• TypeScript 接口统一存放于 types/ 或 models/ 目录；

示例目录结构

src/
├── views/
│   └── user/
│       ├── UserList.vue
│       └── UserDetail.vue
├── components/
│   └── common/
│       ├── DataGrid.vue
│       └── SearchBar.vue
├── services/
│   └── user.service.ts
├── types/
│   └── user.model.ts
├── store/
│   └── user.store.ts
└── router/
    └── user.routes.ts

2. 模块化开发模式

• 按功能模块划分代码，如 userModule、orderModule；
• 每个模块包含独立的组件、服务、路由、样式等资源；
• 支持按需加载，提升首屏加载速度；
• 公共模块抽取为 shared 目录，便于复用；

3. 路由配置策略

• 路由与菜单绑定，支持动态加载；
• 使用嵌套路由组织父子页面关系；
• 路由守卫用于权限验证、登录跳转；
• 路由路径命名清晰，如 /user/list、/order/detail/:id；

4. 状态管理策略

• 使用 Pinia（Vue）或 Zustand（React）进行状态管理；
• 明确状态变更流程（如 Action -> Mutation -> State）；
• 避免多个组件之间直接共享状态，通过统一的状态中心通信；
• 对敏感状态（如用户信息、权限）做持久化处理；

5. 生命周期使用建议

• 在组件/页面中合理使用生命周期钩子函数；

  • Vue：onMounted、onBeforeUnmount
  • React：useEffect

• 避免在生命周期中执行过多副作用，建议封装为可复用的服务方法；

• 清理副作用（如定时器、事件监听）在组件销毁前完成；

二、用户交互

1. 表单交互规范

• 所有表单字段应有明确的 label 和 placeholder；
• 必填项使用红色星号标记；
• 表单提交前进行校验，错误提示定位到对应字段；
• 异步校验（如用户名是否已存在）应给出 loading 提示；
• 表单提交成功后给予明确反馈（如 Toast 提示、跳转页面）；

2. 按钮行为规范

• 主操作按钮突出显示（如蓝色背景）；
• 辅助操作按钮采用次级样式（如灰色边框按钮）；
• 禁用状态下按钮不可点击，并给出视觉反馈；
• 提交类按钮在请求期间显示 loading 状态，防止重复提交；

3. 错误与提示机制

• 页面异常统一展示“空状态”或“错误页”（如 404、网络异常）；
• 后端接口错误码统一处理，避免裸露原始错误信息；
• 用户操作失败时，提示应具备指导性（如“请检查网络后重试”）；
• 成功提示使用绿色图标 + 简短文案，如“保存成功”；

4. 加载与过渡体验

• 首屏内容优先渲染，非关键资源延迟加载；
• 数据请求期间展示骨架屏或 Loading 动画；
• 页面切换使用平滑动画，增强用户体验；
• 大型操作（如文件上传、复杂计算）应提供进度条；

5. 权限与引导机制

• 根据用户角色动态控制菜单和按钮的可见性；
• 初次使用功能时提供引导提示（如 Tooltip、弹窗）；
• 敏感操作（如删除、清空）应二次确认，避免误操作；
• 所有权限受限的操作加灰处理，并提示无权限原因；

6. 数据交互规范

• 分页、排序、筛选等交互统一设计；
• 所有分页组件支持自定义每页数量；
• 表格列支持排序、筛选、固定列等功能；
• 所有异步数据操作提供 loading 状态反馈；

7. 日志与埋点机制

• 所有关键操作添加埋点，如按钮点击、页面进入、接口失败；
• 日志记录统一格式，如 click、submit；
• 上线前移除调试日志输出；
• 所有埋点上报统一封装，便于后期接入分析平台；