jiu/CLAUDE.md

酒库管理系统 — 项目规则与 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）

前端 URL 配置

• 所有后端 URL 必须通过 AppConfig 读取（client/lib/core/config/app_config.dart）
• 禁止在任何 provider / repository / widget 中硬编码 localhost:8080 或任何 IP/域名
• 使用：AppConfig.apiBaseUrl、AppConfig.healthUrl、AppConfig.versionUrl

前端平台判断

• 使用 dart:io 的 Platform 类前，必须先检查 kIsWeb（import 'package:flutter/foundation.dart'）
• Web 平台不支持 dart:io，直接使用会在 Web 构建时崩溃

表格列头筛选

• 可筛选列使用 FilterableColumnHeader（来自 widgets/multi_select_dropdown.dart）
• 不要在 toolbar 放独立的筛选按钮，筛选入口应内嵌在列头
• 列定义使用 ColDef，可隐藏列用 ColumnToggleButton 控制

权限中间件（已全局挂载）

• middleware.ReadOnly()：已挂载到主 api 路由组，只读用户（role=readonly）所有写操作自动返回 403
• middleware.AdminOnly()：挂载在 /users 路由组，仅管理员可管理用户
• 新增写操作路由时，默认受 ReadOnly() 保护；若仅管理员可用，需加入 AdminOnly() 子组

并发安全（数据库操作）

• 在同一事务内读后写的操作，必须用 FOR UPDATE 锁行：

  tx.Set("gorm:query_option", "FOR UPDATE").Where(...).First(&model)
  

• 适用场景：单号生成（number_rules）、库存扣减（inventories）、任何 check-then-act 模式