页面对齐标杆

这份文档用于当前 ALIAPI Web 与演示项目 L-LimAPI 的页面校对工作。

核心原则只有一条：

• 不把演示项目当成最终 UI 产物
• 先对齐功能模块、入口、视角边界和信息归属
• 再决定当前项目里哪些内容接真实接口，哪些内容只保留为占位或补充

校对目标

每个页面都按下面四层去对照：

1. 模块是否一致
2. 视角是否一致
3. 信息边界是否一致
4. 真实接口是否接对位置

对照维度

1. 模块一致

先确认演示项目里这个页面到底承担什么职责。

要检查的内容：

• 页面标题是否一致
• 是否有同类的顶部指标
• 是否有同类的筛选器
• 是否有同类的表格 / 卡片 / 抽屉 / 弹窗
• 是否有同类的辅助说明或空状态

2. 视角一致

要确认当前项目在不同角色下是否和演示项目同样分流。

常见视角包括：

• 成员视角
• 管理员视角
• 平台管理员视角

要检查的内容：

• 成员是否误入管理员页
• 管理员是否还能看到成员专属流程
• 提示页的跳转是否合理

3. 信息边界一致

要确认页面展示的内容是不是演示项目里这个模块该展示的内容。

例子：

• observability 在演示里是调用归因和结算归属页，不是纯日志审计页
• billing 在演示里是成员账户流水页，组织财务另有独立页

4. 真实接口接入位置

当前项目不是 demo，所以允许也应该接真实接口。

但要注意：

• 接口字段要填到演示模块对应的位置
• 如果真实接口比 demo 多，优先作为补充信息保留
• 如果真实接口缺 demo 某个模块，先记录缺口，再决定是否补能力

观察标杆

当前已经作为标杆的页面是：

• observability

原因是它最容易把“模块校对”做偏：

• 演示项目的模块是“调用归因 / 结算归属”
• 当前项目容易误做成“日志审计 / 调用记录”

因此后续其他页面都建议先回答这三个问题：

1. 演示项目里这个页面的核心职责是什么
2. 当前项目现在是不是同一职责
3. 如果不是，是模块错位还是仅仅字段命名不同

建议执行顺序

1. 先看演示项目
2. 提炼模块清单
3. 对照当前项目
4. 标记缺项 / 错项 / 可补充项
5. 再决定是否改代码

当前校对矩阵

以下结果以“模块职责和角色边界已对齐，数据来自真实接口”为完成标准，不要求复制演示项目的视觉实现。

成员视角

页面	对齐模块	真实数据来源	结果
/dashboard	余额、账户摘要、近期扣费、我的 Key、开放模型、新成员引导	profile、billing summary、billing、keys、models	已校对
/models	模型广场、筛选、详情、创建 Key 入口	/portal/models	已校对
/keys	Key 列表、状态、限额、调用量、重置与删除	/portal/keys、/portal/logs	已校对
/keys/create	基础信息、允许模型、QPS/RPM、TPM、额度、一次性密钥	/portal/keys、/portal/models	已校对
/playground	模型选择、Key 选择、真实对话调用	/portal/models、/portal/keys、Chat API	已校对
/billing	成员余额、充值入口、调用扣费流水	profile、/portal/billing、/portal/billing/summary	已校对
/billing/credits	充值档位、支付单、订单状态	Portal 支付与充值接口	已校对
/analytics/usage	个人调用、Token、模型分布、Key、扣费	/portal/logs、/portal/billing	已校对
/analytics/usage/model/:modelId	单模型 Token、明确状态成功率、调用明细	/portal/logs	已校对

管理员视角

页面	对齐模块	真实数据来源	结果
/dashboard	模型、成员、成员余额、成功调用、成员排行、经营摘要	models、org members、member usage、logs、billing	已校对
/models	模型供给、开放状态、成员可见价格、写能力边界	/portal/models	已校对，组织级模型写接口缺失
/members	成员、邀请、余额发放、总/个人/组织余额、详情能力边界	org members、invitations、member usage、allocate	已校对
/departments	部门树、未分配成员、成员归属	org info、org members	已校对，部门写接口缺失
/analytics/usage	全员筛选、成员排行、调用明细、双侧结算	logs、billing、member usage	已校对
/org/billing	采购成本、成员消费、按模型/成员结算、口径说明	logs、billing、member usage	已校对
/observability	调用归因、成员、Key、模型、双侧成本、调用详情	logs、billing	标杆页
/org/settings	组织信息、成员规则、治理边界	/portal/org/info	已校对，更新接口缺失

共享与扩展页面

/docs、/growth/invite、/settings、/settings/security 是真实项目在演示项目之外的扩展能力。保留这些页面，但仍遵守相同规则：只提交后端接受的字段，不在前端模拟保存、安全策略、奖励余额或不存在的跳转链接。

路由收敛

历史入口不再维护第二套演示页面，而是根据角色跳转到唯一真实页面：

• /keys/management：管理员到成员管理，成员到我的 Key
• /billing/records：管理员到组织财务，成员到我的账户
• /analytics/cost：管理员到组织财务，成员到我的用量
• /routing/auto：管理员到模型供给，成员到在线测试
• /rankings：统一到模型服务
• /notifications：统一到设置
• /growth/team：管理员到成员管理，成员到工作台

已确认的接口缺口

演示项目有模块，但当前 OpenAPI 没有可靠写入或聚合能力时，页面必须显示能力缺口，不能使用本地状态伪造成功。

当前缺口包括：

• 部门树 CRUD、成员部门归属和调整接口
• 组织级模型开放状态与成员价格写接口
• 组织信息更新接口
• 组织采购成本的全量同口径汇总接口
• 组织月账单和发票接口
• 管理员查看成员 Key 的接口
• 按成员、按模型的消耗分布接口
• 安全策略、IP 黑名单和阻断事件接口
• 账单主体、通知偏好、BYOK 等设置写入接口

数据口径约束

• generationId 是调用请求标识，不能回退显示为 API Key。
• 缺失或无法识别的调用状态是“未知”，不能默认算成功。
• BillingRecord.cost 是成员扣费，不能直接当成组织采购成本。
• member-usage 的 totalBalance、personalBalance、orgBalance 是当前余额及其来源，不得标成累计充值或累计发放。
• 调用日志为空但账单存在时，Observability 必须保留账单调用；缺失的 Key、状态和采购成本继续显示“未提供”。
• 组织采购成本只读取明确的供应侧成本字段。
• 结算差额只能在同一批调用同时取得成员扣费和采购成本时计算。
• 分页或最近 N 条明细的汇总必须标明“已加载”，不能伪装成全量累计。