# Rule 配置脚本目录

本目录存放全模块规则配置相关 SQL 草案。

当前文件：

- `01_ado_rule_config.sql`：全模块规则配置表草案，包含 `ado_rule_profile`、`ado_rule_item`、`ado_rule_schema`，以及 S3 / `DELIVERY_GENERATE` 默认规则种子。
- `02_enable_rule_repository_checklist.md`：数据库规则仓储启用前检查与开关方案。

## 注意

- 当前 SQL 已在 `aidopdev` 研发库执行并验证；预发/生产执行前仍需确认表命名、主键策略、权限、审计字段、版本策略和初始化 ID 段。
- 规则配置只承载参数、阈值、名单、策略枚举和开关，不承载 SQL、事务顺序、写表目标或 Service 调用链。
- S3 试点为保持 P5 现有行为，`enableExternalPushTracking` 草案默认开启；后续正式生产配置仍需结合外部系统消费机制确认。
- P26 已新增后端实体和 `DbRuleConfigRepository` 草案。
- P27 的 `RuleConfig:RepositoryMode=Empty|Db` 开关方案保留为预发/生产启用参考。
- P28 研发阶段已直接启用 `DbRuleConfigRepository`，因此研发库需要执行 DDL 和默认种子；缺表或字段不一致会直接暴露错误。
- P29 已在 `user-mysql-aidopdev` 默认库 `aidopdev` 执行 DDL 和 S3 默认种子，并验证 Profile 1 条、Schema 10 条、Item 10 条。

## 建议启用顺序

1. 研发库已完成 `01_ado_rule_config.sql` DDL、默认种子和读取验证。
2. 研发阶段已直接启用 `DbRuleConfigRepository`，并完成 S3 规则读取、覆盖、前端编辑和保存恢复验证。
3. 预发/生产启用前，按 `02_enable_rule_repository_checklist.md` 补充仓储开关、缺表保护、权限和回退策略。
4. 正式上线前需结合真实业务验收，确认 `enableExternalPushTracking` 等高风险开关的默认值。

## 研发库执行记录

- **环境**：`user-mysql-aidopdev` / `aidopdev`
- **执行内容**：`ado_rule_profile`、`ado_rule_item`、`ado_rule_schema` DDL 与 S3 / `DELIVERY_GENERATE` 默认种子。
- **验证结果**：Profile 1 条、Schema 10 条、Item 10 条；仓储查询可返回 10 条生效规则项。
- **执行提示**：P32 已将 `ON DUPLICATE KEY UPDATE ... VALUES(col)` 调整为 `AS new` 别名写法，研发库重跑无弃用警告。

## 最小生成验证记录

- **接口**：`POST /api/Supply/delivery-schedule/generate`
- **结果**：`demandCount=1`、`createdCount=0`、`skippedCount=1`、`qadTrackingCount=0`
- **规则快照**：`RuleSnapshot.Source=configured`，`AppliedItems=10`
- **操作日志**：`SysLogOp.Id=805860787408965`
- **说明**：本次需求已有关联交货单，因此没有新增业务单据，仅验证 DB 规则读取和操作日志快照链路。

## 规则覆盖验证记录

- **临时修改**：`ado_rule_item.defaultLeadDays` 从 `1` 改为 `2`
- **接口**：`POST /api/Supply/delivery-schedule/generate`
- **验证结果**：`RuleSnapshot.Options.DefaultLeadDays=2`，`AppliedItems` 对应 `RuleValue=2`
- **操作日志**：`SysLogOp.Id=805862349242437`
- **恢复结果**：已将 `ado_rule_item.defaultLeadDays` 恢复为 `1`
- **说明**：匿名接口下 `TenantId=0`，本轮用全局规则临时覆盖验证，不保留额外租户级测试 Profile。

## SQL 幂等重跑记录

- **调整内容**：三段种子 SQL 改为 `AS new` 行别名写法，替代 `VALUES(col)`。
- **补充内容**：`ado_rule_schema` 种子显式写入 `is_enabled=1`。
- **验证环境**：`user-mysql-aidopdev` / `aidopdev`
- **验证结果**：Profile、Schema、Item 三段种子 SQL 重跑成功，`Warnings=0`；默认数据计数保持 1/10/10。

## 只读查询接口

- **接口**：`GET /api/RuleConfig/effective-options`
- **默认参数**：`moduleCode=S3`、`scenarioCode=DELIVERY_GENERATE`
- **可选参数**：`tenantId`、`factoryId`
- **返回内容**：当前生效 `RuleSnapshot`，包含最终 Options 和 AppliedItems。
- **说明**：接口只读，不修改 `ado_rule_*`，也不触发 S3 生成。

## 前端只读入口

- **页面**：S3 / 物料交货计划。
- **按钮**：`查看当前规则`，位于“生成交货单”旁。
- **展示内容**：规则来源、模块/场景、解析时间、租户/工厂、关键 S3 Options、生效配置项数量和 Warnings。
- **说明**：只做业务可读摘要展示，不编辑配置、不保存规则、不触发 S3 生成。

## 研发阶段编辑入口

- **接口**：`POST /api/RuleConfig/s3-delivery-generate/save`
- **页面**：S3 / 物料交货计划，按钮为 `编辑当前规则`。
- **保存范围**：S3 / `DELIVERY_GENERATE` 全局默认 Profile 下的既有规则项。
- **更新方式**：直接更新 `ado_rule_item.rule_value`，保存后返回最新 `RuleSnapshot`。
- **边界**：不新增 Profile/Schema，不做版本发布、审批、回滚和多模块通用编辑器。

## 保存闭环验证记录

- **验证项**：`defaultLeadDays`
- **临时保存**：`1` -> `2`
- **验证结果**：保存接口返回 `RuleSnapshot.Options.DefaultLeadDays=2`，查询接口和数据库均确认 `rule_value=2`。
- **恢复结果**：已通过保存接口恢复为 `1`，查询接口和数据库均确认恢复。
- **说明**：验证过程未触发 S3 生成，不新增业务单据或外部事务。

## 当前边界

- S3 研发试点规则链路已完成：DDL、种子、仓储读取、生成规则快照、只读接口、前端查看、前端编辑、保存恢复验证。
- 多模块规则配置推广暂不真实开发，仅作为后续方向；推广前需先确认公共页面、权限、版本发布、回滚和首个模块试点。
- 当前任务流仅停留在执行日志和异常入口层面的闭环雏形；通用任务流能力另行立项。

## 执行前检查清单

- [ ] **表命名**：确认 `ado_rule_profile`、`ado_rule_item`、`ado_rule_schema` 是否符合全模块命名约定。
- [ ] **主键策略**：确认使用手工固定 ID、雪花 ID，还是数据库自增；当前草案使用固定 ID。
- [ ] **ID 段**：确认 `1003000000001` 等 S3 默认种子 ID 不与其它种子冲突。
- [ ] **租户/工厂覆盖**：确认 `tenant_id = 0`、`factory_id = 0` 的全局/租户级语义符合现有多租户模型。
- [ ] **唯一约束**：确认 `profile_code + tenant_id + factory_id + version` 与 `profile_id + rule_code` 能满足后续版本管理。
- [ ] **审计字段**：确认是否需要统一使用项目已有 `CreateTime/CreateUserId` 风格，或保留 `created_at/created_by`。
- [ ] **软删除**：确认是否需要 `is_deleted` 字段；当前草案只使用 `is_enabled`。
- [ ] **外键策略**：确认是否添加外键；当前草案不加物理外键，避免跨模块迁移耦合。
- [ ] **高风险默认值**：确认 S3 试点 `enableExternalPushTracking=true` 是否仅用于保持现有 P5 行为，生产正式配置是否需要改为默认关闭。
- [ ] **权限菜单**：确认后续规则配置页面归属菜单和权限编码。
- [ ] **缓存策略**：确认后续只读服务是否采用 30-60 秒 TTL 缓存。
- [ ] **回滚策略**：确认执行 SQL 前是否需要备份同名对象或提供 drop 脚本。

## 暂不执行原因

- 当前仅完成 S3 规则试点设计，S4/S8/S9 的规则场景尚未统一评审。
- 表属于全模块基础设施，需先确认命名、审计字段、权限和版本策略。
- 高风险开关会影响外部事务写入，需要结合 P8 受控验证。
- 后端数据库仓储仍为未启用草案，配置页面尚未实现，提前建表价值有限。