# AI Coding 工具用量（AI Usage）

> **负责人**: chentao.jia
> **模块标识**: `it-operations/ai-usage`
> **状态**: 🚧 In Progress (Draft → PRD 中)
> **提单**: [Issue #338](http://43.130.59.228/FFAIWorkspace/workspace/issues/338)
> **最后更新**: 2026-05-15

---

## 📋 文档导航

| 文档 | 状态 | 最后更新 |
|------|------|---------|
| [产品需求文档](./01-prd.md) | 🚧 Draft | 2026-05-15 |
| [状态机](./04-state-machine.md) | 🚧 Draft | 2026-05-15 |
| [UI 交互规范](./05-ui-interaction-spec.md) | 🚧 Draft | 2026-05-15 |
| [数据模型](./06-data-model.md) | 🚧 Draft | 2026-05-15 |
| [API 文档](./07-api.md) | 🚧 Draft | 2026-05-15 |
| [错误码](./08-error-codes.md) | 🚧 Draft | 2026-05-15 |
| [测试场景](./09-test-scenarios.md) | 🚧 Draft | 2026-05-15 |

---

## 📌 概述

为全公司 Claude Code + Codex CLI 用量提供跨员工、跨机器、跨项目的集中可见 dashboard。作为 `it-operations` 一级模块的 sub-capability，与 `cloud-costs` 并列。

### 何时读取

| 任务 | 必读 |
|------|------|
| 改 ingestion 逻辑 / token 鉴权 | `07-api.md` + `04-state-machine.md` |
| 改 dashboard 查询 / 聚合 | `06-data-model.md` + `07-api.md` |
| 改前端页面 | `05-ui-interaction-spec.md` + `07-api.md` |
| 改 schema / 加字段 | `06-data-model.md` + `01-prd.md`「隐私与合规」段 |
| 改客户端 agent | `01-prd.md` § 1 + `07-api.md` § 1 + `04-state-machine.md` § 3 |
| 错误处理 / 客户端 retry | `08-error-codes.md` |
| 写测试 | `09-test-scenarios.md` |

---

## 🏗️ 技术信息

### 代码位置（MVP 独立挂载，避免空头复用 it-operations 外壳）

- 后端：`backend/src/modules/ai-usage/`（独立顶层模块）
- 前端 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）
- Schema：`backend/prisma/schema/platform_ai_usage.prisma`（**新建**，独立于 `platform_ai.prisma`）
- 客户端 agent：`tools/ffctk/`（新建目录）

### API Base

- Ingestion：`POST /api/v1/ai-usage/events`（Bearer = personal token）
- 业务 API：`/api/v1/ai-usage/...`（JWT + `@RequirePermissions`）

### 权限点（IAM 新增）

- `ai-usage:view-own` — 看自己
- `ai-usage:view-all` — 看全公司
- `ai-usage:manage-tokens-all` — admin 跨用户 token 管理
- `ai-usage:block-device` — 拉黑/解黑 device
- `ai-usage:export` — 导出 CSV