5.2 KiB
5.2 KiB
开发经验与注意事项
先按本任务模块、路径、症状和机制检索，再读命中条目的适用条件与来源。执行步骤与维护要求见 闭环规范；事实入口见 问题台账。这些是仓库可共享的外部经验，不依赖单个聊天会话或某个客户端私有记忆。
| lesson_id | 触发条件 / 关键词 | 注意事项 | lesson_state | 主记录 / 最近复核 |
|---|---|---|---|---|
| LESSON-20260928-docgov-shared-map-race | docgov、memDocs、per-doc 锁、concurrent map、登录 500 | 拆锁后共享 map 仍要单独互斥；锁不可重入；全站 500 先看进程是否退出 | candidate | 共享 map 互斥；2026-09-28 |
| LESSON-20260928-quality-heading-normalize | 缺少必填章节、State-of-the-Art、H3、质量门禁、AutoRepair | 标题比对去空白并跨 H2–H4；层级漂移不扣分；真实缺章仍失败 | candidate | 章节标题归一化；2026-09-28 |
| LESSON-20260928-task-write-verb-visible-refusal | 帮我定、制定、ClarificationQuestion、前置条件、quality_failed | 写动词覆盖制定与帮我定；拒绝和澄清进对话；质量失败不写宿主机路径 | candidate | 写动词与可见拒绝；2026-09-28 |
| LESSON-20260928-activation-preview-client-gate | activation-preview、NO_GOVERNED_DOCUMENT、clientDutyIssues、400 | 服务端激活门禁要有同等前端预检；live_edit 不套激活门禁 | validated | 激活预检对齐；2026-09-28 |
| LESSON-20260928-squad-commit-as-author | 小队落盘、uow permission denied、AutoCommitUserID、OnBehalfOf、非编制人 | 自动提交身份用文档编制人，触发者只写入 OnBehalfOf；不要放宽 ActionCommit | candidate | 编制人代理提交；2026-09-28 |
| LESSON-20260928-standard-role-reseed | 注册、role-guest、system_roles、is_system、23503、23505、INTERNAL | 硬编码标准角色须幂等补种并标 is_system；用户名冲突返回领域 400，不要包进 insert user | validated | 标准角色可自愈；2026-09-28 |
| LESSON-20260928-ui-dead-control | 死按钮、端点未开通、UsersSection、重置密码、merge-base | 删除「未开通」控件前用当前基线核对路由已存在；注释不能代替 merge-base | validated | 删控件前核对端点；2026-09-28 |
| LESSON-20260927-server-facts-and-iso-db-recipe | 上传持久化、fileMeta、占位模板、config.Load 默认 DSN、TEST_DATABASE_URL、隔离库、RefuseSharedEnvDSN、goose 顺序 | 服务端事实源优先（本地仅缓存）；worktree 测试必须显式钉隔离库并避开 5433/5434/5435 子串端口；隔离库配方=扩展→goose→init SQL，重组件用例先做基线四格对照 | validated | 服务端事实源与隔离库配方 |
| LESSON-20260923-nullable-duty | docgov、SQL、nullable、23503、可选职责、创建/heal | 检查所有写入口的缺席值语义；用真实 PG 验证 NULL/FK | validated | 可选职责持久化；2026-09-23 |
| LESSON-20260923-content-hash | docrevision、canonicalize、hash、bootstrap、hard-break、404、水合 | 保持文本语义并检查账本/文件一致性；新数据通过不能覆盖旧数据迁移 | validated | 正文规范化与投影；2026-09-23 |
| LESSON-20260923-matrix-status-cas | FEATURE-MATRIX、docs-apply、record_id、merge conflict、CAS | 矩阵/CURRENT 行变更走 docs apply；合并后核验状态列未被回退 | validated | 矩阵状态 CAS；2026-09-23 |
| LESSON-20260924-pi-tool-boundaries | PI、MCP、readonly、path、snapshot、process-group | 路径语义与快照边界一致，合法路径和拒绝路径都验收 | validated | 文件工具边界；2026-09-24 |
| LESSON-20260924-cursor-hook-advisory-gates | Cursor、hooks、advisory、fail-open、probe、stdin | hook 与执行器分层；契约未知 fail-open；审计日志放 ignore 路径 | candidate | 客户端 hook 门禁；2026-09-24 |
| LESSON-20260924-deny-only-submit | 非编制、DOC_DUTY、400、run/edit、送审 | 权限哨兵映射 403；三道门协同放宽；ActorIsMember 不复用 RoleSystem | validated | deny_only_submit；2026-09-24 |
| LESSON-20260926-failclosed-bypass-contract | IDOR、旁路、fail-open、白名单前缀、sh -c、validated_only、untracked、table_owners | 旁路入口必须继承主路径硬边界+SQL 防御纵深；门禁/授权器/执行器对未知默认拒绝；安全契约由执行器硬拒不依赖注释 | validated | 旁路与未知即拒绝契约；2026-09-26 |
validated 的证据范围见各条目；本日复核为历史材料和源码阅读，未重跑产品回归。后续按机制补充，过时条目标 superseded/retired 并保留替代链接。