# clinical-web 开发规范

## 技术栈与边界

- 使用 Vue 3、TypeScript、Vite、Vue Router、Pinia、Element Plus 和 Axios。
- 所有接口请求统一经过 `src/utils/request.ts` 的单例实例。
- 开发环境默认使用 `/api`，由 `vite.config.ts` 代理到后端；不要在页面中直接拼接后端域名。
- 当前除登录外的业务接口可以使用 Mock，但 Mock 数据必须遵守真实接口类型。

## 目录约定

```text
src/
├─ api/
│  ├─ auth.ts
│  ├─ workbench/
│  │  ├─ home.ts
│  │  ├─ signing.ts
│  │  └─ types.ts
│  └─ management/
│     ├─ documents.ts
│     ├─ reports.ts
│     ├─ users.ts
│     ├─ permissions.ts
│     ├─ document-permissions.ts
│     ├─ settings.ts
│     └─ types.ts
├─ components/
│  ├─ layout/
│  └─ signing/
├─ composables/
├─ stores/
├─ types/
├─ utils/
└─ views/
   ├─ auth/
   ├─ workbench/
   └─ management/
```

- API 文件按页面业务域对应；管理端直接使用 `documents.ts`、`reports.ts` 等文件，不再额外套同名目录。
- 每个具体 View 使用 `index.vue` 作为入口；当前页面专用组件放在同级 `components`。
- 跨页面的领域组件放在 `src/components`，布局组件统一放在 `src/components/layout`。
- API DTO 类型放在对应 API 业务域的 `types.ts`；页面展示和交互类型放在 View 的 `types.ts`；全局类型放在 `src/types/common.ts`。

## API 规范

- API 文件只负责请求、响应类型和必要的数据标准化。
- 不在 API 文件中创建新的 Axios 实例，不在 API 层操作组件、路由或 `ElMessage`。
- 所有请求通过 `request` 单例发送；接口函数必须提供明确的返回类型。
- 接口地址使用相对路径，不重复写基础地址。
- 业务接口的列表、详情、创建、更新和删除函数按资源命名，例如：

```ts
import { request } from '@/utils/request'
import type { ReportOverviewResponse, ReportQuery } from './types'

export function getReportOverview(params: ReportQuery) {
  return request.get<ReportOverviewResponse>('/management/reports/overview', { params })
}
```

- 响应包装、错误码和后端 DTO 与页面展示模型不一致时，在 API 边界或 composable 中转换，组件不负责猜测接口结构。
- 登录 Token、用户信息和本地持久化只由 `stores/login.ts` 与 `utils/auth-storage.ts` 管理，页面不直接操作 `localStorage`。

## 页面与组件拆分

- `views/**/index.vue` 负责页面编排、接口调用、加载/错误状态、筛选条件和路由联动。
- 当前页面专用组件负责展示和交互，通过类型化 `props` 接收数据，通过 `emit` 通知父组件。
- 展示型组件不直接调用 API、不直接修改全局 Store；确有跨页面业务复用时，放入领域组件并明确其边界。
- 组件只承担一个清晰职责。不要为了减少文件长度机械拆分小片段，也不要让页面入口堆积复杂表单和弹窗逻辑。
- 复杂表单、弹窗流程、校验、提交和异步状态抽到 `composables/useXxx.ts`；弹窗组件负责表单渲染和事件呈现。
- 签署任务新增流程由 `components/signing/NewSigningTaskDialog.vue` 和 `composables/useSigningTaskForm.ts` 共同维护，供签署工作台和文档库复用。

## 状态管理

- 页面只使用一次的表格数据、筛选条件、弹窗显隐和 loading，优先使用页面内的 `ref`、`reactive` 和 composable。
- 只有跨页面共享、需要持久化或代表全局上下文的状态才进入 Pinia。
- Store 按业务域拆分，并统一使用 Composition API 写法：

```ts
export const useExampleStore = defineStore('example', () => {
  const value = ref('')

  const isReady = computed(() => Boolean(value.value))

  function setValue(nextValue: string) {
    value.value = nextValue
  }

  return { value, isReady, setValue }
})
```

- 不使用 Pinia 的 `state`、`getters`、`actions` 配置式写法。
- `stores/app.ts` 只管理院区、环境等应用上下文。
- `stores/login.ts` 只管理登录态、用户信息、Token 和登录/退出流程。
- 不把所有业务数据集中到 `app` Store；签署任务列表等页面数据默认留在页面或 composable 中。
- 避免 Store 之间互相依赖，尤其不要让 `request.ts` 静态依赖业务 Store，防止循环依赖。

## 类型与命名

- 不使用无理由的 `any`；后端字段不确定时先定义 `unknown`，在边界处完成校验或标准化。
- Vue 组件使用 PascalCase；API、composable、Store 和工具文件使用 kebab-case 或项目已有命名方式。
- `useXxx` 表示 composable，`useXxxStore` 表示 Pinia Store。
- 类型名描述业务含义，避免使用 `Data`、`Info` 等无语义名称。

## 提交前检查

```bash
npm run lint
npm run format:check
npx vue-tsc --noEmit
npm run build
```

如果构建被本机 `node_modules` 或已有 `dist` 的权限问题阻断，应保留错误信息并使用临时输出目录验证，不要删除或覆盖已有构建产物。