wangjia
f8524bfa3f
新增 10 个专职 Agent 定义文件（.claude/agents/）： - requirements-analyst: 需求分析，输出用户故事和验收标准 - architect: 技术方案设计，模块划分和接口定义 - api-designer: RESTful API 规范，混合格式文档 - db-designer: MySQL 表设计和迁移脚本 - backend-coder: Go 后端实现，严格分层架构 - flutter-coder: Flutter 跨端 UI 实现 - test-engineer: 自动化测试，只写测试不改业务代码 - linter: 代码风格检查和自动修复 - code-reviewer: 代码质量审查，输出审查报告 - security-auditor: 安全漏洞扫描，重点多租户隔离 - devops: Dockerfile 和 CI/CD 流水线 - sre: 故障诊断和运维 Runbook - doc-writer: API 文档和用户手册 新增 CLAUDE.md Orchestrator 规则： - 自动判断任务类型并选择 Agent 组合 - 并行/串行调度规则（api+db 并行，backend+flutter 并行） - Agent 边界规则（每个 Agent 只能写自己职责范围的文件） - 文件传递 + 短链式反馈的混合通信协议 - Git 提交规范和质量门禁 新增 docs/context/project.md： - 所有 Agent 的共享项目上下文 - 技术栈、目录结构、核心业务规则、已实现接口列表 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
162 lines
5.4 KiB
Markdown
162 lines
5.4 KiB
Markdown
# 酒店仓库管理系统 — 项目上下文
|
||
|
||
> 所有 Agent 在开始工作前必须读取此文件，了解项目全貌。
|
||
|
||
## 项目简介
|
||
|
||
面向酒店的酒水仓库管理系统。核心特点：
|
||
- **多租户**：一个账号对应一个酒店，数据完全隔离（通过 `hotel_id` 字段）
|
||
- **付费授权**：许可证绑定设备 ID，支持试用/年付/买断
|
||
- **跨端客户端**：Flutter 单一代码库，支持 Windows / Web / macOS / iOS / Android
|
||
|
||
## 技术栈
|
||
|
||
```yaml
|
||
后端:
|
||
语言: Go 1.26
|
||
框架: Gin（HTTP）+ GORM（ORM）
|
||
数据库: MySQL 8.0
|
||
认证: JWT（HS256），Access Token 60分钟，Refresh Token 7天
|
||
模块路径: github.com/wangjia/jiu/backend
|
||
|
||
前端:
|
||
框架: Flutter 3.x
|
||
状态管理: Riverpod
|
||
HTTP客户端: Dio
|
||
路由: go_router
|
||
目录: client/
|
||
|
||
数据库迁移:
|
||
工具: golang-migrate
|
||
迁移文件: backend/migrations/
|
||
完整schema: backend/schema/schema.sql
|
||
```
|
||
|
||
## 项目目录结构
|
||
|
||
```
|
||
jiu/
|
||
├── backend/
|
||
│ ├── main.go # 入口
|
||
│ ├── config/config.yaml # 配置（本地开发）
|
||
│ ├── internal/
|
||
│ │ ├── handler/ # HTTP 处理器（每模块一文件）
|
||
│ │ ├── service/ # 业务逻辑层
|
||
│ │ ├── model/ # GORM 数据模型
|
||
│ │ ├── middleware/auth.go # JWT 验证 + 租户注入
|
||
│ │ └── router/router.go # 路由注册
|
||
│ ├── migrations/ # 版本迁移 SQL
|
||
│ └── schema/schema.sql # 完整建表 SQL
|
||
├── client/ # Flutter 跨端客户端
|
||
├── deploy/
|
||
│ └── docker-compose.yml # 本地开发：MySQL + Adminer
|
||
└── docs/
|
||
├── context/project.md # 本文件
|
||
├── requirements/ # 需求文档
|
||
├── architecture/ # 架构设计
|
||
├── api/ # API 接口规范
|
||
├── review/ # 代码审查报告 + bug 报告
|
||
├── security/ # 安全审计报告
|
||
└── runbooks/ # 运维操作手册
|
||
```
|
||
|
||
## 核心数据模型
|
||
|
||
```yaml
|
||
主要表:
|
||
hotels: # 酒店（租户）
|
||
users: # 用户（含 hotel_id）
|
||
licenses: # 许可证（含 device_id 绑定）
|
||
products: # 商品（含 custom_fields JSON 动态扩展）
|
||
warehouses: # 仓库
|
||
partners: # 往来单位（supplier/customer）
|
||
stock_in_orders: # 入库单（draft→pending→approved/rejected）
|
||
stock_in_items: # 入库单明细
|
||
stock_out_orders: # 出库单
|
||
stock_out_items: # 出库单明细
|
||
inventory: # 实时库存（唯一键：hotel_id+warehouse_id+product_id）
|
||
inventory_logs: # 库存流水（每次变动记录）
|
||
inventory_checks: # 盘点单
|
||
finance_records: # 财务流水
|
||
number_rules: # 单号生成规则
|
||
```
|
||
|
||
## 关键业务规则
|
||
|
||
1. **多租户**：所有查询必须带 `hotel_id` 条件，`hotel_id` 只从 JWT 获取，不信任请求参数
|
||
2. **库存变更**：入库/出库审核通过时，在同一事务中更新 `inventory` + 写 `inventory_logs`
|
||
3. **出库前检查**：出库审核时必须校验库存充足，不足时返回错误并回滚事务
|
||
4. **单号生成**：通过 `number_rules` 表事务安全生成，格式 `{前缀}{日期}{6位序号}`
|
||
5. **扩展字段**：所有业务主表含 `custom_fields JSON`，用于存储动态业务字段
|
||
|
||
## 已实现的 API 接口
|
||
|
||
```yaml
|
||
认证:
|
||
- POST /api/v1/auth/login
|
||
- POST /api/v1/auth/refresh
|
||
|
||
许可证:
|
||
- POST /api/v1/license/activate
|
||
- GET /api/v1/license/verify
|
||
- POST /api/v1/license/deactivate
|
||
|
||
商品:
|
||
- GET/POST /api/v1/products
|
||
- PUT/DELETE /api/v1/products/:id
|
||
|
||
仓库:
|
||
- GET/POST /api/v1/warehouses
|
||
- PUT/DELETE /api/v1/warehouses/:id
|
||
|
||
往来单位:
|
||
- GET/POST /api/v1/partners
|
||
- PUT/DELETE /api/v1/partners/:id
|
||
|
||
入库:
|
||
- GET/POST /api/v1/stock-in/orders
|
||
- GET /api/v1/stock-in/orders/:id
|
||
- PUT /api/v1/stock-in/orders/:id/submit
|
||
- PUT /api/v1/stock-in/orders/:id/approve
|
||
- PUT /api/v1/stock-in/orders/:id/reject
|
||
|
||
出库:
|
||
- GET/POST /api/v1/stock-out/orders
|
||
- GET /api/v1/stock-out/orders/:id
|
||
- PUT /api/v1/stock-out/orders/:id/submit
|
||
- PUT /api/v1/stock-out/orders/:id/approve
|
||
- PUT /api/v1/stock-out/orders/:id/reject
|
||
|
||
库存:
|
||
- GET /api/v1/inventory
|
||
- GET /api/v1/inventory/logs
|
||
- POST/GET /api/v1/inventory/checks
|
||
|
||
数据导入:
|
||
- POST /api/v1/import/products (Excel/CSV)
|
||
- POST /api/v1/import/partners (Excel/CSV)
|
||
```
|
||
|
||
## 本地开发启动
|
||
|
||
```bash
|
||
# 1. 启动数据库
|
||
cd deploy && docker compose up -d
|
||
|
||
# 2. 启动后端（会自动 AutoMigrate）
|
||
cd backend && export PATH="/opt/homebrew/bin:$PATH" && go run main.go
|
||
|
||
# 3. 运行测试
|
||
cd backend && go test ./... -cover
|
||
|
||
# 4. 数据库管理界面
|
||
# 打开 http://localhost:8888，服务器:mysql, 用户:root, 密码:password, 数据库:jiu_db
|
||
```
|
||
|
||
## 文档索引
|
||
|
||
| 文档 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| 本文件 | docs/context/project.md | 项目全貌，所有 Agent 必读 |
|
||
| Schema | backend/schema/schema.sql | 完整数据库建表 SQL |
|