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

docs/import/reusable/backend-development-guidelines.md

@@ -99,6 +99,21 @@ server/src/main/java/<base_package>
 - 表、字段、索引和约束命名应清晰表达业务含义。
 - 业务表建议包含创建时间、更新时间、创建人、更新人、逻辑删除和版本字段。
 - 需要查询、排序、唯一性或关联的字段必须有明确索引策略。
+- 新项目建表前必须确认数据库字符集和 collation 策略，不能依赖数据库实例默认值。
+- MySQL 项目建议新建表显式使用 `ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin COMMENT='...'`，让字符串默认按大小写敏感保存和比较。
+- 外部 opaque id、第三方消息 ID、哈希、Token、nonce、幂等键、状态码和业务代码必须大小写敏感；否则容易出现 `X` 与 `x` 被误认为同一值的幂等或唯一键问题。
+- 如果业务需要大小写不敏感搜索，应通过查询层归一化、搜索字段、专门索引或搜索引擎实现，并在项目规范和 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)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin COMMENT='示例业务表';
+```
+
 - 测试数据、真实业务数据和本地样本不得直接提交到仓库。
 
 ## 7. API 设计规范

docs/import/reusable/general-development-guidelines.md

@@ -85,6 +85,7 @@
 - Service 编排业务流程、事务、领域对象、Repository 和外部端口。
 - 外部系统通过 Port / Adapter 隔离，业务层不直接依赖厂商 SDK 或外部 DTO。
 - 数据库变更必须可追踪；已发布 migration 不直接修改。
+- 新项目建表前必须明确数据库字符集和 collation 策略；MySQL 项目默认建议使用 `utf8mb4_bin`，避免外部 ID、Token、哈希、状态码或业务代码因大小写不敏感而误判。
 - 写接口要考虑幂等、并发版本、审计、失败恢复和脱敏。
 
 Java 后端代码默认参考 Alibaba Java Coding Guidelines。可复用摘要见 `docs/import/reusable/alibaba-java-coding-guidelines-summary.md`。