wangjia/jiu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 130 Wiki Activity
Files
31ea370cea954d945240ee13b8f485dc4ff00018
jiu/docs/context/project.md
T
wangjia 31ea370cea fix(backend): JWT config mapstructure tag 修复 + 模型从 hotel 重构为 shop 
- 修复 JWTConfig 缺少 mapstructure tag 导致 access_expire_min 解析为 0，
  token 签发即过期，所有 API 请求返回 401
- 全部 config struct 补齐 mapstructure tag（secret/dsn/hmac_secret 等）
- 模型层从 hotel/HotelID 统一重命名为 shop/ShopID
- 删除旧 migrations（001-004），新增 001_init 综合迁移文件
- 更新 schema.sql、testutil、handler/service/model 相关引用

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-07 22:20:12 +08:00

7.2 KiB
Raw Blame History

酒店仓库管理系统 — 项目上下文

所有 Agent 在开始工作前必须读取此文件，了解项目全貌。

项目简介

面向酒水门店的仓库管理系统。核心特点：

  • 多租户：一个账号对应一个门店，数据完全隔离（通过 shop_id 字段）
  • 付费授权：许可证绑定设备 ID，支持试用/年付/买断
  • 跨端客户端：Flutter 单一代码库，支持 Windows / Web / macOS / iOS / Android

技术栈

后端:
  语言: 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/                   # 运维操作手册

核心数据模型

主要表:
  shops:              # 酒店（租户）
  users:               # 用户（含 shop_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:           # 实时库存（唯一键：shop_id+warehouse_id+product_id）
  inventory_logs:      # 库存流水（每次变动记录）
  inventory_checks:    # 盘点单
  finance_records:     # 财务流水
  number_rules:        # 单号生成规则

关键业务规则

  1. 多租户：所有查询必须带 shop_id 条件，shop_id 只从 JWT 获取，不信任请求参数
  2. 库存变更：入库/出库审核通过时，在同一事务中更新 inventory + 写 inventory_logs
  3. 出库前检查：出库审核时必须校验库存充足，不足时返回错误并回滚事务
  4. 单号生成：通过 number_rules 表事务安全生成，格式 {前缀}{日期}{6位序号}
  5. 扩展字段：所有业务主表含 custom_fields JSON，用于存储动态业务字段

已实现的 API 接口

认证:
  - 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)

Flutter 客户端结构

client/
├── pubspec.yaml                        # 依赖：riverpod, go_router, dio, intl
├── lib/
│   ├── main.dart                       # 入口，ProviderScope + MaterialApp.router
│   ├── core/
│   │   ├── theme/app_theme.dart        # 颜色常量 + ThemeData
│   │   ├── auth/auth_state.dart        # AuthUser, AuthState, AuthNotifier
│   │   ├── api/api_client.dart         # Dio 封装
│   │   └── router/app_router.dart      # go_router 路由定义（含登录重定向）
│   ├── screens/
│   │   ├── auth/login_screen.dart      # 登录页（蓝色背景 + 居中卡片）
│   │   ├── shell/app_shell.dart        # 主框架（顶栏 + 侧边栏 + 状态栏）
│   │   ├── stock_in/                   # 入库单列表 + 新建表单
│   │   ├── stock_out/                  # 出库单列表
│   │   ├── inventory/                  # 库存查询 + 盘点
│   │   ├── partners/                   # 往来单位
│   │   ├── finance/                    # 财务管理
│   │   ├── products/                   # 商品管理
│   │   └── settings/                   # 系统设置（用户/仓库/编号规则）
│   └── widgets/
│       ├── page_scaffold.dart          # Tab 页面封装
│       ├── data_table_card.dart        # 含工具栏+分页的数据表格
│       ├── status_badge.dart           # 状态标签（草稿/待审/已审/拒绝）
│       └── form_dialog.dart            # 弹窗表单封装

启动 Flutter 客户端（需先安装 Flutter）：

cd client
flutter pub get
flutter run -d macos   # macOS 桌面
flutter run -d chrome  # Web

本地开发启动

# 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
Reference in New Issue View Git Blame Copy Permalink