| content |
{"Commits":[{"Sha1":"744d532b8 {"Commits":[{"Sha1":"744d532b80ba3fd239cfbdd2b3700e3d73c08675","Message":"test(governance): 三级门禁全绿——runtime 396/396、UI 12/12，合同与多角色补齐验收\n\n本轮把欠了整条线的运行态证据补齐：静态 → 真实 DB → 浏览器三级全部实跑通过。\n\n## 合同域门禁（5 条断言 + 自检固化）\n`check:module-integration` 新增：渲染必须调 contracts 纯函数、清单必须走 contracts\n清洗、定稿必须校验金额、激活必须要求合同已定稿、合同列表必须有自己的读模型。\n5 条负向注入逐条实跑判红，并固化进 `scripts/lib/contract-integration.test.mjs`\n（fixture 隔离，不碰真文件；配「未注入 → 绿」基线用例，防止所有\"期望红\"\n以完全错误的理由通过）。gateSelftests 地板 6 → 7。\n\n其中「合同列表必须有自己的读模型」防的是真实发生过的缺陷：\n借用「待激活申请」options（只返 REQUESTED）会让财务一激活，刚签的合同就从界面消失。\n\n## 状态机不变量逼出的设计修正\n`contractMachine` 原本是 `DRAFT ⇄ FINALIZED` 的**无终态环**——合同永远走不完，\n而\"订单已激活则不可修改\"只是运行时守卫。contracts 的状态机不变量测试\n（\"从任一状态都能走到终态\"）当场判红。加终态 `EFFECTIVE`，由财务激活时迁入：\n`revise` 从 EFFECTIVE 出发在**状态机层面就不存在**，运行时检查降为第二层。\n\n## 修掉一个我自己制造的严重问题\n早先用批量正则把测试里的 `role:` 改成 `roles:`，**误伤 153 处 `api()` helper 入参**。\n该 helper 收的是 `role`，`roles` 被静默忽略并回落成默认 ADMIN——\n**测试照样绿，但所有「某角色应当 403」的负例都退化成「ADMIN 当然 200」**。\n已全部回退。教训：批量正则改测试比改源码危险得多，源码有编译器兜底，测试没有。\n\n## 修掉一处静默降级（用户反馈两次）\n`draft()` 里 `template ? render(...) : \"\"`——取不到默认模板就给空正文，不报错不提示。\n而\"合同建出来了、正文是空的\"在界面上与\"模板没生效\"完全一样。改为：\n默认模板优先，没设默认但只有一个模板时直接采用；仍取不到时界面明确说明原因。\n另补「套用模板」选择器——此前 `templateId` 存了却从不重渲染，已有合同换不了模板。\n\n## 版式\n按反馈调整为：套用模板 → 合同正文 → 合同清单。\n打印改为只打这一份合同：`@media print` 内 5 条规则（全页隐藏 → 放行合同卡 →\n正文去滚动上限并允许换行 → 按钮与留证快照不打印），沿用配货单打印同一模式，\n含「window.print() 必须在原始 click 内同步调用」那条硬约束。\n\n## 三级门禁证据（本地工作区）\n- `pnpm check` exit 0；门禁自检 8 组\n- `pnpm check:runtime` **396/396**（地板抬至 380），双后端 HTTP 各 45/45\n- `pnpm check:ui` **12/12**，unexpected 0（地板抬至 12）\n- 新增双后端 HTTP 验收：未定稿激活 409 CONTRACT_NOT_FINALIZED、\n 改金额定稿 409 CONTRACT_TOTAL_MISMATCH、合同清单只有对客七列且不含 cost\n- 新增 E2E 真实界面链路：建模板 → 生成合同 → 断言正文按模板渲染 →\n 定稿 → 只读预览 → 激活\n\n## 顺带修复的真账\n多角色改造遗留：两后端测试夹具签单值 role、fromRole/toRole 断言、\nNestJS api() helper 签发、E2E 建账号入参、合同外键 Restrict 导致的清理顺序。\n\nCo-Authored-By: Claude Fable 5 \u003cnoreply@anthropic.com\u003e\n","AuthorEmail":"luoguoguo@gmail.com","AuthorName":"luoguoguo","CommitterEmail":"luoguoguo@gmail.com","CommitterName":"luoguoguo","Timestamp":"2026-08-03T06:17:45-07:00"},{"Sha1":"0e13b856b65685957296087a642c46a9b57c8d0a","Message":"feat(contract): 合同管理界面——模板维护、清单改写、预览与定稿\n\n## 界面三段\n- **模板维护**：正文编辑 + 可用变量清单（真源是 contracts 白名单，不手抄）；\n 默认模板里乙方那几行留了「请填写」占位提示，免得有人以为忘了配变量\n- **合同面板**：清单可改名称/规格/单位/备注，**单价与金额只读**——\n 金额与报价锁死，改写法不改钱，只读比\"改了再被服务端拒绝\"少一次挫败\n- **定稿后**：正文转只读预览 + 打印 + 撤回定稿；留证快照可展开查看\n\n## 浏览器验证时抓到一个真实缺陷\n最初用「待激活申请」的 options 驱动合同列表——而它只返 `status=REQUESTED`。\n结果是**财务一激活，刚签的合同就从界面上凭空消失**。\n补了 `GET /api/contracts` 作为合同自己的读模型（两后端对等），\n视图改为「已有合同 + 尚未起草的待激活申请」两段驱动，后者按 contractRequestId 去重。\n\n这个 bug 单测抓不到，也不会有任何红盘——它只在\"数据恰好处于某状态\"时显形，\n而 dev 库里正好一条 REQUESTED 都没有，所以一打开就是空白。\n\n## 前端不做第二份渲染\n预览直接显示服务端渲染好的 `body`，前端**没有任何占位符处理**。\n在前端补一套 replace 会变成第二份渲染实现（G17 漂移形态）：\n两边看起来一样，直到某天对空值的处理不同，界面上好好的合同打印出来金额是空的。\n\n## 证据（本地工作区）\n- `pnpm check` exit 0；全仓 typecheck 0 错误\n- 浏览器实测：模板维护渲染、合同面板 1 个、状态「已定稿」、清单 1 行、\n 合计 ¥660000.00、预览/撤回定稿/打印按钮齐全（截图见会话）\n- `GET /api/contracts` 返回真实合同（编号、报价号、客户名、合计、定稿时间）\n\n## 未做\nE2E 用例、两后端 HTTP 验收、`check:module-integration` 合同断言均未补（#31）。\n\nCo-Authored-By: Claude Fable 5 \u003cnoreply@anthropic.com\u003e\n","AuthorEmail":"luoguoguo@gmail.com","AuthorName":"luoguoguo","CommitterEmail":"luoguoguo@gmail.com","CommitterName":"luoguoguo","Timestamp":"2026-08-02T23:19:14-07:00"},{"Sha1":"ef882dee3f2d670038bff1151a04e6cb4a4d3d45","Message":"feat(contract): 合同管理落地——模板、清单清洗、预览、定稿快照与激活前置\n\n动手前先证伪了「优化完善」这个词：**本仓此前没有合同**。\n`ContractRequest` 只是流程凭证（状态 + 报价引用 + 拒绝留痕），没有正文、条款、\n甲乙方、签署；「合同管理」视图做的是财务把报价激活成订单，本质是审批队列。\n所以这是新建业务对象，不是加按钮。\n\n## 用户裁决（五条）\n模板+变量填充 / 定稿即快照 / 仅内部预览打印 / 乙方写进模板正文 / 定稿为激活前置。\n另就清单追加两条：只改写法金额锁死 / PUBLIC 附件归入主行备注。\n\n## 合同清单与报价清单是两份不同明细\n报价行 26 列里 9 列是内部的——成本价、底价、成本合计、低于底价标记、调价原因、\n标准价、三种折扣构成。投影**重建对象字面量**而不是删字段，成本列在结构上进不来\n（单测断言 Object.keys 恰为七列，并扫描序列化结果确认成本数字不出现）。\n最隐蔽的一条是 `QuoteLineAccessory.visibility=INTERNAL`：「别显示成本」人人记得，\n「别显示内部附件」没人会想到，因为它藏在子表里。\n\n**金额锁死**先验了算术前提才敢定：dev 库 `sum(quote_lines.total_cents)` 恒等于\n`quote_options.total_cents`，差额全为 0，否则这条不变量会一上线就误杀所有合同（C1 同型）。\n校验放在**定稿**而非每次保存——草稿期正在合并行，中间态必然对不上，\n每次都校验会让「合并两行」这个动作根本做不完。\n\n## 渲染两层 fail-closed\n未知变量、取不到值的变量都抛错并点名。理由：一份看起来正常、金额那行却空白的合同\n被打印去签，比当场报错危险一个量级。另单独检查未闭合 `{{`——它会被正则整段跳过，\n不专门查就会原样印进合同且无人报错。\n\n## 真实链路验证抓出两个 bug\n① `variablesSnapshot` 恒为空：起草时正文已渲染，到定稿时里面早没有 `{{}}` 可提取。\n 改为快照**全部可解析变量**——留证本就该全记，不该取决于模板作者当初印没印。\n② Fastify 路由多写了 `/api` 前缀（注册作用域已带 prefix），实际成了 `/api/api/...`。\n\n## 又踩了一次同字面量陷阱\nNestJS 激活前置最初插错位置——「仓库不存在」那段在文件里出现多次，\n`replace` 只换第一处，守卫落进了 `createStocktake`（盘点）。\n已改为断言锚点唯一性后再插入。CLAUDE.md 点名过两次的坑，我这是第三次踩。\n\n## 证据（本地工作区，Fastify 真实链路）\n- `pnpm check` exit 0；contracts 单测 302（新增 22 条合同用例）\n- 模板：经理可建 201 / 销售 403 / 未登记变量 409 点名「甲方开户行」\n- 合同：起草生成 1 行清单（七列，含\"含：附件\"备注）、正文变量全替换、大写金额正确\n- 定稿：改金额 → 409 报出差额 -10000.00 元；销售定稿 403；正确金额 → FINALIZED\n- 撤回定稿：订单已激活 → 409 ORDER_ALREADY_ACTIVATED\n- 缺税号时起草 → 409 MISSING_VALUE 点名「甲方税号」（真实数据触发，非构造）\n- 留证快照 12 项（缺签署人两项因该报价未走客户接受，属正确 fail-closed）\n\n## 未做（不隐藏）\n前端界面（模板维护/预览/修改）未做；两后端 HTTP 验收测试与 E2E 未补；\n`check:runtime`/`check:ui` 本轮未跑；激活前置只在代码与单测层验证，\n未构造完整「未定稿→拒绝激活」的真实 HTTP 流程（dev 库无待激活申请，\n且 quotation_id 唯一约束挡住了造数）。\n\nCo-Authored-By: Claude Fable 5 \u003cnoreply@anthropic.com\u003e\n","AuthorEmail":"luoguoguo@gmail.com","AuthorName":"luoguoguo","CommitterEmail":"luoguoguo@gmail.com","CommitterName":"luoguoguo","Timestamp":"2026-08-02T23:07:37-07:00"},{"Sha1":"e0b780d18833713a675d8903f407bd7afd55e650","Message":"feat(auth): 多角色并存——一个账号可持多个角色，能力取并集，互斥组合硬禁止\n\n用户裁决两条：① 多角色并存（而非租户自定义角色）；② 互斥组合硬禁止（而非仅警示）。\n\n## 为什么是多角色而不是自定义角色\n备选方案是「租户自建角色 + 勾选任意 capability 子集」。不选它只有一条理由但足够硬：\n那会把「谁能做什么」的真源从 ROLE_PERMISSION_MAP **搬进数据库**，\n`check:role-permissions` 里「数据库不另存权限副本」这条核心断言随即失效，\n排查越权要同时看代码和数据。多角色只在 DB 存**角色分配**，真源不动，门禁继续有牙。\n代价是表达力：拼不出「销售但能看成本」这种现有角色组合不出的能力集。**已知取舍，非遗漏。**\n\n## 互斥矩阵为什么按角色对而不是 capability 对\n按能力对看着更本质，实则注册即红：`FINANCE` 单角色本身就同时持有 `payment.record`\n与 `payment.confirm`，门禁上线当天就判自己违规（C1 同型：扫到自身定义源）。\n故定义在角色层，并由 `it.each(MANAGED_USER_ROLES)`「每个单角色都不触发冲突」常驻断言守住。\n三组：采购三责分离 / 收款与发货放行 / 财务发起与审批；ADMIN 须单独持有。\n**这挡不住 ADMIN**——它持全部 capability，三责分离对它本就不成立，\n所以审批动作仍按 actor 硬校验 `approver !== requester`，两层缺一不可。\n\n## 删掉 requestRole 是本次最关键的决定\n`hasRolePermission` 改为同时接受单角色与角色集，好让 185 处调用点逐字不变。\n但这带来一个隐患：若保留 `requestRole`/`RequestRole` 单值访问器，\n调用点会**照常编译通过、静默只按主角色授权**——并集悄悄失效，零红盘。\n删掉它，编译器逼出 122+29 个错误，一个都跑不掉。\n\n编译器抓不到的恰是最危险的一处：`lockActiveAdmins` 的裸 SQL `\"role\" = 'ADMIN'`。\n它绕过 Prisma 类型检查；若当初保留 role 列做「兼容」，这句会静默匹配陈旧数据——\n**最后管理员保护看似还在，锁的却是错的行**。这是坚持 DROP COLUMN（并按门禁写\n`migration-allow` 留痕）的真正理由。计数侧同理：数组列上等值查询恒不匹配，\n`count` 恒为 0 会让保护永远放行。\n\n## 顺带修掉一个存量 bug\n两后端 `reverseAllocation` 把**角色名当操作人**存进 `reversedBy`（`reversedBy: role` → \"FINANCE\"）。\n列是 String? 所以静默收下，反核销记录追不到人。多角色改造让它变成类型错误才暴露，已改传 actor。\n\n## token 与失效语义\nclaims `role` → `roles`，**无兼容分支**：留着它，只带 `role` 的旧令牌会走进「按单角色授权」\n的窄路径而调用方以为拿到并集，这种不一致比直接 401 难查得多。旧令牌一律 401 CLAIMS。\n受管理令牌回查用 `sameRoleSet` **集合语义**——按数组逐位比会让管理员调整勾选顺序\n就把在线用户全部踢下线（同 sameTagSet 那条教训）。\n\n## 迁移\n两端对等：users.role → users.roles、user_events 角色快照转集合，先回填再删旧列。\nDROP COLUMN 与 CREATE INDEX 均按门禁要求加 `-- migration-allow:` 留痕。\n\n## 前端\n账号页角色由单选下拉改多选勾选，实时显示并集能力数与互斥冲突——\n预览调 contracts 同一个 `previewRoleAssignment`，不在前端另写一套 if。\n**前端只提示不裁决**：绕过 UI 直接 curl 照样 400。\n\n## 证据（本地工作区）\n- `pnpm check` exit 0；contracts 273/273（新增 33 条多角色单测）；全仓 typecheck 0 错误\n- 门禁负向已实跑判红：注入「退化成只按主角色授权」→ check:role-permissions exit 1；\n 注入「待办中心放行全集」→ check:module-integration exit 1；均恢复后转绿\n- 迁移在 dev 库实跑：单角色→单元素集合、0 个空角色集账号、旧列已删\n- 真实 HTTP 四条对抗：仓库+采购 400 点名冲突／空集 400／ADMIN 混搭 400／销售+技术 201\n- 浏览器：多选控件 10 角色、并集能力数实时更新、互斥冲突当场提示\n\n## 未做（不隐藏）\n`check:runtime` 与 `check:ui` 本轮未实跑；两后端多角色 HTTP 验收与 E2E 用例尚未补齐。\n动态区 runtime/UI 证据行仍是上一轮日期，未据本次改动更新。\n\nCo-Authored-By: Claude Fable 5 \u003cnoreply@anthropic.com\u003e\n","AuthorEmail":"luoguoguo@gmail.com","AuthorName":"luoguoguo","CommitterEmail":"luoguoguo@gmail.com","CommitterName":"luoguoguo","Timestamp":"2026-08-02T22:26:56-07:00"}],"HeadCommit":{"Sha1":"744d532b80ba3fd239cfbdd2b3700e3d73c08675","Message":"test(governance): 三级门禁全绿——runtime 396/396、UI 12/12，合同与多角色补齐验收\n\n本轮把欠了整条线的运行态证据补齐：静态 → 真实 DB → 浏览器三级全部实跑通过。\n\n## 合同域门禁（5 条断言 + 自检固化）\n`check:module-integration` 新增：渲染必须调 contracts 纯函数、清单必须走 contracts\n清洗、定稿必须校验金额、激活必须要求合同已定稿、合同列表必须有自己的读模型。\n5 条负向注入逐条实跑判红，并固化进 `scripts/lib/contract-integration.test.mjs`\n（fixture 隔离，不碰真文件；配「未注入 → 绿」基线用例，防止所有\"期望红\"\n以完全错误的理由通过）。gateSelftests 地板 6 → 7。\n\n其中「合同列表必须有自己的读模型」防的是真实发生过的缺陷：\n借用「待激活申请」options（只返 REQUESTED）会让财务一激活，刚签的合同就从界面消失。\n\n## 状态机不变量逼出的设计修正\n`contractMachine` 原本是 `DRAFT ⇄ FINALIZED` 的**无终态环**——合同永远走不完，\n而\"订单已激活则不可修改\"只是运行时守卫。contracts 的状态机不变量测试\n（\"从任一状态都能走到终态\"）当场判红。加终态 `EFFECTIVE`，由财务激活时迁入：\n`revise` 从 EFFECTIVE 出发在**状态机层面就不存在**，运行时检查降为第二层。\n\n## 修掉一个我自己制造的严重问题\n早先用批量正则把测试里的 `role:` 改成 `roles:`，**误伤 153 处 `api()` helper 入参**。\n该 helper 收的是 `role`，`roles` 被静默忽略并回落成默认 ADMIN——\n**测试照样绿，但所有「某角色应当 403」的负例都退化成「ADMIN 当然 200」**。\n已全部回退。教训：批量正则改测试比改源码危险得多，源码有编译器兜底，测试没有。\n\n## 修掉一处静默降级（用户反馈两次）\n`draft()` 里 `template ? render(...) : \"\"`——取不到默认模板就给空正文，不报错不提示。\n而\"合同建出来了、正文是空的\"在界面上与\"模板没生效\"完全一样。改为：\n默认模板优先，没设默认但只有一个模板时直接采用；仍取不到时界面明确说明原因。\n另补「套用模板」选择器——此前 `templateId` 存了却从不重渲染，已有合同换不了模板。\n\n## 版式\n按反馈调整为：套用模板 → 合同正文 → 合同清单。\n打印改为只打这一份合同：`@media print` 内 5 条规则（全页隐藏 → 放行合同卡 →\n正文去滚动上限并允许换行 → 按钮与留证快照不打印），沿用配货单打印同一模式，\n含「window.print() 必须在原始 click 内同步调用」那条硬约束。\n\n## 三级门禁证据（本地工作区）\n- `pnpm check` exit 0；门禁自检 8 组\n- `pnpm check:runtime` **396/396**（地板抬至 380），双后端 HTTP 各 45/45\n- `pnpm check:ui` **12/12**，unexpected 0（地板抬至 12）\n- 新增双后端 HTTP 验收：未定稿激活 409 CONTRACT_NOT_FINALIZED、\n 改金额定稿 409 CONTRACT_TOTAL_MISMATCH、合同清单只有对客七列且不含 cost\n- 新增 E2E 真实界面链路：建模板 → 生成合同 → 断言正文按模板渲染 →\n 定稿 → 只读预览 → 激活\n\n## 顺带修复的真账\n多角色改造遗留：两后端测试夹具签单值 role、fromRole/toRole 断言、\nNestJS api() helper 签发、E2E 建账号入参、合同外键 Restrict 导致的清理顺序。\n\nCo-Authored-By: Claude Fable 5 \u003cnoreply@anthropic.com\u003e\n","AuthorEmail":"luoguoguo@gmail.com","AuthorName":"luoguoguo","CommitterEmail":"luoguoguo@gmail.com","CommitterName":"luoguoguo","Timestamp":"2026-08-03T06:17:45-07:00"},"CompareURL":"luoanwu/juhai-quotation-system/compare/4e06b62635319faead311e0b6799c2e47877f859...744d532b80ba3fd239cfbdd2b3700e3d73c08675","Len":4}... |