Imported from dztyykxx/auction (AGENTS.md). Install upstream with npx skills add dztyykxx/auction. Copyright stays with the author.

AGENTS.md

全局语言偏好

默认使用中文与用户沟通、编写说明文档、提交总结和审查意见。
代码标识符、框架名、协议名、文件格式、命令参数等保留英文技术标识。
除非用户明确要求英文，否则项目文档、注释说明、测试说明和任务记录均使用中文。

项目背景

本项目是“抖音电商 AI 全栈挑战赛”的直播竞拍全栈系统，MVP 主线为：

实时竞拍。
AI 定价建议。
AI 拍卖主持。
图片/文字形式模拟直播间。
主播 PC 管理端 + 用户 H5 竞拍端。

项目重点不是堆功能，而是体现：

竞拍链路闭环。
高并发出价一致性。
WebSocket 实时同步。
AI 工具和 AI 业务能力落地。
清晰的设计思路、文档沉淀和可演示结果。

文档目录规范

项目文档统一放在 docs 下，按主题分目录维护：

docs
  00-项目资料
  01-需求
  02-总体架构
  03-后端设计
  04-前端设计
  05-AI设计
  06-测试压测
  07-答辩材料
  官方资料

新增文档优先放入对应子目录，不要继续堆在 docs 根目录。

稳定文档使用版本号，例如：

后端设计-v0.1.md
系统架构设计-v0.1.md
AI主持设计-v0.1.md

开发方法

本项目采用“文档驱动开发 + TDD 开发”。

每次开发只取一个小任务，任务粒度要足够小，能够在一次开发循环中完成设计、测试、实现和审查。

标准流程：

选择一个小任务。
开发前生成该任务的任务文档，说明目标、范围、接口、数据结构、边界条件和验收标准。
开发前生成测试用例设计，先明确单元测试、集成测试和必要的并发测试。
编写或补齐失败测试。
实现代码。
运行测试并确保通过。
开发者自查，修复明显问题。
独立审查 agent 审查代码、测试和文档。
审查通过后再提交。

禁止在没有任务文档和测试用例设计的情况下直接进入复杂功能开发。

Agent 协作规范

Codex 负责方案设计、任务拆解、文档生成、架构审查和代码审查。
cc + deepseelv4pro 负责代码实现、测试编写、测试执行和开发者自查。
任务生成和任务审查必须视为两个独立 agent 的职责，不能用同一个视角既生成又放行。
审查重点包括：需求是否满足、测试是否覆盖、关键逻辑是否可解释、并发一致性是否可靠、日志是否足够定位问题。
审查未通过时，必须先修复问题，再重新测试和审查。
审查通过后才能提交。

如果多个任务之间互不影响、文件写入范围清晰且可以并行开发，应使用 git worktree 为每个任务创建独立工作区，避免互相污染。

并行任务要求：

每个 worktree 只处理一个小任务。
每个任务要有独立任务文档和测试用例设计。
不同任务尽量避免修改同一批文件。
合并前必须分别测试和审查。

Git 与提交规范

不要回滚他人或其他 agent 的改动，除非用户明确要求。
不要使用 git reset --hard、git checkout -- 等破坏性命令，除非用户明确要求。
每次提交只包含一个小任务的相关修改。
提交前必须确认测试通过、审查通过、文档同步更新。
提交信息应简洁说明业务目的，例如：

feat: 实现竞拍出价幂等校验
test: 补充竞拍状态机单元测试
docs: 新增 AI 主持设计文档

复杂功能、审查修复、线上 bug 修复或跨前后端改动的提交信息不能只写一行。提交信息应使用“简洁标题 + 分块正文”的格式，正文按需说明任务范围、核心实现、修复点、风险控制和测试验证。

推荐格式：

fix: 限制支付订单可见性并主动刷新

直播间订单可见性修复：
- 订单详情和按竞拍查询改为当前买家专属，非买家返回 ORDER_NOT_YOURS
- 避免同房间其他用户按 auction_id 看到支付订单和支付入口

前端主动刷新：
- SOLD 快照和 auction.sold 事件只在当前用户为赢家时拉取订单
- 对异步落库订单查询增加短重试，避免刷新直播间后才出现支付入口

测试：
- OrderControllerTest 新增非买家按竞拍 ID / 订单 ID 查询订单的权限断言
- mvn test
- npm run build

提交正文要求：

使用中文说明业务目的和用户可见影响。
分块标题可按任务实际情况使用，例如“核心实现”“审查修复”“Bug 修复”“前端主动刷新”“测试”。
测试块必须列出实际执行过的命令或测试类；如果未执行测试，必须说明原因。
提交内容应只包含本次任务相关文件，不要把无关生成物、缓存文件或其他 agent 的改动混入提交。

接口字段规范

前后端交互字段统一使用下划线风格，即 snake_case。

适用范围：

REST API 请求体。
REST API 响应体。
WebSocket 消息字段。
错误响应字段。
前后端共享接口文档。

示例：

{
  "auction_id": 10001,
  "current_price": 12800,
  "leader_user_id": 20001,
  "request_id": "client-generated-uuid"
}

Java 内部实体、DTO 字段可以使用 camelCase，但必须通过 Jackson 命名策略或明确注解保证对外 JSON 为 snake_case。

数据库表名和字段名统一使用 snake_case。

后端技术规范

基础技术栈

JDK 17。
Spring Boot 3.x。
Spring Cloud Gateway。
MySQL 8.x。
Redis 7.x。
Sa-Token 作为用户认证与权限校验方案。
MyBatis-Plus 作为 ORM/数据访问方案。
Lombok 简化样板代码。

本地开发中间件

本项目本地开发的 MySQL、Redis 等中间件默认运行在 Docker 容器中，通过宿主机端口映射访问。

本地连接信息如下：

MySQL:
  host: localhost
  port: 13306
  username: root
  password: 123456

Redis:
  host: localhost
  port: 16379
  database: 6

注意：

运行后端服务或测试前，先确认对应 Docker 容器已启动并完成端口映射。
Redis 不要使用默认数据库 0，该数据库已被其他程序使用。
上述账号密码仅用于本地开发环境，不要作为生产环境配置。
配置文件中如需保留默认值，应允许通过环境变量覆盖。

Maven 环境

本机 Maven 使用 IntelliJ IDEA 2025.2.2 自带的 3.9.11 版本。

Maven 路径已在 ~/.bashrc 中配置：

export PATH="/c/Program Files/JetBrains/IntelliJ IDEA 2025.2.2/plugins/maven/lib/maven3/bin:$PATH"

新终端中如果 mvn 不可用，先执行 source ~/.bashrc。

在 Codex 的 Windows PowerShell 环境中，不要直接执行 mvn test，也不要手工绕过 mvn.cmd 用 Java 启 Maven；这可能导致找不到 Maven 或触发 Windows socket 异常。应通过 Git Bash 加载 ~/.bashrc 后执行，例如：

& 'C:\Program Files\Git\bin\bash.exe' -lc 'source ~/.bashrc && cd /e/vibe\ coding/字节比赛/backend && mvn test'

已验证该方式会使用 IntelliJ IDEA 自带 Maven 3.9.11，并可正常跑通后端测试。

本地 Maven 仓库路径：C:\Users\Admin\.m2\repository，配置文件：C:\Users\Admin\.m2\settings.xml。

代码结构

后端优先采用 Maven 多模块组织，保持微服务边界清晰。

推荐模块：

auction-platform
  auction-common
  auction-gateway
  user-service
  auction-service
  bidding-service
  realtime-service
  ai-service
  order-service

第一版可以按实际开发成本合并服务进程，但包结构和职责边界要尽量保持清楚。

权限与用户

使用 Sa-Token 做登录态、用户身份和权限校验。
用户 ID、主播 ID 等身份信息以后端登录上下文为准，不信任前端传入。
主播接口必须校验主播身份和资源归属。
用户竞拍接口必须校验登录态。

MyBatis-Plus 与 SQL

常规 CRUD 优先使用 MyBatis-Plus。
SQL 语句尽量通过 Java 代码、Wrapper、注解方式编写。
复杂 SQL 需要说明原因，避免隐藏业务逻辑。
禁止把关键业务规则散落在难以测试的 SQL 字符串中。

数据库建表 SQL

每一次数据库表定义或变更，都必须以 SQL 文件形式保存。

推荐路径：

src/main/resources/db/schema
src/main/resources/db/migration

如果是多服务模块，则放在对应服务的 src/main/resources/db 子目录下。

SQL 文件命名建议：

V001__create_product_table.sql
V002__create_auction_table.sql
V003__create_bid_table.sql

数据库表和字段必须添加注释，说明业务含义。

示例：

CREATE TABLE auction (
  id BIGINT NOT NULL COMMENT '竞拍ID',
  product_id BIGINT NOT NULL COMMENT '商品ID',
  status VARCHAR(32) NOT NULL COMMENT '竞拍状态：DRAFT/RUNNING/SOLD/CANCELLED',
  PRIMARY KEY (id)
) COMMENT='竞拍场次表';

注释规范

关键逻辑必须写注释说明流程和实现方案理由。

必须写注释的场景：

出价校验。
Redis Lua 原子更新。
幂等控制。
竞拍状态机流转。
自动延时。
封顶成交。
断线重连恢复。
AI 主持兜底。
数据一致性补偿。

注释不是复述代码，而是解释“为什么这样做”和“这个流程如何保证正确性”。

日志规范

关键逻辑必须有日志，日志用于可观测性和错误定位。

建议使用 Lombok：

@Slf4j

必须记录日志的场景：

竞拍创建、开始、取消、成交、流拍。
出价成功。
出价失败及失败原因。
幂等重复请求。
自动延时触发。
封顶成交触发。
Redis Lua 执行异常。
WebSocket 连接、断开、重连。
AI 调用开始、成功、失败、兜底。

日志字段建议包含：

trace_id, user_id, auction_id, request_id, event, result_code, cost_ms

不要在日志中打印 API Key、Token、密码等敏感信息。

后端测试规范

后端开发必须优先写测试。

至少覆盖：

状态机单元测试。
出价金额校验测试。
幂等测试。
自动延时测试。
封顶成交测试。
主播取消竞拍后出价失败测试。
Redis 出价原子逻辑测试。
WebSocket 事件格式测试。
AI 输出解析与兜底测试。

并发关键逻辑必须设计并发测试或集成测试，不能只靠手工验证。

前端技术规范

前端使用：

React。
TypeScript。
WebSocket。
组件化开发。
清晰的状态管理。

前端页面：

主播端为 PC 管理后台。
用户端为 H5 风格页面，可以先在电脑浏览器移动端模拟器中开发。

前端要求：

组件职责清晰，避免大组件堆积所有逻辑。
前端页面实现时必须合理拆分组件、类型、示例数据和工具函数；单个页面文件不应长期承载大量互不相干的 UI 区块，发现页面组件开始膨胀时应优先拆到同目录组件或 feature 目录，方便后续维护和替换接口数据。
API 类型集中管理。
WebSocket 消息类型集中定义。
前后端交互字段保持 snake_case。
页面状态以服务端快照和 WebSocket 事件为准，不在前端自行推断竞拍终态。
出价按钮、倒计时、排行榜、AI 主持消息等核心交互要有明确 loading、失败和重连状态。

前端验收协作约定

为节省 token 和本地调试成本，Codex/Claude 在实现前端 UI 时默认不主动启动浏览器、截图或进行视觉效果审查；浏览器实际观感由用户自行检查。
前端代码变更仍应优先运行轻量命令验证，例如 npm run build、相关单元测试或类型检查；如果未运行，需要在总结中说明原因。
只有当用户明确要求“帮我看浏览器效果”“截图验证”“调试页面交互”或类似表述时，agent 才执行浏览器级视觉/交互验证。

可观测性优先级

本项目评分关注系统可用性、性能和可观测性。开发时不要把日志、错误码、测试和压测留到最后。

第一版至少做到：

统一错误码。
关键链路日志。
出价耗时记录。
WebSocket 在线人数记录。
AI 调用耗时记录。
基础压测结果可复现。

当前核心文档

docs/README.md
docs/01-需求/需求文档-MVP.md
docs/01-需求/加分项评估.md
docs/03-后端设计/后端设计-v0.1.md
docs/07-答辩材料/技术特性对标评估-v0.1.md
docs/08-开发任务/非紧急任务清单-v0.1.md

开发前应先阅读相关文档，再开始任务拆解。

auction

About