docs(project): correct stale #1867 crash notes on actual_cost / progress_percent (#84)#91
Merged
Merged
Conversation
…ess_percent (#84) Unlike the other four #84 fields, neither project field is a reconstructible child aggregate, so there is nothing to convert to a summary or hook roll-up — only the stale framing to fix. Investigation (boot-inspected the seed): - `actual_cost` (105000 / 340000 / 0) has NO child cost source. pm_timesheet records `hours` only; cost = hours × a person/role rate, and no rate column exists in the 4-object CHARTER schema. It is an externally-computed actual, not a rollup a summary or hook could rebuild. - `progress_percent` (38 / 55 / 0) is NOT a milestone ratio. Both 2-milestone projects have the same status mix (1 completed + 1 in_progress = 50%), and issues are 0% — so any child aggregate flattens the hand-tuned 38/55 to a single value. It is a curated delivery metric, not a naive count. What changed (comments/descriptions only, no logic/schema change): the notes in pm_project.hook.ts, pm_project.object.ts (both field descriptions) and pm_timesheet.view.ts claimed these are stored "because a nested write crashes the QuickJS sandbox". That is no longer true (framework#1867 is fixed). Reframe them to the real reason — actual_cost has no child cost column to sum; progress_percent is a curated metric a child count would flatten — and note that nested hook writes are now safe. Follow-up left to the maintainer: `progress_percent` COULD be made a live milestone-completion roll-up via an afterInsert/afterUpdate hook (the #1867 fix enables it), but only if count-based progress is acceptable — it would re-seed 38/55 → 50/50 and lose the per-project nuance. Flagged in the field note rather than done here, since it changes shipped demo semantics. Build-verified (tsc + build, 6 objects / 72 fields); format:check clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01BZguyAaQbyUpwMZ2gMLaAP
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
2 participants
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.
背景
延续 #84。project 是五个受影响字段里唯一没有可转换 rollup 的模板 —— 所以这里只修过时的说明,不做转换。
调查结论(对 seed 做了 boot 核对)
actual_cost(105000 / 340000 / 0)没有子表金额来源。pm_timesheet只记hours,成本 = 工时 × 人/角色费率,而 4-object CHARTER schema 里根本没有费率列。它是外部算出来的实际值,summary 和 hook 都重建不出来。progress_percent(38 / 55 / 0)不是里程碑比例。两个各 2 个里程碑的项目状态分布完全一样(1 completed + 1 in_progress = 50%),issue 又都是 0% —— 所以任何子表聚合都会把手工调的 38/55 压成同一个值。它是精心编排的交付指标,不是朴素计数。改动(纯注释 / description,无逻辑、无 schema 变更)
pm_project.hook.ts、pm_project.object.ts(两个字段 description)、pm_timesheet.view.ts里都写着「因为 hook 嵌套写会把 QuickJS 沙箱写崩所以存成字段」。framework#1867 修复后这已不成立。改成真实原因:留给 maintainer 的选择(未在本 PR 中做)
progress_percent可以用 afterInsert/afterUpdate 钩子做成实时的里程碑完成度 rollup(#1867 的修复已支持),但前提是接受 count-based 进度——那样会把 seed 的 38/55 重写成 50/50,失去每个项目的差异。我把这个选项写在字段注释里而没有直接做,因为它会改变已发布样板的演示语义。如果你希望我做成实时 rollup(A 方案),回复一声即可。验证
tsc✓、build✓(6 objects / 72 fields)、format:checkclean。纯文档改动,无需 boot。影响
至此 #84 五个字段全部处理完:
summary(已合并 feat(expense): make total_amount a live summary roll-up (#84) #87 / feat(procurement): make received_amount a live summary roll-up (#84) #88 / docs(content): correct stale #1867 crash notes on live roll-ups (#84) #89)Generated by Claude Code