整理项目文档索引和规范说明

docs/project/backend-development-guidelines.md

@@ -10,6 +10,8 @@
 模型或 Agent 能力提供方并消费其结构化结果；本项目不开发模型、Prompt 优化平台、Agent
 Runtime、Planner、Memory 或通用工具调用框架。
 
+当前项目时间存储、接口返回、酒店时区展示和本地业务日期边界统一参考 `docs/project/backend-time-design.md`。
+
 ## 2. 技术栈
 
 以 `server/pom.xml` 为准，当前后端技术栈如下：
@@ -209,6 +211,22 @@ groupCode
 - SQL 文件应使用中文行注释划分表、索引、约束等主要结构。
 - 注释必须说明业务含义、来源或代码值范围。
 - 禁止使用“字段1”“备用字段”等模糊注释。
+- 新建 MySQL 表必须显式指定存储引擎、字符集和排序规则，默认使用 `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin COMMENT='...'`。
+- 本项目字符串字段默认大小写敏感，包含用户名、展示名、邮件主题、菜单名称、状态筛选、外部 ID、哈希、Token、nonce、幂等键、业务代码等。这样可以避免 MySQL 默认大小写不敏感 collation 把 `X` 和 `x` 之类的外部 opaque id 误判为同一个值。
+- 已有表通过 `V13__make_existing_string_columns_case_sensitive.sql` 统一转为 `utf8mb4_bin`；后续新增表或新增字符串列不能重新退回默认 `*_ci` collation。
+- 如果某个功能确实需要大小写不敏感搜索，不应改变整表默认 collation，应在查询层使用规范化字段、搜索索引、`LOWER()`/归一化值或专门搜索方案实现，并在需求文档和 migration 注释中写明原因。
+- 新建表推荐模板：
+
+```sql
+CREATE TABLE example_table (
+    id BIGINT NOT NULL COMMENT '内部主键 ID',
+    external_id VARCHAR(256) NULL COMMENT '外部系统 ID，按大小写敏感保存和比较',
+    created_at DATETIME(6) NOT NULL COMMENT '记录创建 UTC 时间',
+    PRIMARY KEY (id),
+    KEY idx_example_external_id (external_id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin COMMENT='示例业务表';
+```
+
 - 业务时间点以 UTC 写入数据库，API 层负责返回带 `Z` 的 ISO 8601 UTC 时间，例如 `2026-07-08T03:00:00Z`。
 - 新增 API 响应 DTO 中的时间点字段优先使用 `OffsetDateTime`；从数据库 `LocalDateTime` 快照输出到接口时，应通过 `UtcTimeFormatter` 转换，禁止直接把无时区 `LocalDateTime` 暴露给前端或 SuperAgent。
 - 酒店本地业务日期，例如入住日期、离店日期、营业日，优先使用 `LocalDate` 或明确酒店时区语义的字段，不和 UTC 时间点混用。