# 《先马 AI 设计平台｜数据智能｜管理报表完整模块 PRD》

## 0. 文档信息

| 项目 | 内容 |
|---|---|
| 所属平台 | 先马 AI 设计平台 |
| 所属模块 | 管理区 / 数据智能 |
| 需求类型 | 完整模块 PRD / 真实数据能力建设 |
| 文档版本 | V1.1 |
| 文档状态 | 已确认，待技术评审与开发排期 |
| 创建日期 | 2026-08-25 |
| REQ 需求来源 | 无独立 REQ；来源为用户 2026-08-18 至 2026-08-25 对数据智能报表原型、权限和统计口径的逐项确认 |
| 项目业务输入 | `01_业务输入/需求入口.md` |
| 关键证据 | `先马AI设计平台_埋点需求PRD_V1.0_2026-07-27.md`、`平台使用数据快照_2026-07-30.txt`、项目记忆 2026-08-18 至 2026-08-20 数据智能记录 |
| 对应原型 | `/admin/data`；`src/app/admin/data/DataOverviewClient.jsx`；`src/data/demo/data-intelligence.js` |
| 原型版本 | 2026-08-20 最终统计口径，2026-08-25 资产与复用模拟数据复验版 |

### 0.1 变更摘要

1. 将当前六主题演示原型转为可使用真实数据的管理报表，统一时间、组织和功能查询条件。
2. 复用现有平台权限与组织数据范围：系统管理员查看全公司；主管或部门管理员查看授权组织及下级；普通用户不开放个人报表入口。
3. 复用既有埋点 PRD 已定义的任务、结果、积分和资产事件，并补齐创作链、组织快照、资源所有人与跨任务复用关联字段。

### 0.2 版本记录

| 版本 | 日期 | 变更内容 | 状态 |
|---|---|---|---|
| V1.0 | 2026-08-25 | 冻结页面范围、权限、统计口径、数据边界和 30 条验收标准 | 已确认 |
| V1.1 | 2026-08-25 | 增加旧埋点/补强/本期新增标识；补齐逐事件采集位置、成功时机、幂等规则、逐指标映射、接口响应字段、Codex 实施顺序及最小回归数据集 | 已确认，待技术评审与开发排期 |

## 1. 需求背景与目标

### 1.1 当前问题

`/admin/data` 已完成可点击前端原型，但页面数字来自 `src/data/demo/` 的脱敏模拟数据。当前原型可以确认信息架构、指标口径和交互，不代表真实埋点、聚合接口、服务端权限或历史数据已经可用。

既有《全功能埋点与效果衡量需求》已覆盖大部分任务、结果、积分与资产事件，但以下能力仍不足以直接支撑当前报表：

- 事件、任务、结果、积分和资产使用尚未完成稳定串联与数据验收；
- 组织字段虽已设计，但报表要求事件发生时组织快照必须完整，不能随人员调岗漂移；
- 首轮直接采纳率缺少创作链与业务轮次字段；
- 跨任务复用和团队使用缺少任务、资源所有人与所属组织关联；
- 当前页面筛选主要驱动模拟展示，尚未形成真实查询契约；
- 模型字段历史完整性未验证，因此本期不展示模型筛选与模型分析。

### 1.2 本次目标

- 为系统管理员和部门主管提供同一套数据智能报表，不拆分企业版、部门版和个人版页面。
- 让管理者从使用规模、任务运行、积分投入、资产复用和人员使用结构判断平台运营状态。
- 统一六个主题、顶部筛选、指标口径、权限范围、统计归属和异常状态。
- 明确现有埋点可支持项与本次必须新增或补全的字段，形成研发和测试可执行的数据契约。
- 保持管理判断边界：报表不直接证明人工提效、业务 ROI、积分浪费或人员绩效。

### 1.3 成功判断

- 同一查询条件下，指标卡、图表、排行和明细使用同一数据范围并保持汇总守恒。
- 系统管理员、主管、部门管理员和无权限用户的入口与数据范围符合现有权限规则，前端不可扩大服务端授权范围。
- 六个主题可使用真实任务、结果、积分、资产与组织数据，不再读取前端模拟数据。
- 每个展示指标均能追溯到已验收的事件、事实表或平台业务表，并能说明统计口径。
- 缺失、延迟或异常数据不会被显示为 `0`，不会与正常数据混合形成错误管理结论。

## 2. 当前能力基线

| 编号 | 当前能力或规则 | 状态 | 事实来源 |
|---|---|---|---|
| BASE-01 | 管理区已有 `/admin/data` 数据智能入口和 `PageShell` 页面结构 | 当前原型 | 当前代码与导航配置 |
| BASE-02 | 页面包含数据总览、使用分析、任务与效率、积分使用、资产与复用、人员洞察六个主题 | 已确认 | 当前原型与项目记忆 |
| BASE-03 | 顶部查询条件包含时间、组织和功能，并位于六主题标签上方 | 已确认 | 用户确认与当前原型 |
| BASE-04 | 报表功能口径统一为 6 个生图工具、6 个 AI 能力和 AI 无限画布；技术标识归并到业务工具 | 已确认 | 项目记忆 2026-08-18 |
| BASE-05 | 生图、视频和画布以后台成功创建任务计一次实际使用；AI 提示词以核心动作成功计一次实际使用；页面访问不计 | 已确认 | 项目记忆与埋点 PRD |
| BASE-06 | AI 提示词纳入使用统计但不产生生图积分；积分报表只统计实际结算扣减 | 已确认 | 埋点 PRD与项目记忆 |
| BASE-07 | 结果下载、继续编辑、加入素材库、认可、复制/导出或带入其他任务属于成功后续行为；仅预览不计 | 已确认 | 埋点 PRD与项目记忆 |
| BASE-08 | 当前权限已具备系统管理员、主管、部门管理员、审批员和普通用户，以及组织数据范围计算 | 已确认 | 权限管理 PRD与当前权限原型 |
| BASE-09 | 当前报表全部数字为脱敏模拟数据，数据关系已通过守恒检查 | 当前原型占位 | `src/data/demo/data-intelligence.js` 与 2026-08-25 复验 |
| BASE-10 | 既有埋点 PRD要求历史数据不补埋，真实趋势从埋点正式生效日开始 | 已确认 | 埋点 PRD TBD-07 已确定项 |

### 2.1 已知原型差异

| 差异 | 正式规则 | 当前原型表现 | 本次是否处理 |
|---|---|---|---|
| 数据来源 | 正式报表只展示真实、已验收的数据 | 所有数字来自前端模拟数据 | 是，整体替换数据源 |
| 组织筛选 | 必须作用于六个主题内所有适用指标 | 当前主要用于人员候选展示，其他主题仍为模拟总量 | 是 |
| 时间筛选 | 必须作用于六个主题内所有周期指标 | 当前趋势按模拟总量重新分配，非真实日期序列 | 是 |
| 功能筛选 | 必须作用于任务、积分、人员和资产使用类指标 | 资产库存总量与部分范围统计保持模拟总量 | 是，按 6.3 筛选矩阵处理 |
| 权限展示 | 系统管理员与主管/部门管理员复用同一页面，显示各自有效范围 | 当前页头固定展示“系统管理员” | 是 |
| 空与异常 | 无记录显示空状态；查询失败显示错误状态 | 当前主要面向演示，缺少真实接口异常 | 是 |
| 模型分析 | 仅在统一模型标识和历史完整性验收后增加 | 当前已移除模型筛选 | 否，本期不做 |

## 3. 本次范围

### 3.1 本次变更

| 编号 | 变更类型 | 变更内容 | 影响页面/区域 | 事实来源 |
|---|---|---|---|---|
| CHG-01 | 新增 | 接入真实报表聚合数据，移除生产环境对模拟数据的依赖 | `/admin/data` 全页 | 用户本轮确认 |
| CHG-02 | 修改 | 时间、组织和功能条件作为全页统一查询上下文 | 顶部查询区、六个主题 | 用户多轮确认 |
| CHG-03 | 新增 | 系统管理员与主管/部门管理员按现有权限访问同一报表 | 页面入口、组织树、人员洞察 | 用户确认“按现在权限执行” |
| CHG-04 | 新增 | 数据总览、使用分析、任务与效率、积分使用真实统计 | 前四个主题 | 当前原型与已确认指标 |
| CHG-05 | 新增 | 素材与提示词资产沉淀、使用和团队复用真实统计 | 资产与复用 | 当前原型与已确认规则 |
| CHG-06 | 新增 | 授权范围内人员搜索、个人使用与产出结构真实统计 | 人员洞察 | 当前原型与已确认规则 |
| CHG-07 | 新增 | 补齐创作链、轮次、来源结果、组织快照、资源所有人和资产任务关联 | 埋点与事实数据 | 项目记忆 2026-08-19/20 |
| CHG-08 | 新增 | 加载、空、错误、无权限和数据未就绪状态 | 六个主题与弹窗 | 正式报表必要边界 |
| CHG-09 | 修改 | 指标说明统一为“指标解读、统计口径、管理参考” | 指标说明弹窗 | 已确认原型规则 |

### 3.2 本次不做

- 不展示人民币成本、人工节省工时、业务 ROI 或人工效率提升结论。
- 不增加模型筛选、模型排行或模型成功率分析；待 `model_key` 历史完整性和组合查询验收后另立增量需求。
- 不增加普通用户个人报表入口；个人仅作为有权限管理者的分析对象。
- 不提供任务流水明细、单个结果内容、原图、提示词全文或文件地址。
- 不提供综合评分、人员价值评分、绩效排名、浪费判断、低效判断或自动异常结论。
- 不提供报表导出、定时报表、订阅、阈值配置和异常告警。
- 不补造历史埋点数据；历史快照可作为独立存档证据，不与新埋点趋势混合。
- 不展示固定少样本阈值或固定阈值管理信号。

### 3.3 范围外建议

- 模型字段验收后增加“模型分析”专题，而不是把模型列硬塞入现有六主题。
- 完成真实数据稳定性验证后，再评估报表导出、订阅与异常提醒。
- 后续如普通用户确有自我复盘场景，再单独评估轻量个人使用摘要，不复用管理者人员洞察原样开放。

## 4. 用户与权限

### 4.1 角色权限

| 身份 | 页面入口 | 可选组织范围 | 人员洞察 | 说明 |
|---|---|---|---|---|
| 系统管理员 `SYSTEM_ADMIN` | 可见 | 全公司及全部下级组织 | 可查看授权范围内全部有记录人员 | 复用现有系统管理员权限 |
| 钉钉主管 `is_supervisor=true` | 可见 | 当前权限服务计算的所属组织、下级组织及有效附加范围 | 仅可查看有效范围内人员 | 主管标识来自聚合管理平台同步，不在报表中维护 |
| 部门管理员 `DEPARTMENT_ADMIN` | 可见 | 当前权限服务返回的有效组织范围及下级 | 仅可查看有效范围内人员 | 手动授权与主管默认角色按现有权限规则合并 |
| 审批员 `APPROVAL_ADMIN` | 不因审批员身份自动可见 | 无 | 无 | 审批权限不等于数据智能权限 |
| 普通用户 `MEMBER` | 不可见 | 无 | 无 | 不开放个人报表入口 |
| 停用账号 `DISABLED` | 不可访问 | 无 | 无 | 沿用账号停用规则 |

### 4.2 服务端权限规则

1. 页面入口隐藏不能替代服务端鉴权；所有报表查询必须按当前登录人的有效角色和组织范围过滤。
2. 客户端只可从服务端返回的可选组织树中选择范围，不得传入未授权组织扩大查询。
3. 选择父组织时包含全部下级；历史统计按事件或任务发生时的组织快照归属，不按人员当前组织回算。
4. 主管调岗、组织调整或附加授权失效后，历史事实归属不变，但其当前可见范围按最新权限重新计算。
5. 人员搜索只返回当前有效数据范围内、当前筛选条件下有实际使用记录的人员。

## 5. 用户流程

### 5.1 前置条件

- 用户已登录且账号状态为 `ACTIVE`。
- 权限服务可返回当前用户有效角色、可见组织根节点及下级范围。
- 埋点和任务事实已经过数据验收，报表可返回统计起点。

### 5.2 主流程

1. 有权限用户从管理区进入“数据智能”。
2. 系统加载默认时间“今日”、默认组织范围和“全部功能”。
3. 系统按同一查询上下文返回当前主题的指标、图表、排行、明细及数据元信息。
4. 用户修改时间、组织或功能，系统重新查询当前主题全部适用数据。
5. 用户切换六个主题，系统保留顶部查询条件并加载新主题数据。
6. 用户点击指标说明，系统展示该指标的解读、统计口径和管理参考。
7. 用户进入人员洞察后搜索或选择人员，系统只展示当前授权范围和筛选条件下有记录人员。

### 5.3 分支流程

- 当前条件无记录：展示当前主题空状态，保留查询条件供用户修改。
- 查询失败：不显示旧数字或 `0`，展示错误状态并允许重试。
- 权限失效：服务端拒绝查询；页面进入无权限状态，不保留先前敏感数据。
- 数据尚未达到统计起点：展示可用统计起点和空状态，不拼接 2026-07-30 历史快照。
- 用户切换主题时已滚动到标签下方：保持主题标签吸顶，并将内容定位到标签下方，不返回顶部筛选区。

## 6. 页面与交互规则

### 6.1 页面结构

| 区域 | 内容 | 交互规则 |
|---|---|---|
| 页头 | 页面标题、当前身份与有效组织路径 | 身份和路径由权限服务返回；不得固定写“系统管理员” |
| 查询区 | 时间、组织、功能 | 位于六主题标签上方；任何条件变化触发当前主题重新查询 |
| 主题标签 | 数据总览、使用分析、任务与效率、积分使用、资产与复用、人员洞察 | 切换保留查询条件；滚动后吸顶 |
| 核心指标 | 当前主题四项核心指标 | 人员洞察不使用统一四卡结构；每张指标卡支持说明 |
| 分析内容 | 图表、排行、表格、人员详情 | 使用同一查询上下文；表格只在自身区域横向滚动 |
| 指标说明 | 指标解读、统计口径、管理参考 | 顶层弹窗；支持关闭按钮、遮罩和 Escape 关闭 |

### 6.2 时间筛选

| 选项 | 规则 |
|---|---|
| 今日 | 上海时区当日 00:00 至查询时刻 |
| 近 7 天 | 含今日共 7 个上海自然日 |
| 近 30 天 | 含今日共 30 个上海自然日 |
| 自定义 | 用户选择开始日期和结束日期；开始不得晚于结束，结束不得晚于今日 |

趋势聚合粒度统一为：

- 今日：每 2 小时一个区间，共 12 个区间；未结束区间可展示当前累计值。
- 2 至 31 天：按上海自然日。
- 32 至 180 天：从所选开始日期起每 7 天一组，最后不足 7 天单独成组。
- 超过 180 天：按自然月。

### 6.3 筛选联动矩阵

| 数据类型 | 时间 | 组织 | 功能 | 说明 |
|---|---:|---:|---:|---|
| 实际使用、任务状态、任务效率 | 是 | 是 | 是 | 按任务或核心动作发生时间统计 |
| 积分消耗与积分效率 | 是 | 是 | 是 | 仅统计实际结算扣减；AI 提示词显示不扣积分 |
| 后续使用结果 | 是 | 是 | 是 | 分母为所选时间内生成的成功结果；后续行为统计截至查询时 |
| 可用素材数、可用提示词数 | 截止时间 | 是 | 否 | 属库存状态，不因功能筛选改变；按查询结束时点和权限范围统计 |
| 素材/提示词新增量 | 是 | 是 | 否 | 按资源创建时间统计 |
| 活跃资产、资产使用次数、热门资产 | 是 | 是 | 是 | 按使用行为发生时间及目标功能统计 |
| 人员候选与人员详情 | 是 | 是 | 是 | 只返回当前条件下有实际使用记录人员 |
| 注册用户覆盖率分母 | 截止时间 | 是 | 否 | 使用目标用户范围快照，不随功能变化 |

### 6.4 六个主题

#### 6.4.1 数据总览

- 核心指标：实际使用用户、实际使用次数、成功任务、积分消耗。
- 内容：高频功能、任务状态构成、管理关注项、部门使用与价值概览。
- 管理关注项固定从产出使用、创作过程、资产复用和积分效率展示数据事实，不生成异常或绩效结论。

#### 6.4.2 使用分析

- 核心指标：实际使用用户、注册用户覆盖率、实际使用次数、人均使用次数。
- 内容：功能使用次数排行、功能用户覆盖排行、部门使用统计、功能使用明细。
- 排序：默认按实际使用次数降序；同值按实际使用用户降序。

#### 6.4.3 任务与效率

- 核心指标：成功任务、取消任务、失败任务、平均处理时长。
- 部分成功任务计入成功任务；只有实际成功结果进入成功结果统计。
- 内容：任务状态构成、效率明细、功能运行状态。
- 平均处理时长按任务开始至任务最终结束计算；创建失败且无任务 ID 不进入处理时长。

#### 6.4.4 积分使用

- 核心指标：消耗积分、积分使用人数、平均每次使用积分、平均后续使用结果积分。
- 平均每次使用积分 = 消耗积分 / 扣积分实际使用次数。
- 平均后续使用结果积分 = 消耗积分 / 后续使用结果数；分母为 0 时显示 `--`，不显示 `0`。
- 内容：积分趋势、功能统计、部门统计、有效产出贡献 TOP N。
- 部门和人员默认按后续使用结果数降序，同值按消耗积分降序。
- 消耗积分仅表示投入；效率指标不作为人员绩效评价。

#### 6.4.5 资产与复用

- 核心指标：可用素材数、素材复用率、可用提示词数、提示词使用率。
- 素材实际使用：素材成功选入平台任务；仅浏览、预览或选择失败不计。
- 提示词实际使用：平台内复制成功或确认使用；成功带入工具单独计深层使用。
- 素材复用率 = 统计范围内被实际使用的去重可用素材数 / 统计范围内可用素材数。
- 提示词使用率 = 统计范围内被实际使用的去重可用提示词数 / 统计范围内可用提示词数。
- 内容：素材使用概览、提示词使用概览、个人/团队/公共范围统计、团队贡献与使用、热门素材、热门提示词。
- 灵感广场和站外行为不纳入本主题。
- 团队使用范围按资源所有人所属一级部门及其下级组织计算；其他一级部门使用计为跨团队使用。

#### 6.4.6 人员洞察

- 人员候选仅包含当前条件下有实际使用记录者，支持按姓名或部门搜索。
- 展示：人员基本信息、实际使用次数、有效活跃天数、使用功能数、主要使用功能、产出后续使用率、首轮直接采纳率、跨任务复用资产、被团队使用的素材与提示词、积分效率、功能使用结构和使用趋势。
- 有效活跃天数：上海自然日内至少发生一次任务创建成功、提示词核心动作成功、采纳成功或资产复用成功；登录、浏览、搜索、预览和失败动作不计。
- 对比范围只使用同部门、当前条件下有记录且有权限查看的人员均值。
- 固定从功能使用、资产复用和积分效率三个维度输出数据总结，不配置阈值，不做人员评分。

### 6.5 指标说明

每项指标说明固定包含：

1. **指标解读**：说明指标反映的组织状态及变化含义。
2. **统计口径**：说明计算、去重、时间归属和包含/排除范围。
3. **管理参考**：说明可辅助的决策以及不能直接得出的结论。

页面说明使用业务语言，不展示内部字段名、英文状态值或埋点参数名。

## 7. 核心统计规则

### R-01 实际使用

- 生图、视频和无限画布：后台成功创建任务计一次实际使用；任务后续失败或取消仍计入。
- AI 提示词：生成、润色或反推等核心动作成功计一次实际使用。
- 页面访问、入口点击、搜索、预览和任务创建失败不计实际使用。

### R-02 任务最终状态

- 每个 `task_id` 只按最终业务状态计一次。
- `SUCCESS` 与 `PARTIAL_SUCCESS` 计入成功任务。
- `FAILED`、`CANCELLED` 和未完成分别统计，不重复计入。
- 部分成功任务中只有成功结果进入成功结果和后续使用结果统计。

### R-03 后续使用结果

- 统计所选时间内生成成功，且截至查询时至少发生一次成功后续行为的去重 `result_id`。
- 成功后续行为包括下载、继续编辑、加入素材库、认可、复制/导出或跨任务复用。
- 同一结果发生多个动作只计一个后续使用结果；动作次数可另行统计。
- 仅预览、点击失败、取消动作或无后续行为不计。
- 历史结果之后发生成功后续行为时，原生成周期的后续使用结果数允许自然更新。

### R-04 创作链与首轮直接采纳

- 无来源任务、来源结果或来源历史的首次提交创建新 `creative_chain_id`，`round_index=1`。
- 继续编辑、基于结果重新生成、带入其他工具和从历史继续编辑沿用原创作链，业务轮次加一。
- 系统失败自动重试不增加业务轮次；用户主动重新提交按来源关系判断。
- 同一任务产生多张候选属于同一轮。
- 首轮任一成功结果发生直接采纳，该创作链计为一条首轮直接采纳链；同链只计一次。
- 首轮直接采纳率 = 首轮直接采纳创作链数 / 首轮成功产出结果的创作链数。

### R-05 积分统计

- 只统计 `credit_settled` 中实际完成扣减的积分，不统计申请、余额、补发或退还展示值。
- AI 提示词不进入积分消耗和积分排行。
- 积分必须通过 `task_id` 与任务、结果和后续使用事实关联。
- 任务失败、部分成功、重试和取消的积分按平台实际结算结果统计，报表不根据任务状态推算积分。

### R-06 组织归属

- 事件或任务创建时必须保存用户组织快照；组织未知仅作为异常兜底，不能归入任一业务部门。
- 历史归属使用事件发生时快照，不随人员当前组织变化。
- 报表需单独监控组织未知数据量；该数量不进入部门排行，但仍进入有合法任务事实的公司总量。

### R-07 统计一致性

- 同一查询条件下，卡片、趋势、排行和明细必须来自同一统计版本。
- 公司总量应与可见下级组织汇总一致；因组织未知或权限范围造成不一致时必须有可解释的独立项。
- 空值和数据缺失显示 `--` 或空状态，不得自动转为 `0`。

## 8. 状态、边界与异常

### 8.1 页面状态

| 状态 | 枚举标识 | 进入条件 | 页面表现 | 可执行操作 | 退出条件 |
|---|---|---|---|---|---|
| 加载中 | `LOADING` | 首次进入、切换条件或主题 | 保留页面骨架，指标与内容显示加载状态 | 可修改未提交条件的规则待技术确认 | 查询成功或失败 |
| 成功 | `SUCCESS` | 查询完成且有记录 | 展示指标、图表、排行和表格 | 筛选、切换主题、查看说明 | 再次查询 |
| 空数据 | `EMPTY` | 查询成功但当前条件无记录 | 展示“当前条件暂无数据”及当前范围 | 修改筛选 | 查询有记录 |
| 查询失败 | `ERROR` | 聚合接口失败、超时或数据校验失败 | 不展示旧数字；展示重试入口 | 重试、修改筛选 | 查询成功 |
| 无权限 | `FORBIDDEN` | 无有效角色、组织越权或权限已失效 | 隐藏数据内容，提示无权限 | 返回其他页面 | 权限恢复后重新进入 |
| 数据未就绪 | `NOT_READY` | 统计起点尚未生效或关键事实未通过验收 | 展示可用统计起点和说明，不展示模拟值 | 修改日期、返回 | 进入可用日期范围 |

枚举为产品建议命名，待技术确认后前后端统一，不得各自定义中文字符串判断。

### 8.2 边界

| 边界场景 | 处理规则 | 用户反馈 |
|---|---|---|
| 开始日期晚于结束日期 | 前端联动修正或阻止查询；服务端再次校验 | 日期字段明确提示 |
| 结束日期晚于今日 | 不允许提交 | 日期字段明确提示 |
| 选择未授权组织 | 前端不展示；伪造请求由服务端拒绝 | 进入无权限或返回授权范围错误 |
| 功能无积分 | 仍展示使用数据；积分主题显示“不扣积分” | 不参与积分排行 |
| 分母为 0 | 比率与单位效率显示 `--` | 指标说明仍可打开 |
| 人员无当前功能记录 | 不进入候选列表 | 人员区显示当前条件无匹配人员 |
| 组织未知 | 不进入部门排行 | 公司总量保留，数据质量侧可追踪 |
| 超长趋势区间 | 图表内容区局部横向滚动 | 页面本身不横向溢出 |

### 8.3 异常

| 异常场景 | 数据处理 | 页面处理 | 是否影响历史 |
|---|---|---|---|
| 单一数据源失败 | 当前主题不混合展示半套数据；接口返回失败或明确不可用项 | 展示错误并允许重试 | 不改历史事实 |
| 埋点重复上报 | 按事件唯一 ID或业务去重键幂等 | 用户无感 | 不重复计数 |
| 任务与积分无法关联 | 不推算单位成本；记录数据质量异常 | 相关效率显示 `--` 或主题失败 | 待修复关联后重算 |
| 资源所有人组织缺失 | 不计算团队与跨团队归属 | 相关范围显示不可用 | 原始使用事实保留 |
| 权限在页面打开后被撤销 | 下次查询立即拒绝并清空当前数据 | 进入无权限状态 | 历史事实不变 |
| 网络中断 | 不用缓存旧值覆盖新条件 | 展示错误和重试 | 无影响 |

## 9. 数据结构与埋点影响

### 9.1 复用既有对象

以下对象沿用《全功能埋点与效果衡量需求》现有结构，本 PRD只描述增量字段或必填性变化：

- `AnalyticsEvent`
- `GenerationTaskFact`
- `GenerationResultFact`
- `ResultAdoptionFact`
- `TargetUserScope`
- `credit_settled`、`task_created`、`task_finished`、`result_created` 与各类结果成功后续事件

### 9.2 报表查询对象 `AnalyticsReportQuery`

| 字段名 | 类型 | 必填 | 长度/范围 | 默认值 | 格式/枚举 | 校验规则 | 说明 |
|---|---|---:|---|---|---|---|---|
| start_date | 日期 | 是 | - | 今日 | `YYYY-MM-DD` | 不晚于 `end_date` | 上海时区开始日期 |
| end_date | 日期 | 是 | - | 今日 | `YYYY-MM-DD` | 不早于开始且不晚于今日 | 上海时区结束日期 |
| timezone | 字符串 | 是 | 固定值 | `Asia/Shanghai` | IANA 时区 | 本期仅允许固定值 | 统一自然日边界 |
| organization_id | 字符串 | 是 | 沿用组织结构 | 当前默认范围 | 组织 ID | 必须在服务端有效权限范围内 | 用户当前选中的组织根节点 |
| tool_key | 字符串 | 否 | 沿用埋点 PRD | 空 | 既有工具枚举 | 空表示全部功能 | 功能筛选 |
| theme_key | 枚举 | 是 | - | `OVERVIEW` | `OVERVIEW` / `USAGE` / `EFFICIENCY` / `POINTS` / `ASSETS` / `PEOPLE` | 非空 | 当前主题 |
| person_query | 字符串 | 否 | 长度待技术确认 | 空 | 文本 | 仅人员洞察使用 | 匹配姓名或部门展示名 |
| person_id | 字符串 | 否 | 沿用用户表 | 空 | 用户 ID | 必须在当前授权与筛选候选内 | 人员详情查询 |

### 9.3 任务与创作链增量字段

| 对象 | 字段名 | 类型 | 必填 | 默认值 | 格式/枚举 | 校验规则 | 说明 |
|---|---|---|---:|---|---|---|---|
| GenerationTaskFact | creative_chain_id | 字符串 | 是 | 无 | 沿用 ID 规范 | 全局可追溯 | 创作链 ID |
| GenerationTaskFact | round_index | 整数 | 是 | 1 | `>=1` | 同链业务轮次递增 | 系统自动重试不递增 |
| GenerationTaskFact | source_task_id | 字符串 | 否 | 空 | 任务 ID | 有来源任务时必填 | 来源任务 |
| GenerationTaskFact | source_result_id | 字符串 | 否 | 空 | 结果 ID | 基于结果继续时必填 | 来源结果 |
| GenerationTaskFact | source_history_id | 字符串 | 否 | 空 | 沿用历史 ID | 从历史继续时必填 | 既有字段提升为来源链规则的一部分 |
| GenerationTaskFact | organization_id_at_event | 字符串 | 是 | 无 | 组织 ID | 任务创建成功时必须保存 | 任务组织快照 |
| GenerationTaskFact | top_level_organization_id_at_event | 字符串 | 是 | 无 | 组织 ID | 可由组织快照稳定计算 | 一级部门归属 |
| GenerationTaskFact | organization_path_at_event | 字符串或数组 | 是 | 无 | 技术方案待确认 | 不作为唯一授权依据 | 用于历史展示和排查 |

### 9.4 结果与后续使用增量字段

| 对象 | 字段名 | 类型 | 必填 | 默认值 | 格式/枚举 | 校验规则 | 说明 |
|---|---|---|---:|---|---|---|---|
| GenerationResultFact | creative_chain_id | 字符串 | 是 | 无 | 沿用任务 | 与来源任务一致 | 结果所属创作链 |
| GenerationResultFact | round_index | 整数 | 是 | 无 | `>=1` | 与来源任务一致 | 结果所属业务轮次 |
| ResultAdoptionFact | event_id | 字符串 | 是 | 无 | 沿用事件 ID | 全局唯一 | 后续动作事实 ID |
| ResultAdoptionFact | user_id | 字符串 | 是 | 无 | 沿用用户表 | 非空 | 执行后续动作人员 |
| ResultAdoptionFact | task_id | 字符串 | 条件必填 | 空 | 任务 ID | 图片、视频和跨任务复用必须有 | 来源任务 |
| ResultAdoptionFact | creative_chain_id | 字符串 | 条件必填 | 空 | 创作链 ID | 生成结果后续行为必须有 | 用于首轮直接采纳 |
| ResultAdoptionFact | round_index | 整数 | 条件必填 | 空 | `>=1` | 生成结果后续行为必须有 | 判断首轮 |
| ResultAdoptionFact | organization_id_at_event | 字符串 | 是 | 无 | 组织 ID | 动作成功时保存 | 后续动作组织快照 |

### 9.5 资产使用事实对象 `AssetUsageFact`

| 字段名 | 类型 | 必填 | 默认值 | 格式/枚举 | 校验规则 | 说明 |
|---|---|---:|---|---|---|---|
| event_id | 字符串 | 是 | 无 | 沿用事件 ID | 全局唯一 | 使用事件 ID |
| event_time | 日期时间 | 是 | 服务端时间 | 时间戳 | 非空 | 使用行为发生时间 |
| resource_id | 字符串 | 是 | 无 | 素材或提示词 ID | 非空 | 资源 ID |
| resource_type | 枚举 | 是 | 无 | `MATERIAL` / `PROMPT` | 非空 | 资源类型 |
| resource_scope | 枚举 | 是 | 无 | `PERSONAL` / `TEAM` / `PUBLIC` | 灵感广场不进入 | 使用时资源范围 |
| action_type | 枚举 | 是 | 无 | `SELECT_TASK` / `COPY` / `CONFIRM_USE` / `APPLY_TOOL` / `CROSS_TASK_REUSE` | 非空 | 使用行为类型 |
| action_status | 枚举 | 是 | `SUCCESS` | `SUCCESS` / `FAILED` | 统计只使用成功 | 行为结果 |
| task_id | 字符串 | 条件必填 | 空 | 任务 ID | 选入任务、带入工具、跨任务复用时必填 | 补齐既有 `asset_reuse` 关联 |
| target_tool_key | 字符串 | 否 | 空 | 既有工具枚举 | 进入工具时必填 | 功能筛选 |
| user_id | 字符串 | 是 | 无 | 沿用用户表 | 非空 | 使用人 |
| organization_id_at_event | 字符串 | 是 | 无 | 组织 ID | 行为成功时保存 | 使用人组织快照 |
| top_level_organization_id_at_event | 字符串 | 是 | 无 | 组织 ID | 与组织快照一致 | 使用人一级组织 |
| owner_user_id | 字符串 | 是 | 无 | 沿用用户表 | 资源所有人非空 | 判断本人资产被使用 |
| owner_organization_id | 字符串 | 条件必填 | 空 | 组织 ID | 团队资源和人员复用分析必填 | 资源所有人所属组织快照 |
| owner_top_level_organization_id | 字符串 | 条件必填 | 空 | 组织 ID | 可稳定计算 | 判断团队内/跨团队使用 |

### 9.6 现有埋点支持与新增补充

| 报表能力 | 现有事件/字段 | 本次新增或补全 |
|---|---|---|
| 实际使用用户与次数 | `task_created`、`prompt_generate_success` 及成功核心动作 | 核验 AI 提示词 `mode` 完整覆盖生成、润色、反推 |
| 任务状态与耗时 | `task_status_change`、`task_finished`、`duration_ms` | 统一最终状态映射；组织快照改为必填 |
| 积分消耗与任务效率 | `credit_settled`、`task_id`、`result_id` | 验收任务、积分、结果稳定关联 |
| 后续使用结果 | 下载、继续编辑、加入素材库、认可、复制/导出成功事件 | 统一 `ResultAdoptionFact`；补创作链、轮次和组织快照 |
| 首轮直接采纳率 | 现有后续成功行为 | 新增 `creative_chain_id`、`round_index`、`source_result_id` |
| 素材复用 | `material_select_success`、`asset_reuse` | `asset_reuse.task_id` 必填；统一 `AssetUsageFact` |
| 提示词使用 | `text_copy_success`、`prompt_template_selected`、`prompt_apply_to_tool_success` | 补 `resource_id/resource_scope` 与资源所有人字段 |
| 团队与跨团队复用 | 用户与组织基础字段 | 新增资源所有人组织快照与一级组织字段 |
| 人员洞察 | 用户、任务、结果、积分、资产行为 | 所有事实按授权范围可关联到稳定 `user_id`；姓名只用于授权后展示 |

### 9.7 埋点来源状态与采集总则

本章状态用于研发识别工作量，不代表代码仓库中已经完成实现。研发或 Codex 必须先检查目标后端仓库、数据库迁移和公共埋点库，再把“产品事件”映射到现有物理表、消息或接口；不得仅凭本 PRD 新建语义重复的第二套服务。

| 状态 | 含义 | 开发动作 |
|---|---|---|
| `EXISTING` | 2026-07-27 旧埋点 PRD 已定义，且本期不改变采集语义 | 核实现状；已有则复用，缺失则按旧 PRD 补实现 |
| `EXISTING_ENHANCE` | 旧事件或事实对象已定义，但当前报表需要补必填字段、成功时机、组织快照或稳定关联 | 保留原事件名；迁移字段并补采集、回归和数据质量检查 |
| `NEW_THIS_PHASE` | 旧埋点 PRD 未定义，本期为支撑已确认报表新增 | 先复用现有业务审计/状态流水；确无等价事实时再新增表、事件或定时快照 |

统一采集规则：

1. 后端业务事实只在业务事务成功提交后采集；任务、结果、积分、资源状态不得依赖前端点击推算。
2. 前端成功行为只在对应 Promise、下载响应、参数恢复或页面接收动作成功后上报；点击、打开、预览失败均不进入核心指标。
3. 所有核心事实统一使用服务端接收时间校正，并保留原始客户端时间用于排查；报表时间归属使用事实表中的业务时间。
4. 后端事实优先使用“业务事务 + outbox/可靠消息”或现有等价机制；上报失败不得回滚主业务，重试必须使用同一幂等键。
5. 前端事件先生成全局唯一 `event_id`；失败时沿用旧 PRD 的 `analytics_report_retry` 机制，以 `original_event_id` 幂等重放。
6. 不采集提示词正文、图片 URL、文件内容、账号、联系方式或客户/订单信息。姓名和部门名从权限服务按当前授权展示，不写入事件主键。
7. 同一用户动作同时产生前端诊断事件和后端业务事实时，核心报表只统计后端规范化事实，禁止把两条原始事件相加。

### 9.8 采集事件目录

#### 9.8.1 公共必填字段

除下表单独说明外，进入报表的事件或事实必须包含：`event_id`、`event_name`、`event_time`、`user_id`、`tool_key`、`organization_id_at_event`、`top_level_organization_id_at_event`、`organization_path_at_event`。无登录用户或无工具语义的系统事实可不填 `user_id/tool_key`，但必须在事件定义中明确；组织未知写入质量异常，不得虚构组织。

#### 9.8.2 逐事件采集契约

| 事件/事实 | 状态 | 采集责任与代码触发点 | 成功采集时机 | 本期必填业务字段 | 幂等/去重键 | 报表用途 |
|---|---|---|---|---|---|---|
| `page_view` | `EXISTING` | Web 前端公共路由埋点；目标页面首屏可交互后触发 | 路由完成且页面容器渲染成功 | `page_path`、`source_page`（有来源时） | `event_id` | 仅数据质量和访问诊断；不计实际使用 |
| `task_created` / `GenerationTaskFact` | `EXISTING_ENHANCE` | 任务服务创建命令；任务记录事务提交后写事实 | 已生成稳定 `task_id` 且任务可被查询 | `task_id`、`submit_time`、`task_status`、`creative_chain_id`、`round_index`、来源 ID、组织快照 | `task_id` | 实际使用、用户、功能、组织、创作链分母 |
| `task_status_change` | `EXISTING_ENHANCE` | 任务编排/回调处理器；状态落库后写状态流水 | `old_status` 已成功更新为 `new_status` | `task_id`、`old_status`、`new_status`、`event_time`，失败时 `error_code` | 现有状态流水主键；无主键时 `task_id + new_status + 状态版本` | 状态追溯；最终统计仍以任务最终事实为准 |
| `task_cancelled` | `EXISTING_ENHANCE` | 用户取消命令处理器或任务超时/系统终止处理器 | 任务最终状态已落为 `CANCELLED` | `task_id`、`cancel_time`、`cancel_source`、`cancel_reason_code`、取消前成功结果数 | 每个 `task_id` 只保留最终取消事实 | 取消任务及取消来源；页面当前未单列原因时仍用于质量验收 |
| `task_finished` | `EXISTING_ENHANCE` | 任务服务最终态收敛处 | 最终状态、结果计数、开始/结束时间均已落库 | `task_id`、`task_status`、`start_time`、`finish_time`、`duration_ms`、成功/失败结果数 | `task_id` | 成功/失败/未完成、平均/中位耗时、2 分钟内完成率 |
| `credit_settled` | `EXISTING` | 积分结算服务；流水事务提交后采集 | 扣减、退回或不扣费结算结果已持久化 | `credit_record_id`、`task_id`、`settle_type`、`credit_cost`、`refund_credit` | `credit_record_id`；若现有流水无 ID，使用现有唯一业务键 | 消耗积分、积分用户、单位使用/结果积分；不得从任务状态推算 |
| `result_created` / `GenerationResultFact` | `EXISTING_ENHANCE` | 结果服务或模型回调持久化结果处 | 单个结果记录已提交并具有稳定 `result_id` | `result_id`、`task_id`、`result_type`、`result_status`、`creative_chain_id`、`round_index`、组织快照 | `result_id` | 成功结果、后续使用率分母、首轮链路 |
| `result_download_success` | `EXISTING_ENHANCE` | 下载接口返回成功文件响应后；若浏览器直连对象存储，由前端在获取成功响应后上报 | 文件响应成功，不以按钮点击代替 | `result_id`、`task_id`、`download_type`、组织快照 | 动作次数按 `event_id`；后续使用结果按 `result_id` 去重 | 下载动作、后续使用结果 |
| `result_continue_edit_success` | `EXISTING_ENHANCE` | 继续编辑流程；目标工作台完成参数恢复并确认接收后上报 | 目标工具已进入且来源结果参数可用 | `result_id`、`task_id`、`target_tool_key`、创作链/轮次、组织快照 | `event_id`；后续使用结果按 `result_id` 去重 | 后续使用、创作链延续 |
| `result_add_asset_success` | `EXISTING_ENHANCE` | 资源服务“加入素材库”事务提交后写事实 | 服务端返回稳定 `asset_id` | `result_id`、`task_id`、`asset_id`、资源所有人及组织快照 | `asset_id`，禁止前后端重复计数 | 后续使用、素材沉淀、资源来源 |
| `result_approve_success` | `EXISTING_ENHANCE` | 认可/点赞保存接口；记录持久化成功后采集 | 服务端已保存认可状态 | `result_id`、`task_id`、认可人及组织快照 | `result_id + user_id` | 后续使用结果 |
| `text_copy_success` | `EXISTING_ENHANCE` | Web 前端复制动作；`navigator.clipboard.writeText` Promise 成功后上报 | 剪贴板写入成功 | `source_type`、`source_id/resource_id`、`copy_scope`、资源范围/所有人、组织快照 | 动作次数按 `event_id`；提示词活跃数按 `resource_id` 去重 | 文案后续使用、提示词实际使用 |
| `text_export_success` | `EXISTING_ENHANCE` | 导出服务生成文件成功后；纯前端导出则在 Blob 创建且下载触发成功后上报 | 导出文件已成功生成 | `source_type`、`source_id`、`export_format`、有关联任务时 `task_id` | `event_id`；结果后续使用按 `result_id/source_id` 去重 | 文案后续使用 |
| `history_continue_edit_success` | `EXISTING_ENHANCE` | 历史记录恢复流程；目标工具参数恢复成功后上报 | 历史参数已成功带入目标工具 | `history_id`、`source_task_id`、`target_tool_key`、创作链/轮次 | `event_id` | 创作链延续；不得与同次 `result_continue_edit_success` 重复生成两条采纳事实 |
| `material_select_success` | `EXISTING` | Web 素材选择器；选中结果成功回填工具输入后上报 | 输入控件已接收 `asset_id` | `asset_id`、`tool_key`、选择来源 | `event_id` | 仅选择器诊断；核心素材使用以 `asset_reuse` 为准 |
| `asset_reuse` / `AssetUsageFact` | `EXISTING_ENHANCE` + `NEW_THIS_PHASE` 规范化事实 | 任务服务在任务创建成功并提交输入资源绑定后写事实 | `asset_id + task_id` 绑定已持久化 | `asset_id/resource_id`、`task_id`、`target_tool_key`、使用人/所有人及双方组织快照、`action_type` | `resource_id + task_id + action_type` | 素材活跃数、使用次数、任务数、团队内/跨团队使用、跨任务复用 |
| `prompt_generate_success` | `EXISTING_ENHANCE` | 提示词服务成功返回并保存核心动作结果后采集 | 生成、润色或反推结果成功可用 | `action_id`、`mode`、`duration_ms`、用户与组织快照；有结果 ID 时一并记录 | `action_id`；旧实现无该字段时以现有请求/结果唯一 ID 映射 | AI 提示词实际使用、活跃用户和成功动作；与同一 `PromptActionFact` 不重复计数 |
| `PromptActionFact`（含开始/结束事实） | `NEW_THIS_PHASE` | 提示词服务接收核心动作请求和最终收敛处 | 开始事实在请求被服务接收后；结束事实在成功、失败或取消最终态落库后 | `action_id`、`mode`、`action_status`、起止时间、`duration_ms`、用户与组织快照，失败时 `error_code` | `action_id` | 提示词成功/失败/取消动作、动作成功率和平均处理时长 |
| `prompt_template_selected` | `EXISTING_ENHANCE` | Web 提示词选择器；用户确认且目标输入框完成回填后上报 | 选择不是仅高亮，提示词已进入目标输入 | `prompt_template_id/resource_id`、`prompt_template_source/resource_scope`、`tool_key`、所有人及组织快照 | `event_id`；活跃提示词按 `resource_id` 去重 | 提示词确认使用、热门提示词 |
| `prompt_apply_to_tool_success` | `EXISTING_ENHANCE` | 目标工具接收提示词 ID 和文本引用后上报；若同时创建任务，任务服务补 `task_id` | 目标工具确认接收成功 | `source_prompt_id/resource_id`、`target_tool_key`、组织快照；创建任务时 `task_id` 必填 | `resource_id + task_id + APPLY_TOOL`；无任务时 `event_id` | 提示词深层使用、目标功能分布 |
| `resource_status_changed` / `ResourceInventoryFact` | `NEW_THIS_PHASE` | 素材/提示词资源服务的创建、审核通过、发布、停用、删除状态事务 | 资源可用状态或范围变更已提交 | `resource_id`、`resource_type`、`availability_before`、`availability_after`、`resource_scope`、`owner_user_id`、所有人组织快照、`effective_at` | 资源状态流水主键或 `resource_id + 状态版本` | 截至结束日可用数、本期新增量、历史库存回溯 |
| `TargetUserScope` 组织快照 | `EXISTING_ENHANCE` | 账号/组织同步任务；每次同步成功后生成组织粒度快照 | 聚合管理平台账号与组织同步批次完成 | `snapshot_at`、`organization_id`、`eligible_user_count`、`sync_batch_id`、停用账号排除标识 | `sync_batch_id + organization_id` | 注册用户分母及组织覆盖率 |

`cancel_source` 建议枚举为 `USER`、`SYSTEM`、`TIMEOUT`，`cancel_reason_code` 沿用任务域现有错误/原因码；若现有命名不同，Codex 应建立映射而不是改写业务状态。该字段是旧 `task_cancelled` 的本期补强，不是新增取消流程。

旧 PRD中的 `nav_click`、`side_menu_click`、`tool_entry_click`、`local_upload_success`、`model_select`、`parameter_change`、`task_submit_click`、`task_create_failed`、`task_retry`、`result_preview`、`result_reject`、`text_batch_generate_success`、`history_detail_view`、`history_add_asset_success`、`admin_config_save`、`analytics_report_retry` 继续沿用原定义。本期页面没有对应核心指标时，不得为“利用已有数据”而混入实际使用、任务成功率、积分或后续使用结果。

### 9.9 本期新增与补强字段清单

| 对象/事件 | 字段 | 状态 | 采集来源 | 规则 |
|---|---|---|---|---|
| `GenerationTaskFact` | `creative_chain_id`、`round_index`、`source_task_id`、`source_result_id` | `NEW_THIS_PHASE` | 任务创建服务 | 首次提交建链；继续编辑沿链并递增业务轮次；系统自动重试不递增 |
| 任务、结果、采纳、资产使用事实 | `organization_id_at_event`、`top_level_organization_id_at_event`、`organization_path_at_event` | `EXISTING_ENHANCE` | 权限/组织服务在业务事实发生时提供快照 | 不得在查询时用人员当前组织回填历史 |
| `GenerationResultFact` | `creative_chain_id`、`round_index` | `NEW_THIS_PHASE` | 从所属任务复制 | 与 `task_id` 对应任务完全一致 |
| `ResultAdoptionFact` | `event_id`、`user_id`、创作链/轮次、组织快照 | `EXISTING_ENHANCE` | 各成功后续行为归一化 | 原始动作可多条，后续使用结果按 `result_id` 去重 |
| `task_cancelled` | `cancel_source`、`cancel_reason_code` | `EXISTING_ENHANCE` | 取消命令/系统终止处理器 | 最终取消后必填；不从文案猜测 |
| `asset_reuse` | `task_id` | `EXISTING_ENHANCE` | 任务输入资源绑定 | 成功选入任务时条件必填 |
| `AssetUsageFact` | 全对象 | `NEW_THIS_PHASE` | 归一化素材/提示词成功使用事实 | 可由现有事件与业务表生成，不要求一定新建同名物理表 |
| 资源事实 | `owner_user_id`、`owner_organization_id`、`owner_top_level_organization_id` | `NEW_THIS_PHASE` | 资源创建/发布时所有人快照 | 用于本人、团队内和跨团队归属 |
| `ResourceInventoryFact` | 全对象 | `NEW_THIS_PHASE` | 资源状态流水或现有审计日志 | 支持按查询结束时点重建可用库存 |
| `TargetUserScope` | `snapshot_at`、`organization_id`、`eligible_user_count`、`sync_batch_id` | `EXISTING_ENHANCE` | 聚合管理平台同步批次 | 按结束时点最近一次成功快照取分母；不能用当前总人数回填历史 |
| `PromptActionFact` | 全对象 | `NEW_THIS_PHASE` | 提示词服务核心动作请求与最终态 | 旧 PRD只有成功事件，不能计算失败/取消和完整成功率；本期新增规范化动作事实 |

#### 9.9.1 `ResourceInventoryFact` 字段契约

| 字段名 | 类型 | 必填 | 默认值 | 格式/枚举 | 校验规则 | 说明 |
|---|---|---:|---|---|---|---|
| inventory_event_id | 字符串 | 是 | 无 | 沿用事件/审计 ID 规范 | 全局唯一 | 资源库存状态事实 ID |
| resource_id | 字符串 | 是 | 无 | 沿用素材/提示词 ID | 非空 | 资源稳定 ID |
| resource_type | 枚举 | 是 | 无 | `MATERIAL` / `PROMPT` | 非空 | 资源类型 |
| availability_before | 布尔或空 | 否 | 空 | `true` / `false` / `null` | 首次创建可为空 | 变更前是否计入可用库存 |
| availability_after | 布尔 | 是 | 无 | `true` / `false` | 非空 | 变更后是否计入可用库存 |
| source_status_key | 字符串 | 是 | 无 | 沿用资源域状态枚举 | 必须能映射到 `availability_after` | 保留真实业务状态用于审计，不在 PRD虚构物理状态名 |
| resource_scope | 枚举 | 是 | 无 | `PERSONAL` / `TEAM` / `PUBLIC` | 灵感广场不进入 | 变更后的资源范围 |
| owner_user_id | 字符串 | 是 | 无 | 沿用用户 ID | 非空 | 资源所有人 |
| owner_organization_id | 字符串 | 条件必填 | 空 | 沿用组织 ID | 团队统计资源必填 | 所有人组织快照 |
| owner_top_level_organization_id | 字符串 | 条件必填 | 空 | 沿用组织 ID | 团队统计资源必填 | 所有人一级组织快照 |
| effective_at | 日期时间 | 是 | 服务端业务时间 | ISO 时间戳 | 非空且同一资源状态版本单调递增 | 状态生效时点 |
| status_version | 整数或字符串 | 是 | 无 | 沿用资源域版本 | 同一 `resource_id` 唯一 | 幂等与顺序校验 |

#### 9.9.2 `TargetUserScope` 补强字段契约

| 字段名 | 类型 | 必填 | 默认值 | 格式/枚举 | 校验规则 | 说明 |
|---|---|---:|---|---|---|---|
| snapshot_at | 日期时间 | 是 | 同步完成时间 | ISO 时间戳 | 不晚于数据批次完成时间 | 分母快照时间 |
| organization_id | 字符串 | 是 | 无 | 沿用组织 ID | 非空 | 当前统计根组织 |
| include_descendants | 布尔 | 是 | `true` | 固定 `true` | 本期不得为 false | 计数已包含全部下级并按用户去重 |
| eligible_user_count | 整数 | 是 | 0 | `>=0` | 与同步批次账号明细核对 | 已开通设计平台且有效的去重账号数 |
| sync_batch_id | 字符串 | 是 | 无 | 沿用组织同步批次 ID | 同批次同组织唯一 | 快照来源批次 |
| exclude_inactive | 布尔 | 是 | `true` | 固定 `true` | 停用账号不得进入 | 与当前账号权限规则一致 |

#### 9.9.3 取消字段契约

| 对象 | 字段名 | 类型 | 必填 | 默认值 | 格式/枚举 | 校验规则 | 说明 |
|---|---|---|---:|---|---|---|---|
| `task_cancelled` / 任务最终事实 | cancel_source | 枚举 | 最终取消时是 | 无 | `USER` / `SYSTEM` / `TIMEOUT`（建议规范值，物理枚举可映射） | 不得为空或从页面文案猜测 | 取消发起来源 |
| `task_cancelled` / 任务最终事实 | cancel_reason_code | 字符串 | 最终取消时是 | 无 | 沿用任务域原因码 | 必须能回溯取消处理器 | 取消具体原因；页面是否展示原因不影响采集 |

#### 9.9.4 `PromptActionFact` 字段契约

| 字段名 | 类型 | 必填 | 默认值 | 格式/枚举 | 校验规则 | 说明 |
|---|---|---:|---|---|---|---|
| action_id | 字符串 | 是 | 无 | 沿用请求/动作 ID 规范 | 全局唯一 | 一次生成、润色或反推动作 ID |
| user_id | 字符串 | 是 | 无 | 沿用用户 ID | 非空 | 发起人 |
| tool_key | 字符串 | 是 | `ai_prompt` | 固定 `ai_prompt` | 不允许其他值 | 功能标识 |
| mode | 枚举 | 是 | 无 | `GENERATE` / `POLISH` / `REVERSE`（建议规范值，物理枚举可映射） | 非空 | 核心动作类型 |
| action_status | 枚举 | 是 | 无 | `PROCESSING` / `SUCCESS` / `FAILED` / `CANCELLED` | 最终事实不得为 `PROCESSING` | 动作状态 |
| submit_time | 日期时间 | 是 | 服务端接收时间 | ISO 时间戳 | 非空 | 发起时间 |
| finish_time | 日期时间 | 最终态是 | 空 | ISO 时间戳 | 不早于 `submit_time` | 最终结束时间 |
| duration_ms | 整数 | 成功时是 | 空 | `>=0` 毫秒 | 等于或可核对起止时间差 | 成功动作处理时长 |
| error_code | 字符串 | 失败时是 | 空 | 沿用提示词服务错误码 | 失败时非空 | 失败定位，不展示原始错误详情 |
| organization_id_at_event | 字符串 | 是 | 无 | 沿用组织 ID | 非空或进入组织未知质量项 | 动作组织快照 |
| top_level_organization_id_at_event | 字符串 | 是 | 无 | 沿用组织 ID | 与组织快照一致 | 一级组织快照 |
| organization_path_at_event | 字符串或数组 | 是 | 无 | 物理格式沿用技术方案 | 不作为唯一授权依据 | 历史组织展示与排查 |

### 9.10 页面数据指标全量映射

下表覆盖卡片、图表、排行、表格及人员详情中出现的所有不同统计数据。同名指标在不同主题、功能、部门或人员维度复用同一公式，只改变分组键和权限过滤范围。

| 页面数据 | API 建议字段 | 来源事实 | 计算/去重口径 | 来源状态 |
|---|---|---|---|---|
| 实际使用用户/人数 | `actualUsers` | `task_created`、`PromptActionFact` / `prompt_generate_success` | 周期内符合 R-01 的去重 `user_id` | `EXISTING_ENHANCE` |
| 注册用户数 | `eligibleUsers` | `TargetUserScope` | 取不晚于 `effectiveEndAt` 的最近成功组织快照；父组织对下级用户去重 | `EXISTING_ENHANCE` |
| 注册用户覆盖率/用户覆盖率 | `coverageRate` | 上两项 | `actualUsers / eligibleUsers`；分母 0 返回 `null` | `EXISTING_ENHANCE` |
| 实际使用次数/使用数/核心动作 | `actualUses` | `task_created`、`PromptActionFact` / `prompt_generate_success` | 去重任务数 + 去重提示词 `SUCCESS` 动作数；页面访问、失败/取消动作和任务创建失败不计 | `EXISTING_ENHANCE` |
| 人均使用次数/人均实际使用 | `usesPerUser` | 上两项 | `actualUses / actualUsers`；分母 0 返回 `null` | `EXISTING_ENHANCE` |
| 高频功能、功能使用次数排行 | `featureRows[].actualUses` | 实际使用事实 | 按 `tool_key` 分组并降序；同值按实际使用用户降序 | `EXISTING_ENHANCE` |
| 功能使用人数排行 | `featureRows[].actualUsers` | 实际使用事实 | 按 `tool_key` 去重 `user_id` 并降序 | `EXISTING_ENHANCE` |
| 成功任务/成功动作 | `successfulTasks` | `GenerationTaskFact` / `PromptActionFact` | 最终 `SUCCESS`、`PARTIAL_SUCCESS` 的去重任务；提示词按成功动作 | `EXISTING_ENHANCE` |
| 失败任务/失败动作 | `failedTasks` | `GenerationTaskFact` / `PromptActionFact` | 最终 `FAILED` 的去重任务/动作 | 任务 `EXISTING`；提示词 `NEW_THIS_PHASE` |
| 取消任务/取消动作 | `cancelledTasks` | `GenerationTaskFact`、`task_cancelled` / `PromptActionFact` | 最终 `CANCELLED` 的去重任务/动作 | 任务 `EXISTING_ENHANCE`；提示词 `NEW_THIS_PHASE` |
| 未完成 | `unfinishedTasks` | `GenerationTaskFact` | 截至 `dataAsOf` 尚未进入任何最终态的去重任务 | `EXISTING` |
| 成功率/失败率/取消率 | `successRate` 等 | 上述状态数 | 任务：对应状态数 / 实际创建任务数，部分成功只计成功；提示词：对应最终状态动作数 / 全部最终态动作数 | `EXISTING_ENHANCE` |
| 任务状态构成/功能运行状态 | `statusBreakdown[]`、`featureRows[]` | 任务最终事实 | 每个 `task_id` 只进入一个最终状态；状态合计等于任务数 | `EXISTING_ENHANCE` |
| 平均处理时长 | `averageDurationMs` | `task_finished` / 提示词动作 | 成功或部分成功且起止时间完整的 `duration_ms` 算术平均；失败、取消、无任务 ID 不计 | `EXISTING_ENHANCE` |
| 中位处理时长 | `medianDurationMs` | 同上 | 同一有效时长集合的 P50；偶数样本取中间两值平均 | `EXISTING_ENHANCE` |
| 2 分钟内完成 | `completedWithin120sRate` | 同上 | `duration_ms <= 120000` 的成功任务 / 有有效时长的成功任务 | `EXISTING_ENHANCE` |
| 使用高峰 | `peakPeriod` | `task_created`、提示词核心成功动作 | 按上海时区 2 小时段聚合实际使用次数，取最高时段；并列取较早时段 | `EXISTING_ENHANCE` |
| 成功产出结果 | `successfulResults` | `GenerationResultFact` | `result_status=SUCCESS` 的去重 `result_id`；失败候选不计 | `EXISTING_ENHANCE` |
| 后续使用结果数 | `followupUsedResults` | `ResultAdoptionFact` | 所选周期成功结果中，截至 `dataAsOf` 至少一次成功后续行为的去重 `result_id` | `EXISTING_ENHANCE` |
| 产出后续使用率/后续使用率 | `followupUseRate` | 上两项 | `followupUsedResults / successfulResults`；同一结果多个动作只计一次 | `EXISTING_ENHANCE` |
| 创作链数 | `creativeChains` | `GenerationTaskFact`、`GenerationResultFact` | 周期内首轮产生至少一个成功结果的去重 `creative_chain_id` | `NEW_THIS_PHASE` |
| 首轮直接采纳链数/首轮直接采纳率 | `firstRoundAdoptedChains`、`firstRoundAdoptionRate` | 创作链 + `ResultAdoptionFact` | 首轮任一成功结果被后续使用的去重链数 / `creativeChains` | `NEW_THIS_PHASE` |
| 跨任务复用资产/跨任务复用次数/复用率 | `crossTaskReusedAssets` 等 | `AssetUsageFact` | 来源生成结果/资产进入不同 `task_id`；资产数按 `resource_id` 去重，次数按幂等使用事实计；复用率分母为可用生成素材数 | `NEW_THIS_PHASE` |
| 消耗积分 | `consumedPoints` | `credit_settled` | 汇总实际扣减：扣减值减同一流水已结算退回值；不统计余额、申请、补发 | `EXISTING` |
| 积分使用人数 | `pointsUsers` | `credit_settled` + 任务 | 发生正向实际扣减的去重任务用户 | `EXISTING` |
| 扣积分实际使用次数 | `chargedUses` | `credit_settled` + 任务 | 至少有一条正向实际扣减结算的去重 `task_id` | `EXISTING` |
| 平均每次使用积分 | `pointsPerUse` | 上两项 | `consumedPoints / chargedUses`；分母 0 返回 `null` | `EXISTING` |
| 平均后续使用结果积分 | `pointsPerFollowupResult` | 积分 + 后续使用结果 | `consumedPoints / followupUsedResults`；分母 0 返回 `null` | `EXISTING_ENHANCE` |
| 积分占比 | `pointsShare` | `credit_settled` | 当前分组消耗积分 / 当前授权及筛选总消耗积分 | `EXISTING` |
| 积分与使用增速 | `pointsGrowthRate`、`useGrowthRate` | 积分与实际使用事实 | 当前周期对比紧邻的等长前一周期；前期不完整或为 0 返回 `null`，不显示无限增长 | `EXISTING_ENHANCE` |
| TOP 10 人员积分占比 | `topTenPointsShare` | 积分事实 | 当前范围积分最高 10 人消耗积分之和 / 总消耗积分 | `EXISTING` |
| 需关注功能 | `reviewFeature` | 功能后续使用率 | 仅在至少两个扣积分功能有完整分子分母时，取后续使用率最低者；这是复核信号，不是异常判断 | `EXISTING_ENHANCE` |
| 可用素材数/可用提示词数/资产总数 | `availableMaterials` 等 | `ResourceInventoryFact` | `effectiveEndAt` 时状态为可用且在授权范围内的去重资源；审核中、驳回、删除、停用不计 | `NEW_THIS_PHASE` |
| 本期新增素材/提示词 | `addedMaterials`、`addedPrompts` | 资源状态事实 | 周期内首次进入可用状态的去重资源，不按草稿创建时间计算 | `NEW_THIS_PHASE` |
| 活跃素材/提示词/资产 | `activeMaterials` 等 | `AssetUsageFact` | 周期内至少发生一次成功使用的去重 `resource_id` | `NEW_THIS_PHASE` |
| 素材/提示词/资产使用次数 | `materialUsageCount` 等 | `AssetUsageFact` | 统计幂等后的成功使用事实；不同 `action_type` 分开保留 | `NEW_THIS_PHASE` |
| 素材产生任务数 | `materialTaskCount` | `AssetUsageFact` | 素材成功选入任务的去重 `task_id` | `EXISTING_ENHANCE` |
| 平均每项使用 | `averageUsesPerActiveAsset` | 活跃资产与使用次数 | `usageCount / activeAssets`；分母 0 返回 `null` | `NEW_THIS_PHASE` |
| 素材复用率/提示词使用率/资产使用率 | `usageRate` | 可用库存 + 使用事实 | 周期内活跃去重资源 / 查询结束时点可用资源；分母 0 返回 `null` | `NEW_THIS_PHASE` |
| 复制成功/确认使用/带入工具/深层使用率 | `copyCount` 等 | `text_copy_success`、`prompt_template_selected`、`prompt_apply_to_tool_success` | 次数按各事件幂等计；深层使用率 = 带入工具次数 / 提示词全部成功使用次数 | `EXISTING_ENHANCE` |
| 按资产范围统计 | `assetScopeRows[]` | 资源库存 + 使用事实 | 按 `PERSONAL/TEAM/PUBLIC` 分组；素材数、提示词数、活跃数、次数、人数按同一范围归属 | `NEW_THIS_PHASE` |
| 按团队统计/跨团队使用 | `teamAssetRows[]` | 资源所有人快照 + 使用人快照 | 资源所有人一级组织为贡献团队；其他一级组织使用计跨团队 | `NEW_THIS_PHASE` |
| 热门素材/热门提示词 | `topMaterials[]`、`topPrompts[]` | 资源库存 + 使用事实 | 按成功使用次数降序，同值按去重用户数、最近使用时间降序；返回名称、范围、团队、主功能、人数、最近使用时间 | `NEW_THIS_PHASE` |
| 有效产出贡献 TOP N | `peopleRanking[]` | 人员任务、结果、积分事实 | 默认按后续使用结果数降序，同值按消耗积分降序；支持 10/20/50 | `EXISTING_ENHANCE` |
| 有效活跃天数 | `effectiveActiveDays` | 任务创建、提示词成功、后续使用、资产使用事实 | 按上海自然日去重；任一纳入行为成功即计 1 天 | `EXISTING_ENHANCE` |
| 使用功能数/主要使用功能/主要功能占比 | `usedFeatureCount` 等 | 实际使用事实 | 有实际使用的去重 `tool_key`；主要功能取次数最高，同值按 `tool_key` 稳定排序 | `EXISTING_ENHANCE` |
| 人员功能使用结构与趋势 | `person.featureRows[]`、`person.trend[]` | 人员实际使用、积分、结果事实 | 按功能或时间桶分组；各分组汇总必须等于人员总量 | `EXISTING_ENHANCE` |
| 被团队使用素材/提示词及次数 | `teamUsedMaterials` 等 | 资源所有人 + `AssetUsageFact` | 所有人为当前人员，使用人为同一级组织内其他人员；资产按资源去重，次数按事实计 | `NEW_THIS_PHASE` |
| 部门有记录人员及部门均值 | `peerCount`、`departmentAverage*` | 授权人员集合与上述事实 | 同部门、当前筛选有记录且当前用户有权查看的人员；先算个人值再取算术平均 | `EXISTING_ENHANCE` |
| 纳入统计功能 | `includedFeatureCount` | 平台工具注册表/`tool_key` 映射 | 统计本 PRD已确认纳入且当前有效的去重一级工具；本期基线为 13 个 | `EXISTING_ENHANCE` |
| 积分规则 | `pointsMode` | 平台功能计费配置 | 映射为 `CHARGED` / `FREE`；AI 提示词为 `FREE`，不得由积分是否为 0 反推 | `EXISTING` |
| 最近使用 | `lastActiveAt` | 实际使用、后续使用、资产使用事实 | 当前人员纳入有效活跃定义的最大 `event_time` | `EXISTING_ENHANCE` |
| 趋势时间桶 | `trend[]` | 对应主题基础事实 | 按 6.2 统一分桶；每桶返回起止时间、标签和原始数值，所有桶合计等于周期总量 | `EXISTING_ENHANCE` |
| 资产使用人数 | `assetUsers` | `AssetUsageFact` | 当前分组成功使用资源的去重 `user_id` | `NEW_THIS_PHASE` |

### 9.11 报表查询与响应字段契约

本 PRD定义逻辑契约，不强制未知后端仓库的物理 URL。Codex 扫描现有 API 约定后，可实现为一个主题聚合接口或六个主题接口，但必须保持以下请求和响应字段；不得让前端自行拉取原始事实后计算权限聚合。

#### 9.11.1 公共响应

| 字段 | 类型 | 必填 | 说明 |
|---|---|---:|---|
| `query` | 对象 | 是 | 服务端归一化后的 `AnalyticsReportQuery` |
| `effectiveScope` | 对象 | 是 | 当前用户角色、有效组织根和实际展开的组织 ID；不返回未授权组织 |
| `dataAsOf` | 日期时间 | 是 | 本次统计数据截点 |
| `earliestAvailableAt` | 日期时间 | 是 | 当前主题最早可用真实数据时间 |
| `aggregationVersion` | 字符串 | 是 | 同一页面各模块一致性版本，用于排查汇总漂移 |
| `qualityStatus` | 枚举 | 是 | `READY` / `NOT_READY` / `ERROR`；`NOT_READY` 不返回模拟数 |
| `warnings` | 数组 | 是 | 只返回组织未知、关联缺失等数据质量代码与数量，不返回敏感明细 |
| `data` | 对象或空 | 是 | `READY` 时返回主题数据；其他状态为 `null` |

#### 9.11.2 六主题 `data` 字段

| `theme_key` | 必填字段 |
|---|---|
| `OVERVIEW` | `metrics`、`featureRanking`、`statusBreakdown`、`managementFocus`、`departmentRows` |
| `USAGE` | `metrics`、`featureUseRanking`、`featureUserRanking`、`featureRows` |
| `EFFICIENCY` | `metrics`、`statusBreakdown`、`efficiencySummary`、`featureRows` |
| `POINTS` | `metrics`、`trend`、`managementSignals`、`featureRows`、`departmentRows`、`peopleRanking` |
| `ASSETS` | `metrics`、`materialSummary`、`promptSummary`、`assetScopeRows`、`teamRows`、`topMaterials`、`topPrompts` |
| `PEOPLE` | `candidateCount`、`candidates`、`selectedPerson`；`selectedPerson` 内含 `profile`、`usageMetrics`、`valueMetrics`、`pointsMetrics`、`peerComparison`、`featureRows`、`trend`、`assetMetrics` |

数值字段使用原始整数或小数，不返回已格式化千分位和百分号；百分比统一返回 `0..100` 数值。分母为 0、数据缺失或未验收时返回 `null`，前端显示 `--`。排行中的资源名称和人员名称由服务端在鉴权后返回，API 不返回资源内容、文件地址或提示词正文。

`effectiveEndAt = min(end_date 当日 23:59:59, dataAsOf)`；选择“今日”时不得读取查询时刻之后的未来快照或库存状态。

### 9.12 数据质量与补采边界

| 检查项 | 规则 | 未通过处理 |
|---|---|---|
| 事件唯一性 | `event_id` 或业务幂等键无重复 | 重复记录隔离，不重复计数 |
| 任务链完整性 | 任务可关联结果、积分、历史及后续行为 | 依赖该链路的主题 `NOT_READY`，不得推算 |
| 组织快照完整性 | 纳入组织排行的事实均有合法组织快照 | 公司总量保留合法事实；未知组织单列质量数量，不进入部门排行 |
| 资源库存可回溯 | 能按结束时点还原资源可用状态 | 资产库存和使用率不展示，使用次数可在独立验收通过后展示 |
| 旧数据 | 旧埋点缺新增字段 | 不补造；只从 V1.1 生效并验收的时间开始统计相关指标 |
| 延迟后续行为 | 历史结果在查询时点前新增成功后续行为 | 原生成周期的后续使用结果允许重算；响应 `dataAsOf` 必须更新 |
| 聚合守恒 | 卡片、分组、趋势和排行可回加到同一总量 | 失败时主题整体不可发布为 `READY` |

## 10. 公共能力与依赖

| 项目 | 是否影响 | 依赖的现有能力 / 对接方式 | 具体影响或无影响依据 |
|---|---|---|---|
| 账号与组织同步 | 是 | 复用聚合管理平台和权限管理同步结果 | 获取稳定用户、主管标识、账号状态、组织树与组织路径 |
| 权限与数据范围 | 是 | 复用权限服务有效角色与组织范围计算 | 不在数据智能内建立第二套权限算法 |
| 任务与结果 | 是 | 复用任务、结果、历史事实 | 补创作链、轮次、来源和组织快照 |
| 积分与计费 | 是 | 只读复用实际积分流水 | 不改变积分扣减、退还或审批逻辑 |
| 素材库与提示词库 | 是 | 复用统一资源 ID、范围和所有权 | 只读统计，不改变资源编辑、审批或删除规则 |
| 历史记录 | 是 | 复用 `history_id` 与继续编辑来源 | 只用于创作链归因，不修改历史页面 |
| 下载与文件 | 否 | 只读取下载成功事件 | 报表不读取或展示文件内容与地址 |
| 外部平台 | 否 | 无 | 灵感广场与站外行为不纳入一期 |
| 模型管理 | 否 | 本期不使用模型筛选 | 模型字段验收后另立需求 |
| SPA / 独立原型 | 否 | 正式入口仅当前 Next.js `/admin/data` | 历史静态复刻和独立参考页不要求同步 |

## 11. 非功能与约束

| 维度 | 本次要求 | 状态 |
|---|---|---|
| 数据安全 | 报表不返回原图、结果文件、提示词全文、账号、联系方式或其他非统计必需信息 | 已确认 |
| 权限 | 所有聚合与人员搜索必须服务端过滤；越权请求拒绝并清空客户端数据 | 已确认 |
| 数据一致性 | 同一查询上下文内卡片、图表、排行、明细必须使用同一统计版本 | 已确认 |
| 数据时区 | 统一 `Asia/Shanghai`；自然日、周分桶和组织快照均按此口径 | 已确认 |
| 历史数据 | 不补埋；展示实际统计起点，不与 2026-07-30 快照拼接趋势 | 已确认 |
| 数据保留 | 沿用埋点和业务事实现有保留规则；具体时长待技术确认，但不得短于产品可查询周期 | 待技术确认 |
| 查询性能 | 用户触发查询后立即显示加载反馈；具体响应目标、缓存和预聚合方案由技术评审确定 | 待技术确认 |
| 并发 | 多标签或多用户查询为只读操作；不得改变业务事实。缓存键必须包含权限范围和全部查询条件 | 已确认产品约束 |
| 响应式 | 1280px、1024px、736px、390px、360px 无整页横向溢出；宽表只允许局部滚动 | 已确认 |
| 可访问性 | 标签、按钮、搜索、弹窗和空/错状态支持键盘；弹窗保持标题和操作区可见 | 沿用 UI 规范 |

## 12. 用户可见文案

| 场景 | 文案 | 展示方式 |
|---|---|---|
| 空数据 | 当前条件暂无数据 | 当前主题内容区空状态 |
| 人员空数据 | 当前时间、组织、功能和人员搜索条件下，没有实际使用记录 | 人员详情区空状态 |
| 查询失败 | 数据加载失败，请重试 | 当前主题错误状态，提供“重试” |
| 无权限 | 暂无数据智能访问权限 | 页面无权限状态 |
| 数据未就绪 | 当前时间早于可用统计起点 | 空状态，并展示可用统计起点 |
| 分母为 0 | `--` | 指标值，不展示错误百分比 |
| 指标说明标题 | 指标解读 / 统计口径 / 管理参考 | 指标说明弹窗 |
| 人员判断边界 | 数据用于理解使用结构与产出行为，不作为人员绩效评价 | 人员数据总结底部 |

## 13. 验收标准

| 编号 | 关联变更/规则 | 前置条件 | 操作步骤 | 预期结果 | 类型 |
|---|---|---|---|---|---|
| AC-01 | CHG-01 / R-07 | 已接入验收数据 | 打开 `/admin/data` 并查看六主题 | 页面不读取 `src/data/demo/`；所有数字来自真实接口并返回数据元信息 | 正常 |
| AC-02 | CHG-02 | 准备跨多日任务与行为数据 | 依次选择今日、近 7 天、近 30 天和自定义 | 六主题适用指标按同一时间范围变化；日期边界按上海时区 | 联动 |
| AC-03 | CHG-02 | 有父子组织数据 | 选择公司、一级部门和子部门 | 全部适用指标同步变化；父级汇总包含下级且不重复 | 联动 |
| AC-04 | CHG-02 | 多功能均有数据 | 选择一个功能并切换六主题 | 任务、积分、人员和资产使用指标只统计所选功能；库存类指标按 6.3 不随功能变化 | 联动 |
| AC-05 | CHG-03 | 系统管理员登录 | 打开报表并展开组织树 | 可选择全公司和全部下级组织，可查看授权范围内人员 | 权限 |
| AC-06 | CHG-03 | 主管或部门管理员登录 | 打开报表并尝试选择组织 | 只返回权限服务授权组织及下级；无法看到或请求其他组织 | 权限 |
| AC-07 | CHG-03 | 审批员和普通用户分别登录 | 访问导航和直接请求页面/接口 | 无数据智能入口；直接访问与接口均被拒绝 | 权限 |
| AC-08 | R-01 | 存在访问、创建失败、成功创建后失败三种行为 | 查询实际使用次数 | 页面访问和创建失败不计；成功创建后失败的任务计一次实际使用 | 口径 |
| AC-09 | R-02 | 准备成功、部分成功、失败、取消和未完成任务 | 查询任务状态 | 每个任务只进入一个最终状态；部分成功计成功，状态总和等于任务总数 | 数据 |
| AC-10 | R-03 | 同一成功结果发生下载、继续编辑和加素材 | 查询后续使用结果 | 该 `result_id` 只计一个后续使用结果，动作次数可分别保留 | 去重 |
| AC-11 | R-03 | 历史周期结果当前无后续行为 | 查询历史周期后完成一次下载再重查 | 原历史周期后续使用结果数增加 1；成功结果总数不变 | 历史更新 |
| AC-12 | R-04 / CHG-07 | 创建首轮多候选并采纳两张 | 查询首轮直接采纳率 | 同一创作链只计一条首轮直接采纳；多候选不重复计链 | 数据 |
| AC-13 | R-04 / CHG-07 | 首轮失败后系统自动重试成功 | 查询创作链轮次 | 自动重试仍为首轮；用户基于结果继续编辑才进入下一业务轮次 | 边界 |
| AC-14 | R-05 | 准备收费功能与 AI 提示词使用 | 查询积分主题 | 只统计实际扣减积分；AI 提示词显示不扣积分且不进入排行 | 口径 |
| AC-15 | R-05 | 同一任务有积分、结果和后续行为 | 核对单位效率 | 可通过 `task_id/result_id` 追溯；单位结果积分等于扣减积分除以后续使用结果数 | 数据 |
| AC-16 | CHG-05 | 个人、团队、公共素材各有成功使用 | 查询资产范围统计 | 可用数、活跃数、使用次数和使用率按范围正确汇总，总量守恒 | 数据 |
| AC-17 | CHG-05 | 同一资源被本团队和其他一级部门使用 | 查询团队统计 | 本团队及下级计团队内使用；其他一级部门计跨团队使用 | 组织 |
| AC-18 | CHG-05 | 浏览素材、选择失败、成功选入任务各一次 | 查询素材使用 | 仅成功选入任务计一次使用 | 边界 |
| AC-19 | CHG-05 | 提示词发生复制成功、确认使用、带入工具和站外复制 | 查询提示词分析 | 平台内成功行为按类型统计；带入工具计深层使用；站外行为不计 | 边界 |
| AC-20 | CHG-06 | 当前组织内外均有人员记录 | 搜索姓名和部门并选择人员 | 只返回授权范围且当前条件有记录人员；范围外人员不可检索 | 权限 |
| AC-21 | CHG-06 | 人员有多功能、多资产和积分记录 | 查看人员详情 | 汇总等于功能明细合计；趋势合计等于当前人员周期总量 | 数据 |
| AC-22 | CHG-06 | 人员无当前功能记录 | 选择该功能并搜索人员 | 人员不进入候选；页面展示明确空状态，不展示其他功能旧数据 | 空状态 |
| AC-23 | CHG-08 | 当前条件无记录 | 查询任一主题 | 显示当前条件空状态，保留筛选，不把无记录显示为全 0 | 空状态 |
| AC-24 | CHG-08 | 模拟聚合接口失败 | 切换主题或筛选 | 不展示上一条件旧数字；显示错误与重试，恢复后重新加载 | 异常 |
| AC-25 | CHG-08 | 页面打开后撤销用户权限 | 再次筛选或刷新 | 服务端拒绝并清空数据，页面进入无权限状态 | 安全 |
| AC-26 | CHG-09 | 任一指标可见 | 点击帮助并使用键盘关闭 | 只展示当前指标三段说明；弹窗不被导航裁切，Escape 可关闭 | 交互 |
| AC-27 | CHG-02 | 今日有跨 24 小时数据 | 查看积分和人员趋势 | 两张趋势均展示 12 个两小时区间并使用相同边界 | 口径 |
| AC-28 | CHG-02 | 选择 32 至 180 天范围 | 查看趋势 | 从开始日期起每 7 天一组，最后不足 7 天单独成组 | 口径 |
| AC-29 | CHG-01 | 埋点生效前存在 2026-07-30 快照 | 查询跨越统计起点的时间 | 页面不拼接历史快照；只展示真实可用区间并标明统计起点 | 兼容 |
| AC-30 | CHG-01 | 使用 1280、1024、736、390、360px 视口 | 遍历六主题、筛选和指标弹窗 | 无整页横向溢出或遮挡；宽表和长趋势仅内容区滚动 | 兼容 |
| AC-31 | CHG-07 | 同一任务创建事件被重复投递 3 次 | 执行原始事件入库与聚合 | 仅生成 1 条任务事实，实际使用次数增加 1 | 幂等 |
| AC-32 | CHG-07 | 同一素材先前端选择成功，随后成功创建任务并绑定 | 查询素材使用次数 | 只统计 1 条规范化 `AssetUsageFact`；不把 `material_select_success` 与 `asset_reuse` 相加 | 去重 |
| AC-33 | CHG-07 | 用户点击下载但文件响应失败；随后重试成功 | 查询后续使用 | 第一次不计，第二次产生成功事实；该结果只计 1 个后续使用结果 | 异常 |
| AC-34 | CHG-07 | 人员在 8 月 20 日调岗，8 月 21 日查询 8 月 19 日任务 | 对比历史部门与当前权限 | 任务仍归 8 月 19 日组织快照；当前可见范围按 8 月 21 日权限判断 | 历史/权限 |
| AC-35 | CHG-05 / 资源库存 | 素材先审核通过，后在查询结束日前停用 | 查询结束日前后两个日期 | 停用前计可用，停用后不计；历史库存不随当前状态回写 | 历史 |
| AC-36 | CHG-04 / 积分 | 同一任务有扣减 10、已结算退回 4 | 查询积分主题 | 消耗积分为 6；不得显示 10，也不得按任务成功状态推算 | 结算 |
| AC-37 | CHG-04 | 当前周期有值，紧邻等长前周期为 0 | 查看积分与使用增速 | API 返回 `null`，前端显示 `--`，不显示无限增长或 100% | 边界 |
| AC-38 | CHG-01 | 聚合缺少资源库存历史，但使用事件完整 | 查询资产与复用 | 主题返回 `NOT_READY` 或明确不可用，不使用当前库存或模拟数据补分母 | 数据质量 |
| AC-39 | CHG-03 | 客户端篡改 `organization_id` 为未授权组织 | 直接请求报表接口 | 服务端拒绝；响应不包含目标组织名称、人数或任何聚合值 | 安全 |
| AC-40 | CHG-01 | 使用第 18 章最小数据集 | 运行指标单元/集成测试 | 所有预期值逐项相等，卡片、分组和趋势汇总守恒 | 回归 |
| AC-41 | CHG-07 / R-01 | AI 提示词各准备 1 次成功、失败和取消核心动作 | 查询 AI 提示词的任务与效率主题 | 实际使用次数只增加 1 次成功动作；状态构成为成功 1、失败 1、取消 1，动作成功率为 33.33%，平均时长仅使用成功动作 | 数据 |

## 14. 数据验收门槛

正式切换真实数据前，研发与测试必须完成：

1. `task_id`、`result_id`、`credit_record_id`、`history_id`、`asset_id` 的关联完整性检查。
2. 用户、组织快照、功能、任务状态、开始/结束时间和积分字段完整率检查。
3. 创作链、轮次、来源任务/结果/历史字段的链路抽样回放。
4. 素材和提示词使用事件的资源 ID、任务 ID、所有人和组织快照检查。
5. 公司、部门、人员、功能和趋势分桶的汇总守恒检查。
6. 系统管理员、主管/部门管理员、审批员、普通用户和停用账号的权限回归。
7. 数据未通过验收时不得用前端模拟数据替代上线；对应主题应保持 `NOT_READY`。

## 15. 待确认项

| 编号 | 问题 | 可选方案 | 不确认的影响 | 负责人/状态 |
|---|---|---|---|---|
| TBD-01 | 真实埋点正式生效时间与可用统计起点 | 由研发部署和数据验收后回填 | 影响页面最早可查日期与 AC-29 | 研发 / 待技术评审 |
| TBD-02 | 报表聚合、缓存与刷新策略 | 实时查询 / 定时聚合 / 混合方案 | 影响响应性能和历史数据自然更新时效，不改变统计口径 | 研发 / 待技术评审 |
| TBD-03 | 事件与聚合结果保留时长 | 沿用现有日志规则并覆盖最大查询周期 / 建立独立聚合存储 | 影响长周期查询范围 | 研发 / 待技术评审 |
| TBD-04 | `organization_path_at_event` 的具体存储形态 | 字符串快照 / 组织 ID 数组 / 关联快照表 | 影响实现方式，不改变历史归属规则 | 研发 / 待技术评审 |

以上待确认项不改变页面范围、权限角色或核心指标口径，不阻塞本 PRD交付；技术评审后需回写实施结论。

## 16. 开发交付边界

- 本 PRD为正式产品规则，不等于已授权开发、已完成埋点、已接入接口或已上线。
- 当前 `/admin/data` 是经过验证的前端演示原型；模拟数据只用于评审页面结构，生产环境不得作为真实报表数据源。
- 开发完成后必须按第 13、14 章验收，并将“已完成、已验证、已部署、已上线”分别记录。

## 17. 交给 Codex 的开发执行说明

### 17.1 必须同时提供的输入

仅提供本 Markdown 不能识别未知后端仓库的物理表名和接口路径。执行开发时，研发必须同时把以下材料放入 Codex 可读的本地工作区：

1. 当前前端仓库 `xianma-new-ai-design`。
2. 承载账号/组织权限、任务、结果、积分、素材和提示词的目标后端仓库；如为多个仓库，应全部提供。
3. 当前数据库 schema、迁移目录、任务状态枚举、积分结算枚举、资源状态枚举及公共埋点/消息组件。
4. 本 PRD 与 2026-07-27 旧埋点 PRD；不得只给截图或口头摘要。
5. 本地测试环境启动方式和脱敏测试账号/种子数据；不得把生产凭证写入文档或代码。

如果缺少第 2～3 项，Codex 只能完成前端契约和阻塞清单，不能声称真实数据开发完成。

### 17.2 Codex 开工指令

> 按本 PRD V1.1 实现数据智能真实数据能力。先读取各仓库 `AGENTS.md/CLAUDE.md`、架构文档、迁移规范、权限实现和测试命令；扫描现有事件、表、接口和共享组件，建立“PRD 逻辑对象 → 现有物理实现”映射。优先复用现有业务表、审计流水、消息/outbox、权限服务和页面组件，不创建语义重复的第二套系统。按 `EXISTING`、`EXISTING_ENHANCE`、`NEW_THIS_PHASE` 实施最小迁移、采集、规范化事实、服务端权限聚合、接口和前端替换。任何无法从仓库确认的表名、路由、枚举或保留时长必须标记并停止相关部分，不得虚构。生产页面移除对 `src/data/demo/data-intelligence.js` 数值数据的依赖，但保留必要的纯展示配置时应迁移到非 demo 配置。完成后运行各仓库要求的 lint、测试、类型检查、构建及 AC-01～AC-41，输出变更文件、迁移、映射、验证证据和未解决风险。

### 17.3 固定实施顺序

| 阶段 | Codex 必须完成 | 输出/验证 |
|---|---|---|
| 1. 现状扫描 | 查找旧事件名、任务/结果/积分/资源表、权限范围函数、报表页面和 API 规范 | 形成逻辑对象到物理表/代码位置映射；识别重复或缺失 |
| 2. 数据迁移 | 只为缺失字段或事实增加向前兼容迁移；索引覆盖时间、组织、功能、用户和关联 ID | 迁移可重复执行/回滚方式符合仓库规范；不伪造旧数据 |
| 3. 采集补强 | 按 9.8 在真实成功点采集；后端事件可靠投递、前端事件可重试且幂等 | 事件单元测试、重复投递测试、失败不阻塞主流程 |
| 4. 事实规范化 | 建立或复用任务最终事实、结果采纳、资产使用、资源库存和目标用户快照 | 第 18 章数据可生成唯一事实，关联完整 |
| 5. 权限聚合 | 在服务端应用当前用户有效角色和组织范围，再做聚合与人员搜索 | 越权 ID 测试、父子组织守恒、调岗历史归属测试 |
| 6. 查询接口 | 实现 9.2 请求与 9.11 响应；统一时区、时间桶、空值和数据版本 | 契约测试覆盖六主题、四类状态和全部筛选组合 |
| 7. 前端替换 | `DataOverviewClient.jsx` 接真实接口，保留 `PageShell`、顶部筛选、六主题和现有响应式结构 | 加载、空、错误、无权限、未就绪、重试均可操作；无模拟数字兜底 |
| 8. 回归与交付 | 运行 AC-01～AC-40、仓库 lint/test/build 和多视口检查 | 记录已完成、已验证、已部署、已上线四个独立状态 |

### 17.4 物理实现约束

- 物理表名、API 路径、缓存方案和任务调度名称沿用目标仓库规范；本 PRD中的对象名是逻辑契约，不要求机械新建同名表。
- 若现有业务表已具备不可变状态流水和所有字段，可用只读视图/查询层生成规范化事实，不重复落库。
- 若只有可变当前状态，且无法还原历史，必须补状态流水或快照后才能将相关主题标为 `READY`。
- 聚合缓存键必须包含：当前用户有效权限范围版本、`start_date`、`end_date`、`organization_id`、`tool_key`、`theme_key`、`person_id/person_query` 及 `aggregationVersion`。
- 任何查询都先鉴权再聚合；禁止先算全公司人员明细再在浏览器过滤。
- 不允许为通过页面验收而在接口、组件或测试 fixture 之外硬编码公司、部门、人员和模拟统计值。
- 新数据从迁移和埋点验收后的 `earliestAvailableAt` 生效；新增字段为空的旧事实不得自动补默认组织、创作链或资源所有人。

### 17.5 最低测试清单

- 单元测试：状态映射、时间分桶、前一等长周期、百分比分母为 0、部分成功、首轮链、后续结果去重、净积分、团队/跨团队归属。
- 幂等测试：任务、积分、结果、采纳和资产使用重复投递。
- 契约测试：六个 `theme_key` 的请求/响应字段、`null` 处理、`dataAsOf` 和 `aggregationVersion`。
- 权限测试：系统管理员、主管、部门管理员、单独审批员、普通用户、停用账号和篡改组织 ID。
- 集成测试：任务 → 结果 → 积分 → 后续使用 → 资产复用完整链路。
- 前端测试：筛选保留、主题切换、人员候选限制、加载/空/错误/无权限/未就绪、指标说明弹窗。
- 视觉测试：1280、1024、736、390、360px；整页无横向溢出，宽表和趋势只局部滚动。

## 18. 最小回归数据集与预期结果

以下为脱敏逻辑 fixture，日期统一为 `2026-08-20`、时区 `Asia/Shanghai`。Codex 应将其转换为目标仓库的测试工厂或 seed，不得写入生产数据。

### 18.1 基础维度

| 对象 | 数据 |
|---|---|
| 组织 | `O_ROOT` 公司；下级 `O_A`、`O_B` |
| 用户 | `U1@O_A`、`U2@O_A`、`U3@O_B`，均为有效设计平台账号 |
| 目标用户快照 | 公司 3 人，`O_A` 2 人，`O_B` 1 人；快照时间 `2026-08-20 23:59:59` |

### 18.2 任务、结果与积分

| 任务 | 人员/组织 | 功能 | 最终状态 | 时间/耗时 | 创作链 | 结果 | 净扣积分 |
|---|---|---|---|---|---|---|---:|
| `T1` | `U1/O_A` | `expert_mode` | `SUCCESS` | 10:00～10:01 / 60 秒 | `C1` 第 1 轮 | `R1`、`R2` 成功 | 10 |
| `T2` | `U1/O_A` | `expert_mode` | `PARTIAL_SUCCESS` | 11:00～11:03 / 180 秒 | `C2` 第 1 轮 | `R3` 成功、`R4` 失败 | 8 |
| `T3` | `U2/O_A` | `ai_buyer_show` | `FAILED` | 12:00 最终失败 | `C3` 第 1 轮 | 无成功结果 | 0 |
| `T4` | `U3/O_B` | `expert_mode` | `CANCELLED` | 13:00 最终取消 | `C4` 第 1 轮 | 无成功结果 | 0 |

另有 `U2/O_A` 在 14:00 完成一次 `ai_prompt` 生成核心动作，耗时 5 秒，不产生任务和积分。

### 18.3 后续行为与资源

| 事实 | 数据 |
|---|---|
| 后续行为 | `R1` 下载成功；`R1` 加入素材库成功并生成 `M1`；`R3` 继续编辑成功。`R1` 虽有两个动作，后续使用结果只计 1 个 |
| 素材库存 | `M0` 为周期前已可用团队素材，所有人 `U1/O_A`，来源为周期前任务；`M1` 在 15:05 首次变为可用团队素材，所有人 `U1/O_A` |
| 素材使用 | `U2/O_A` 将 `M0` 成功绑定到 `T3`，形成 1 条 `AssetUsageFact`；对应前端 `material_select_success` 不另计核心使用 |
| 提示词库存 | `P1` 为周期前已可用团队提示词，所有人 `U1/O_A` |
| 提示词使用 | `U2/O_A` 对 `P1` 确认使用 1 次，并成功带入工具 1 次；形成两个不同 `action_type` 的幂等使用事实 |

### 18.4 公司范围预期断言

| 指标 | 预期值 | 推导 |
|---|---:|---|
| 实际使用用户 | 3 | `U1/U2/U3` 去重 |
| 注册用户覆盖率 | 100% | 3 / 3 |
| 实际使用次数 | 5 | 4 个成功创建任务 + 1 个提示词成功动作 |
| 人均使用次数 | 1.67 | 5 / 3 |
| 成功/失败/取消/未完成任务 | 2 / 1 / 1 / 0 | `PARTIAL_SUCCESS` 计成功 |
| 任务成功率 | 50% | 2 / 4 |
| 平均/中位处理时长 | 120 秒 / 120 秒 | 仅 60、180 秒两个成功任务 |
| 2 分钟内完成率 | 50% | 1 / 2 |
| 使用高峰 | 10:00～12:00 | 与 12:00～14:00 同为 2 次，取较早时段 |
| 成功产出结果 | 3 | `R1/R2/R3` |
| 后续使用结果 | 2 | `R1/R3` 去重 |
| 产出后续使用率 | 66.67% | 2 / 3 |
| 首轮直接采纳率 | 100% | `C1/C2` 均有首轮成功结果且均被采纳；`C3/C4` 不进分母 |
| 消耗积分 | 18 | 10 + 8 |
| 积分使用人数 | 1 | 仅 `U1` 发生正向扣减 |
| 扣积分实际使用次数 | 2 | `T1/T2` |
| 平均每次使用积分 | 9 | 18 / 2 |
| 平均后续使用结果积分 | 9 | 18 / 2 |
| 可用素材/本期新增/活跃素材 | 2 / 1 / 1 | `M0/M1` 可用；`M1` 新增；仅 `M0` 被使用 |
| 素材使用次数/产生任务数/素材复用率 | 1 / 1 / 50% | 1 条使用事实、1 个任务、1 / 2 |
| 可用提示词/活跃提示词/提示词使用率 | 1 / 1 / 100% | `P1` |
| 提示词确认/带入工具/深层使用率 | 1 / 1 / 50% | 带入 1 / 全部成功使用动作 2 |
| 跨任务复用资产 | 1 | 周期前生成素材 `M0` 在 `T3` 中被复用 |

### 18.5 组织与人员守恒

| 范围 | 实际使用用户 | 实际使用次数 | 消耗积分 | 后续使用结果 |
|---|---:|---:|---:|---:|
| `O_A` | 2 | 4 | 18 | 2 |
| `O_B` | 1 | 1 | 0 | 0 |
| 公司 | 3 | 5 | 18 | 2 |

`U1` 的人员详情应为：实际使用 2 次、有效活跃 1 天、成功结果 3 个、后续使用结果 2 个、首轮直接采纳链 2/2、消耗积分 18、平均每次使用积分 9、平均后续使用结果积分 9、本人生成资产跨任务复用 1 个、被团队使用素材 1 个/1 次。

## 19. 完成定义（Definition of Done）

只有同时满足以下条件，才能把本需求状态标为“开发完成并已验证”：

1. 9.8 全部 `EXISTING` 事件已核实现状，全部 `EXISTING_ENHANCE` 和 `NEW_THIS_PHASE` 项已实现或明确对应到等价现有事实。
2. 六主题生产数据不读取 `src/data/demo/` 数值，所有可见数据均可追溯到 9.10。
3. 服务端权限、组织下钻、时间/功能筛选、历史组织快照和人员候选限制全部通过。
4. 第 18 章断言及 AC-01～AC-41 通过；重复投递、关联缺失、权限篡改和资源历史回溯均有自动化测试。
5. 各目标仓库规定的 lint、测试、类型检查和构建通过，最终 diff 无无关格式化、敏感数据、模拟生产值或元数据噪音。
6. `earliestAvailableAt`、数据保留、缓存/聚合和组织路径物理存储方案已经技术评审并回写第 15 章。
7. 部署、数据验收、灰度和正式上线分别有证据；未完成任一步骤不得把状态写为“已上线”。