# 酒库管理系统 — 项目规则与 Orchestrator

## 必读

**开始任何任务前，先读 `docs/context/project.md`** 了解项目全貌。

---

## Orchestrator：如何自动选择 Agent

根据用户请求的关键词和意图，按以下规则判断调用哪些 Agent：

### 新功能开发（完整流水线）

触发词：「新增」「开发」「实现」「做一个」+ 功能描述

```
串行：requirements-analyst → architect
并行：api-designer + db-designer（同时进行，都依赖架构但互不依赖）

→ ui-designer 判断复杂度：
    简单变更：直接输出规范 → 继续下一步
    复杂设计：输出 Figma 需求文档 → 暂停等用户确认设计稿

并行：backend-coder + flutter-coder（都依赖 API 设计，互不依赖）
串行：test-engineer → linter → code-reviewer → security-auditor
```

### 仅后端修改

触发词：「修复后端」「后端接口」「API」+ 具体描述

```
backend-coder → test-engineer → linter → code-reviewer
```

### 仅前端修改

触发词：「UI」「界面」「Flutter」「页面」

```
flutter-coder → linter
```

### Bug 修复

触发词：「bug」「报错」「修复」「问题」

```
1. 先判断 bug 来源（后端/前端/数据库）
2. 调用对应的 coder agent 修复
3. test-engineer 验证修复
```

### 安全/代码质量检查

触发词：「安全」「漏洞」「review」「审查」「代码质量」

```
并行：security-auditor + code-reviewer + linter
```

### 线上问题

触发词：「线上」「故障」「宕机」「慢」「报错」

```
sre（优先级最高，立即响应）
→ 根据 sre 诊断结果，再决定是否调用 backend-coder 修复
```

### 文档需求

触发词：「文档」「说明」「手册」「README」

```
doc-writer
```

---

## Agent 边界规则（强制执行）

| Agent | 可以写 | 不可以写 |
|-------|--------|----------|
| requirements-analyst | docs/requirements/ | 任何代码 |
| architect | docs/architecture/ | 任何代码 |
| api-designer | docs/api/ | 任何代码 |
| db-designer | backend/schema/ | 业务代码、测试代码 |
| backend-coder | backend/internal/, backend/main.go | *_test.go, schema/ |
| ui-designer | docs/design/ | 任何代码 |
| flutter-coder | client/ | backend/ |
| test-engineer | *_test.go, docs/review/*-bugs.md | 业务代码 |
| linter | 格式自动修复（gofmt/dart format），docs/review/lint-report.md | 逻辑代码 |
| code-reviewer | docs/review/*-review.md | 任何代码 |
| security-auditor | docs/security/ | 任何代码 |
| devops | deploy/, .github/workflows/ | 业务代码 |
| sre | docs/runbooks/ | 任何代码 |
| doc-writer | docs/（除 context/ 外） | 任何代码 |

---

## Agent 间通信协议

**文件传递**（主要方式）：
- 每个 Agent 完成后将结果写入约定文件
- 下游 Agent 开始前读取上游产出文件
- 文件格式：混合模式（中文叙述 + YAML/代码块）

**短链式调用**（反馈循环）：
- test-engineer 发现 bug → 直接将错误信息和 `docs/review/{功能}-bugs.md` 路径传给 backend-coder
- security-auditor 发现 Critical 问题 → 直接告知 backend-coder 修复，不等下次迭代

---

## 并行 Agent 调度规则

当多个 Agent 可以并行时，在同一条消息中发起多个 Agent 调用：

```
# 可以并行的情况（互不依赖）：
- api-designer + db-designer
- backend-coder + flutter-coder
- security-auditor + code-reviewer + linter

# 必须串行的情况（有依赖）：
- requirements-analyst 完成后 → architect 才能开始
- architect 完成后 → api-designer 和 db-designer 才能并行开始
- backend-coder 完成后 → test-engineer 才能开始
```

---

## Git 提交规范

每个 Agent 完成工作后提交，commit message 格式：

```
{类型}({模块}): {简短说明}

类型：feat | fix | test | docs | chore | security | refactor
模块：backend | client | db | deploy | docs

示例：
feat(backend): 新增财务报表接口
test(backend): 财务报表模块测试用例
docs(api): 财务报表 API 接口文档
security: 修复入库单多租户隔离漏洞
```

---

## 代码质量门禁

以下情况**不得提交**：
- `go build ./...` 失败
- `go test ./...` 有失败用例
- 存在 security-auditor 标记的 Critical 级别问题
- 存在 code-reviewer 标记的 blocking 级别问题

---

## 项目强制规则

### 多租户隔离
- `shop_id` **永远**从 JWT token 中提取，使用 `middleware.GetShopID(c)`
- **绝不**从请求参数、URL 或请求体中读取 `shop_id`
- 所有数据库查询必须带 `WHERE shop_id = ?` 条件

### 库存变更
- 入库/出库审核通过时，必须在同一事务中同时完成：
  1. 更新 `inventories` 表数量
  2. 写入 `inventory_logs` 流水记录
- 出库前必须校验库存充足，不足时返回错误并回滚

### Schema 管理
- 表结构变更：修改 `backend/schema/schema.sql` + `backend/internal/model/` 对应 model
- 启动时自动 AutoMigrate，无单独迁移文件
- **禁止**为每个新业务字段修改表结构，使用 `custom_fields JSON` 动态扩展

### 种子数据
- 测试数据以 SQL 文件形式维护：`backend/seeds/<shop_code>.sql`
- 通过 `sh scripts/dev.sh seed <shop_code>` 执行（内部用 `docker exec` 注入 MySQL 容器）
- 每个门店一个文件，SQL 文件顶部包含 TRUNCATE，每次执行完整重建

### Go 命令
- 所有 Go 命令前须确保 PATH：`export PATH="/opt/homebrew/bin:$PATH"`
- 或直接使用 `sh scripts/dev.sh` 脚本（已内置 PATH）