管理后台功能说明 - CodeNote Admin

1. 概述

CodeNote Admin 是 CodeNote 二维码管理系统的全局管理后台。

1.1 核心定位

全局数据中心：可查看全平台所有用户、组织、二维码、资源等数据
审计监控中心：实时监控平台运行状态，审计用户行为和操作日志
高权限管理中心：执行强制删除、审批、配置修改等高权限操作
系统配置中心：管理系统级配置参数，控制平台运行规则

1.2 技术栈

框架: Vue 3 (Composition API + <script setup>)
语言: TypeScript
构建工具: Vite
UI 组件库: Element Plus
状态管理: Pinia
路由: Vue Router (HashRouter)
HTTP 客户端: Axios
部署方式: 本地构建 dist → Git 推送 → 服务器拉取静态文件 → NPM (Nginx Proxy Manager) 代理

1.3 角色与权限

主要角色（PLATFORM 域 RBAC 预置，调整）：

系统管理员 SYSTEM_ADMIN：默认账号 admin / admin123（支持用户名/邮箱或手机号+密码），访问所有管理页面，唯一可管理 RBAC/系统配置/日志
用户管理员 USER_ADMIN：用户 + 组织管理（含转让所有权/解散/成员管理）+ 登录记录/账号（已并入原 ORG_ADMIN 权限）
业务管理员 BUSINESS_ADMIN：二维码/资源/分类/相册/文件/元字段/元模板/模板绑定（meta_*，P3 已接入管理界面）
运营管理员 OPERATION_ADMIN：活动/签到/通行证/通知/分享/扫码记录

权限特点：

仅 ADMIN 角色可登录管理后台
可查看全平台所有用户、组织、二维码、资源等数据
可执行强制删除、审批、配置修改等高权限操作
所有操作自动记录到 admin_logs 表
管理组织时可查看全局组织列表、转移所有权、解散组织、管理成员

注意：系统管理员虽然拥有全局查看权限，但在操作某个组织的资源时，仍需遵循该组织的权限规则（如解散组织时需要先清空组织资源）。

2. 项目结构

codenote-admin/
├── src/
│   ├── api/
│   │   ├── request.ts                  # Axios 实例 + 拦截器
│   │   └── index.ts                    # adminApi 封装（16 组 API 调用）
│   ├── stores/
│   │   └── app.ts                      # Pinia: sidebar + Token/用户
│   ├── types/
│   │   └── index.ts                    # TS 类型定义
│   ├── components/layout/
│   │   └── AppLayout.vue               # 侧边栏 + 顶栏布局
│   ├── views/                          # 24 个管理页面（含 admin/ 子目录）
│   │   ├── Login.vue                   # 登录页
│   │   ├── Dashboard.vue               # 仪表盘
│   │   ├── Users.vue                   # 用户管理
│   │   ├── Orgs.vue                    # 组织管理
│   │   ├── QrCodes.vue                 # 二维码审计
│   │   ├── Assets.vue                  # 资源管理
│   │   ├── AssetCategories.vue         # 资源分类管理
│   │   ├── AssetCategoriesEnhanced.vue # 资源分类管理（增强版）
│   │   ├── Activities.vue              # 活动管理
│   │   ├── CheckIn.vue                 # 签到管理
│   │   ├── Passes.vue                  # 通行证管理
│   │   ├── Albums.vue                  # 水印相册管理
│   │   ├── Categories.vue              # 分类管理
│   │   ├── Notifications.vue           # 通知管理
│   │   ├── Shares.vue                  # 分享记录管理
│   │   ├── Files.vue                   # 文件管理
│   │   ├── Settings.vue                # 系统配置
│   │   ├── Logs.vue                    # 操作日志
│   │   ├── LoginRecords.vue            # 登录记录
│   │   ├── AccountManagement.vue       # 账号管理（会话+关联）
│   │   └── admin/
│   │       ├── FieldDefinitions.vue    # 字段管理（对象+scope+config 动态编辑，类型统一大写）
│   │       ├── Templates.vue           # 模板管理（CRUD/字段编排/复制）
│   │       ├── Objects.vue             # 业务对象管理（注册/启停，仅 SYSTEM_ADMIN）
│   │       ├── ScanRecords.vue         # 扫码记录查询
│   │       ├── Login.vue               # 管理员登录页
│   │       └── Register.vue            # 注册页
│   └── router/
│       └── index.ts                    # 路由 + 登录守卫
├── package.json                        # 依赖配置
├── vite.config.ts                      # Vite 配置
├── tsconfig.json                       # TypeScript 配置
├── index.html                          # HTML 入口
├── deploy.sh                           # 部署脚本
└── README.md                           # 项目说明

3. 功能清单

3.1 核心管理模块

#	模块	页面	主要功能
A1	仪表盘	Dashboard.vue	全局概览（注册用户/二维码总量/活动数/签到数/组织数）/快速入口
A2	用户管理	Users.vue	用户列表/搜索/筛选/启用禁用/角色设置/新增编辑/成员关系管理（查看/添加/移除用户的组织成员身份）
A3	组织管理	Orgs.vue	组织一览/成员统计/转移所有权/解散/组织成员管理（查看/编辑/添加/移除成员）
A5	二维码审计	QrCodes.vue	全局搜索/类型筛选/预览/强制删除
A6	资源管理	Assets.vue	全局一览/直接报废/强制删除/动态字段渲染（meta 固定列列表 + 详情 meta 视角，已去 CURRENCY 分支）
A8	活动管理	Activities.vue	全局活动列表/详情/创建/编辑/删除/签到记录 tab/通行证 tab
A9	签到管理	CheckIn.vue	签到记录列表/按活动筛选/删除记录
A10	通行证管理	Passes.vue	通行证列表/核验日志/撤销/删除
A11	水印相册管理	Albums.vue	全局照片列表/删除
A12	分类管理	Categories.vue	全局分类列表/树形展示/拖曳排序/批量操作
A13	资源分类管理	AssetCategoriesEnhanced.vue	资源分类列表/按范围筛选/置顶/拖拽排序/移动分类/批量操作/模板绑定（P3 已接入）
A14	通知管理	Notifications.vue	全局通知列表/删除/发送系统通知
A15	分享记录管理	Shares.vue	按组织查看/删除
A16	系统配置	Settings.vue	注册开关/配额设置/存储限制/上传限制
A17	操作日志	Logs.vue	管理员操作审计/按操作类型/时间筛选
A18	文件管理	Files.vue	全局文件列表/按类型筛选/预览/批量删除/存储统计/孤儿文件检测
A19	登录记录	LoginRecords.vue	登录记录查询/按用户ID/状态/时间范围筛选/安全审计
A20	账号管理	AccountManagement.vue	会话管理（查询/切换/删除）+ 账号关联管理（查询/添加/移除）
A21	字段管理	admin/FieldDefinitions.vue	按对象+scope 维护字段，config JSON 动态编辑（校验/选项/分组/单位），类型统一 UPPER_SNAKE（15 种注册表）
A21b	模板管理	admin/Templates.vue	元模板 CRUD/字段编排（排序/分组/必填/移除/添加）/复制/组织模板查看
A21c	业务对象管理	admin/Objects.vue	业务对象注册/启停（仅 SYSTEM_ADMIN）
A22	扫码记录	admin/ScanRecords.vue	全局扫码记录查询/筛选

3.2 详细功能说明

3.2.1 用户管理

全局概览：统计卡片展示用户总数、活跃用户数、禁用用户数、管理员数量
用户列表：分页展示所有注册用户，含所属组织信息、身份聚合（邮箱/手机/身份类型/设备数）
搜索筛选：按用户名/邮箱搜索，按角色、状态、**身份筛选（仅设备/已绑定可恢复身份/未绑定）**筛选
新增用户：填写用户名、邮箱、密码、角色及初始状态创建账户
编辑用户：修改邮箱、角色、状态，并支持调整用户归属的组织
角色切换：USER ↔ ADMIN
状态管理：启用/禁用用户
详情查看：用户基本信息、存储使用、二维码数量
成员关系管理：
- 点击"成员"按钮查看用户所属的所有组织
- 支持将用户加入新的组织（可选择角色）
- 支持从组织中移除用户（不能移除所有者）
- 操作后自动刷新成员列表

身份聚合特性（身份分离后）：

用户类型列：显示"仅设备"（hasRecoverableCredential=false）或"普通用户"标签
身份列：展示该账号绑定的 provider 列表（PHONE/EMAIL/DEVICE...）
设备数列：绑定设备数量（DEVICE identities 计数）
筛选功能：device_user=仅设备身份；bound=有密码或有手机/邮箱；unbound=无任何可恢复身份

3.2.2 组织管理

全局概览：统计卡片展示组织总数、活跃组织数、禁用组织数
组织列表：分页展示所有组织，显示成员数 + 可见性列（公开/内部）
创建组织：管理员可创建新组织，自动生成8位随机组织码；可见性单选（公开默认/内部），选内部后加入策略锁定仅邀请
编辑组织：支持修改组织名称、描述、状态（活跃/禁用）、可见性（公开/内部）
转移所有权：将组织所有权转移给其他管理员/成员，原所有者降级为普通成员
组织详情：弹窗展示基本信息、成员列表及角色
解散组织：强制删除组织（有成员时会显示警告提示）
组织成员管理：
- 点击"成员"按钮查看组织的所有成员列表
- 支持编辑成员角色（MEMBER/MANAGER/LEADER），使用 Element Plus 对话框选择角色
- 支持添加新成员到组织（选择用户并设置角色）
- 支持移除组织成员（不能移除所有者）
- 操作后自动刷新成员列表

3.2.4 二维码审计

全局搜索：搜索所有用户的二维码
类型筛选：按二维码类型过滤
预览：弹窗查看二维码详情
强制删除：删除任意用户的二维码

3.2.5 活动管理

活动列表：分页展示所有用户的活动，每行显示归属（个人/组织）+ 可见性标签（公开/组织内部/仅邀请）
活动详情：展示活动基本信息（含可见性 + 邀请码）、签到记录子页、通行证子页
创建活动：填写名称/描述/地点/时间/封面，可选开启签到/通行子功能；归属可选个人/组织（选组织时可见性按归属过滤：个人 2 项/组织 3 项）
编辑活动：修改活动基本信息和子功能开关
删除活动：删除活动及其关联数据

3.2.6 签到管理

签到记录列表：分页展示所有签到记录
按活动筛选：通过 activityId 参数按活动过滤签到记录
删除记录：删除指定签到记录

3.2.7 通行证管理

通行证列表：分页展示所有已签发通行证
撤销通行证：将指定通行证标记为 REVOKED 状态
删除通行证：永久删除通行证及其使用记录

3.2.8 资源管理

全局资源：所有用户资源一览
直接报废：管理员点击报废按钮，确认后直接将资源状态标记为 SCRAPPED（无审批流程）
强制删除：删除任意资源
动态字段渲染：列表列来自 meta GLOBAL 固定列字段（brand/model/... 直接读资产行），详情弹窗走 /admin/assets/{id}/fields meta 视角（支持 TEXT/TEXTAREA/NUMBER/DATE/DATETIME/BOOLEAN/SELECT/RADIO/MULTI_SELECT/CHECKBOX/ATTACHMENT/PHOTO/GEO/REF/COMPUTED 大写类型渲染，已移除 CURRENCY 分支）
模板绑定：分类管理页「模板」按钮，按分类 scope 过滤可用模板（PERSONAL→GLOBAL+USER；ORG→GLOBAL+本组织 ORG），多选保存（默认模板+附加模板）

3.2.9 系统配置

注册开关：允许/禁止新用户注册
默认存储配额：新用户默认存储空间
默认二维码配额：新用户默认二维码数量

3.2.10 操作日志

管理员操作审计记录
按操作类型筛选
按时间范围筛选
查看操作详情

3.2.11 协议管理

类型切换：用户服务协议（SERVICE）/ 隐私政策（PRIVACY）
版本列表：全部版本（新版在前），当前生效版本高亮标记
发布新版本：textarea 编辑 Markdown 原文，发布即生效（版本号自动 +1，历史版本自动失效）
渲染预览：调 POST /api/admin/common/render-markdown，v-html 展示（样式与 App 端 MarkdownView 一致，所见即所得）
切换生效版本：历史版本可回滚激活
复制编辑：任意版本（含当前生效版）点「复制」→ 标题/内容预填进入编辑模式 → 修改后发布为新版本（原版本不变，符合只增不改）
版本化策略：只增不改（内容发布后不可编辑/删除），历史版本可回滚激活，发布即生效（版本号自动 +1）
预置：隐私政策（PRIVACY）v1 模板已预置，可直接复制编辑发布正式版

3.2.17 文件管理【新增】

主要功能：

全局文件列表展示（所有用户上传的文件）
按存储方式筛选（本地存储/OSS存储）
按上传者ID筛选
文件预览（点击缩略图放大查看，仅支持图片格式）
单个文件删除
批量文件删除
存储空间统计（总大小、文件数、按类型分布、按存储方式分布）
孤儿文件检测（数据库存在但物理文件已丢失的记录）
孤儿文件清理

界面设计：

顶部统计卡片：总存储空间、文件总数、文件类型数、存储方式数
筛选区：文件类型下拉框、存储方式下拉框、上传者ID搜索框、批量删除按钮、检测孤儿文件按钮、刷新按钮
文件列表表格：选择框、预览缩略图、文件名、类型、大小、存储方式、上传者、关联实体、上传时间、操作
分页组件：支持翻页浏览

文件类型说明：

avatar: 用户头像
album: 水印相册照片
asset: 资源实物照片
qr_code: 二维码Logo
activity: 活动封面图
org: 组织Logo
other: 其他文件

存储方式说明：

LOCAL: 本地文件系统存储
OSS: 阿里云对象存储

使用场景：

存储空间管理：查看各类型文件占用情况，识别大文件
内容审核：检查用户上传的违规图片
清理无效文件：检测并清理孤儿文件释放存储空间

注意事项：

删除文件时会同时删除OSS/本地物理文件和缩略图
图片文件支持预览，非图片文件显示文档图标
孤儿文件检测只检查本地文件，OSS文件检查待实现
建议定期运行孤儿文件检测，保持数据一致性

3.2.18 资源分类管理（AssetCategoriesEnhanced.vue）【新增】

主要功能：

全局查看所有资源分类（个人分类 + 组织分类）
按范围筛选（个人/组织）
支持按创建者、所属组织快速定位
分类置顶/取消置顶（调用 batchPinAssetCategories API）
拖拽排序（调用 reorderAssetCategory API）
移动分类到其他父级（调用 updateAssetCategoryParent API）
批量置顶（调用 batchPinAssetCategories API）
强制删除任意资源分类（会写操作日志）

界面设计：

分类列表表格：ID、名称、范围标签（个人/组织）、所属组织ID、创建者ID、是否共享分类、排序、创建时间、操作
操作：删除按钮（弹出确认）

注意事项：

删除资源分类不会删除关联的资源，仅置空 category_id
删除组织分类前建议确认是否有正在使用的资源
按操作类型/时间筛选
查看操作详情（目标类型、ID、描述）

3.5 聊天设置（新增，联系人聊天模块）

完整设计见专用文档 /designs/messaging/contacts-chat.md §9。

页面：views/ChatSettings.vue，路由 /chat-settings（侧边栏「运营管理 → 聊天设置」）
统计卡片：总会话数 / 总消息数 / 今日新增消息 / 今日活跃会话 / 今日活跃用户（GET /api/admin/chat/stats）
设置分组：媒体与文件限制（图片/语音/视频/文件大小、文本长度、每日媒体上传总量）、联系人限制（好友上限/每日申请/备注/标签/置顶上限）、聊天行为（陌生人开关/验证开关/手机号可搜索/撤回时限/发消息限流/保留天数/草稿长度）、群聊限制（二期）
权限：chat_setting:read（可访问）chat_setting:update（保存按钮显隐，无权限只读）；变更写 admin_logs

4. 前端权限配置

4.1 Auth 拦截器

管理后台使用统一的 Axios 实例（utils/request.ts）进行 API 调用，包含：

Token 自动注入（Authorization 头）
Token 刷新逻辑（自动处理过期）：
- 每次请求前检查，距过期 <5 分钟 → 先调 POST /api/admin/auth/refresh 预刷新（isRefreshing + 并发队列防重，超时 15s）
- 请求返回 401 → 刷新后重放原请求（_retry 防死循环）
- 刷新失败：网络错误（无响应）不清登录态，放行由 401 兑底；业务失败（401）→ 清 localStorage → 跳转登录页
- 路由守卫：token 已过期时先进门刷新续期，仅 401 才踢去登录
错误统一处理（401 跳转登录页）

配置文件：src/utils/request.ts

4.2 权限守卫

前端通过 permission.ts 实现路由级权限控制：

全局前置守卫：检查用户角色
动态路由：根据角色动态生成可访问的路由表
后端双重校验：所有管理接口在后端通过 @PreAuthorize("hasRole('ADMIN')") 注解强制校验

配置文件：src/router/permission.ts、src/router/index.ts

4.3 登录流程

用户访问管理页面 → 路由守卫检查 Token
无 Token → 跳转登录页（/admin/login）
提交登录表单 → POST /api/admin/auth/login
后端校验用户名密码 + 角色必须为 ADMIN
返回 Token → 前端存储 Token → 跳转管理首页

注意：后端通过 @PreAuthorize("hasRole('ADMIN')") 注解强制校验所有 /api/admin/** 接口，只有 ADMIN 角色可访问。

版本更新：系统设置页底部提供 Android App 版本信息查看和发布历史记录浏览，参见 /reference/app-update.md。版本发布通过本地 deploy.sh 脚本执行，管理后台不提供发布功能。

附录：用户管理与昵称词库

用户管理

用户列表补 nickname 列（与 username 并列显示）、signature 列（个性签名，PC 表格 + 移动卡片均展示）
编辑用户：username 输入框禁用（用户名不可修改）
身份筛选（身份分离）：device_user=username/password 为空且无 PHONE/EMAIL identity；bound=有密码或有 PHONE/EMAIL identity；unbound=无任何可恢复身份；邮箱/手机列改为从 user_identities 聚合展示
登录记录类型中文映射（LoginRecords.vue）：注册/登录/设备登录/设备自动注册/移除设备/登出/登记设备/登出解绑设备/手机/邮箱/一键登录/Token刷新/会话切换/账号切换/改密/注销账户等
登录记录全量查询：GET /api/login-records/admin/all（仅 ADMIN，支持按 userId 筛选 + 时间范围）；登录记录页默认显示全部用户记录，不再只显示当前管理员
创建用户：仍要求 username，昵称自动生成兜底

新增「昵称词库」页面（3.2 节新增页面）

路由：/nickname-words（NicknameWords.vue）
形容词 / 名词两个 Tab，各自列表 + 新增 + 编辑 + 删除
对应 API：/api/admin/nickname/adjectives|nouns（仅 ADMIN）
词库变更即时生效（生成时实时查库，无缓存）

RBAC 权限管理（新增）

权限管理三页（菜单：权限点管理 / 角色管理 / 用户授权）：

权限点管理（/permissions）：列表（可按域过滤）/ 启停 / 新增 / 编辑描述；无物理删除，停用代替删除（§3.3）
角色管理（/roles）：PLATFORM / APP / ORG 域角色 CRUD + 权限勾选搭配；ORG 域可选「初始角色模板」（scopeId=0，修改只影响新建组织）或具体组织（scopeId=orgId，即时生效）；系统预置角色（isSystem）编码不可改、不可删；OWNER 为短路角色内置组织全部权限，仅可改显示名（权限不可配置，前后端双重拦截）；自定义角色（含模板级）可创建/删除
用户授权（/user-roles）：按用户 ID 查询已授权 PLATFORM 角色、授予/撤销；初始 admin（SYSTEM_ADMIN）绑定不可撤销（后端校验）

用户管理适配：角色列显示 PLATFORM 角色编码（空=普通用户）；「升为管理员」= 授予 USER_ADMIN；「降为用户」= 撤销全部 PLATFORM 角色（role=NONE）；新建/编辑用户表单角色下拉为普通用户(USER)/管理员(ADMIN)（旧值兼容），RBAC 精细角色授权走「用户授权」页（ORG_ADMIN 已并入 USER_ADMIN）。

组织管理适配：成员角色展示 roleName（拥有者/管理员/成员/自定义）；添加/编辑成员角色下拉为 MEMBER / ADMIN（LEADER/MANAGER 废弃）。

管理后台功能说明 - CodeNote Admin ​

1. 概述 ​

1.1 核心定位 ​

1.2 技术栈 ​

1.3 角色与权限 ​

2. 项目结构 ​

3. 功能清单 ​

3.1 核心管理模块 ​

3.2 详细功能说明 ​

3.2.1 用户管理 ​

3.2.2 组织管理 ​

3.2.4 二维码审计 ​

3.2.5 活动管理 ​

3.2.6 签到管理 ​

3.2.7 通行证管理 ​

3.2.8 资源管理 ​

3.2.9 系统配置 ​

3.2.10 操作日志 ​

3.2.11 协议管理 ​

3.2.17 文件管理【新增】 ​

3.2.18 资源分类管理（AssetCategoriesEnhanced.vue）【新增】 ​

3.5 聊天设置（新增，联系人聊天模块） ​

4. 前端权限配置 ​

4.1 Auth 拦截器 ​

4.2 权限守卫 ​

4.3 登录流程 ​

附录：用户管理与昵称词库 ​

用户管理 ​

新增「昵称词库」页面（3.2 节新增页面） ​

RBAC 权限管理（新增） ​