frontend-backend-alignment

前后端对齐规范 Skill

解决"代码 / 文档 / 版本 / API 字段四处对齐"难题。前端 Flutter + 后端 NestJS + 文档 Markdown 三者必须一致，本 skill 列举强约束 + 自检清单。

1. API 字段对齐：Freezed Model ↔ Prisma Schema

强约束：前端 lib/data/models/<resource>_model.dart 的 Freezed 字段 + 后端 server/prisma/schema.prisma 的 model 字段，一对一对齐。

后端 Prisma	前端 Freezed	说明
id String @id @default(uuid())	required String id	主键
hotelId String @map("hotel_id")	required String hotelId	DB snake_case，TS/Dart camelCase
title String	required String title
description String?	String? description	nullable 一致
tags String[] (Postgres) / String @db.Text(MySQL JSON)	@Default(<>) List<String> tags	数组字段两端类型对齐
createdAt DateTime	required DateTime createdAt	ISO 8601 字符串 ↔ DateTime
metadata Json?	Map<String, dynamic>? metadata	JSON 字段

自检脚本：scripts/check_api_alignment.sh（建议每次 schema 改动后跑）：

#!/usr/bin/env bash
# 1. 列 Prisma model 字段
echo "=== Prisma <Model> 字段 ==="
sed -n '/^model <Model> /,/^}/p' server/prisma/schema.prisma

# 2. 列 Freezed model 字段
echo "=== Freezed <Resource>Model 字段 ==="
grep -E "required|@Default|String\?|int\?|bool\?" lib/data/models/<resource>_model.dart

肉眼比对 → 字段名 / nullable / 类型 三者必须一致。

2. API 契约改动 → 文档同步铁律

每个 API 改动 → 同时更新三个地方：

1. 后端代码：
   server/src/modules/<feature>/dto/<feature>.dto.ts          # DTO 类
   server/src/modules/<feature>/<feature>.controller.ts       # @Post / @Get 端点
   server/src/modules/<feature>/<feature>.service.ts          # 业务逻辑

2. 前端代码：
   lib/data/services/<feature>_api_service.dart               # API 调用
   lib/data/models/<feature>_model.dart                       # Freezed 数据类

3. 文档（强约束）：
   docs/api_contracts/<feature>.md                             # API 契约（请求/响应 JSON 示例）
   docs/backend_spec.md                                        # 后端架构总览（如新增端点段落）
   docs/cards/<tool>.md                                        # 前端工具卡片（5 章节）

强约束：

• ★ 改了代码 → 打开文档 → 检查是否一致 → 不一致立即更新
• ★ 文档过时比没文档更危险
• ★ 当前状态 / 实现 / 口径必须与源码一致，禁止历史结论冒充现状
• ★ 旧审计 / 旧验收文档失效后立即删除或标注"历史归档、不可作为当前依据"