fix(GOV-009): 完成最终复审整改

web/src/api/adapters/health.adapter.ts

@@ -3,8 +3,10 @@ import type { components } from '../generated/schema';
 type HealthResponseDto = components['schemas']['HealthResponseDto'];
 type DependencyHealthDto = components['schemas']['DependencyHealthDto'];
 
+/** 页面级健康状态把后端 disabled 映射为 degraded，避免与真实故障混为一谈。 */
 export type HealthViewState = 'healthy' | 'degraded' | 'unavailable';
 
+/** 单项依赖的展示模型隐藏后端 DTO 结构，只保留名称、可用性和安全说明。 */
 export interface HealthServiceViewModel {
   key: 'redis' | 'mysql' | 'rocketMq';
   name: 'Redis' | 'MySQL' | 'RocketMQ';
@@ -12,6 +14,7 @@ export interface HealthServiceViewModel {
   note: string;
 }
 
+/** 健康页稳定展示契约；Vue 组件不直接依赖 OpenAPI 生成类型。 */
 export interface HealthViewModel {
   state: HealthViewState;
   stateLabel: '运行正常' | '部分能力停用' | '服务异常';
@@ -39,6 +42,7 @@ function toServiceViewModel(
   };
 }
 
+/** 将版本化 HTTP DTO 转为页面展示模型，并拒绝未知的服务端状态枚举。 */
 export function toHealthViewModel(dto: HealthResponseDto): HealthViewModel {
   const dependencies = Object.values(dto.dependencies);
   for (const dependency of dependencies) assertDependencyStatus(dependency.status);

web/src/api/client.ts

@@ -1,6 +1,7 @@
 import createClient, { type Client } from 'openapi-fetch';
 import type { paths } from './generated/schema';
 
+/** 统一的安全请求错误，不把浏览器或代理底层异常直接展示给用户。 */
 export class ApiRequestError extends Error {
   constructor() {
     super('API 请求失败，请稍后重试');
@@ -8,6 +9,7 @@ export class ApiRequestError extends Error {
   }
 }
 
+/** 创建受 OpenAPI paths 约束的客户端，并在边界统一清洗网络异常。 */
 export function createApiClient(
   baseUrl: string,
   fetchImplementation: (request: Request) => Promise<Response> = globalThis.fetch,

web/src/app/providers.ts

@@ -3,6 +3,7 @@ import type { App } from 'vue';
 
 import { createAppRouter } from './router';
 
+/** 集中安装全局 Provider，防止页面自行创建重复的 Pinia 或 Router 实例。 */
 export function installAppProviders(app: App) {
   app.use(createPinia());
   app.use(createAppRouter());

web/src/app/router.ts

@@ -17,6 +17,7 @@ const routes: RouteRecordRaw[] = [
   },
 ];
 
+/** 创建可注入 history 的路由实例，使浏览器运行与单元测试共享同一路由表。 */
 export function createAppRouter(history: RouterHistory = createWebHistory()) {
   return createRouter({ history, routes });
 }