# IT 运营 / AI Coding 用量 - UI 交互规范 > **版本**: v0.1 > **最后更新**: 2026-05-15 > **维护者**: 前端团队 --- ## ✅ 机器读取区（必填） ### 页面与路由 > ⚠️ MVP 阶段独立顶层挂载（it-operations 模块外壳尚未实现，避免空头复用）；外壳就绪后路由 alias 切换，不改 URL。 | 路由 | 标题（zh / en） | 权限 | 描述 | |------|----|------|------| | `/admin/ai-usage` | AI Coding 用量 / AI Coding Usage | `ai-usage:view-all` | Admin 总览 | | `/admin/ai-usage/devices` | 设备管理 / Devices | `ai-usage:view-all` | Admin device 列表 | | `/admin/ai-usage/tokens` | Token 管理 / Tokens | `ai-usage:manage-tokens-all` | Admin token 列表 | | `/admin/ai-usage/dlq` | 死信队列 / DLQ | `ai-usage:view-all` | Admin DLQ | | `/me/ai-usage` | 我的 AI 用量 / My AI Usage | `ai-usage:view-own` | 员工自查 | | `/me/ai-usage/tokens` | 我的 Token / My Tokens | `ai-usage:view-own` | 员工自助 | ### 文件位置 - 前端 admin 路由：`frontend/src/app/(modules)/admin/ai-usage/` - 前端 me 路由：`frontend/src/app/(modules)/me/ai-usage/` - i18n：`frontend/src/locales/aiUsage/`（含 `zh-CN.ts` + `en-US.ts`，按现有 `aiAssistant` / `iamAdmin` 等目录惯例） ### 导航 - 主菜单（admin 视角）新增顶层条目 "AI Coding 用量"（zh）/ "AI Coding Usage"（en），icon 用 `bot` 或 `activity` - 个人菜单（"我的"）下新增 "AI 用量" 条目（跳 `/me/ai-usage`） - 待 it-operations 模块外壳就绪后，admin 主菜单条目迁移到 "IT 运营 → AI Coding 用量" 二级 ### 设计系统 - 严格遵循 Lark 设计系统（参考 frontend-main skill 标准文档） - 颜色：成本红线用 `--color-danger-6`，正常用 `--color-primary-6` - 图表库：Apache ECharts（项目现有依赖） - 表格：项目内 `` 组件 - 文案全部走 i18n key，**无硬编码** --- ## 1. Admin 总览 `/it-operations/ai-usage` ### 布局 ``` ┌────────────────────────────────────────────────────────────────┐ │ 顶部筛选条：[期间▾] [组织▾] [刷新] [导出 CSV] │ ├────────────────────────────────────────────────────────────────┤ │ KPI 卡片 × 4 │ │ ┌───────┐┌───────┐┌───────┐┌───────┐ │ │ │总成本 ││总Token││活跃员工││活跃项目│ │ │ │$xx.xx ││ x.xM ││ xx ││ xx │ │ │ │▲ 5.2% ││▲ 7.1% ││ - 0 ││▼ 2 │ │ │ └───────┘└───────┘└───────┘└───────┘ │ ├────────────────────────────────────────────────────────────────┤ │ 趋势曲线（标题"用量趋势"，右上：[粒度▾] [分组▾]） │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ 📈 折线图 / 堆叠柱图 │ │ │ └────────────────────────────────────────────────────────┘ │ ├────────────────────────────────────────────────────────────────┤ │ 下钻 Tab：[员工] [项目] [工具] [模型] │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ 表格：name | dev 数 | token | cost | 占比 | 环比 | ⋯ │ │ │ │ 分页 + 排序 + 搜索 │ │ │ └────────────────────────────────────────────────────────┘ │ └────────────────────────────────────────────────────────────────┘ ``` ### 交互细节 **期间筛选**： - 选项：今日 / 本周 / 本月（默认） / 本年 / 近 7 天 / 近 30 天 / 近 90 天 / 自定义区间 - 自定义区间用 DateRangePicker，最大跨度 1 年（超出走归档表，提示"已切换到日级聚合"） **趋势曲线**： - 粒度：日 / 周 / 月（根据期间长度智能默认；员工可改） - 分组：无 / 按工具 / 按模型 / 按 Top 5 员工 - hover 显示 tooltip：日期 + 各 series 数值 - 点击图例可隐藏 series **下钻表**： - 默认按 cost desc 排序 - 行点击 → 弹抽屉显示该维度的详细 event 列表（最近 200 条） - "导出 CSV" 按当前筛选 + 排序导出 **空数据**： - 还未有任何 ingestion → 显示引导卡 "邀请员工接入" + 安装文档链接 + 复制 install 命令按钮 --- ## 2. Admin Device 列表 `/it-operations/ai-usage/devices` ### 表格列 | 列 | 说明 | |---|---| | hostname | 主显示 | | 归属员工 | name + email + avatar | | 平台 | linux / darwin / windows icon | | OS user | 文本 | | 首次接入 | 相对时间 | | 最后上报 | 相对时间，> 14 天高亮黄 | | 状态 | ACTIVE 绿 / BLOCKED 红 | | 近 30 天用量 | tokens / costUsd | | 操作 | 拉黑 / 解黑 / 查看详情 | ### 筛选 - 状态：全部 / ACTIVE / BLOCKED - 平台：全部 / linux / darwin / windows - 搜索：hostname / userEmail / deviceId - 异常筛选 chip：「14 天无上报」「软指纹冲突」「疑似 token 共用」 ### 操作 - **拉黑**：弹 modal 输入 reason（必填，长度 1-500，i18n 占位文本"请说明拉黑理由（员工离职、陌生设备等）"），confirm 后调 API；toast 成功 - **解黑**：弹 modal 输入 note（可选），confirm 后调 API - **详情抽屉**：show device 全部字段 + 最近 100 条 event 列表 + audit log 时间线 --- ## 3. Admin Token 列表 `/it-operations/ai-usage/tokens` 简化版 device 列表样式： | 列 | 说明 | |---|---| | name | 员工自命名 | | prefix | `ffai_xxxxxxxx`（只读，非可点击）| | 归属员工 | name + email | | 最后使用 | 相对时间 | | 最后 IP | 文本 | | 状态 | ACTIVE / REVOKED | | 操作 | 撤销（仅 ACTIVE） | 撤销前 confirm modal 提示"撤销后该 token 立即失效，无法恢复，员工需重新生成。请输入理由：" --- ## 4. Admin DLQ `/it-operations/ai-usage/dlq` 简单表格： | 列 | |---| | 时间 | 原因（chip 配色） | device | raw payload preview (点击展开 JSON viewer) | 筛选：reason × 时间区间。无操作（只读，用于排查）。 --- ## 5. 员工自查 `/me/ai-usage` ### 布局 ``` ┌────────────────────────────────────────────────────────┐ │ 顶部：欢迎语 + 期间筛选 + [管理我的 Token →] │ ├────────────────────────────────────────────────────────┤ │ KPI 卡片 × 3：本期 cost / token / 活跃 device 数 │ ├────────────────────────────────────────────────────────┤ │ 趋势曲线（个人维度） │ ├────────────────────────────────────────────────────────┤ │ 项目分布饼图 + Top 5 表格 │ ├────────────────────────────────────────────────────────┤ │ 模型分布饼图 + 表格 │ ├────────────────────────────────────────────────────────┤ │ 我的 device 列表（hostname / 平台 / 最后上报 / 状态） │ ├────────────────────────────────────────────────────────┤ │ "隐私 FAQ" 折叠面板（采集了什么 / 没采集什么） │ └────────────────────────────────────────────────────────┘ ``` ### 注意 - 员工自己看完整 project 路径（不脱敏） - 若有 device 被 admin 拉黑，列表显著标红 + tooltip"已被管理员拉黑，请联系 IT" - 底部固定操作："导出我的全部数据 (CSV)" + "申请删除我的历史数据"（开 modal 选时间区间 → 提交 → admin 审批） --- ## 6. 员工 Token 自助 `/me/ai-usage/tokens` ### 顶部 - 标题"我的 Token" - 主按钮"+ 生成新 Token" - 副链接"接入指南"（跳安装文档 anchor） ### 列表 | 列 | |---| | name（可编辑，inline 改）| prefix | createdAt | lastUsedAt | lastUsedIp | 操作 | 操作列：撤销（带 confirm modal） ### 生成 Modal ``` ┌──────────────────────────────────────────┐ │ 生成新 Token │ ├──────────────────────────────────────────┤ │ Token 名称 (用于区分多台机器)： │ │ [我的 Mac ] │ │ │ │ 取消 生成 │ └──────────────────────────────────────────┘ ``` 生成成功 → 切换为"已生成"视图： ``` ┌──────────────────────────────────────────┐ │ ✅ Token 生成成功 │ │ │ │ ⚠️ 此 Token 仅显示一次，关闭后无法再次查看 │ │ │ │ ffai_a1b2c3d4e5f6789012345678901234... │ │ [复制] │ │ │ │ 接入步骤： │ │ 1. curl ...install.sh | bash │ │ 2. ffctk login <粘贴 token> │ │ 3. ffctk start │ │ │ │ [复制全部命令] 我已保存关闭 │ └──────────────────────────────────────────┘ ``` 关闭按钮 disabled 直到点过"复制"或"复制全部命令"，避免员工忘存（hack：30 秒后强制启用，防止永远关不掉）。 --- ## 7. i18n key 总览 **集成方式**：项目按 `frontend/src/locales//{zh-CN,en-US}.ts` 每模块一目录组织，在 `frontend/src/locales/index.ts` 聚合。本模块新建 `frontend/src/locales/aiUsage/` 目录，文件结构参考 `frontend/src/locales/aiAssistant/`（同类规模模块）。 所有可见文案使用 i18n key，禁止硬编码。命名空间 `aiUsage.*`（按现有目录 camelCase 命名风格，**不用** kebab-case 的 `aiUsage.*`）： ``` aiUsage.menu.title.admin aiUsage.menu.title.me aiUsage.menu.tokens aiUsage.menu.devices aiUsage.kpi.total_cost aiUsage.kpi.total_tokens aiUsage.kpi.active_users aiUsage.kpi.active_projects aiUsage.kpi.active_devices aiUsage.trend.title aiUsage.trend.granularity.day aiUsage.trend.granularity.week aiUsage.trend.granularity.month aiUsage.trend.group_by.none aiUsage.trend.group_by.tool aiUsage.trend.group_by.model aiUsage.trend.group_by.top_user aiUsage.breakdown.tab.user aiUsage.breakdown.tab.project aiUsage.breakdown.tab.tool aiUsage.breakdown.tab.model aiUsage.empty.invite_to_install aiUsage.empty.copy_install_cmd aiUsage.token.list.title aiUsage.token.create.button aiUsage.token.create.dialog.title aiUsage.token.create.name_label aiUsage.token.create.name_placeholder aiUsage.token.create.warning_visible_once aiUsage.token.create.copy_all aiUsage.token.revoke.confirm.title aiUsage.token.revoke.confirm.body aiUsage.token.revoke.reason_label aiUsage.device.block.confirm.title aiUsage.device.block.reason_label aiUsage.device.block.reason_placeholder aiUsage.device.unblock.note_label aiUsage.privacy.faq.title aiUsage.privacy.faq.what_collected aiUsage.privacy.faq.what_not_collected aiUsage.privacy.export_my_data aiUsage.privacy.request_deletion aiUsage.toast.token.created aiUsage.toast.token.revoked aiUsage.toast.device.blocked aiUsage.toast.device.unblocked aiUsage.errors.invalid_token aiUsage.errors.device_blocked aiUsage.errors.rate_limit_exceeded aiUsage.errors.batch_too_large aiUsage.errors.invalid_payload aiUsage.errors.network_unreachable ``` en-US 与 zh-CN 两套都必须提交。 --- ## 8. 关键边界与空态 | 场景 | UI 行为 | |------|---------| | 员工还没生成过 token | `/me/ai-usage` 显示引导卡 + "生成第一个 Token →" 按钮 | | 生成过 token 但还没上报 event | `/me/ai-usage` KPI 全 0 + 显示"等待客户端首次上报，通常 30 秒内"的提示 | | Admin 全公司 0 event | 总览页显示"邀请员工接入"卡 + 复制 install URL | | 数据查询失败 | 卡片显示骨架 → 错误态"加载失败 [重试]" | | 网络断开 | 全局 banner"网络断开，数据可能过期" | --- ## 9. 响应式 - 桌面 ≥ 1280px：完整布局 - 平板 768-1280：图表全宽，KPI 卡 2 列 - 移动 < 768：员工自查页支持，admin 总览页仅显示警示 banner "请使用桌面浏览器获取完整体验" --- ## 10. 可访问性 - 所有交互元素有 aria-label - 表格用 role="grid"，行 role="row" - 拉黑/撤销 modal focus trap - 数字 + 颜色双编码（不能只靠颜色区分状态）