docs(admin): 校准管理端契约边界

design-docs/产品-02B-管理员控制台功能规格.md

@@ -473,7 +473,7 @@
 | 权限 | 不展示或导出 New-API 系统凭据；不提供模型供应商路由配置；只能调用 New-API 已开放的用户、订阅、额度、余额和日志接口。 |
 | 产品接口 | 查询 New-API 网关用户、创建 New-API 网关用户、配置 New-API 订阅额度、查询 New-API 余额、查询 New-API 调用日志、归属 New-API 调用日志。 |
 | 埋点与审计 | 记录网关用户创建、订阅额度配置、余额查询、调用日志查询和用量归属操作。 |
-| 验收要点 | 02B 不做外部网关数据复制队列；New-API 是被 Muse 后端直接调用的 LLM Gateway 管理接口；02B 只负责网关用户、余额查询和调用日志归属，作品级任务/生成用量由 `产品-02C` 展示，账户级余额、套餐、购买和总用量由 `产品-02G` 展示。 |
+| 验收要点 | 02B 不做外部网关数据复制队列；New-API 是被 Muse 后端直接调用的 LLM Gateway 管理接口；02B 只负责网关用户、余额查询、调用日志归属，以及用于治理和对账的脱敏购买/用量摘要。作品级任务/生成用量由 `产品-02C` 展示，用户侧账户余额、套餐、购买和总用量完整体验由 `产品-02G` 展示。 |
 
 ### 3.20 任务治理与异常观察
 
@@ -1148,7 +1148,7 @@ New-API 的权威数据不在 Muse 本地同步。Muse 只保存完成业务归
 8. 全局知识库授权能区分可见、可检索、可生成、可进入模型上下文。
 9. 质量门控能配置、评估、观测线上效果，但不成为用户写作、保存、私人使用或市场发布的叙事质量硬门槛。
 10. 市场审核和治理能处理审核、下架、召回、申诉和来源状态展示，并区分公共市场对象、用户已安装权益、作品绑定引用、来源快照、候选草稿和 Canonical。
-11. New-API 页面只通过 New-API 接口管理网关用户、订阅额度、余额查询和调用日志归属；不做外部网关数据复制队列，不管理模型供应商路由；作品级任务/生成用量由 `产品-02C` 承接，账户级权益、余额、套餐、购买和总用量展示由 `产品-02G` 承接。
+11. New-API 页面只通过 New-API 接口管理网关用户、订阅额度、余额查询、调用日志归属，以及用于治理和对账的脱敏购买/用量摘要；不做外部网关数据复制队列，不管理模型供应商路由；作品级任务/生成用量由 `产品-02C` 承接，用户侧账户权益、余额、套餐、购买和总用量完整体验由 `产品-02G` 承接。
 12. 任务治理重试前必须重验授权、来源、市场状态、来源状态和幂等，不能复用失效旧上下文，不能由管理员重新生成用户写作候选。
 13. 审计事件 append-only，审计查询和导出本身也必须被审计。
 14. 页面、操作和产品接口在第 10 节覆盖表中闭合；新增页面或操作必须同步补接口。

docs/api-contracts/ai/openapi.yaml

@@ -1057,6 +1057,111 @@ paths:
           $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
         '403':
           $ref: '../openapi-base.yaml#/components/responses/Forbidden'
+  /admin-api/muse/audit/api-logs:
+    get:
+      tags: [Admin Jobs & Events]
+      summary: 查询接口调用日志
+      description: |
+        查询系统接口调用的轻量脱敏日志，用于排障、风控和基础审计留痕。
+        响应不得包含请求体全文、响应体全文、token、secret、完整 header 或用户私有正文。
+      operationId: adminListApiAccessLogs
+      security:
+        - adminBearerAuth: []
+      parameters:
+        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
+        - $ref: '../openapi-base.yaml#/components/parameters/pageNo'
+        - $ref: '../openapi-base.yaml#/components/parameters/pageSize'
+        - name: requestId
+          in: query
+          schema:
+            type: string
+          description: 请求 ID 筛选
+        - name: actor
+          in: query
+          schema:
+            type: string
+          description: 调用人摘要筛选
+        - name: module
+          in: query
+          schema:
+            type: string
+          description: 业务模块筛选
+        - name: status
+          in: query
+          schema:
+            type: string
+            enum: [success, failed, slow, sensitive, redacted]
+          description: 调用状态筛选
+        - name: startTime
+          in: query
+          schema:
+            type: string
+            format: date-time
+        - name: endTime
+          in: query
+          schema:
+            type: string
+            format: date-time
+      responses:
+        '200':
+          description: 接口调用日志分页列表
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
+                  - type: object
+                    properties:
+                      data:
+                        allOf:
+                          - $ref: '../openapi-base.yaml#/components/schemas/PaginatedResult'
+                          - type: object
+                            properties:
+                              list:
+                                type: array
+                                items:
+                                  $ref: '#/components/schemas/ApiAccessLogSummary'
+        '400':
+          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
+        '401':
+          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
+        '403':
+          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
+  /admin-api/muse/audit/api-logs/{logId}:
+    get:
+      tags: [Admin Jobs & Events]
+      summary: 查询接口调用日志详情
+      description: |
+        查询单条接口调用日志的脱敏详情。敏感详情查看本身必须写入业务审计事件。
+      operationId: adminGetApiAccessLog
+      security:
+        - adminBearerAuth: []
+      parameters:
+        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
+        - name: logId
+          in: path
+          required: true
+          schema:
+            type: integer
+            format: int64
+      responses:
+        '200':
+          description: 接口调用日志详情
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
+                  - type: object
+                    properties:
+                      data:
+                        $ref: '#/components/schemas/ApiAccessLogDetail'
+        '400':
+          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
+        '401':
+          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
+        '403':
+          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
   /admin-api/muse/audit/business-events:
     get:
       tags: [Admin Jobs & Events]
@@ -1102,17 +1207,52 @@ paths:
                                 type: array
                                 items:
                                   $ref: '#/components/schemas/BusinessAuditEventSummary'
-
-  # ====================================================================
-  # App AI 任务与候选（设计文档 4.5）
-  # ====================================================================
-
         '400':
           $ref: '../openapi-base.yaml#/components/responses/BadRequest'
         '401':
           $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
         '403':
           $ref: '../openapi-base.yaml#/components/responses/Forbidden'
+  /admin-api/muse/audit/business-events/{eventId}:
+    get:
+      tags: [Admin Jobs & Events]
+      summary: 查询业务审计详情
+      description: |
+        查询高危操作、敏感读取、配置变更和治理动作的审计详情。
+        before/after 快照必须为脱敏摘要，审计事件 append-only，不提供修改或删除接口。
+      operationId: adminGetBusinessAuditEvent
+      security:
+        - adminBearerAuth: []
+      parameters:
+        - $ref: '../openapi-base.yaml#/components/parameters/XApiVersion'
+        - name: eventId
+          in: path
+          required: true
+          schema:
+            type: integer
+            format: int64
+      responses:
+        '200':
+          description: 业务审计详情
+          content:
+            application/json:
+              schema:
+                allOf:
+                  - $ref: '../openapi-base.yaml#/components/schemas/CommonResult'
+                  - type: object
+                    properties:
+                      data:
+                        $ref: '#/components/schemas/BusinessAuditEventDetail'
+        '400':
+          $ref: '../openapi-base.yaml#/components/responses/BadRequest'
+        '401':
+          $ref: '../openapi-base.yaml#/components/responses/Unauthorized'
+        '403':
+          $ref: '../openapi-base.yaml#/components/responses/Forbidden'
+
+  # ====================================================================
+  # App AI 任务与候选（设计文档 4.5）
+  # ====================================================================
   /app-api/muse/ai/tasks:
     post:
       tags: [App AI]
@@ -2352,6 +2492,76 @@ components:
           type: string
           format: date-time
 
+    ApiAccessLogSummary:
+      type: object
+      required: [logId, requestId, actor, method, pathSummary, status, statusCode, durationMs, createdAt]
+      properties:
+        logId:
+          type: integer
+          format: int64
+        requestId:
+          type: string
+          description: 请求链路 ID
+        actor:
+          type: string
+          description: 调用人脱敏摘要
+        actorType:
+          type: string
+          enum: [admin, system, user, anonymous]
+        module:
+          type: string
+          description: 业务模块
+        method:
+          type: string
+          enum: [GET, POST, PUT, PATCH, DELETE]
+        pathSummary:
+          type: string
+          description: 脱敏路径摘要，不能包含敏感查询参数
+        objectSummary:
+          type: string
+          description: 关联对象脱敏摘要
+        clientIp:
+          type: string
+          description: 客户端 IP 脱敏摘要
+        status:
+          type: string
+          enum: [success, failed, slow, sensitive, redacted]
+        statusCode:
+          type: integer
+        durationMs:
+          type: integer
+          description: 接口耗时毫秒数
+        errorCode:
+          type: string
+        errorSummary:
+          type: string
+        createdAt:
+          type: string
+          format: date-time
+
+    ApiAccessLogDetail:
+      allOf:
+        - $ref: '#/components/schemas/ApiAccessLogSummary'
+        - type: object
+          properties:
+            requestHeadersSummary:
+              type: object
+              description: 请求头脱敏摘要，不包含 token、secret、cookie 或完整 header
+              additionalProperties:
+                type: string
+            requestBodySummary:
+              type: object
+              description: 请求体脱敏摘要，不包含用户私有正文全文
+              additionalProperties: true
+            responseBodySummary:
+              type: object
+              description: 响应体脱敏摘要，不包含用户私有正文全文
+              additionalProperties: true
+            relatedAuditEventId:
+              type: integer
+              format: int64
+              description: 查看敏感调用详情时写入的业务审计事件 ID
+
     BusinessAuditEventSummary:
       type: object
       required: [eventId, eventType, operator, createdAt]
@@ -2378,6 +2588,36 @@ components:
           type: string
           format: date-time
 
+    BusinessAuditEventDetail:
+      allOf:
+        - $ref: '#/components/schemas/BusinessAuditEventSummary'
+        - type: object
+          properties:
+            reason:
+              type: string
+              description: 操作理由
+            result:
+              type: string
+              enum: [success, failed, rejected, pending_review]
+              description: 操作结果
+            beforeSnapshot:
+              type: object
+              description: 变更前脱敏快照摘要
+              additionalProperties: true
+            afterSnapshot:
+              type: object
+              description: 变更后脱敏快照摘要
+              additionalProperties: true
+            impactSummary:
+              type: string
+              description: 影响范围摘要
+            approvalSummary:
+              type: string
+              description: 审批或复核摘要
+            immutable:
+              type: boolean
+              description: 审计事件是否 append-only
+
     # ==================================================================
     # App AI Schemas
     # ==================================================================

docs/superpowers/plans/2026-05-24-P3-muse-admin.md

@@ -2,7 +2,7 @@
 
 > **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task.
 
-**目标:** 在 Vben Admin fork 基础上搭建 muse-admin，实现 MetaSchema 管理、系统治理、AI 配置、市场治理、全局知识管理 5 个功能域。
+**目标:** 在 Vben Admin fork 基础上搭建 muse-admin，实现 MetaSchema 管理、系统治理、AI 配置、市场治理、全局知识管理、Account/New-API、任务监控、日志审计功能域。
 
 **架构:** Vue 3 + Vben Admin + TypeScript，Composition API + SFC script setup，defHttp API 集成，Vben 内置表格/表单组件复用。
 
@@ -10,6 +10,13 @@
 
 注: muse-admin 已 fork 完成，存在 `apps/web-antd` 和 `packages/` 结构。
 
+**合同校准（2026-05-24）:**
+
+- 以 `design-docs/产品-02B-管理员控制台功能规格.md`、`docs/dev-baseline/muse-admin/CLAUDE.md` 和 `docs/api-contracts/**/openapi.yaml` 为实现依据；本文示例代码如与上述合同冲突，以上述合同为准。
+- Muse 业务页面目录使用 `apps/web-antd/src/views/muse/**`，不是根级 `src/views/{governance,ai,...}`。
+- Account/New-API 页面只实现治理和对账所需的脱敏摘要、配额调整、网关绑定、余额查询、调用日志归属；用户侧账户完整体验仍由 `产品-02G` 承接。
+- 日志审计必须包含接口调用日志和业务审计日志两个 surface；对应契约为 `/admin-api/muse/audit/api-logs`、`/admin-api/muse/audit/api-logs/{logId}`、`/admin-api/muse/audit/business-events`、`/admin-api/muse/audit/business-events/{eventId}`。
+
 ---
 
 ## Step 1: 工程调整
@@ -21,8 +28,8 @@
 - [ ] **Step 1: 创建业务模块目录**
 
 ```bash
-mkdir -p muse-admin/apps/web-antd/src/views/{governance,ai,knowledge,market,account,jobs,audit}
-mkdir -p muse-admin/apps/web-antd/src/api/muse/{governance,ai,knowledge,market,account,jobs,audit}
+mkdir -p muse-admin/apps/web-antd/src/views/muse/{governance,ai,knowledge,market,account,newapi,jobs,audit}
+mkdir -p muse-admin/apps/web-antd/src/api/muse/{governance,ai,knowledge,market,account,newapi,jobs,audit}
 ```
 
 - [ ] **Step 2: 检查现有结构**
@@ -35,8 +42,8 @@ ls muse-admin/packages/@core/
 - [ ] **Step 3: 提交**
 
 ```bash
-git add muse-admin/apps/web-antd/src/views/governance/ muse-admin/apps/web-antd/src/api/muse/
-git commit -m "feat(struct): 建立管理端业务模块目录（governance/ai/knowledge/market/account）"
+git add muse-admin/apps/web-antd/src/views/muse/ muse-admin/apps/web-antd/src/api/muse/
+git commit -m "feat(struct): 建立管理端业务模块目录"
 ```
 
 ### Task 1.2: API 类型集成
@@ -239,7 +246,7 @@ git add -A && git commit -m "feat(governance): 实现 MetaSchema 列表页（Vbe
 | 用户权益列表 | `/account/entitlements` | 表格：用户 + 权益类型 + 上限 + 已用 + 过期时间 |
 | 配额调整表单 | `/account/quota-adjustments` | 弹窗：用户 + 资源类型 + 调整量 + 原因 + commandId |
 | New-API 绑定状态 | `/account/new-api-bindings` | 表格：用户 + 绑定状态 + 同步状态 |
-| 购买/使用记录 | `/account/records` | 只读汇总表格 |
+| 购买/使用记录 | `/account/records` | 只读脱敏治理摘要；不实现 `产品-02G` 的用户侧完整账户体验 |
 
 **API endpoints:**
 
@@ -248,6 +255,8 @@ GET    /admin-api/muse/account/users                        # 用户列表
 GET    /admin-api/muse/account/users/{userId}/entitlements  # 用户权益
 POST   /admin-api/muse/account/users/{userId}/quota-adjustments  # 配额调整
 GET    /admin-api/muse/account/new-api-bindings             # New-API 绑定状态
+GET    /admin-api/muse/account/usage-records                # 脱敏用量摘要
+GET    /admin-api/muse/account/purchase-records             # 脱敏购买摘要
 ```
 
 **代码示例 — API service:**
@@ -367,11 +376,16 @@ export function listSourceEvents(params: { pageNo: number; pageSize: number }) {
 |------|------|------|
 | 业务审计事件列表 | `/audit/business-events` | 表格：时间戳 + 操作者 + 操作 + 目标 + 结果 |
 | 审计详情 | `/audit/business-events/:eventId` | 完整 before/after 快照对比 |
+| 接口调用日志 | `/audit/api-logs` | 表格：请求 ID + 调用人 + 路径摘要 + 状态码 + 耗时 |
+| 接口调用详情 | `/audit/api-logs/:logId` | 只展示脱敏请求/响应摘要，不展示 token、secret、完整 header 或私有正文 |
 
 **API endpoints:**
 
 ```
+GET    /admin-api/muse/audit/api-logs              # 接口调用日志列表
+GET    /admin-api/muse/audit/api-logs/{logId}      # 接口调用日志详情
 GET    /admin-api/muse/audit/business-events       # 业务审计事件列表
+GET    /admin-api/muse/audit/business-events/{eventId} # 业务审计详情
 ```
 
 **代码示例 — API service:**
@@ -419,4 +433,4 @@ export function getBusinessAuditDetail(eventId: string) {
 - [ ] 组件单元测试覆盖率 ≥70%（Vitest + Vue Test Utils）
 - [ ] E2E 测试覆盖核心管理流程（Playwright）
 - [ ] ESLint + Prettier + TypeScript 类型检查通过
-- [ ] Vite build 成功
+- [ ] Vite build 成功