Repository navigation
Commit 2a32bd4
feat(ui): preview the home amount a record-mode amount will store, and say so when the rate cannot be read (#31724)
<!-- claude-projects-attribution: {"github_login":"zhuangjianguo"} -->
_Requested by **Steedos** · [project
thread](https://claude.ai/code/project/chan_018ETKaNwMZCNRYD7D8Q9Ubb?thread=cmsg_018ETKaNwMZCNRYD7D8Q9UbbKY5oMZsVopxN5eVhk1kG6N)_
Fixes #27196
Clause-②: yes (widening)
Metadata-protocol: none
## 维护者速读
- **改了什么:** 编辑多币种金额(`record` 模式且声明了
`homeAmount`)时,输入框下方实时显示保存后会写入的本位币金额,例如「≈ CN¥71,994.24 at 0.1389 on Mar
15, 2026」。汇率取自 `sys_exchange_rate` 中单据日期当天或之前最近的一条,同一币种和日期只读一次。换算函数直接引用
`@objectstack/formula`(#31631 从引擎提出来的同一份),所以预览数字与保存后的数字逐位一致。同币种显示「≈ 金额
(home
currency)」,没有汇率时提示保存会被拒绝,没有单据日期时提示先填日期。无权读取汇率的成员(403)看到「保存时折算为本位币」,不会看到「没有汇率」,也不会看到估算金额。
- **为什么改:** 卡片 Task 2:录入外币单据时,用户应在保存前看到折算结果,而不是保存后才发现汇率缺失被拒。
- **风险与回滚:** 只影响声明了 `homeAmount`
的金额字段的编辑态:其他币种字段不读取任何数据、不渲染新行(有对照测试)。新增五个翻译键(widening)。`@object-ui/fields`
新增依赖 `@objectstack/formula`(`@object-ui/core` 早已依赖,依赖图不变);fields 包体积
+3.6 KB(gzip +1.0 KB)。回滚即 revert 本 PR。
- **先看:**
`ui/packages/fields/src/widgets/homeAmountPreview.tsx`(`readRateOn` 与
`useHomeAmountPreview`),以及 `CurrencyField.tsx` 中挂载它的一行。
- **两分钟验证:** `cd ui && pnpm exec vitest run
packages/fields/src/__tests__/homeAmountPreview-27196.test.tsx`,预期 8
例全绿。其中一致性一例逐个比对引擎测试里的 JPY / CNY / KWD 和 71994.24 用例。
- **需要你做的:** 无,席位落地(落地前席位欠一次 Clause-② 声明复审)。
## What changes
The ui half of multi-currency M3-2, slice 2 of 2 (Task 2 of the card).
Slice 1 was #31638. The arithmetic moved into `@objectstack/formula` in
#31631, which this PR imports. Nothing is copied.
- **`ui/packages/fields/src/widgets/homeAmountPreview.tsx` (new,
internal to the package, not exported).**
- `readRateOn(source, currency, date)` issues the engine's own `rateOn`
query: `find('sys_exchange_rate', { $filter: { currency, effective_date:
{ $lte: date } }, $orderby: [{ field: 'effective_date', order: 'desc'
}], $top: 1, $select: ['rate', 'effective_date'] })`. Results are cached
per adapter (a `WeakMap`), then by currency and date. A 403
(`classifyLoadError(...) === 'forbidden'`) is cached as `refused`. Any
other failure is dropped from the cache so the next render asks again.
- `useHomeAmountPreview` replays `projectHomeAmounts` over the live form
record: a blank amount or code gives no line; a code or home currency
outside ISO 4217 gives no line. The same currency as home converts at 1
with no read, through `divideToPlaces`. A foreign currency with a blank
date asks for the date. `documentDateOf(value, localization.timezone)`
gives the day, and a `YYYY-MM-DD` value is its own day. No row, or a
rate that is not positive, is awaiting-rate. Otherwise the line shows
`divideToPlaces(amount, rate, CURRENCY_FRACTION_DIGITS[home])`.
- The adapter is the widget's `dataSource` prop when a host passes one,
else the `SchemaRendererContext` adapter, the `LookupField` order. The
form renderer's strip is unchanged: `form.tsx` hands registered widgets
the context adapter anyway, so forwarding it again would add a line no
test could tell apart. This differs from step-1 item 2, which listed the
strip as surface.
- **`CurrencyField`:** mounts `HomeAmountPreview` under the edit box.
The read face, and therefore the record page, is unchanged.
- **Five locale keys** in all eleven packs (zh-Hant generated with
`gen:zh-hant`) and in `FIELD_DEFAULTS`: `fields.currencyHome.preview`,
`previewSame`, `awaitingRate`, `awaitingDate` and `rateUnreadable`.
`awaitingDate` reads "Set the document date to see the home amount"
instead of the step-1 "Pick FIELD …", because the amount widget does not
hold its sibling field's label (step-0 6727854849).
- **`ui/packages/fields/package.json`** gains `"@objectstack/formula":
"workspace:^"`, approved in the claim amendment. `pnpm-lock.yaml` moves
by one importer entry.
## Tests
- `ui/packages/fields/src/__tests__/homeAmountPreview-27196.test.tsx`
(new, 8 cases):
- **Parity with the engine.** The engine's own cases go through the ui
hook and must equal the number it stores. From
`home-amount-projection.test.ts`: EUR 100 into JPY 15385, CNY 775.8, KWD
33.219. From `engine-home-amount-projection.test.ts`: USD 10,000 at
0.1389 into CNY 71994.24, and USD 150 on 2026-04-02 into 1000.
- A foreign amount reads once per currency and date across a re-render
and a remount, with exactly the engine's query, and the line follows a
typed amount.
- The same currency converts at 1 with zero reads: 1.005 gives 1.01, as
the engine's decimal rounding does.
- No rate in force shows awaiting-rate, naming the currency and date. A
blank date asks for one and reads nothing.
- A 403 shows "Converted to the home currency when you save"
(`data-state="refused"`).
- A non-refusal failure draws nothing and is asked again.
- CONTROL: no `homeAmount`, a blank amount or a blank code previews
nothing and reads nothing, and the input stays.
-
`ui/packages/plugin-form/src/__tests__/sectionFormHomeAmount-27196.test.tsx`,
new `describe`: an `ObjectForm` in edit mode under a
`SchemaRendererProvider` shows the line under the amount. This proves
the adapter reaches the widget through the form.
- `form-field-channel-census-12130` passes unchanged. The census records
no new key on the channel, so the approved reader extension was not
needed.
## Acceptance notes
- **Measured live** on `pnpm dev:crm` with the built Console at
`/_console`. The fixture is a scratch package with a record-mode amount
declaring `homeAmount`, home currency CNY, and USD rates 0.1389
(2026-01-01) and 0.15 (2026-04-01). The engine stored the invoice (USD
10,000, 2026-03-15) as `amount_home` 71994.24 and `amount_rate` 0.1389.
- **Admin:** the edit form's line reads "≈ CN¥71,994.24 at 0.1389 on Mar
15, 2026", the stored number. One `sys_exchange_rate` read answered 200
and picked the 2026-01-01 row, not the later one. Typing 20000 moved the
line to "≈ CN¥143,988.48 …" with no second read.
- **Member** (a permission set grants the invoice object only): the same
read answered **403 `PERMISSION_DENIED`**. The adapter threw
`httpStatus: 403`, `code: 'PERMISSION_DENIED'`, which
`classifyLoadError` classes as `forbidden`. The line reads "Converted to
the home currency when you save". Typing did not read again.
- Scripts, readings and screenshots:
`/mnt/project-files/issue-27196/live-pr2/` (`setup.mjs`, `measure.mjs`,
`shot.cjs`, `live-report.json`, `shots/`).
- **Bundle delta:** `@object-ui/fields` `dist/index.js` grows 349,245 →
352,872 bytes (+3,627), gzip 90,342 → 91,356 (+1,014). This was measured
by building with and without the mount. `@objectstack/formula` is
external to the fields build and already in the Console's graph through
`@object-ui/core`.
- **Display width:** the previewed NUMBER is rounded with the spec's
`CURRENCY_FRACTION_DIGITS`, the engine's table. It is drawn with
`formatCurrency`, the same call that draws the stored home field, so the
preview and the saved field read the same.
- **Document date:** the engine passes the timezone only for a
`datetime` document date. The preview passes `localization.timezone`
always. A `date` value in the form is `YYYY-MM-DD`, which
`documentDateOf` returns as-is whatever zone it is given, so both agree
for both types.
## Verification
Head `57993ba65a6d74dadc132374899bf4d3356da389`. It merges `origin/main`
(10 commits); none of them touches a file on this PR. The suites and
gates below ran on `78863476`, the pre-merge head with the same PR
files. 19 files, +447 / −2.
- **Gates:** `node scripts/pm/dispatch-gates.mjs --ran` reports 59
derived, 59 run, 0 NOT-MEASURED, 0 UNRUN, and every exit code is 0.
- `check:query-options-erasure` timed out at 300 s in the loop. It was
re-run alone: exit 0 in 5m22s.
- `check:dual-build-cjs-loads` answered exit 3 (unbuilt) until the
platform packages were built. It was re-run: exit 0.
- **Also run:** `turbo run type-check` for fields, i18n and plugin-form,
55 tasks, green. eslint on the touched files: 0 errors.
`check-i18n-en-drift` (from `ui/`): 0. The form-field census: 34/34.
- **Package suites** (all exit 0, under the verify lock):
- `@object-ui/i18n` + `ui/examples/schema-catalog`: 144 files, 4241
passed, 13 skipped.
- `@object-ui/fields`: 301 files passed, 1 skipped; 4556 tests passed, 7
skipped.
- `@object-ui/plugin-form`: 226 files; 2466 passed, 1 skipped.
- `pnpm --dir ui exec vitest run scripts/`: 170 files passed, 2 skipped;
5027 tests passed, 2 skipped.
- **Examples census grep** (`git grep -l PATH --
'ui/examples/**/test/**' 'ui/e2e/**'` for every touched path): only
`catalog-gallery-render.test.tsx` names `useFieldTranslation.ts`. It is
inside the schema-catalog run above, green.
- **Ablations** (`ablation-replace.mjs`; each restored to a blob equal
to HEAD with an empty `git diff HEAD`):
1. The rate cache removed (`if (held) return held;`): 1 of 8 red, the
once-per-currency-and-date pin.
2. The 403 branch removed: 1 of 8 red, the refused pin.
3. The home digits taken as 2 instead of
`CURRENCY_FRACTION_DIGITS[home]`: 1 of 8 red, the engine parity pin (JPY
and KWD).
4. The `HomeAmountPreview` mount removed from `CurrencyField`: 7 of 14
red across the two files, the form pin included. The 7 that stay green
are PR 1's five home-field pins, the parity case (it calls the hook
directly) and the CONTROL.
<details><summary>Gate list (59, exit codes as recorded)</summary>
```
node scripts/check-adr-0087-registration.mjs --base origin/main :: exit 0
node scripts/check-adr-0087-registration.mjs --self-test :: exit 0
node scripts/check-changeset-no-major.mjs --base origin/main :: exit 0
node scripts/check-closing-keyword-parity.mjs :: exit 0
node scripts/check-closing-keyword-parity.mjs --self-test :: exit 0
node scripts/check-comment-mask-corpus.mjs :: exit 0
node scripts/check-console-intercept-disarm.mjs :: exit 0
node scripts/check-console-intercept-disarm.mjs --self-test :: exit 0
node scripts/check-dts-emitted.mjs --self-test :: exit 0
node scripts/check-empty-changeset.mjs --base origin/main :: exit 0
node scripts/check-empty-changeset.mjs --self-test :: exit 0
node scripts/check-osv-exemptions.mjs :: exit 0
node scripts/check-osv-exemptions.mjs --self-test :: exit 0
node scripts/check-sdui-manifest.mjs :: exit 0
node scripts/check-sdui-manifest.mjs --self-test :: exit 0
node scripts/ci/assert-turbo-remote-cache.mjs --self-test :: exit 0
node scripts/ci/plan-test-core-shards.mjs --self-test :: exit 0
node scripts/ci/prune-turbo-cache.mjs --self-test :: exit 0
node scripts/ci/snapshot-next.mjs --self-test :: exit 0
node scripts/osv-base-relative.mjs --self-test :: exit 0
node scripts/pm/release-rehearsal-clone.mjs --self-test :: exit 0
node scripts/release-pending-publish.mjs --self-test :: exit 0
pnpm --filter @objectstack/spec run check:duration-unit-keys :: exit 0
pnpm --filter @objectstack/spec run check:llms-txt :: exit 0
pnpm check:changeset-fixed :: exit 0
pnpm check:changeset-gate-self-tests :: exit 0
pnpm check:closed-ceremony-text :: exit 0
pnpm check:cross-package-test-inputs :: exit 0
pnpm check:dispatcher-error-vocabulary :: exit 0
pnpm check:driver-memory-census :: exit 0
pnpm check:dts-closure :: exit 0
pnpm check:dual-build-cjs-loads :: exit 0
pnpm check:engine-double-contract :: exit 0
pnpm check:gitlink-declared :: exit 0
pnpm check:lean-entry-closure :: exit 0
pnpm check:manifest-repository-directory :: exit 0
pnpm check:merge-driver :: exit 0
pnpm check:nul-bytes :: exit 0
pnpm check:override-consistency :: exit 0
pnpm check:pnpm-flag-spellings :: exit 0
pnpm check:published-files :: exit 0
pnpm check:query-options-erasure :: exit 0
pnpm check:refd-timer-probe :: exit 0
pnpm check:registry-log-declared :: exit 0
pnpm check:rest-log-spy-declared :: exit 0
pnpm check:role-word :: exit 0
pnpm check:skill-identifier-liveness :: exit 0
pnpm check:sourcemap-no-sources-content :: exit 0
pnpm check:test-source-alias :: exit 0
pnpm check:tier-file-adoption :: exit 0
pnpm check:turbo-task-graph :: exit 0
pnpm check:undeclared-dep-imports :: exit 0
pnpm check:vendor-export-contract-resolve :: exit 0
pnpm check:watch-hint-literal :: exit 0
pnpm check:where-matcher :: exit 0
pnpm check:workspace-manifest-cycles :: exit 0
pnpm --dir ui exec vitest run scripts/ :: exit 0
pnpm check:type-check-coverage :: exit 0
pnpm check:type-check-debt :: exit 0
```
</details>
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01QsR2jQyTLkpKcX2UF8X3Ss
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent 8aaa69f commit 2a32bd4
19 files changed
Lines changed: 447 additions & 2 deletions
File tree
- .changeset
- ui/packages
- fields
- src
- __tests__
- widgets
- i18n/src/locales
- plugin-form/src/__tests__
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
37 | 37 | | |
38 | 38 | | |
39 | 39 | | |
| 40 | + | |
40 | 41 | | |
41 | 42 | | |
42 | 43 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
| 1 | + | |
| 2 | + | |
| 3 | + | |
| 4 | + | |
| 5 | + | |
| 6 | + | |
| 7 | + | |
| 8 | + | |
| 9 | + | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
| 24 | + | |
| 25 | + | |
| 26 | + | |
| 27 | + | |
| 28 | + | |
| 29 | + | |
| 30 | + | |
| 31 | + | |
| 32 | + | |
| 33 | + | |
| 34 | + | |
| 35 | + | |
| 36 | + | |
| 37 | + | |
| 38 | + | |
| 39 | + | |
| 40 | + | |
| 41 | + | |
| 42 | + | |
| 43 | + | |
| 44 | + | |
| 45 | + | |
| 46 | + | |
| 47 | + | |
| 48 | + | |
| 49 | + | |
| 50 | + | |
| 51 | + | |
| 52 | + | |
| 53 | + | |
| 54 | + | |
| 55 | + | |
| 56 | + | |
| 57 | + | |
| 58 | + | |
| 59 | + | |
| 60 | + | |
| 61 | + | |
| 62 | + | |
| 63 | + | |
| 64 | + | |
| 65 | + | |
| 66 | + | |
| 67 | + | |
| 68 | + | |
| 69 | + | |
| 70 | + | |
| 71 | + | |
| 72 | + | |
| 73 | + | |
| 74 | + | |
| 75 | + | |
| 76 | + | |
| 77 | + | |
| 78 | + | |
| 79 | + | |
| 80 | + | |
| 81 | + | |
| 82 | + | |
| 83 | + | |
| 84 | + | |
| 85 | + | |
| 86 | + | |
| 87 | + | |
| 88 | + | |
| 89 | + | |
| 90 | + | |
| 91 | + | |
| 92 | + | |
| 93 | + | |
| 94 | + | |
| 95 | + | |
| 96 | + | |
| 97 | + | |
| 98 | + | |
| 99 | + | |
| 100 | + | |
| 101 | + | |
| 102 | + | |
| 103 | + | |
| 104 | + | |
| 105 | + | |
| 106 | + | |
| 107 | + | |
| 108 | + | |
| 109 | + | |
| 110 | + | |
| 111 | + | |
| 112 | + | |
| 113 | + | |
| 114 | + | |
| 115 | + | |
| 116 | + | |
| 117 | + | |
| 118 | + | |
| 119 | + | |
| 120 | + | |
| 121 | + | |
| 122 | + | |
| 123 | + | |
| 124 | + | |
| 125 | + | |
| 126 | + | |
| 127 | + | |
| 128 | + | |
| 129 | + | |
| 130 | + | |
| 131 | + | |
| 132 | + | |
| 133 | + | |
| 134 | + | |
| 135 | + | |
| 136 | + | |
| 137 | + | |
| 138 | + | |
| 139 | + | |
| 140 | + | |
| 141 | + | |
| 142 | + | |
| 143 | + | |
| 144 | + | |
| 145 | + | |
| 146 | + | |
| 147 | + | |
| 148 | + | |
| 149 | + | |
| 150 | + | |
| 151 | + | |
| 152 | + | |
| 153 | + | |
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
9 | 9 | | |
10 | 10 | | |
11 | 11 | | |
| 12 | + | |
12 | 13 | | |
13 | | - | |
| 14 | + | |
14 | 15 | | |
15 | 16 | | |
16 | 17 | | |
| |||
218 | 219 | | |
219 | 220 | | |
220 | 221 | | |
| 222 | + | |
| 223 | + | |
221 | 224 | | |
222 | 225 | | |
223 | 226 | | |
| |||
0 commit comments