baiyue-firstleg/audit-service/AGENTS.md

Audit Service 模块指引

职责边界

• 负责接收 common-audit 产生的审计事件并持久化到 baiyue_audit。
• 审计注解、切面、脱敏和发送策略在 common-audit/；本服务不复制业务服务的审计采集逻辑。

快速索引

功能	入口
应用入口	src/main/java/com/baiyue/audit/BaiyueAuditApplication.java
内部接收 API	controller/AuditIngestController.java（/internal/audit/events）
接收 DTO	dto/AuditIngestRequest.java
入库编排	service/AuditIngestService.java
持久化	entity/AuditLogEntity.java、mapper/AuditLogMapper.java、repository/AuditEventRepository.java
表结构	src/main/resources/db/audit.sql
本地/Nacos 配置	src/main/resources/application.yml、../config/nacos/{local,cn}/audit-service.yml

修改与验证

• 当前接收接口尚未实现内部令牌保护，仅适合受控本地/内网联调；部署到共享或生产环境前必须补齐可信服务身份校验，且不对前端开放。
• POST /internal/audit/events 成功接收保留真实 HTTP 202；请求进入 common-web 异常处理后的业务/校验失败遵循 HTTP 200 + body code。不要把 202 改成普通 200，也不要把业务失败重新改成 HTTP 4xx/5xx。
• common-web/CommonWebAutoConfiguration 负责在本服务仅扫描 com.baiyue.audit 时注册统一异常处理和 Correlation 过滤器；相关改动需连同本模块做启动/上下文验证。
• 入库前确保密码、Token、证件等敏感信息已脱敏；新增字段时同步检查 ../common-audit/src/main/java/com/baiyue/common/audit/AuditEvent.java 与发送实现。
• 审计链路故障不得阻塞核心交易；保留幂等、超时、容量和留存策略的演进空间。
• 当前没有专属自动化测试；从父目录运行 mvn -pl audit-service -am test，并按改动验证接收和持久化结果。