order_site/AGENTS.md

order_site 项目规则

项目目标

维护一个多渠道订单履约平台，覆盖平台入单、内部 SKU、履约路由、接单工单、自动发货、人工客服、 第三方卡券、寄卖、成本、销售事实与财务总账。

每次任务的读取顺序

1. 本文件。
2. docs/README.md。
3. 涉及订单、内部 SKU、履约、商品、成本或财务时，必须完整阅读 docs/统一订单履约与财务模型-权威版.md。
4. 涉及部署、数据库或备份时，再读取对应的运维文档。
5. 涉及生产升级、数据库迁移、领域模型切换或财务重建时，必须完整阅读 docs/生产升级操作手册.md。
6. docs/archive/ 只用于追溯，不作为实现依据。

唯一权威

订单、内部 SKU、渠道路由、履约载体、标准商品、成本和财务口径只有一个权威来源：

docs/统一订单履约与财务模型-权威版.md

禁止：

• 在代码注释、接口、页面或新文档中定义另一套业务口径。
• 将商品名称、canonical_sku 前缀、商品分类或支付状态用于反推履约渠道。
• 让多个服务同时写履约核心状态。
• 用自由 JSON 或字符串状态替代正式领域字段。

代码实现与权威文档冲突时，先停止修改并核对生产数据，不得自行选择其中一方继续开发。

数据安全边界

永久保留，不得删除或重写历史：

• orders
• order_items 中的平台原始字段
• 平台原始订单与原始报文
• 平台售后、退款和支付事实
• work_orders、work_order_shares、work_order_events
• 真实 fulfillment_tasks 执行记录
• worker_wallet_ledgers、fund_accounts 等真实资金流水
• admin_audit_logs

允许在备份和验收方案完备后删除并重建：

• cost_snapshots
• cost_exceptions
• sales_daily_facts
• finance_journal_*
• fulfillments / fulfillment_attempts / fulfillment_issues
• 页面投影、统计缓存、水印和任务重试状态

任何数据清理必须先区分“原始事实”“业务输入配置”“可重建派生数据”。

开发规则

1. 先读权威文档，再改代码。
2. 结构性变更必须新增迁移，不修改已发布迁移。
3. 核心状态只能通过对应领域服务修改。
4. 新功能必须有真实 PostgreSQL 集成测试或明确说明无法覆盖的原因。
5. 页面与统计如果显示同一个业务量，必须读取同一投影或同一查询口径。
6. 不把临时修数据脚本当成长期业务流程。
7. 历史清理必须可 dry-run、可审计、可回滚，并且全量扫描存量。
8. 结构性切换采用“备份 → 回填 → 一致性审计 → 原子切换 → 观察”。 不再新增双读、双写或旧表运行期兼容；无法确定的数据进入待分类，不做猜测。

文档规则

1. 业务与架构口径只更新唯一权威文档。
2. docs/README.md 只做导航，不定义业务规则。
3. 被替代的内部设计文档移动到 docs/archive/<日期>/。
4. 外部平台协议可以保留，但不得覆盖项目自身领域模型。
5. 文档中的生产迁移号、代码基线、数据结论必须注明日期和来源。
6. 不保留第二份“现行方案”“最终口径”或“统一总纲”。

验证要求

涉及代码时至少执行：

apps/backend: npm run check
apps/frontend: npm run check

涉及生产数据判断时：

• 默认只读。
• 显式设置只读事务。
• 不执行 UPDATE、DELETE、TRUNCATE、DDL 或调度任务。

Git

• 所有 Git commit 提交信息使用中文。
• 不回退或覆盖用户的未提交修改。
• 提交时只暂存本次任务相关文件。