96 lines
3.5 KiB
Markdown
96 lines
3.5 KiB
Markdown
# 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 提交信息使用中文。
|
|
- 不回退或覆盖用户的未提交修改。
|
|
- 提交时只暂存本次任务相关文件。
|