# F006 新管理后台 - 架构原则

> **核心铁律**:本项目在设计架构时,必须把"后续修改的灵活性、可配置性、先进性、前瞻性"放在第一位。
> 老的 renren-cloud-admin 之所以改不动,就是因为缺乏这 4 个性质。

## 1. 4 个核心原则

### 1.1 灵活性(Flexibility)
- **业务代码不耦合样式**:每个 view 模板只关心数据流,样式全部从主题/布局组件继承
- **可插拔的目录约定**:`src/modules/{模块名}/` 每个模块自带 `views/`、`api/`、`types/`、`components/`,删除模块 = 删除文件夹
- **运行时配置**:菜单、路由、权限都从后端拉,不在前端硬编码

### 1.2 可配置性(Configurability)
- **主题系统由配置驱动**:新增主题 = 加 22 个 CSS 变量 + ThemePicker 加一个按钮,不改业务代码
- **菜单从后端配置**:管理员可以在系统里改菜单,前端不用动
- **权限从后端配置**:按钮级别权限 = `v-permission="'sys:user:add'"`,不写死在组件里
- **页面配置化**:列表页的列、搜索项、筛选条件都在 meta 配置里,不改代码就能加列

### 1.3 先进性(State of the Art)
- **Vue 3.4 Composition API + `<script setup>`**(不混用 Options API)
- **Pinia**(不混用 Vuex)
- **TypeScript 严格模式**(`strict: true`)
- **Vite 5+**(不混用 Webpack/Vue CLI)
- **Element Plus 2.4+**(用新主题系统,不覆写内部 CSS)
- **SCSS Modules**(组件级样式隔离,不全局污染)

### 1.4 前瞻性(Future-proof)
- **预留微前端入口**:用 Vite Module Federation 或 qiankun,后期可以拆出独立模块
- **预留 i18n 接口**:组件文案都走 `t('key')`,即使现在只有中文
- **预留暗色模式**:主题系统已经是 4 套,加第 5 套(比如企业定制色)只改 22 个变量
- **预留 OpenAPI 集成**:api 层用类型化客户端,后期后端换 schema 前端零改动
- **预留移动端**:布局组件按响应式写,后期加移动端只需要换 layout

## 2. 目录结构(按"修改灵活性"优化)

```
admin_new/
├── ARCHITECTURE.md                # 本文档(架构原则,所有开发必读)
├── .env                           # 环境变量(API 地址、开关)
├── .env.development
├── .env.production
├── package.json
├── vite.config.ts                 # 构建配置
├── tsconfig.json
├── index.html
├── public/
├── src/
│   ├── main.ts                    # 启动入口(主题恢复 + 路由 + store + UI 库)
│   ├── App.vue                    # 根组件(只决定 layout 策略)
│   │
│   ├── theme/                     # 主题系统(独立子模块,可整体替换)
│   │   ├── tokens.scss            # 22 个 CSS 变量(主题无关部分)
│   │   ├── themes.scss            # 4 套主题(主题相关部分)
│   │   ├── presets.ts             # 主题选项配置(新增主题只改这里)
│   │   └── README.md              # 主题系统使用说明
│   │
│   ├── layout/                    # 布局组件(顶栏 + 侧边栏 + 内容区)
│   │   ├── AppLayout.vue          # 主布局
│   │   ├── TopBar.vue             # 顶栏
│   │   ├── SideBar.vue            # 侧边栏
│   │   ├── ThemePicker.vue        # 主题切换器
│   │   └── UserMenu.vue           # 用户菜单
│   │
│   ├── router/
│   │   ├── index.ts               # 路由配置
│   │   ├── routes.ts              # 静态路由(从后端拉的也注入这里)
│   │   └── guards.ts              # 路由守卫
│   │
│   ├── stores/                    # Pinia 状态管理
│   │   ├── user.ts                # 用户 + token
│   │   ├── theme.ts               # 当前主题
│   │   ├── menu.ts                # 菜单(从后端拉)
│   │   └── permission.ts          # 权限(v-permission 用)
│   │
│   ├── api/                       # API 层(所有 HTTP 请求)
│   │   ├── request.ts             # axios 封装(拦截器 + token 注入)
│   │   ├── auth.ts                # 登录/登出
│   │   ├── menu.ts                # 菜单 + 权限
│   │   └── ...
│   │
│   ├── modules/                   # 业务模块(每个模块独立,可整体删除)
│   │   ├── dashboard/             # 数据看板
│   │   │   ├── DashboardView.vue
│   │   │   ├── api.ts
│   │   │   ├── types.ts
│   │   │   └── components/
│   │   ├── inquiry/                # 询价管理
│   │   ├── order/                  # 订单管理
│   │   ├── supplier/               # 供应商
│   │   ├── user/                   # 用户/角色
│   │   └── system/                 # 系统设置
│   │
│   ├── components/                # 全局通用组件(跨模块)
│   │   ├── DataTable/             # 通用列表(分页 + 搜索 + 列配置)
│   │   │   ├── DataTable.vue
│   │   │   ├── types.ts           # 列配置类型
│   │   │   └── README.md
│   │   ├── StatusTag/             # 状态徽章
│   │   ├── SearchForm/            # 搜索表单
│   │   └── PageContainer/         # 页面容器(统一 padding + 面包屑)
│   │
│   ├── composables/               # Vue 3 组合式 API(可复用逻辑)
│   │   ├── useTable.ts            # 列表逻辑(分页 + 搜索 + 加载)
│   │   ├── usePermission.ts       # 权限判断
│   │   └── useDict.ts             # 字典查询
│   │
│   ├── directives/                # 全局指令
│   │   ├── permission.ts          # v-permission
│   │   └── copy.ts                # v-copy
│   │
│   ├── utils/                     # 工具函数
│   │   ├── auth.ts                 # token 存储
│   │   ├── format.ts               # 格式化
│   │   └── request.ts              # 旧兼容(逐步废弃)
│   │
│   ├── styles/                    # 全局样式
│   │   ├── reset.scss
│   │   └── global.scss
│   │
│   ├── icons/                     # 图标(按需引入)
│   │   └── index.ts
│   │
│   ├── types/                     # 全局类型定义
│   │   ├── api.ts                  # 通用 API 响应类型
│   │   └── global.d.ts
│   │
│   └── env.d.ts
└── Dockerfile                      # nginx 镜像
```

## 3. 关键架构决策(为什么这么做)

### 3.1 为什么用 `src/modules/` 而不是 `src/views/`
- **修改灵活**:删除一个模块 = 删除一个文件夹,不会污染其他模块
- **团队协作**:不同人负责不同模块,merge 冲突少
- **微前端准备**:后期可以拆出独立 module,用 qiankun 加载

### 3.2 为什么菜单从后端拉
- **配置灵活**:管理员可以在系统里改菜单,不用发版
- **多租户**:不同租户看不同菜单
- **角色权限**:菜单本身就是权限的载体,后端管控最准确

### 3.3 为什么主题系统独立成 `src/theme/`
- **整体替换**:后期要换主题方案(比如用 styled-components),只改 `theme/` 文件夹
- **新增主题 = 加 22 个变量 + 1 个 button**,不碰业务
- **可被 design token 工具读取**:后期对接 Figma Tokens,只导出 `themes.scss`

### 3.4 为什么 DataTable 通用化
- **列表页占 60% 工作量**,通用化能省一半时间
- **列配置化**:新增列表 = 配 columns,不写模板
- **统一交互**:所有列表分页/筛选/排序行为一致,降低学习成本

### 3.5 为什么用 composables 而不是 mixins
- **类型友好**:TypeScript 推断更准
- **逻辑复用**:同一逻辑可在多个组件复用,不污染 options
- **tree-shaking 友好**:只引入用到的

### 3.6 为什么用 v-permission 指令而不是组件
- **声明式**:`<button v-permission="'sys:user:add'">` 比 `<Permission code="sys:user:add">` 更直观
- **可扩展**:支持 hide / disable / function 三种模式
- **性能好**:编译时确定,无运行时组件嵌套

## 4. 命名规范(避免后期混乱)

### 4.1 文件命名
- **组件**:PascalCase (`UserMenu.vue`)
- **工具/脚本**:camelCase (`auth.ts` / `format.ts`)
- **样式**:kebab-case (`user-menu.scss`)
- **常量**:UPPER_SNAKE_CASE (`MAX_FILE_SIZE`)

### 4.2 CSS 变量
- 主题相关:加 `--brand` / `--bg-soft` 等
- 主题无关:加 `--radius` / `--shadow` 等
- 模块私有:加 `--module-` 前缀

### 4.3 Pinia store
- 名:模块名,如 `useUserStore`
- 状态:`xxx` (如 `token`, `profile`)
- 动作:`xxx` (如 `login`, `logout`, `fetchMenu`)

## 5. 测试策略(后期可加,本期不做)

- **单元测试**:Vitest + Vue Test Utils(测试 composables 和工具函数)
- **E2E 测试**:Playwright(测关键流程:登录 → 进看板 → 切换主题)
- **视觉回归**:Chromatic / Percy(主题切换不能破坏布局)

## 6. CI/CD 策略(后期可加)

- PR 必须通过 ESLint + TypeScript 类型检查
- 自动跑 build,失败禁止 merge
- 每次发版生成 changelog

## 7. 演进路线(避免后期推倒重来)

- **当前**:模块化 + 主题系统 + 4 套主题
- **3 个月内**:加入 E2E 测试 + 性能监控
- **6 个月内**:支持微前端拆分(独立 module 可独立部署)
- **12 个月内**:加入低代码能力(列表列配置化 → 可视化配置)

---

**所有开发必须遵守本文件。** 任何架构变更必须先更新本文件,再改代码。