Imported from xxu29958-jpg/xpj (
AGENTS.md). Install upstream withnpx skills add xxu29958-jpg/xpj. Copyright stays with the author.
小票夹仓库工作合同
本文件是 Codex、Claude Code 和开发者进入仓库时默认加载的施工入口。它约束施工方法，不裁决产品事实；详细工程约束按任务责任从 docs/ 选读。
0. 权威顺序
产品事实、施工范围和完成声明发生冲突时，固定按以下顺序裁决：
- 用户当前 Goal、Owner 明确裁决和本次任务合同；
- Gmail 中三份最终选定合同：《Ticketbox 产品与全系统架构合同（当前版）》《Ticketbox Windows 与数据生命周期架构合同（当前版）》《Ticketbox G2 后产品完整化与 Internal Beta 施工合同》；
- 当前 exact HEAD 的代码、数据库、构建和运行事实；
- 官方平台语义与成熟产品现实。
仓库文档、ADR、测试、短交接和历史报告只作施工指引或证据，不能覆盖上述 authority；要求读取 Gmail 原文但入口不可用时必须报告，不能用摘要替代。短交接只恢复工作状态，ADR 只保存决定历史。
先按上述权威顺序与已有授权裁决冲突。只有裁决仍未明确、确需 Owner 取舍，或敏感/不可逆动作超出既有授权时，才暂停该动作并报告；已授权的模型、Owner 与消费者纠正继续推进。
1. 开工协议
修改前完成最小必要预检：
- 确认仓库、分支/worktree、exact HEAD 与
git status --short；不得猜测当前基线。 - 恢复当前任务合同；
.claude/HANDOFF.md存在且非IDLE时把它作为短交接读取，压缩上下文后重新读取。 - 用目录、搜索、调用链和测试定位责任面；只读真正影响本任务的章节和 ADR。
- 需要了解模块体量、复杂函数或债务变化时，优先读对应 exact SHA 的 CI
repository-codebase-weight报告；入口与口径见docs/rules/CODE_QUALITY_STANDARDS.md的全仓工程地图。把它作为源码导航，不代替产品合同或真实调用链，不为普通修改重复跑全仓重测试。 - 明确五项：
Goal / Allowed Changes / Forbidden Surface / Done Checks / Evidence。用户已给出的口语要求应翻译成这五项，不另造庞大流程。 - 先分清现存基线失败与本次回归。没有证据时，不把旧失败算到本次修改上，也不顺手修。
没有独立任务合同不等于没有边界：以用户当前要求、直接调用链、受影响消费者和本文件形成最小合同。只有真正阻塞、不可逆或需要 Owner 取舍的问题才询问；已授权、可逆、可审查的工作直接推进。
2. 稳定系统边界
小票夹是本地优先、Windows 原生受管的家庭财务事实系统：PostgreSQL 与附件保留在 Owner 控制的 Windows 安装中，Android、/web、/owner 与 Desktop Manager 是受约束消费者或管理面。
任何修改都必须保护这些不变量：
- 不丢失、不静默改写财务事实、身份、离线意图、附件及它们的归属关系。
- OCR、分类和外部模型只能产生建议，不得自动覆盖用户确认事实。
- 账本隔离、角色授权、凭证 scope 与公网 allowlist 由后端执行，不能靠 UI 隐藏代替。
/owner保持 loopback 管理面；公网入口必须显式允许并有对应鉴权，不公开挂载uploads/。- Windows 运行时不依赖 Docker、WSL、Linux shell 或外部云主数据。
- 数据根、installation identity、服务身份、升级、备份、恢复、保留数据重装和卸载语义必须显式；禁止静默切换数据库、目录、身份或降级路径。
任务若不触及某项，不得借它扩张范围。
3. 施工纪律
- 最小充分改动：只实现当前退出门需要的纵向切片；不做邻接清理、顺手重构或未来路线施工。
- 复杂度必须有证据：没有当前需求、已观察失败或明确不变量，不新增防御检查、fallback、兼容层、wrapper、helper、抽象、缓存、迁移路径或额外测试。
- 禁止验证宫殿：已有测试能证明同一不变量时不复制一套；小而可逆的改动不扩成全仓、全平台或全生命周期验收。
- 根因优先但范围仍窄：修真实责任点，不堆症状补丁；找到深层原因不等于获准重写邻接拓扑。
- 复用事实，不继承旧 UI：复用正确的模型、服务和真实能力；现有 UI、IA 和 token 没有视觉 authority。新前端迁移消费者后删除旧实现，不并存两套 current surface。
- 一个事实一个权威：切换权威时同时迁移本任务范围内全部消费者，并物理退役旧入口；禁止两套真相长期并存或用隐式 fallback 掩盖缺口。
- 能力不得退化：产品化、重构和视觉改造必须保留真实权限、冲突、离线、错误和恢复语义，不能只换壳。
- 达到退出门就停：目标行为成立、约定验证通过、diff 已审查后结束。没有新证据不得继续“加固”。
4. 风险比例验证
验证强度由实际风险决定，不由文件数量或模型焦虑决定：
- 低风险：文案、静态文档、局部样式或可逆小改——做格式/diff 检查和最相关的窄验证。
- 中风险：业务行为、API/DTO、跨端消费者、状态流——跑受影响单测、契约或集成路径，再审查 diff。
- 高风险：财务事实、身份、权限、幂等/OCC、迁移、附件、Windows 安装/升级/恢复——按任务合同覆盖成功、失败与恢复路径，并在 exact HEAD 上执行对应门禁。
只有以下情况才扩大验证：窄检查失败；调用图证明影响扩大；改动新增了风险面；任务合同明确要求。不要在代码未变化时重复全量门，也不要为低风险改动制造新的生命周期矩阵。
Review 只证伪固定 exact subject 的当前 claims；候选必须有可执行反例、Owner/consumer、具体后果和当前片关系，由主控裁 FIX / REJECT / HOLD。主审、定向回归和 final-head 复核后无当前 blocker 就停止，P3 默认不阻断。
报告必须区分：实际执行且通过、实际执行但失败、未执行、环境阻塞。不得把“预计会过”“代码看起来正确”写成已验证。
5. 数据、安全与副作用
- 金额、币种、账务时间、修订号和更正事实按当前领域契约处理；禁止用
float、请求时区或显示文案重解释历史事实。 - outbox-routed mutation 的幂等键、principal binding、OCC 与首次稳定结果是不同责任；不得用其中一个冒充另一个。
- 多表业务动作和“幂等 claim + 业务提交”必须保持事务边界；失败后不得留下看似成功的半状态。
- Android Room 和前端缓存是可重建投影；未提交离线 intent 不是缓存，不能被刷新或退出流程悄悄吞掉。
- 数据库中的附件路径必须经过项目统一 resolver 与租户/账本边界校验。
- Token、密钥、pairing code、数据库口令和内部路径不得进入源码、PR、日志、截图或公开回执。
- 破坏性命令、数据删除、权限放宽、force push、
reset --hard、clean -fd等必须有 Owner 明确授权和可核对目标。
6. Git 与改动边界
- 默认从用户指定或当前已确认的 exact HEAD 建立独立分支/worktree；不得在不明来源的脏树上施工。
- 不覆盖、删除或格式化与本任务无关的本地改动；发现未知脏状态先隔离并报告。
- 一个 PR 只承载一个可解释目标。大任务按依赖顺序拆纵向门，不按文件类型制造长期半成品。
- 只提交本任务文件；生成文件仅在源发生变化且真实运行生成器后提交。
- 不直接改受保护的
main；用户已授权合并时，在所需 exact HEAD 门禁通过后自主按分支保护流程合并并完成约定的 main 验证。不用旧测试结果给新 HEAD 背书。
7. 文档与 ADR 的按需读取
从责任出发读取，而不是从文档数量出发：
- 架构、API、安全：
docs/architecture/中与调用链直接相关的文件。 - Windows 安装、服务、备份、恢复与发布：
distribution/、desktop/、docs/runbook/及相关测试。 - Android：状态流、上传、外观等对应架构文件与受影响模块。
- 工程细则：
docs/rules/ENGINEERING_RULES.md的相关编号章节；依赖、质量、错误文案分别读对应专题文件。 - ADR：先在
docs/DECISIONS/README.md或代码搜索中定位，再读直接相关决定。docs/current/adr-registry.json、状态表和依赖图只反映其标注的 review base；若早于当前 HEAD，只能当线索，不能当现状证明。
常规 bugfix、局部重构、样式调整、测试补充和既有决定的实现，不需要新 ADR。只有长期、跨模块、难逆转并会改变现有架构边界的决定才写后继 ADR；已接受 ADR 的历史正文不因实施进度而改写。
8. 完成报告
结束时只报告可核验事实：
- exact HEAD / 分支；
- 改了什么以及为什么这些文件足够；
- 执行的命令与结果；
- 未执行项及原因；
- 尚存风险、基线失败或需要 Owner 裁决的事项。
不要重复任务全文，不写空泛“全面加固”，不把未完成包装成完成。