ouyangxq
19745e46c1
18 个服务与公共模块重复复制的 314 字符数据库访问约束改为指向后端根唯一定义，并给索引门禁增加防退化校验。 - 18 处重复段落合并为一句指针，规则正文只在后端根 AGENTS.md 维护 - 门禁新增路由表行宽上限（根/Admin/Client/后端根/海外 PDA），防止业务规则重新回流表格 - 同步包含此前未提交的链接与锚点、表格存在性校验 - 仅索引文档与门禁脚本，未改动业务代码
2.8 KiB
2.8 KiB
Audit Service 模块指引
数据库访问与中文注释约束
- 强制继承
../AGENTS.md的“数据库访问与中文代码注释”全部规则；该节是分层、SQL 执行和方法/核心逻辑中文注释的唯一维护处，本模块不另设例外。
职责边界
- Mapper 只由
BaiyueAuditApplication.java对com.baiyue.audit根包按@Mapper过滤扫描；新增或移动 Mapper 后从后端根运行node scripts/mapper-scan-contract.mjs，不得增加子域扫描配置。 - 负责接收
common-audit产生的审计事件并持久化到baiyue_audit。 - 审计注解、切面、脱敏和发送策略在
common-audit/；本服务不复制业务服务的审计采集逻辑。
快速索引
| 功能 | 入口 |
|---|---|
| 应用入口 | src/main/java/com/baiyue/audit/BaiyueAuditApplication.java |
| 内部接收 API | controller/AuditIngestController.java（/internal/audit/events） |
| 平台日志查询 API | controller/PlatformAuditLogController.java（/api/platform/v1/audit/logs）、service/AuditLogQueryService.java；列表与详情统一使用 platform:audit:list |
| 接收 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/test/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与发送实现。 - 平台日志列表不得返回变更前后快照，详情才返回已脱敏 JSON；客户账号不得访问平台查询接口。
- 审计链路故障不得阻塞核心交易；保留幂等、超时、容量和留存策略的演进空间。
- 自动化测试位于
src/test/java/com/baiyue/audit/，覆盖平台日志查询、Controller 权限、MQ 接收/死信和持久化；从父目录运行mvn -pl audit-service -am test，并按改动验证接收和持久化结果。