kindergarten_java/docs/前端项目规范.md

AI 开发规范（media-science-frontend）

本文档基于当前仓库的真实配置与现有代码风格整理，目标是让 AI/新同学在不“自作主张改风格/改架构”的前提下，稳定产出可合并的代码。

技术栈与关键约束

• 框架：Vue 3 + TypeScript + Vite（type: module
• 路由：unplugin-vue-router 文件路由（vue-router/auto），Hash 模式（createWebHashHistory()）
• 状态：Pinia（setup store 风格）
• 图表：图表：echarts
• UI：Ant Design Vue
• 样式：UnoCSS（virtual:uno.css），允许在模板里大量使用原子类（复杂样式例如动画，渐变等使用class声明，其余使用原子样式）
• 国际化：@intlify/unplugin-vue-i18n（src/locales/*.json）
• 格式化门禁：Husky + lint-staged + Prettier（提交前会对 *.{vue,ts,tsx,js,jsx,md,css,less,json} 自动 prettier --write）
• TypeScript 严格性：strict: true，并开启 noUnusedLocals/noUnusedParameters
• 自动导入：unplugin-auto-import（vue、pinia、@vueuse/core、router auto imports），因此代码里可能未显式 import ref/computed/watch/...

项目架构（目录分层）

以 src/ 为根：

• 入口：src/main.ts（创建 app、挂载 router/pinia/Antd、全局指令）
• 根组件：src/App.vue（全局初始化逻辑、主题/locale、监听生命周期等）
• 页面：src/pages/**（文件路由：一个目录通常对应一个页面模块；页面内可用 definePage({ alias: [...] })）
• 通用组件：src/components/**（跨页面复用的 UI/布局组件，如 Layout.vue）
• 状态管理：src/store/**（Pinia stores）
• 接口层：src/api/**
  • src/api/generated/**：Orval 自动生成（接口类型与路径的唯一真源，禁止手改）
  • src/api/client.ts：项目侧统一入口/别名层（导出客户端实例与类型工具）
  • src/api/*.ts：业务适配层（可选：解包 Result、分页扁平化、兼容旧页面结构等）
• 工具：src/utils/**（如 useRouteUtil.ts、useLocalStorage.ts、useWebSocket.ts 等）
• 类型声明：src/**/*.d.ts、src/global.d.ts、src/vite-env.d.ts

仓库根目录速览（常用）

.
├─ src/                  # 应用源码
├─ public/               # 静态资源（按 Vite 约定）
├─ vite/                 # Vite 插件/构建辅助（如 LocaleType）
├─ vite.config.ts        # 构建与插件配置（含 proxy、自动路由、自动导入等）
├─ uno.config.ts         # UnoCSS 主题/shortcuts
├─ tsconfig*.json        # TS 严格配置（strict + noUnused*）
├─ .prettierrc           # 代码格式标准（提交前会强制执行）
├─ .husky/pre-commit     # 提交钩子：lint-staged
├─ .env*                 # 环境变量（通过 import.meta.env 读取）
└─ AI_DEV_GUIDE.md       # 本规范

编码风格（必须遵守）

代码格式（Prettier 为准）

来自 .prettierrc：

• 单引号：'...'
• 缩进：2 空格，禁用 tab
• 行宽：100

任何“手动对齐/自定义格式化习惯”都会被提交前的 Prettier 重写，AI 不要和格式化对抗。

Vue SFC 约定

• 优先使用：<script lang="ts" setup>（当前仓库主流写法）
• 模板类名：允许 UnoCSS 原子类；尽量复用 uno.config.ts 里的 shortcuts（如 flex-center）
• 样式块：
  • 页面级样式：优先 scoped
  • 全局样式：放在明确的全局入口（项目当前也存在在 App.vue 内写全局样式的情况；新增时优先放到统一样式文件，除非确实需要跟随根组件）

TypeScript/类型策略

• 避免：any（除非是三方库/遗留代码无法避免，且要把 any 限制在最小范围）
• 参数与返回值：对外导出的工具函数、store action、请求函数调用处尽量补齐类型
• 未使用变量/参数：因为启用了 noUnusedLocals/noUnusedParameters，新增代码必须确保无未使用项

路由规范（文件路由 + definePage）

• 页面文件位置：放在 src/pages/... 下，按业务模块分目录
• 页面元信息：在页面组件的 setup 中使用：

import { definePage } from 'vue-router/auto';

definePage({
  alias: ['/xxx', '/yyy'],
});

• 路由工具：推荐使用 src/utils/useRouteUtil.ts 获取 route/router/params<T>()

状态管理规范（Pinia setup store）

• 位置：src/store/*.ts
• 风格：defineStore('name', () => { ... })，对外返回 ref/computed 等
• 与请求层鉴权同步：涉及登录态/鉴权时，确保“状态层的 token”与“API 客户端实际使用的鉴权头/拦截器/存储”一致，避免出现“界面认为已登录但请求未携带 token”或相反的情况

API 开发规范（Orval 生成代码）

本规范以 src/api/generated/ 为接口类型与路径的唯一真源，通过 Orval 从后端 OpenAPI 自动生成 TypeScript 类型 + 客户端方法。

1. 目录与职责边界

• src/api/generated/：Orval 自动生成目录，禁止手改。
  • api.ts：getReadingPlatformAPI() 工厂函数，返回包含全部接口方法的对象。
  • model/：OpenAPI 生成的 DTO/VO/Result/PageResult/Params 类型。
• src/api/client.ts：项目侧的“统一入口/别名层”，导出 readingApi（完整客户端实例）以及常用的类型工具（解包、分页别名等）。
• src/api/*.ts：业务侧“适配层”（可选），用于：
  • 兼容既有页面期望的“扁平结构/字段名/返回形态”
  • 补齐 OpenAPI 暂未覆盖的历史接口（短期过渡）
  • 汇聚跨接口的业务逻辑（例如组合请求、额外校验）

2. 基本原则（必须遵守）

• 生成代码只读：不得在 src/api/generated/** 内做任何手工修改（包括修复类型、改路径、加字段）。
• 以生成类型为准：参数/返回类型优先使用 src/api/generated/model 导出的类型，避免手写 interface 漂移。
• 对外只暴露稳定的业务接口：页面/组件尽量通过 src/api/*.ts（适配层）或 src/api/client.ts（直接调用）访问，避免散落调用方式导致难以迁移。

3. 推荐调用方式

3.1 直接使用 Orval 客户端

• 统一从 src/api/client.ts 引入：
  • readingApi: getReadingPlatformAPI() 的实例
  • ApiResultOf / UnwrapResult / PageDataOf 等类型工具

示例（以 Result<T> 为包裹结构）：

import { readingApi } from '@/api/client';
import type { ResultTenant } from '@/api/generated/model';

async function loadTenant(id: number) {
  const res = (await readingApi.getTenant(id)) as ResultTenant;
  return res.data; // T（可能为 undefined，取决于后端返回与类型定义）
}

3.2 使用“适配层”稳定返回结构

当页面已经依赖历史返回结构（例如直接要 items/total/page/pageSize），在 src/api/*.ts 内做一次性适配，页面只消费适配后的结构。

分页适配建议统一输出：

• items: T[]
• total: number
• page: number
• pageSize: number

4. Result / PageResult 约定与解包

后端统一响应通常为：

• 普通接口：Result<T>，字段一般为 code/message/data
• 分页接口：Result<PageResult<T>>，字段一般为 items/total/page/pageSize

在生成代码中常见类型形态：

• ResultXXX（如 ResultTenant、ResultUserInfoResponse）
• ResultPageResultXXX（如 ResultPageResultTenant）
• PageResultXXX（如 PageResultTenant）

建议做法：

• 组件/页面层尽量不要直接处理 ResultXXX，而是由适配层解包并做兜底（空数组、默认分页参数等）。
• 严禁在页面散落 as any；确需兼容时，集中在 src/api/*.ts 适配层进行，并在适配层内把“最终对页面返回的类型”定义清楚。

5. 命名与重复接口（getXxx/getXxx1/getXxx2）

由于不同角色端点（teacher/school/parent/admin）可能存在同名资源，Orval 在生成时会用 1/2/3 后缀消歧，例如：

• getTask（teacher） vs getTask1（school） vs getTask2（parent）

规范建议：

• 业务层不要直接暴露带数字后缀的方法名；
• 在 src/api/*.ts 中封装为语义化名称，例如：
  • teacherGetTask / schoolGetTask / parentGetTask
  • 或按模块拆分到 src/api/teacher/task.ts 等（如后续重构允许）

6. 何时需要更新生成代码

当后端 Controller 或 DTO/VO 发生变更：

1. 后端更新 OpenAPI（Knife4j/SpringDoc）
2. 前端更新规范并重新生成（项目已有脚本）：

npm run api:update

3. 提交生成物（通常包含 api-spec.* 与 src/api/generated/**）

注意：如果某接口在后端已存在但 OpenAPI 未导出（例如缺少注解/返回类型不规范），应优先修后端文档，而不是在前端“硬编码路径”长期绕过。

7. 禁止事项（高频踩坑）

• 禁止：手改 src/api/generated/**（下次生成会被覆盖，且会引入不可追踪差异）。
• 禁止：页面里手写 axios 调用去访问 /api/v1/...（除非 OpenAPI 暂缺且已在适配层集中兜底）。
• 禁止：在业务代码中扩散 any 来“快速通过类型检查”。

8. 迁移策略（从旧 http 到 Orval）

若已有模块使用 src/api/index.ts 的 http.get/post/...：

• 短期：保留旧实现，但新增/变更接口优先走 readingApi
• 中期：逐模块把旧 http 调用替换为 readingApi，并在适配层维持页面不改
• 长期：页面全面只依赖适配层/生成客户端，减少重复封装

本地存储规范

• Key 统一：只在 src/utils/useLocalStorage.ts 的 LocalStorageKey 中声明与复用
• 登出清理：使用 outLoginClearStorage()（如需扩展清理范围，优先扩展 LocalStorageKey）

组件与文件命名

• Vue 组件：
  • 通用组件：src/components/PascalCase.vue（现有仓库既有 PascalCase 也有小写文件名；新增时优先 PascalCase，避免混乱扩大）
  • 页面组件：src/pages/<module>/index.vue（仓库已有此习惯）
  • 页面子组件：src/pages/<module>/components/*.vue
• TS 工具：src/utils/camelCase.ts 或 useXxx.ts（hook/组合式函数）
• Store：src/store/useXxx.ts 或 src/store/xxx.ts（与现有文件保持一致，避免引入第三种命名体系）

变更边界（AI 必须遵守）

• 不做无关重构：只改与需求相关的文件/代码；不要“顺便”换写法、换目录结构、统一命名
• 不引入新依赖：除非需求明确且必要；新增依赖要同步更新 package.json 并说明原因
• 不改公共行为：如 request、token 同步、路由生成规则、构建配置（除非需求明确）

环境变量与配置（不要绕开）

• 读取方式：统一用 src/utils/env.ts 的 getAppEnvConfig()，不要在业务代码里到处直接读 import.meta.env.xxx
• 常用字段：
  • VITE_PREFIX_API：请求前缀（当前 request 使用的是 (${VITE_PREFIX_API}${url})）
  • VITE_BASE_API：存在但当前请求实现未拼接（历史上有注释；如需启用必须全局评估影响）
• 注意：vite.config.ts 已配置 proxy（如 /scienceApi、/localhostApi）；开发环境应优先通过前缀 + proxy 工作，而不是写死域名

提交与协作

• 提交前：确保 pnpm dev 能启动、关键页面可访问（至少覆盖改动路径）
• 格式化：提交时会自动跑 Prettier；如果出现大量无关格式 diff，说明你改动触发了更大范围格式化，需收敛修改范围
• 变更说明：PR/提交信息优先解释“为什么”而不是“改了什么”

AI 变更自检清单（提交前必过）

• 范围：是否只改了需求相关文件？是否避免“顺手重构/改命名/大面积格式化”？
• 类型：tsconfig 已启用 strict 与 noUnused*，新增代码是否无未使用变量/参数？
• 路由：新增页面是否放在 src/pages/ 并使用 definePage（如需 alias）？
• 请求：是否遵守 Orval 规范（生成代码只读、调用集中在 src/api/client.ts/适配层，避免页面散落 axios/fetch）？
• 鉴权：涉及登录态/鉴权时，是否确保 store 中的 token 与 API 客户端实际使用的鉴权头/拦截器/存储一致？
• 存储：localStorage key 是否只使用 LocalStorageKey？
• 格式：是否符合 .prettierrc（单引号、2 空格、行宽 100），并接受提交前会被 Prettier 重写？

常见开发模板（给 AI 直接套用）

新增页面（文件路由）

1. 新建 src/pages/<biz>/index.vue
2. 在 script setup 中写 definePage({ alias: [...] })
3. 使用 RouterView/组件拼装页面

新增接口并调用

1. 后端更新 OpenAPI（确保该接口可被导出）
2. 前端执行 npm run api:update 重新生成（产物在 src/api/generated/**）
3. 在 src/api/client.ts 或 src/api/*.ts（适配层）封装稳定接口
4. 页面/组件只从 src/api/client.ts 或适配层引入调用，避免散落直连请求