feat(rest): treatAsHistorical import option — skip the state machine for historical-data migration (#3479)#3483
Merged
Conversation
…for historical-data migration (#3479) Sibling of #3433 (seed exemption), one entry point over. #3165's `initialStates` enforced the FSM entry point on every INSERT, so importing established historical facts — already-`closed` tickets, `closed_won` deals, `completed` projects — was rejected row-by-row with `invalid_initial_state`, blocking the core data-migration path. Visible (per-row errors), unlike the silent seed case, but still a functional block on a legitimate use. - spec: `ExecutionContext.skipStateMachine` — general server-set flag (seedReplay's sibling) skipping the `state_machine` rule for a write; `ImportRequestSchema. treatAsHistorical` (default false) — the user-facing import option. - objectql: engine skips the state machine for `seedReplay` OR `skipStateMachine` (one `shouldSkipStateMachine` helper) — covers seed replay and historical import. - rest: the import runner sets `skipStateMachine` on the write context iff the request opts into `treatAsHistorical`; default off, so a normal import still walks the FSM. Import undo also carries it now (restoring a prior snapshot re-writes an earlier state that need not be a legal transition from the current one). - platform-objects: `sys_import_job.treat_as_historical` audit column (additive). Scope identical to the seed exemption: ONLY the `state_machine` rule is skipped; field shape / format / cross_field / script all still run. Regression tests (red-verified): engine.test — a `skipStateMachine` context bypasses the FSM (sibling of the seedReplay case); import-runner-historical — the option maps to `skipStateMachine` on the write context, gated (off by default), automation toggle independent. The objectui import-wizard checkbox is a separate follow-up. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
📓 Docs Drift CheckThis PR changes 4 package(s): 108 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
github-actions
Bot
added
documentation
This was referenced Jul 25, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #3479. #3433(种子豁免)的同构缺口,换了一个入口。
问题
#3165 的
initialStates在每次 INSERT 强制 FSM 入口,所以导入历史既成事实(一批已closed的工单、closed_won的商机、completed的项目)会被逐行invalid_initial_state拒,挡住数据迁移这个核心场景。与种子不同它可见(per-row 报错),但仍功能性挡住合法用途。方案(用户开关,默认关 —— 不照抄种子一刀切)
导入意图二义:历史迁移该豁免,批量新建该走 FSM。所以加一个显式开关,默认走 FSM。引擎豁免管道已由 #3433 备好,本 PR 只接线。
ExecutionContext.skipStateMachine(通用 server-set 旗标,seedReplay 的姊妹)+ImportRequestSchema.treatAsHistorical(默认 false,用户面选项)seedReplay || skipStateMachine都跳 state_machine(一个shouldSkipStateMachinehelper),覆盖种子重放 + 历史导入treatAsHistorical时往 writeCtx 塞skipStateMachine;默认关(正常导入仍走 FSM,严格是默认)。undo 也带上(恢复旧快照会重写一个非法 transition 的旧态)sys_import_job.treat_as_historical审计列(加性)prepareImportRequest的输出经...preparedspread 自动流入同步 + 异步 job worker 两条 runImport 路径,零额外接线。语义范围
与种子豁免完全一致:只跳
state_machine规则;字段 shape / format / cross_field / script 照跑。测试(均已验红)
skipStateMachine上下文豁免 FSM(seedReplay 的姊妹用例)。端到端由引擎豁免 + import 接线两半单测覆盖;objectui 导入向导复选框是独立 follow-up。
🤖 Generated with Claude Code