diff --git a/frontend/admin/ADMIN_PAGES.md b/frontend/admin/ADMIN_PAGES.md new file mode 100644 index 0000000..de85a4d --- /dev/null +++ b/frontend/admin/ADMIN_PAGES.md @@ -0,0 +1,186 @@ +# QuyUn Tenant Admin(frontend/admin)页面与功能规划 + +基于 `backend/docs/swagger.json` 中 `/t/{tenantCode}/v1/admin/*` 管理端接口(租户维度),规划 `frontend/admin/` 的信息架构、页面路由与核心交互。 + +> 当前 `frontend/admin/src/tenant.ts` 的路由基座为 `/t/:tenantCode/admin/`,API 基座为 `/t/:tenantCode/v1`;本文中 API 路径均以该 baseURL 为前缀(即请求 `/admin/...`)。 + +## 0. 全局约定(前端通用能力) + +- **租户上下文**:从 URL 解析 `tenantCode`(已存在 `getTenantCodeFromPath`),所有接口都带上路径参数 `{tenantCode}`。 +- **分页/排序**:多数列表接口使用 `page/limit`,部分支持 `asc/desc`;统一封装 `Pager` 查询参数与列表组件。 +- **过滤条件同步 URL**:列表页筛选项写入 query(便于分享/刷新不丢失)。 +- **危险操作二次确认 + 审计信息**:退款、禁用邀请码、审批加入申请、移除成员、删除媒体资源等,弹窗确认并强制填写 `reason`(后端字段标注为可选,但管理端建议必填以便追溯)。 +- **枚举展示**:基于 swagger 的 `consts.*` 枚举做 label 映射(见文末“枚举”)。 + +## 1. 路由与菜单(建议) + +路由均相对 `getAdminRouterBase()`(`/t/:tenantCode/admin/`): + +- `/dashboard`:概览 +- `/members`:成员管理 +- `/invites`:邀请码管理 +- `/join-requests`:加入申请 +- `/orders`:订单管理 +- `/orders/:orderID`:订单详情 +- `/ledgers`:余额流水(审计) +- `/media`:媒体资源库 +- `/media/upload`:上传媒体资源 +- `/media/:assetID`:媒体资源详情 +- `/contents`:内容管理(接口缺口见“待补接口/风险”) +- `/contents/new`:创建内容(草稿) +- `/contents/:contentID`:内容编辑(基础信息/价格/绑定资源) + +## 2. 页面规格(页面 → 功能 → API) + +### 2.1 概览 `/dashboard` + +目标:提供“运营入口 + 关键待办”。 + +- 待办卡片:`加入申请待处理数量`、`最近退款/退款中订单`、`最近上传失败媒体资源` +- 快捷入口:跳转到成员/订单/媒体/内容 +- 数据来源(可先不做聚合,使用列表接口取前 N 条): + - 加入申请列表:`GET /admin/join-requests?status=pending&limit=10&page=1` + - 订单列表:`GET /admin/orders?status=refunding,refunded,paid&limit=10&page=1`(按 `paid_at`/`created_at` 排序) + - 媒体资源列表:`GET /admin/media_assets?status=failed,processing&limit=10&page=1` + +### 2.2 成员管理 `/members` + +核心对象:租户成员关系 + 用户基础信息(`dto.AdminTenantUserItem` 组合 `models.TenantUser` + `models.User`)。 + +- 成员列表(带筛选/分页) + - 过滤:`username`、`user_id`、`role`、`status` + - API:`GET /admin/users` +- 添加成员(通过 `userID` 加入) + - 交互:输入 `userID`(或未来可通过用户名搜索,当前 swagger 未提供) + - API:`POST /admin/users/{userID}/join` +- 设置角色 + - 交互:角色下拉(`member` / `tenant_admin`) + - API:`PATCH /admin/users/{userID}/role`(`dto.AdminTenantUserRoleUpdateForm`) +- 移除成员 + - API:`DELETE /admin/users/{userID}` + +### 2.3 邀请码管理 `/invites` + +- 邀请码列表(筛选/分页) + - 过滤:`code`、`status` + - API:`GET /admin/invites` +- 创建邀请码 + - 表单字段:`code?`、`expires_at?`、`max_uses?`、`remark?`(`dto.AdminTenantInviteCreateForm`) + - API:`POST /admin/invites` +- 禁用邀请码 + - 表单字段:`reason?`(建议必填;`dto.AdminTenantInviteDisableForm`) + - API:`PATCH /admin/invites/{inviteID}/disable` + +### 2.4 加入申请 `/join-requests` + +- 加入申请列表(筛选/分页) + - 过滤:`status`、`user_id` + - API:`GET /admin/join-requests` +- 审核通过 / 拒绝 + - 表单字段:`reason?`(建议必填;`dto.AdminTenantJoinRequestDecideForm`) + - API: + - `POST /admin/join-requests/{requestID}/approve` + - `POST /admin/join-requests/{requestID}/reject` + +### 2.5 订单管理 `/orders` + +- 订单列表(筛选/分页/导出) + - 过滤: + - 金额:`amount_paid_min` / `amount_paid_max`(单位分) + - 订单:`status`、`type` + - 用户:`user_id`、`username` + - 内容:`content_id`、`content_title` + - 时间:`created_at_from/to`、`paid_at_from/to` + - 排序:`asc` / `desc` + - API: + - 列表:`GET /admin/orders` + - 导出:`GET /admin/orders/export`(应与当前筛选条件一致) +- 订单详情入口:点击行跳 `/orders/:orderID` + +### 2.6 订单详情 `/orders/:orderID` + +- 详情展示 + - API:`GET /admin/orders/{orderID}`(返回 `dto.AdminOrderDetail`,内含 `models.Order`,其中 `items` 为订单项) +- 退款操作 + - 表单字段:`reason`(建议必填)、`idempotency_key`(前端生成 UUID)、`force`(受控开关,默认 false) + - API:`POST /admin/orders/{orderID}/refund`(`dto.AdminOrderRefundForm`) + - 交互:退款前展示校验信息(当前接口描述存在“paid_at + 24h”窗口逻辑),并将强制退款标注为高危操作 + +### 2.7 余额流水(审计)`/ledgers` + +- 流水列表(筛选/分页) + - 过滤:`user_id`、`order_id`、`operator_user_id`、`biz_ref_type`、`biz_ref_id`、`type`、`created_at_from/to` + - API:`GET /admin/ledgers` +- 展示重点: + - `dto.AdminLedgerItem.type_description` 直接用于 UI 展示 + - 金额字段以“分”为单位的,统一格式化为元(保留两位) + +### 2.8 媒体资源库 `/media` + +- 资源列表(筛选/分页/排序) + - 过滤:`type`、`status`、`created_at_from/to` + - 排序:`asc/desc` + - API:`GET /admin/media_assets` +- 删除资源(软删) + - API:`DELETE /admin/media_assets/{assetID}` +- 进入详情:跳 `/media/:assetID` + +### 2.9 上传媒体资源 `/media/upload` + +建议采用“上传任务”模型(可多文件队列): + +1) 初始化上传(创建资源记录 + 获取上传参数) +- API:`POST /admin/media_assets/upload_init`(`dto.AdminMediaAssetUploadInitForm` → `dto.AdminMediaAssetUploadInitResponse`) +- 表单字段:`type`(必填)、`variant`、`source_asset_id?`、`sha256?`、`file_size?`、`content_type?` +2) 直传到对象存储 +- 使用返回的 `upload_url` + `form_fields`/`headers` 完成上传 +3) 确认上传完成,触发后端处理 +- API:`POST /admin/media_assets/{assetID}/upload_complete`(`dto.AdminMediaAssetUploadCompleteForm`) + +### 2.10 媒体资源详情 `/media/:assetID` + +- API:`GET /admin/media_assets/{assetID}` +- 展示:`type/variant/status/provider/bucket/object_key/meta/created_at` 等;对 `failed` 状态展示失败原因(若后端写在 `meta`) + +### 2.11 内容管理 `/contents`(待补接口) + +swagger 中目前仅提供: + +- 创建草稿:`POST /admin/contents`(`dto.ContentCreateForm`) +- 更新内容:`PATCH /admin/contents/{contentID}`(`dto.ContentUpdateForm`) +- 设置价格:`PUT /admin/contents/{contentID}/price`(`dto.ContentPriceUpsertForm`) +- 绑定媒体资源:`POST /admin/contents/{contentID}/assets`(`dto.ContentAssetAttachForm`) + +建议页面拆分: + +- 内容列表 `/contents`:需要后端补 `GET /admin/contents`(支持状态/可见性/标题搜索/分页),否则前端无法管理草稿/下架内容。 +- 内容创建 `/contents/new`:填写 `title/description/preview_seconds/visibility` +- 内容编辑 `/contents/:contentID`: + - 基础信息:`PATCH /admin/contents/{contentID}` + - 价格与折扣:`PUT /admin/contents/{contentID}/price` + - 资源绑定:从媒体资源库选择 `asset_id`,按 `role(main/cover/preview)` 绑定到内容 + +## 3. 枚举(UI 需要的固定值) + +(直接来自 swagger `definitions/consts.*`) + +- 成员角色 `consts.TenantUserRole`:`member`、`tenant_admin` +- 邀请码状态 `consts.TenantInviteStatus`:`active`、`disabled`、`expired` +- 加入申请状态 `consts.TenantJoinRequestStatus`:`pending`、`approved`、`rejected` +- 媒体类型 `consts.MediaAssetType`:`video`、`audio`、`image` +- 媒体状态 `consts.MediaAssetStatus`:`uploaded`、`processing`、`ready`、`failed`、`deleted` +- 订单状态 `consts.OrderStatus`:`created`、`paid`、`refunding`、`refunded`、`canceled`、`failed` +- 订单类型 `consts.OrderType`:`content_purchase` +- 流水类型 `consts.TenantLedgerType`:`debit_purchase`、`credit_refund`、`freeze`、`unfreeze`、`adjustment` +- 内容可见性 `consts.ContentVisibility`:`public`、`tenant_only`、`private` +- 内容状态 `consts.ContentStatus`:`draft`、`reviewing`、`published`、`unpublished`、`blocked` +- 内容资源角色 `consts.ContentAssetRole`:`main`、`cover`、`preview` +- 折扣类型 `consts.DiscountType`:`none`、`percent`、`amount` +- 币种 `consts.Currency`:`CNY` + +## 4. 待补接口 / 风险点(从 swagger 反推) + +- **内容列表缺失**:没有 `GET /admin/contents`;无法做内容管理主列表、草稿管理、下架列表等。 +- **分页返回结构疑似不完整**:多个列表接口在 swagger 中将 `items` 描述为单个 object(`$ref models.*`),但实际应为数组;前端需以实际返回为准,或推动后端修正 swagger(`items: { type: array, items: ... }`)。 +- **鉴权机制未在 swagger 体现**:`securityDefinitions` 仅有 `BasicAuth`,且各接口未标注 `security`;前端需确认实际鉴权方式(JWT/Cookie/BasicAuth),并统一处理 401/403。 + diff --git a/frontend/superadmin/SUPERADMIN_PAGES.md b/frontend/superadmin/SUPERADMIN_PAGES.md new file mode 100644 index 0000000..f1f1e2f --- /dev/null +++ b/frontend/superadmin/SUPERADMIN_PAGES.md @@ -0,0 +1,90 @@ +# QuyUn 平台超级管理员(frontend/superadmin)页面与功能规划 + +基于 `backend/docs/swagger.json` 中平台侧接口 `/super/v1/*`,规划 `frontend/superadmin/` 的信息架构、页面路由与核心交互。 + +> `frontend/superadmin/src/router/index.js` 的路由基座为 `/super/`;API base 由 `VITE_API_BASE_URL` 控制(见 `frontend/superadmin/src/service/apiClient.js`),本文中的 API 路径均为绝对路径(例如 `/super/v1/users`)。 + +## 0. 全局约定(前端通用能力) + +- **鉴权**:登录成功后保存 `token`(建议保存到 `localStorage.super_token`),所有请求带 `Authorization: Bearer `(项目已在 `frontend/superadmin/src/service/apiClient.js` 实现)。 +- **路由守卫**: + - 未登录访问受保护页面 → 跳转 `/auth/login`。 + - 可选:启动时调用 `GET /super/v1/auth/token` 校验 token 是否有效(401 则清理 token 并回到登录页)。 +- **分页/排序**:列表接口使用 `page/limit`,并支持 `asc/desc`(字段名逗号分隔)。统一封装分页表格组件与 URL query 同步。 +- **枚举来源**:优先使用 `GET /super/v1/tenants/statuses`、`GET /super/v1/users/statuses` 返回的 `requests.KV[]` 作为下拉选项(swagger 中 `dto.*StatusUpdateForm` 的 enum 与 `consts.*Status` 存在不一致,见“风险点”)。 + +## 1. 路由与菜单(建议) + +(与现有路由保持一致,业务页面放在 `/superadmin/*`) + +- `/auth/login`:登录 +- `/`:概览 Dashboard +- `/superadmin/tenants`:租户管理 +- `/superadmin/users`:用户管理 + +## 2. 页面规格(页面 → 功能 → API) + +### 2.1 登录 `/auth/login` + +目标:完成超级管理员登录并写入 token。 + +- 登录表单:`username`、`password`(对应 `dto.LoginForm`) +- API: + - 登录:`POST /super/v1/auth/login` → `dto.LoginResponse.token` + - 校验/续期:`GET /super/v1/auth/token`(返回同结构 `dto.LoginResponse`) +- 交互: + - 失败提示:展示后端错误信息 + - 成功:保存 token → 跳转到 `/superadmin/tenants` 或上次访问页面 + +### 2.2 概览 `/`(Dashboard) + +目标:提供“关键指标 + 快捷入口”。 + +- 指标: + - 用户状态统计:`GET /super/v1/users/statistics`(`dto.UserStatistics[]`) + - 可选:租户总数(利用租户列表响应中的 `total`):`GET /super/v1/tenants?limit=10&page=1` +- 快捷入口:租户管理、用户管理 + +### 2.3 租户管理 `/superadmin/tenants` + +核心对象:`dto.TenantItem` + +- 租户列表(筛选/分页/排序) + - 过滤:`name`、`status` + - 排序:`asc/desc` + - API:`GET /super/v1/tenants` +- 状态更新 + - 选项:`GET /super/v1/tenants/statuses`(`requests.KV[]`) + - API:`PATCH /super/v1/tenants/{tenantID}/status`(`dto.TenantStatusUpdateForm`) + - 交互:点击状态 tag 打开弹窗选择新状态并提交 +- 续期/更新过期时间 + - 方案:提供固定档位(7/30/90/180/365 天)或日期选择器(二选一;swagger 当前为 duration 档位) + - API:`PATCH /super/v1/tenants/{tenantID}`(`dto.TenantExpireUpdateForm.duration`) + +### 2.4 用户管理 `/superadmin/users` + +核心对象:`dto.UserItem` + +- 用户列表(筛选/分页/排序) + - 过滤:`username`、`tenantID`、`status` + - 排序:`asc/desc` + - API:`GET /super/v1/users` +- 用户状态统计(页头统计条) + - API:`GET /super/v1/users/statistics` +- 更新用户状态 + - 选项:`GET /super/v1/users/statuses`(`requests.KV[]`) + - API:`PATCH /super/v1/users/{userID}/status`(`dto.UserStatusUpdateForm`) + - 交互:点击状态 tag 打开弹窗 + +## 3. 枚举与数据结构(UI 需要) + +- 租户状态:`consts.TenantStatus`(`pending_verify` / `verified` / `banned`),推荐用 `GET /super/v1/tenants/statuses` 驱动展示 label +- 用户状态:`consts.UserStatus`(`pending_verify` / `verified` / `banned`),推荐用 `GET /super/v1/users/statuses` 驱动展示 label +- KV 结构:`requests.KV`(`key` 为机器值,`value` 为展示文案) + +## 4. 风险点 / 待补能力(从 swagger 反推) + +- **swagger 不一致**:`dto.TenantStatusUpdateForm.status` / `dto.UserStatusUpdateForm.status` 在 swagger 里额外出现 `normal/disabled` enum,但 `consts.*Status` 与列表筛选 enum 为 `pending_verify/verified/banned`;前端应以 `/statuses` 接口返回为准,并推动后端修正 swagger。 +- **分页 items 结构疑似不完整**:列表接口 swagger 中 `items` 被标成单个 object(`$ref dto.TenantItem`/`dto.UserItem`),实际应为数组;当前前端服务层已做兼容(`normalizeItems`),但建议后端修正 swagger。 +- **租户/用户详情与更多运维能力缺失**:目前没有用户详情、租户详情、角色管理、密码重置等超管常见能力;如需要可扩展接口与页面。 + diff --git a/frontend/superadmin/dist/index.html b/frontend/superadmin/dist/index.html index 5842c3d..d4677fc 100644 --- a/frontend/superadmin/dist/index.html +++ b/frontend/superadmin/dist/index.html @@ -7,7 +7,7 @@ Sakai Vue - + diff --git a/frontend/superadmin/src/layout/AppMenu.vue b/frontend/superadmin/src/layout/AppMenu.vue index 8c94646..a06a141 100644 --- a/frontend/superadmin/src/layout/AppMenu.vue +++ b/frontend/superadmin/src/layout/AppMenu.vue @@ -14,151 +14,6 @@ const model = ref([ { label: 'Tenants', icon: 'pi pi-fw pi-building', to: '/superadmin/tenants' }, { label: 'Users', icon: 'pi pi-fw pi-users', to: '/superadmin/users' } ] - }, - { - label: 'UI Components', - items: [ - { label: 'Form Layout', icon: 'pi pi-fw pi-id-card', to: '/uikit/formlayout' }, - { label: 'Input', icon: 'pi pi-fw pi-check-square', to: '/uikit/input' }, - { label: 'Button', icon: 'pi pi-fw pi-mobile', to: '/uikit/button', class: 'rotated-icon' }, - { label: 'Table', icon: 'pi pi-fw pi-table', to: '/uikit/table' }, - { label: 'List', icon: 'pi pi-fw pi-list', to: '/uikit/list' }, - { label: 'Tree', icon: 'pi pi-fw pi-share-alt', to: '/uikit/tree' }, - { label: 'Panel', icon: 'pi pi-fw pi-tablet', to: '/uikit/panel' }, - { label: 'Overlay', icon: 'pi pi-fw pi-clone', to: '/uikit/overlay' }, - { label: 'Media', icon: 'pi pi-fw pi-image', to: '/uikit/media' }, - { label: 'Menu', icon: 'pi pi-fw pi-bars', to: '/uikit/menu' }, - { label: 'Message', icon: 'pi pi-fw pi-comment', to: '/uikit/message' }, - { label: 'File', icon: 'pi pi-fw pi-file', to: '/uikit/file' }, - { label: 'Chart', icon: 'pi pi-fw pi-chart-bar', to: '/uikit/charts' }, - { label: 'Timeline', icon: 'pi pi-fw pi-calendar', to: '/uikit/timeline' }, - { label: 'Misc', icon: 'pi pi-fw pi-circle', to: '/uikit/misc' } - ] - }, - { - label: 'Prime Blocks', - icon: 'pi pi-fw pi-prime', - items: [ - { - label: 'Free Blocks', - icon: 'pi pi-fw pi-eye', - to: '/blocks' - }, - { - label: 'All Blocks', - icon: 'pi pi-fw pi-globe', - url: 'https://blocks.primevue.org/', - target: '_blank' - } - ] - }, - { - label: 'Pages', - icon: 'pi pi-fw pi-briefcase', - to: '/pages', - items: [ - { - label: 'Landing', - icon: 'pi pi-fw pi-globe', - to: '/landing' - }, - { - label: 'Auth', - icon: 'pi pi-fw pi-user', - items: [ - { - label: 'Login', - icon: 'pi pi-fw pi-sign-in', - to: '/auth/login' - }, - { - label: 'Error', - icon: 'pi pi-fw pi-times-circle', - to: '/auth/error' - }, - { - label: 'Access Denied', - icon: 'pi pi-fw pi-lock', - to: '/auth/access' - } - ] - }, - { - label: 'Crud', - icon: 'pi pi-fw pi-pencil', - to: '/pages/crud' - }, - { - label: 'Not Found', - icon: 'pi pi-fw pi-exclamation-circle', - to: '/pages/notfound' - }, - { - label: 'Empty', - icon: 'pi pi-fw pi-circle-off', - to: '/pages/empty' - } - ] - }, - { - label: 'Hierarchy', - items: [ - { - label: 'Submenu 1', - icon: 'pi pi-fw pi-bookmark', - items: [ - { - label: 'Submenu 1.1', - icon: 'pi pi-fw pi-bookmark', - items: [ - { label: 'Submenu 1.1.1', icon: 'pi pi-fw pi-bookmark' }, - { label: 'Submenu 1.1.2', icon: 'pi pi-fw pi-bookmark' }, - { label: 'Submenu 1.1.3', icon: 'pi pi-fw pi-bookmark' } - ] - }, - { - label: 'Submenu 1.2', - icon: 'pi pi-fw pi-bookmark', - items: [{ label: 'Submenu 1.2.1', icon: 'pi pi-fw pi-bookmark' }] - } - ] - }, - { - label: 'Submenu 2', - icon: 'pi pi-fw pi-bookmark', - items: [ - { - label: 'Submenu 2.1', - icon: 'pi pi-fw pi-bookmark', - items: [ - { label: 'Submenu 2.1.1', icon: 'pi pi-fw pi-bookmark' }, - { label: 'Submenu 2.1.2', icon: 'pi pi-fw pi-bookmark' } - ] - }, - { - label: 'Submenu 2.2', - icon: 'pi pi-fw pi-bookmark', - items: [{ label: 'Submenu 2.2.1', icon: 'pi pi-fw pi-bookmark' }] - } - ] - } - ] - }, - { - label: 'Get Started', - items: [ - { - label: 'Documentation', - icon: 'pi pi-fw pi-book', - to: '/documentation' - }, - { - label: 'View Source', - icon: 'pi pi-fw pi-github', - url: 'https://github.com/primefaces/sakai-vue', - target: '_blank' - } - ] } ]); diff --git a/frontend/superadmin/src/layout/AppTopbar.vue b/frontend/superadmin/src/layout/AppTopbar.vue index 82f489d..0a74bc0 100644 --- a/frontend/superadmin/src/layout/AppTopbar.vue +++ b/frontend/superadmin/src/layout/AppTopbar.vue @@ -1,8 +1,16 @@