quwuting-service

Imported from JamesSmith888/quwuting-service (AGENTS.md). Install upstream with npx skills add JamesSmith888/quwuting-service. Copyright stays with the author.

AGENTS.md — quwuting-service（后端）

⚠️ 本文件是主题索引（渐进式披露顶层），不是详细文档库。 详细设计一律按主题拆分在 docs/agents/ 下，本文件只放项目定位、最小事实与索引表。 任何 Agent 修改本文件前，必须先读文末「⚠️ 维护规则」。

项目定位

Spring Boot 4.1 + Java 25 + Spring Data JPA 后端服务，为去舞厅小程序提供舞厅信息查询 REST API（黄页数据展示，无交易/支付逻辑）。连接 Supabase Postgres（外部不稳定环境，韧性为第一优先级）。

最小事实（新 Agent 必读）

• 构建/运行：./mvnw clean compile；./mvnw test -Dspring.profiles.active=dev（连库并验证 SchemaIntegrityChecker）；./mvnw clean package -DskipTests；./mvnw spring-boot:run -Dspring-boot.run.profiles=dev
• HTTP 语义：只允许 GET 和 POST（禁 PUT/PATCH/DELETE）；统一 ApiResponse<T>——业务错 = 200+code、未登录 = 401、404 不存在、DB 瞬时 = 503+5003、未预期 = 500+5000；兜底异常禁以 200 伪装
• Schema 演进唯一通道 = Flyway 迁移（db/migration/V{n}__*.sql），ddl-auto=validate；新 NOT NULL 列唯一通道 = @ColumnDefault；枚举类列禁 CHECK（扩枚举免迁移）
• 连接池韧性（Supabase 不稳定）：6543 JDBC URL 必含 prepareThreshold=0&connectTimeout=5&socketTimeout=8&tcpKeepAlive=true；连接池参数唯一事实源 = application.yaml（禁环境 yaml 重复声明）
• 性能第一约束 = 最少 DB 往返（跨洲 371ms/次）：列表/详情公共数据必须缓存、个人态永不缓存、写路径显式失效——详见 29-performance.md
• 技术债：生产 systemd 跑 dev profile（application-dev.yaml 生效），切 prod 需先补 systemd 环境变量注入
• 命名：表 qwt_ 前缀；根包 org.quwuting.quwutingservice

主题索引（渐进式披露）

需要细节时按主题查阅对应文档；禁止把细节写回本文件。

⚠️ 维护规则（强制：渐进式披露）

本文件曾膨胀至 2200+ 行（教训），现重构为索引。所有 Agent（含未来的 AI 代理）更新本文件时必须遵守：

1. 本文件只承载索引与轻量描述：项目定位、最小事实速查、主题索引表。任何详细设计、迭代历史、根因分析、代码示例一律写入对应主题文档（docs/agents/ 下），本文件只保留「链接 + 一行摘要」。
2. 新增/修改细节 → 先定位主题文档：按索引表找到对应文档，细节写进文档；同步更新索引表摘要（保持一行）。
3. 新主题 → 新建文档并登记：无现成文档承载的新主题，在 docs/agents/ 下新建 NN-主题.md（序号延续），复制现有文档头部模板（含维护警告），并在索引表登记一行。
4. 文档膨胀 → 拆分子文档：单个 docs/agents/ 文档超过 ~300 行时，拆出独立子主题文档，索引表同步。
5. 禁止把历史演进堆进索引：每轮迭代的「决策过程/踩坑复盘」只允许进主题文档，且尽量压缩为可复用的规则沉淀，不留流水账。
6. 写完后自查：本文件应保持在 ~100 行以内；索引表每个主题恰好一行；改动前先读对应主题文档，避免重复/冲突。