# order_site 项目规则

## 项目目标

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

## 每次任务的读取顺序

1. 本文件。
2. [docs/README.md](docs/README.md)。
3. 涉及订单、内部 SKU、履约、商品、成本或财务时，必须完整阅读
   [docs/统一订单履约与财务模型-权威版.md](docs/统一订单履约与财务模型-权威版.md)。
4. 涉及部署、数据库或备份时，再读取对应的运维文档。
5. `docs/archive/` 只用于追溯，不作为实现依据。

## 唯一权威

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

[docs/统一订单履约与财务模型-权威版.md](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. 不保留第二份“现行方案”“最终口径”或“统一总纲”。

## 验证要求

涉及代码时至少执行：

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

涉及生产数据判断时：

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

## Git

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