feat: added frontend_pages models(basic_info) and api(v2), support employees query pages that they can visit by themself token

2026-01-07 14:28:17 +08:00
parent 941f797e35
commit 4566c2a2c8
14 changed files with 1079 additions and 61 deletions
--- a/docs/api_v2_employee_visible_pages.md
+++ b/docs/api_v2_employee_visible_pages.md
@@ -0,0 +1,167 @@
+# 获取当前用户可见页面 API
+
+## 概述
+
+获取当前登录用户关联的员工岗位所拥有的可见前端页面列表。
+
+- **端点**: `GET /api/v2/me/visible-pages/`
+- **认证**: 需要登录
+- **权限**: 任意已认证用户
+
+## 业务逻辑
+
+1. 从 `request.user` 获取当前登录用户
+2. 通过 `user.employee` 获取关联的员工
+3. 员工通过 `position` 字段关联到岗位（`EmployeeType`）
+4. 岗位通过 `visible_pages` 多对多字段关联到前端页面（`FrontendPage`）
+5. **权限继承**: 如果授予主菜单（`page_type=main`），自动包含其所有子菜单
+
+## 请求
+
+无需参数，自动从登录用户获取。
+
+### 请求示例
+
+```bash
+curl -X GET "http://localhost:8000/api/v2/me/visible-pages/" \
+  -H "Authorization: Token <your-token>"
+```
+
+## 响应
+
+### 成功响应 (200 OK)
+
+```json
+{
+  "employee_id": 1,
+  "employee_name": "张三",
+  "position_id": 2,
+  "position_title": "生产主管",
+  "visible_pages": [
+    {
+      "key": "production",
+      "label": "生产管理",
+      "page_type": "main",
+      "parent_key": null,
+      "sort_order": 100
+    },
+    {
+      "key": "production-kanban",
+      "label": "生产看板",
+      "page_type": "sub",
+      "parent_key": "production",
+      "sort_order": 101
+    },
+    {
+      "key": "printing-order-list",
+      "label": "生产订单",
+      "page_type": "sub",
+      "parent_key": "production",
+      "sort_order": 102
+    }
+  ],
+  "visible_keys": [
+    "printing-order-list",
+    "production",
+    "production-kanban"
+  ]
+}
+```
+
+### 响应字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `employee_id` | int \| null | 员工ID（无关联员工时为 null） |
+| `employee_name` | string \| null | 员工姓名 |
+| `position_id` | int \| null | 岗位ID（无岗位时为 null） |
+| `position_title` | string \| null | 岗位名称 |
+| `visible_pages` | array | 可见页面详情列表（按 sort_order 排序） |
+| `visible_keys` | array | 可见页面 key 列表（已排序，便于前端快速查找） |
+
+### visible_pages 对象结构
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `key` | string | 页面唯一标识（前端路由 key） |
+| `label` | string | 页面显示名称 |
+| `page_type` | string | 页面类型：`main`（主菜单）或 `sub`（子菜单） |
+| `parent_key` | string \| null | 父级菜单 key（主菜单为 null） |
+| `sort_order` | int | 排序值 |
+
+### 用户未关联员工
+
+```json
+{
+  "employee_id": null,
+  "employee_name": null,
+  "position_id": null,
+  "position_title": null,
+  "visible_pages": [],
+  "visible_keys": []
+}
+```
+
+### 员工无岗位
+
+```json
+{
+  "employee_id": 5,
+  "employee_name": "无岗位员工",
+  "position_id": null,
+  "position_title": null,
+  "visible_pages": [],
+  "visible_keys": []
+}
+```
+
+### 错误响应
+
+#### 未认证 (401 Unauthorized)
+
+```json
+{
+  "detail": "Authentication credentials were not provided."
+}
+```
+
+## 前端使用示例
+
+```javascript
+// 获取当前用户可见页面
+async function getMyVisiblePages() {
+  const response = await fetch('/api/v2/me/visible-pages/', {
+    headers: { 'Authorization': `Token ${token}` }
+  });
+  const data = await response.json();
+  
+  // 使用 visible_keys 快速判断菜单是否可见
+  const canSeeProduction = data.visible_keys.includes('production');
+  
+  // 或使用 visible_pages 渲染菜单
+  const menuItems = data.visible_pages.filter(p => p.page_type === 'main');
+  
+  return data;
+}
+```
+
+## 相关命令
+
+### 同步前端页面数据
+
+```bash
+# 从 docs/menu_keys.json 同步页面到数据库
+python manage.py sync_frontend_pages
+
+# 预览模式（不实际写入）
+python manage.py sync_frontend_pages --dry-run
+
+# 清空后重新同步
+python manage.py sync_frontend_pages --clear
+```
+
+## 相关模型
+
+- `basic_info.FrontendPage` - 前端页面
+- `basic_info.EmployeeType` - 员工岗位（含 `visible_pages` 字段）
+- `basic_info.Employee` - 员工（含 `position` 和 `sys_user` 字段）