th-hotel-simple/docs/project/frontend-development-guidelines.md

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. 目录约定

当前前端目录：

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. 国际化规范

首期交付：

zh-CN
en-US

架构预留：

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. 配置规范

常用公开配置：

VITE_API_BASE_URL=http://localhost:8080
VITE_APP_ENV=local
VITE_DEFAULT_LOCALE=zh-CN
VITE_ENABLE_MOCKS=false

本地开发如需代理后端：

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. 测试与检查命令

前端最低检查：

cd client
pnpm lint
pnpm typecheck
pnpm test
pnpm build

pnpm typecheck 应执行 vue-tsc --noEmit 或等价命令，确保 .vue 单文件组件也被类型检查覆盖。

聚焦开发时可运行：

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 或说明了无法运行原因？