283 lines
11 KiB
Markdown
283 lines
11 KiB
Markdown
# TH Hotel 前端开发规范
|
||
|
||
## 1. 文档定位
|
||
|
||
本文整理 TH Hotel 当前前端开发约定，供本项目 UI 开发和其他 agent 协作参考。
|
||
|
||
本文是当前项目专属补充，不应整份复制到其他项目。可复用的通用前端规则应沉淀到 `docs/import/reusable/frontend-development-guidelines.md`。
|
||
|
||
前端只负责展示、交互、人工确认、调试入口和调用本项目后端。前端不得直接调用 OHIP、
|
||
SuperAgent、AgentBus 或任何持有 Secret 的外部系统。
|
||
|
||
## 2. 技术栈
|
||
|
||
以 `client/package.json` 为准，当前前端技术栈如下：
|
||
|
||
| 类别 | 当前选择 |
|
||
| --- | --- |
|
||
| 运行时 | Node.js 22.13+ LTS |
|
||
| 框架 | Vue 3.5.x |
|
||
| 语言 | TypeScript ~6.0.x，Strict 模式 |
|
||
| 构建 | Vite 8.x |
|
||
| 组件写法 | Composition API，`<script setup lang="ts">` |
|
||
| 路由 | Vue Router 5.x |
|
||
| 客户端状态 | Pinia 3.x |
|
||
| 服务端状态 | TanStack Vue Query 5.x |
|
||
| UI 组件库 | PrimeVue 4.x |
|
||
| 图标 | PrimeIcons |
|
||
| 国际化 | vue-i18n 11.x |
|
||
| Vue SFC 类型检查 | vue-tsc |
|
||
| 测试 | Vitest 4.x、Vue Test Utils 2.x、jsdom |
|
||
| Lint | ESLint 10.x、typescript-eslint 8.x、eslint-plugin-vue |
|
||
|
||
不引入通用 Admin Template。新增 UI 应延续现有设计语言和样式 token。
|
||
|
||
兼容性要求：
|
||
|
||
- Vite、ESLint 和 Vitest 的 Node.js 要求必须同时满足，当前统一使用 Node.js 22.13+ LTS。
|
||
- TypeScript 版本必须与 `typescript-eslint` 支持范围一致；在确认 `typescript-eslint` 支持更高版本前，TypeScript 锁定为 `~6.0.x`，不得使用宽泛的 `^6.0.0`。
|
||
- Vue SFC 项目必须配置 `vue-tsc` 做类型检查，不能只依赖 `tsc`。
|
||
- 升级 Vue、Vite、TypeScript、ESLint、Vitest、PrimeVue、Pinia、Vue Router 或 Vue Query 前，必须先检查版本兼容性并更新本文。
|
||
|
||
## 3. 目录约定
|
||
|
||
当前前端目录：
|
||
|
||
```text
|
||
client/src
|
||
├── components
|
||
│ ├── common
|
||
│ └── reservation
|
||
├── composables
|
||
├── i18n
|
||
│ └── locales
|
||
├── layouts
|
||
├── router
|
||
├── services
|
||
├── stores
|
||
├── styles
|
||
├── tests
|
||
├── types
|
||
└── views
|
||
└── reservation
|
||
```
|
||
|
||
目录规则：
|
||
|
||
- API 请求封装放入 `src/services`。
|
||
- 手写类型定义放入 `src/types`。
|
||
- 可复用组合逻辑放入 `src/composables`。
|
||
- 路由定义放入 `src/router`。
|
||
- Pinia Store 放入 `src/stores`。
|
||
- i18n 入口和语言包放入 `src/i18n`。
|
||
- 页面级组件放入 `src/views`。
|
||
- 可复用业务组件放入 `src/components/<domain>`。
|
||
- 通用布局放入 `src/layouts`。
|
||
- 全局样式和设计 token 放入 `src/styles`。
|
||
- 未来 OpenAPI 生成代码放入 `src/generated`，禁止手工修改。
|
||
|
||
## 4. 组件规范
|
||
|
||
- 页面和组件统一使用 Vue 3 Composition API。
|
||
- `.vue` 文件使用 `<script setup lang="ts">`。
|
||
- Props、Emits、响应式状态和服务返回值必须有明确类型。
|
||
- 避免在模板中写复杂业务逻辑，复杂逻辑放入 computed、composable 或服务层。
|
||
- 不在组件里直接拼接后端 URL，统一通过 services。
|
||
- 不在组件里直接访问浏览器全局存储保存业务事实。
|
||
- 不把中文或英文显示文案作为业务判断依据。
|
||
- 不为未知的财务部、前台流程硬编码页面、状态或菜单。
|
||
|
||
## 5. 状态管理规则
|
||
|
||
Pinia 只保存客户端状态，例如：
|
||
|
||
- 当前用户上下文
|
||
- 当前酒店
|
||
- 当前部门
|
||
- 语言和页面偏好
|
||
- 轻量 UI 状态
|
||
|
||
服务端数据使用 TanStack Vue Query：
|
||
|
||
- 列表、详情、Timeline、Task、Preflight、SourceMessage 等后端数据通过 Query 获取。
|
||
- Mutation 完成后按 query key 精准失效或更新缓存。
|
||
- 不把服务端数据长期复制进 Pinia。
|
||
- 不用 Pinia 绕过后端权限、状态机或校验。
|
||
|
||
## 6. API 请求规范
|
||
|
||
- 浏览器只能调用本项目后端。
|
||
- 所有请求封装到 `src/services`。
|
||
- 服务函数返回明确 TypeScript 类型。
|
||
- 统一使用 `httpClient` 处理 JSON、错误和 Problem Detail。
|
||
- 前端不直接调用 OHIP、SuperAgent、AgentBus、数据库或对象存储。
|
||
- 前端不发送后端 Secret、replay access key、Provider API Key 或 Oracle 凭证。
|
||
- 调试页面如果需要触发受控后端能力，应由后端提供 debug-only 包装接口，Secret 保留在后端。
|
||
|
||
## 7. 国际化规范
|
||
|
||
首期交付：
|
||
|
||
```text
|
||
zh-CN
|
||
en-US
|
||
```
|
||
|
||
架构预留：
|
||
|
||
```text
|
||
th-TH
|
||
```
|
||
|
||
规则：
|
||
|
||
- 新增页面和组件不得硬编码中英文业务文案。
|
||
- 系统固定文案必须使用稳定 i18n key。
|
||
- 后端返回稳定业务代码和必要 `labelKey`，前端按 key 显示。
|
||
- 前端不得把中文或英文文本作为业务判断依据。
|
||
- 酒店配置名称、客人消息、姓名、备注、邮件正文和附件内容保持原文。
|
||
- 日期、时间、数字和货币按当前语言、酒店时区和币种配置格式化。
|
||
- API 仍传递结构化原始值，不传本地化展示字符串作为业务参数。
|
||
|
||
## 8. 类型与业务代码
|
||
|
||
- TypeScript 类型应贴近后端 API 契约。
|
||
- 稳定业务代码使用 string union 或枚举型常量，避免散落 magic string。
|
||
- 动态操作参数使用稳定 `fieldKey`。
|
||
- 表单字段展示使用 `labelKey` 或 i18n key。
|
||
- 不用 `label`、中文标题或英文标题做字段标识。
|
||
- 接口字段变更时，同步更新 `src/types`、services、页面和测试。
|
||
|
||
## 9. UI 与交互规范
|
||
|
||
- UI 组件库使用 PrimeVue。
|
||
- 避免引入大型 Admin Template。
|
||
- 页面应优先表达业务主线，而不是堆叠技术字段。
|
||
- Debug 页面可以显示技术 ID，但业务页面应优先展示可理解的业务状态和来源摘要。
|
||
- 预检、人工复核、任务确认要清楚区分：
|
||
- 外部 Provider 建议
|
||
- 人工确认值
|
||
- 最终执行结果
|
||
- 邮件原文、附件详情和外部响应详情应通过受控详情接口读取，不默认塞进所有 Task 页面。
|
||
- 涉及客户信息、付款信息和附件时，应默认最小展示。
|
||
|
||
## 10. 前端安全规范
|
||
|
||
- `VITE_*` 变量会暴露到浏览器构建产物，不能保存 Secret。
|
||
- 前端不得保存数据库密码、OHIP 凭证、SuperAgent API Key、AgentBus Token、replay key。
|
||
- 不在 LocalStorage、SessionStorage 或 URL 中保存敏感业务数据。
|
||
- 错误提示不展示 Authorization、Cookie、Token、原始邮件全文或附件 URL。
|
||
- 测试夹具不得使用真实客人、真实酒店或真实支付信息。
|
||
|
||
## 11. 配置规范
|
||
|
||
常用公开配置：
|
||
|
||
```text
|
||
VITE_API_BASE_URL=http://localhost:8080
|
||
VITE_APP_ENV=local
|
||
VITE_DEFAULT_LOCALE=zh-CN
|
||
VITE_ENABLE_MOCKS=false
|
||
```
|
||
|
||
本地开发如需代理后端：
|
||
|
||
```text
|
||
VITE_API_PROXY_TARGET=http://127.0.0.1:8081
|
||
```
|
||
|
||
规则：
|
||
|
||
- 公开配置可以放 `VITE_*`。
|
||
- Secret 一律不进入 `VITE_*`。
|
||
- 生产需要运行时配置时，应由部署系统生成公开配置文件，例如 `/app-config.json`。
|
||
- 需要秘密的外部调用一律经后端代理或适配器。
|
||
|
||
## 12. 路由规范
|
||
|
||
- Vue Router 管理部门级路由。
|
||
- 新增业务路由前确认对应后端 API 和权限边界。
|
||
- 平台 Shell 只保留已确认部门入口，不硬编码未知流程。
|
||
- 详情页路由参数使用稳定 ID。
|
||
- 页面刷新后必须能通过后端详情接口恢复必要状态，不依赖内存临时状态。
|
||
|
||
## 13. 表单与人工确认规范
|
||
|
||
- 人工确认表单优先使用后端返回的字段契约。
|
||
- 保存草稿时使用稳定 `fieldKey`。
|
||
- 不把显示文案作为提交字段名。
|
||
- 表单应展示字段来源：Provider 建议、来源消息、人工修正、最终值。
|
||
- 提交前前端可做基础格式校验，但最终业务校验在后端。
|
||
- 发生版本冲突时，应提示用户刷新或重新确认，不静默覆盖。
|
||
|
||
## 14. Agent 前端开发 Skill 使用
|
||
|
||
当前项目后续如果由 Codex 或其他 agent 开发前端，涉及 UI、交互、视觉或浏览器验证时，应优先使用当前环境可用的前端相关 skill。Skill 只作为辅助，不能覆盖本项目 Vue、TypeScript、Vite、PrimeVue、Pinia、Vue Query、i18n、接口契约和安全边界。
|
||
|
||
当前项目建议：
|
||
|
||
- 新页面、复杂交互或业务页面信息架构：优先使用 `design-taste-frontend` 和 `ui-ux-pro-max`。
|
||
- 设计 token、组件规范和样式体系：优先使用 `design-system`。
|
||
- 已有页面视觉重构：优先使用 `redesign-existing-projects`。
|
||
- 根据截图、设计稿或视觉参考还原页面：优先使用 `image-to-code`。
|
||
- 浏览器验证、截图检查、点击路径和响应式检查：优先使用 `browser:control-in-app-browser`。
|
||
- 需要生成插图、图片或占位视觉资产：可使用 `imagegen`。
|
||
- `ui-styling` 可参考其可访问性、组件状态和样式组织原则，但本项目未确认使用 shadcn 或 Tailwind 前，不得因此引入 shadcn、Tailwind 或替换 PrimeVue。
|
||
- `superpowers:brainstorming`、`superpowers:writing-plans`、`superpowers:test-driven-development`、`superpowers:verification-before-completion` 用于需求澄清、计划、测试和验收，不属于 UI 框架选择依据。
|
||
|
||
交付要求：
|
||
|
||
- 涉及 UI 或交互变更时，应说明使用了哪些 skill，或说明为什么未使用。
|
||
- 涉及可视化结果时，应尽量提供浏览器截图、响应式检查或交互验证结果。
|
||
- 如果 skill 建议与本项目规范冲突，以本项目规范、接口契约和用户明确要求为准。
|
||
|
||
## 15. 测试与检查命令
|
||
|
||
前端最低检查：
|
||
|
||
```bash
|
||
cd client
|
||
pnpm lint
|
||
pnpm typecheck
|
||
pnpm test
|
||
pnpm build
|
||
```
|
||
|
||
`pnpm typecheck` 应执行 `vue-tsc --noEmit` 或等价命令，确保 `.vue` 单文件组件也被类型检查覆盖。
|
||
|
||
聚焦开发时可运行：
|
||
|
||
```bash
|
||
cd client
|
||
pnpm test -- SomeSpecName.spec.ts
|
||
```
|
||
|
||
如果命令尚未配置或因环境问题无法运行，必须明确说明，不能假装通过。
|
||
|
||
## 16. Git 与协作流程
|
||
|
||
- 改动前说明目标、范围和将修改的文件。
|
||
- 每次只处理一个模块、一个页面或一个纵向切片。
|
||
- 不修改与当前任务无关的用户变更。
|
||
- 前后端接口变化前，先确认 API 契约和字段映射。
|
||
- 修改后运行项目已配置的检查命令。
|
||
- Git commit message 使用中文，清楚说明本次提交的业务或技术变更。
|
||
|
||
## 17. 前端提交前检查清单
|
||
|
||
- [ ] 是否只调用本项目后端？
|
||
- [ ] 是否没有把 Secret 放入 `VITE_*`、源码、测试或 URL？
|
||
- [ ] 新文案是否已进入 i18n？
|
||
- [ ] 是否避免用中文或英文显示文本做业务判断？
|
||
- [ ] API 请求是否放在 `src/services`？
|
||
- [ ] 手写类型是否放在 `src/types`？
|
||
- [ ] 可复用逻辑是否放在 `src/composables`？
|
||
- [ ] 服务端数据是否使用 Vue Query，而不是长期塞进 Pinia？
|
||
- [ ] 是否没有手工修改 `src/generated`？
|
||
- [ ] 涉及 UI、交互或视觉变更时，是否使用或说明未使用合适的前端 / 设计 skill？
|
||
- [ ] 涉及可视化结果时，是否做过浏览器、截图或响应式验证？
|
||
- [ ] 是否运行了 `pnpm lint` 或说明了无法运行原因？
|
||
- [ ] 是否运行了 `pnpm typecheck` 或说明了无法运行原因？
|
||
- [ ] 是否运行了 `pnpm test` 或说明了无法运行原因？
|
||
- [ ] 是否运行了 `pnpm build` 或说明了无法运行原因？
|