Repository navigation
Open
Labels
effort/m中等改动,存在一定协同成本 / Medium change with noticeable coordination cost.中等改动,存在一定协同成本 / Medium change with noticeable coordination cost.priority/p3低优先级 / Low priority triage bucket.低优先级 / Low priority triage bucket.triage/needs-info需要补充更多信息后才能分流 / Issue needs more detail before it can be routed.需要补充更多信息后才能分流 / Issue needs more detail before it can be routed.
Description
Problem Statement
管理员目前缺少一个统一的 Skill 使用概览,无法在同一时间范围内快速回答平台调用量如何变化、哪些 Skill 最常用、哪些用户最活跃,以及调用来自哪些入口。现有 Skill 使用统计能力更接近明细查询,缺少面向运营判断的趋势、汇总指标和一致的筛选口径;管理员菜单也没有清晰区分概览分析与明细分析。
Solution
提供独立的 Skill 使用分析信息架构,并在视觉原型验收后落地正式页面和统一统计接口。管理员菜单新增与用户管理同级的“统计分析”父项,父项只负责展开/收起,下面提供“概览分析”和“明细分析”两个独立页面。概览页面使用统一日期和来源口径展示指标卡、调用趋势、热门 Skill、活跃用户和调用来源分布;明细页面继续承载分页明细查询。原型阶段使用模拟数据并支持完整、空数据、加载中和错误状态,已在 1440px 与 390px 视口、明暗主题下完成视觉确认。
User Stories
- As a platform administrator, I want to open a dedicated overview analysis page, so that I can understand Skill usage without scanning raw records.
- As a platform administrator, I want to open a dedicated detail analysis page, so that I can inspect the individual Skill usage events behind the aggregates.
- As an administrator, I want “统计分析” to appear beside “用户管理”, so that the information architecture reflects analytics as a first-class administration capability.
- As an administrator, I want the “统计分析” parent item to expand and collapse without navigating, so that menu state is predictable.
- As an administrator, I want the analytics group to be expanded automatically while I am on either child page, so that the current location is visible after refresh or direct navigation.
- As an administrator, I want role checks to apply to both analytics pages and their API, so that usage information is limited to authorized administrators.
- As an administrator, I want to see total Skill calls for the selected period, so that I can measure overall platform activity.
- As an administrator, I want to see the number of users and Skills with at least one call in the selected period, so that I can measure adoption breadth.
- As an administrator, I want to see daily average calls, including zero-call days, so that the average reflects the entire selected calendar range.
- As an administrator, I want to see a call trend series, so that I can identify growth, drops and quiet periods.
- As an administrator, I want to see the top ten Skills by calls, so that I can identify the most valuable or most heavily used Skills.
- As an administrator, I want to see the top ten active users by calls, so that I can understand who is driving platform usage.
- As an administrator, I want to see the distribution of calls by source, including
/skill,find_skilland other sources, so that I can understand entry-point usage. - As an administrator, I want all cards and charts to use the same filter window, so that displayed totals and rankings are comparable.
- As an administrator, I want presets for the most recent 7, 30 and 90 days, so that common reporting windows require one action.
- As an administrator, I want to enter an inclusive custom start and end date, so that I can report on a business-defined calendar interval.
- As an administrator, I want dates interpreted as Beijing-time natural days, so that reports match the operating team’s calendar.
- As an administrator, I want custom ranges longer than 90 days to aggregate trends by week, so that long-range charts remain readable while preserving totals.
- As an administrator, I want the current range compared with the immediately preceding range of equal length, so that metric cards can show directional change.
- As an administrator, I want loading, empty and error states to be distinct, so that I can tell whether there is no data, data is still being fetched, or the service failed.
- As an administrator, I want a retry action after a failed request, so that I can recover without leaving the page.
- As an administrator, I want charts to provide hover tooltips and legends where useful, so that exact values and series meaning are available without adding drill-down complexity.
- As an administrator, I want charts to remain usable on a narrow viewport with necessary horizontal scrolling, so that the page does not introduce accidental global overflow on mobile-sized screens.
- As an administrator, I want the previously supported
/admin/users/skill-usageaddress to redirect to detail analysis, so that saved links continue to work. - As an administrator, I want
/admin/analyticsto remain a non-navigating parent path, so that selecting the parent does not unexpectedly choose a report. - As an administrator, I want the overview and detail pages to preserve the existing SkillHub theme, controls, keyboard focus behavior and accessible labels, so that analytics feels native to the administration area.
- As a maintainer, I want one unified analytics response to provide all overview and detail sections under the same filter, so that frontend consumers cannot accidentally mix incompatible query windows.
- As a maintainer, I want OpenAPI and generated frontend types updated from the backend contract, so that API changes remain type-safe for all consumers.
- As an operator, I want the analytics response to retain the existing pagination and usage-count semantics, so that the new overview does not change historical detail meaning.
- As a maintainer, I want domain terminology for overview analysis, detail analysis, Skill usage events and call sources documented, so that future implementation and review use consistent language.
Implementation Decisions
- The confirmed prototype is the visual and interaction baseline for the production work. It is reachable at
/prototype/skill-usage-overview, uses mock data, and includes selectable complete, empty, loading and error states. The prototype remains independent until formal visual acceptance; the next implementation phase connects the accepted design to production routes and data. - Production routes are
/admin/analytics/overviewand/admin/analytics/details./admin/analyticsis a parent route with no automatic child redirect./admin/users/skill-usageremains as a compatibility redirect to details. - The administrator navigation places “统计分析” at the same level as “用户管理”. The parent is a button for expansion only; child entries are navigable links. Expansion follows the current child route, and existing keyboard, focus and role-guard behavior is preserved.
- The overview page contains four metric cards: total Skill calls, users with calls, Skills with calls, and average calls per calendar day. It contains a calls trend line chart, horizontal Top 10 Skill and active-user charts, and a source-distribution chart. Charts share one filter model and expose only tooltips, legends where needed and the scrolling required by the layout.
- The default window is the most recent 30 days. Presets cover 7, 30 and 90 days; custom selection accepts inclusive start and end dates. Date-only boundaries use Beijing time and include both dates. The server response must make the resolved boundaries explicit.
- Ranges over 90 days use weekly trend buckets. The average-call denominator is the number of included natural calendar days, including days with no events. Comparison uses an immediately preceding range with the same duration as the current range.
- The existing administrative Skill usage analytics endpoint becomes the single contract for overview and detail data. Its response is extended with trend buckets, source distribution, users-with-calls, Skills-with-calls, daily average and current-versus-previous period metrics while retaining existing top lists, detail pagination, filters, permissions and count semantics.
- The backend application service remains responsible for resolving defaults and validating ranges; the controller remains responsible for transport parsing and authorization. Query/repository projections should calculate aggregates under one normalized filter definition and preserve deleted-user/deleted-Skill display semantics already present in detail results.
- Frontend server state uses the existing typed API client and TanStack Query conventions. Generated OpenAPI types are regenerated through the project command after the contract changes; generated files are not hand-edited. User-visible text is added to translation resources.
- The implementation reuses existing SkillHub Card, Button, Tabs, theme tokens and Lucide icons. Recharts is the selected charting library, as demonstrated by the accepted prototype.
- The glossary is extended with “概览分析”, “明细分析”, “Skill 使用事件” and “调用来源”. An ADR records the non-clickable parent menu, independent child pages, unified statistics endpoint and Recharts decision.
- The implementation is split into two delivery phases: the accepted mock prototype is phase one; production routes, backend extensions, generated types, documentation and full verification are phase two.
Testing Decisions
- Tests assert observable behavior at the highest existing seams. The primary backend seam is the administrative analytics HTTP contract and its application-service query behavior; the primary frontend seam is route/page behavior using the existing router and page/component test conventions.
- Backend tests cover inclusive Beijing-time date boundaries, default and preset windows, invalid ranges, weekly aggregation beyond 90 days, zero-call days in daily averages, equal-length comparison windows, source normalization, empty results, pagination compatibility and role authorization. Existing analytics integration tests are extended rather than replaced.
- Frontend tests cover overview and detail route resolution, compatibility redirection, non-navigating parent behavior, automatic menu expansion, shared filter propagation, complete/empty/loading/error rendering, retry behavior, keyboard focus and narrow-layout overflow containment. Tests assert user-visible roles, labels, links and state transitions rather than Recharts internals.
- API checks regenerate the OpenAPI-derived frontend types and verify affected consumers compile against the new response shape. Schema drift checks are run when the backend contract changes.
- The existing project verification commands are the basis for delivery: focused frontend tests and backend analytics tests first, followed by frontend typecheck/lint/build and backend application tests. Browser verification confirms overview/detail navigation, old-address redirect, refresh, theme switching and error retry at desktop and mobile-sized viewports.
- A successful build or static screenshot is not treated as proof of authorization, date semantics or end-to-end behavior; those behaviors require the corresponding HTTP, application and browser assertions.
Out of Scope
- The prototype phase does not connect production APIs, change production administrator routes or alter persisted usage data.
- The production overview does not provide chart drill-down, per-point navigation, exports, scheduled reports, real-time streaming, alerting or arbitrary grouping dimensions beyond the specified weekly long-range trend.
- This work does not redefine Skill usage event ingestion, source taxonomy, historical backfill, retention, privacy policy or audit semantics.
- This work does not remove the compatibility address before a separate deprecation decision.
- This work does not introduce a second analytics platform or replace the existing optional frontend action-analytics integration.
Further Notes
The prototype was reviewed and explicitly accepted before this specification was requested. The running preview uses port 8766 during review; it is a disposable visual reference, while the production implementation must still be validated against the actual API, permissions, generated contract and existing authentication state.
Metadata
Metadata
Assignees
Labels
effort/m中等改动,存在一定协同成本 / Medium change with noticeable coordination cost.中等改动,存在一定协同成本 / Medium change with noticeable coordination cost.priority/p3低优先级 / Low priority triage bucket.低优先级 / Low priority triage bucket.triage/needs-info需要补充更多信息后才能分流 / Issue needs more detail before it can be routed.需要补充更多信息后才能分流 / Issue needs more detail before it can be routed.
Activity
github-actions commentedon Nov 13, 2026
Issue Triage
triage/needs-infopriority/p3(2.4/5)effort/m(3/5)2/5lowrules-onlyWhy
Missing Info
problem.proposed solution.Next Action
/retriage. Missing: problem, proposed solution.问题分流结果
triage/needs-infopriority/p3(2.4/5)effort/m(3/5)2/5低rules-only原因
缺失信息
problem.proposed solution.下一步
/retriage后重新分流XiaoSeS commentedon Nov 20, 2026
理解这组需求希望提供统一的技能使用概览、趋势、排行和明细。实现前,需要先对齐现有基础与产品范围。
SkillHub 已有前端行为采集接入,以及后端通过 OTLP 导出业务事件的能力(参见 #989、#1009,相关实现 #1037、#1029),支持部署方使用外部采集与分析平台。
我们核对当前
main后,尚未找到提案中提到的“已有技能使用统计接口”和/admin/users/skill-usage页面。因此,#1090 所描述的“扩展已有接口”目前缺少可核验的实现基础。请进一步澄清:
/skill、find_skill的记录由哪个组件产生?下载请求、安装和实际执行需要分别定义。我们的倾向是复用现有采集协议和出口,缺失的业务事件按明确口径补充。是否新增 SkillHub 内置报表,需要单独确认价值、数据来源和维护边界,不默认引入另一套事件存储与统计体系。
建议先完成这些澄清,再确定 #1088 及其子任务的实施范围。
English
This proposal aims to provide unified Skill usage summaries, trends, rankings, and details. Before implementation, we need to align on the existing foundation and product scope.
SkillHub already supports frontend analytics integration and backend business-event export over OTLP (see #989 and #1009, implemented through #1037 and #1029), allowing deployments to use external collection and analytics platforms.
After reviewing current
main, we could not locate the existing Skill usage analytics endpoint or/admin/users/skill-usagepage referenced in the proposal. Consequently, the implementation baseline for “extending the existing endpoint” in #1090 remains unverified.Could you clarify:
/skillandfind_skillrecords? Download requests, installation, and actual execution need separate definitions.Our preference is to reuse the existing collection protocols and export paths, adding clearly defined business events where needed. Built-in reporting should be evaluated separately, including its value, data sources, and maintenance boundaries, without assuming another event-storage and aggregation system.
We suggest resolving these questions before defining the implementation scope of #1088 and its subtasks.