docs: 完善项目说明和注释

2026-05-26 11:06:13 +08:00
commit cd70caafbc
29 changed files with 3165 additions and 0 deletions
@@ -0,0 +1,68 @@
+-- 001_initial_schema.sql
+-- 这个迁移文件负责创建项目的基础表结构。
+-- 迁移脚本会按文件名排序执行，所以 001 会先于 002 执行。
+
+-- 门店表：保存每个门店的基础信息。
+-- deleted_at 用于软删除，业务查询通常只查询 deleted_at IS NULL 的数据。
+CREATE TABLE IF NOT EXISTS stores (
+  id INT UNSIGNED NOT NULL AUTO_INCREMENT,
+  name VARCHAR(100) NOT NULL COMMENT '门店名称',
+  address VARCHAR(255) NULL COMMENT '门店地址',
+  phone VARCHAR(30) NULL COMMENT '门店联系电话',
+  status ENUM('ACTIVE', 'INACTIVE') NOT NULL DEFAULT 'ACTIVE' COMMENT '门店状态',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
+  deleted_at DATETIME(3) NULL COMMENT '软删除时间，NULL 表示未删除',
+  PRIMARY KEY (id),
+  KEY idx_stores_status (status),
+  KEY idx_stores_deleted_at (deleted_at)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='门店表';
+
+-- 角色表：保存系统内可分配给员工的角色。
+-- code 是稳定的角色编码，适合在代码里做权限判断；name 是展示给用户看的名称。
+CREATE TABLE IF NOT EXISTS roles (
+  id INT UNSIGNED NOT NULL AUTO_INCREMENT,
+  code VARCHAR(50) NOT NULL COMMENT '角色编码，代码里使用这个值做权限判断',
+  name VARCHAR(50) NOT NULL COMMENT '角色名称',
+  description VARCHAR(255) NULL COMMENT '角色说明',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_roles_code (code)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='角色表';
+
+-- 员工表：保存员工基础资料，并通过 store_id 关联所属门店。
+-- 这里不直接存角色列表，因为一个员工可以有多个角色，角色关系放在 employee_roles 表。
+CREATE TABLE IF NOT EXISTS employees (
+  id INT UNSIGNED NOT NULL AUTO_INCREMENT,
+  store_id INT UNSIGNED NOT NULL COMMENT '所属门店',
+  name VARCHAR(50) NOT NULL COMMENT '员工姓名',
+  phone VARCHAR(30) NOT NULL COMMENT '员工手机号',
+  status ENUM('ACTIVE', 'INACTIVE') NOT NULL DEFAULT 'ACTIVE' COMMENT '员工状态',
+  remark VARCHAR(500) NULL COMMENT '备注',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3),
+  deleted_at DATETIME(3) NULL COMMENT '软删除时间，NULL 表示未删除',
+  -- MySQL 的唯一索引允许多个 NULL。
+  -- 软删除后 active_phone 会变成 NULL，这样同一门店可以重新录入相同手机号的新员工。
+  active_phone VARCHAR(30) GENERATED ALWAYS AS (
+    CASE WHEN deleted_at IS NULL THEN phone ELSE NULL END
+  ) STORED COMMENT '仅用于保证同一门店未删除员工手机号唯一',
+  PRIMARY KEY (id),
+  UNIQUE KEY uk_employees_store_active_phone (store_id, active_phone),
+  KEY idx_employees_store_status (store_id, status),
+  KEY idx_employees_deleted_at (deleted_at),
+  CONSTRAINT fk_employees_store_id FOREIGN KEY (store_id) REFERENCES stores (id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='员工表';
+
+-- 员工角色关系表：连接 employees 和 roles。
+-- 一个员工可以有多个角色，一个角色也可以分配给多个员工，所以这是多对多关系表。
+CREATE TABLE IF NOT EXISTS employee_roles (
+  employee_id INT UNSIGNED NOT NULL,
+  role_id INT UNSIGNED NOT NULL,
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
+  PRIMARY KEY (employee_id, role_id),
+  KEY idx_employee_roles_role_id (role_id),
+  CONSTRAINT fk_employee_roles_employee_id FOREIGN KEY (employee_id) REFERENCES employees (id) ON DELETE CASCADE,
+  CONSTRAINT fk_employee_roles_role_id FOREIGN KEY (role_id) REFERENCES roles (id)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci COMMENT='员工角色关系表';
@@ -0,0 +1,27 @@
+-- 002_seed_demo_data.sql
+-- 这个迁移文件负责写入项目启动时需要的演示数据。
+-- 它依赖 001_initial_schema.sql 先创建好 stores 和 roles 表。
+
+-- 初始化一个示例门店，方便本地直接创建员工并测试 CRUD。
+-- 指定 id = 1 是为了 README 里的示例请求可以稳定使用 storeId: 1。
+INSERT INTO stores (id, name, address, phone, status)
+VALUES (1, '示例门店', '请改成你的真实门店地址', '13800000000', 'ACTIVE')
+ON DUPLICATE KEY UPDATE
+  name = VALUES(name),
+  address = VALUES(address),
+  phone = VALUES(phone),
+  status = VALUES(status);
+
+-- 初始化常见角色。
+-- code 用于代码和接口里的稳定标识，name/description 用于页面或接口展示。
+INSERT INTO roles (code, name, description)
+VALUES
+  ('store_manager', '店长', '负责门店日常管理、排班和权限审批'),
+  ('cashier', '收银员', '负责收银、订单核对和基础会员操作'),
+  ('kitchen', '后厨', '负责出品、备货和库存相关操作'),
+  ('part_time', '兼职', '临时员工，默认只开放基础操作'),
+  ('admin', '管理员', '系统管理角色，仅授予可信人员')
+-- 如果重复执行迁移或本地重新导入数据，已存在的角色会更新名称和说明，避免重复插入报错。
+ON DUPLICATE KEY UPDATE
+  name = VALUES(name),
+  description = VALUES(description);