软件设计规范
大约 13 分钟languagejava
开发规范
- 先在开发用电脑运行项目，保证能够正常启动，再编译部署到服务器上
- 有
Bean名称冲突（文件名冲突），修改新添加的文件，不要修改之前用到的文件和Bean - 新增的接口统一采用
POST Body传参对象，如果仅要传递主键或者一个字符串则使用Map对象接受
public ResponseResult query01(@RequestBody Map<String,Object> params){
Integer id = (Integer)params.get("val");
....
}
实现细节
单表表格
- 显示行号、拖拽行调整上下顺序、拖拽列调整列左右顺序、拖拽调整列宽、调整列名称、斑马纹
- 列头不要有点击排序功能、手动输入过滤功能
- 行内编辑，表格要显示表格线，拖拽调整列宽鼠标有找寻目标
CRUD
新增一行数据使用 mybatis 自动生成的 insertSelective - 有数据的字段才写入，其他字段使用数据库默认值。修改数据使用 updateByPrimaryKey - 要整体修改，可能某些字段要从有值状态修改为空值。
创建时间
DB默认值当前时间
最后一次修改时间
在服务实现类的方法updateByPrimaryKey 中修改字段 update_time - 或者使用 Navicat 中的更新时间。
返回值
项目中制作 统一返回对象类 ，微服务架构下制作名称为 项目名称-common 的模块，所有其他微服务模块都会依赖该模块，该通用模块中不包含 web-mvc 相关的功能，提供的功能如下
constant包下包含多个常量类，其中属性使用public static final String类型声明常量- 包
utils下的类RSAUtils提供JWT功能中创建公钥、私钥对象功能、根据公钥字符串获取公钥对象、根据私钥字符串获取私钥对象 - 工具类
TokenParseUtils提供解析token的功能 - 包
vo提供实体类CommonResponse，作为统一返回对象类（code= 0 表示请求成功，其他情况下是报错代码，前端根据该属性判断请求是否成功）
命名规范
仓库管理单据
| 单据名称 | 最佳实践 | 可选 |
|---|---|---|
| 采购订单 | Purchase Order | |
| 收货单 | Goods Received Note | Receiving Report |
| 采购退货单 | Purchase Return Note | Return to Vendor |
| 车间领料单 | Pick List | Material Requisition Form |
| 补料单 | Replenishment Request | |
| 调拨单 | Inventory Transfer Request | Transfer Order |
| 生产订单 | Production Order | Work Order |
| 生产入库单 | Finished Goods Receipt | Production Receipt |
| 销售订单 | Sales Order | |
| 发货单 | Shipping Note - 要求的发货物品清单，相当于预发货单 | Picking List - 仓库人员根据SO拣选货物时使用的清单 Packing List - 放入包裹内，详细说明箱内物品的清单，随货同行 |
| 销售出库单 | Sales Delivery Note | Dispatch Note |
| 销售退货单 | Sales Return Note | Return Merchandise Authorization |
| 盘点单 | Inventory Count Sheet | Stock Take Sheet |
| 盘点盈亏调整单 | Inventory Adjustment Document | |
| 其他入库单 | Miscellaneous Receipt | 用于处理非采购、非生产性质的入库，如赠品入库、客户样品入库等 |
| 其他出库单 | Miscellaneous Issue | 用于处理非生产领料、非销售性质的出库，如研发领料、样品赠送、损耗出库等 |
| 班次、班组 | shift, team | 班次 = shift = 早中晚班, 班组 = team = A,B,C组 |
| 白坯 | Greige Fabric | 来自Grok最推荐 |
自定义命名规范
| 场景 | 规范 | 案例 | 备注 |
|---|---|---|---|
| 类、枚举、接口 | 大驼峰 | LineDetail | |
| 方法 | 小驼峰 | doSomething | |
| 存储过程基础资料 | usp_bd_ | ||
| 存储过程序时表 | usp_rpt_chro_ | ||
| 存储过程汇总表 | usp_rpt_sum_ | ||
| 存储过程其他 | usp_ | ||
| 等待被添加的对象 | entriesToAddOnCommit | ||
| 有标准的对比 | actual,expected | 前面是实际值，后面是标准值 | |
| 定制化的工厂 | customizeBeanFactory | ||
| 允许XX操作 | allowXxx | ||
| 加载XX信息 | loadBeanDefinitions | ||
| 通用的 | generic | ||
| 前置处理器 | XxxPreProcessor | ||
| 后置处理器 | XxxPostProcessor | ||
| 不包含xx | selectProductFileNonDeprecated | ||
| 是否存在 | isExists | ||
| 决定当前的配置 | determinCurrentLookupKey | ||
| 处理，工序，加工 | process | ||
| 多种操作 | OP_READ、OP_WRITE、OP_WAIT、OP_AUDIT | ||
| 容量 | capacity | ||
| 源头目标 | src、dst | ||
| 包含读写操作 | XxxHandler | ||
| 解析协议或转换类型 | parseXxx | ||
| 循环次数 | loopNumber | ||
| 为复杂逻辑制作的启动器 | XxxBootstrap | ||
| 前一个下一个 | prev,next | ||
| 缓存 | XxxCache | ||
| 某某事件 | ResolveSerialDataEvent | ||
| 某某监听器 | ResolveSerialDataListener | ||
| 某某解析器 | XxxResolver,XxxParser,XxxHandler,XxxProcessor | ||
| 延迟推迟的 | deferredHandler | ||
| 元数据 | Metadata | ||
| 候选人 | candidate | 等待被加载，被使用的，getCandidateConfigs | |
| 某属性的数量 | numLegs | 后面使用名词复数 | |
| 保留的、未使用的 | reserved | ||
| 起始、终止、创建时间 | start_time,end_time,create_time | ||
| 创建与修改相关 | create_time,create_user,update_time,update_user | 具体到秒钟 | update表示最后一次修改时间、人员 |
| 获取数据 | obtain | SpringSecurity从http获取用户名 | |
| 托盘、货架 | pallet, cube | ||
| 加密/未加密的密码 | ciphertext password / plaintext password | ||
| SpringSecurity加密密码 | rawPassword / encodedPassword | SpringSecurity源码中使用的原始密码/加密后的密码 |
三个班次轮流
在英语中，用来形容这种 24小时不间断轮班生产 的系统，最常用的术语是： "Shift Work"（轮班工作） 具体到 A、B、C 三个班次轮流工作 的情况，可以称为： "Three-shift System"（三班制） "24/7 Shift Rotation"（24小时轮班制） 更具体的表达： "Rotating Shifts"（轮换班次） 强调不同班次（A→B→C）的轮换。 例："Our factory operates on rotating shifts to ensure 24-hour production." "8-hour Shifts in Rotation"（8小时轮班制） 强调每个班次工作8小时。 "Continuous Shift Work"（连续轮班工作） 强调不间断生产。 其他相关术语： "Day Shift"（白班） / "Night Shift"（夜班） / "Swing Shift"（中班，如果有的话） "Shift Schedule"（班次表） 所以，在描述 A→B→C 三个班次轮流工作 8 小时 的体系时，"Three-shift System" 或 "Rotating 8-hour Shifts" 是最合适的表达方式。
保留字
mysql中字段不要使用show，可以使用visible- 不要使用
status，使用state
UI/UX
FastStone
色调 - 220，饱和度 - 240，亮度 - 120 红 - 255，绿 - 0，蓝 - 128
PicPick
H - 234，S - 255，L - 128 R - 255，G - 0 ，B - 128 16进制：FF0080
代码中注释的字体颜色
#c8c8c8vb6版本软件表格选中行的背景色#ffcf31选中行背景色
#ffcc34表格列头背景灰色
#f5f7fa灰色背景
#f5f5f5数据状态颜色：正常有效黑色，已审核蓝色
#0f0cd0，作废红色，驳回#953735
技术选型
webTable
单据的使用要求
- 在单元格中录入字符、数字
- 输入过程中显示下拉单选，输入中有过滤效果 要求可实现两种模式： 2.1. 只能选择下拉的选项 2.2. 显示下拉选项的同时也可以手动录入不存在的新内容 2.3. 选择后有触发事件可执行自定义代码
- 点击单元格内小按钮弹出带有表格的模态窗，可过滤后单选、多选
- 单元格内点击按钮显示日历，选择日期
- 显示色块
- 锁定为不可编辑状态
- 格式化数字的样式（保留一位小数，或者两位小数）
- 下拉单选更换为下拉显示表格，例如显示的表格中同时显示列： 产品编号、产品名称、规格型号
报表的使用要求
- 可过滤 1.1. 单选过滤 1.2. 多选过滤 1.3. 手动输入模糊查询过滤
- 点击列头可排序
- 拖拽调整列宽
- 拖拽调整列顺序
- 显示序号列
- 更换字体颜色、行背景色
- 有单击事件、双击事件
- 可分组折叠，并且带有分组小计
- 报表总计（在表格 footer 上显示汇总数据）
- 导出 excel,pdf
- 通过代码清除所有过滤条件
- 可通过异步请求数据后填充数据到表格
用户操作
表单
- 一直使用 label 提示用户要输入的内容
- 避免Z模式，尽量避免横向两个文本框，产生Z模式后用户无法判断输入顺序
- 标签文字使用右对齐
- 平铺所有要素，尽量避免下拉选择（网上有人提倡相反的设计）
- 尽量使用 placeHolder,输入格式，文字数量要求（0/100）
- 诱导性按钮使用 CTA 样式，其他次要按钮显示为文字模式
树形结构
要带有根节点 “全部” ，这样可以一次全选所有子节点
报表
- 每个用户可自定义列宽、列隐藏、列排序、列标题名称
- 自定义每页显示的行数
- 后台做了分页显示同时也要显示汇总数量
- 导出和打印过滤后的数据 - 用户当前看到的数据
- 在序时表页面有弹出模态窗编辑功能，保存后自动刷新表格，不要清除过滤条件。可能用户前面做了多个列的过滤条件，找到目标进行修改，保存后系统会自动刷新表格，如果此时自动清理掉所有过滤条件可能导致用户找不到刚才编辑的数据
单据设计
- 新增后根据主键重新从DB查询获取新对象并返回 - DB会给部分字段填充默认值返回新增的对象可以使前端获得新增数据的主键
- 修改后返回主键 - 提供 postProcessor 的可能性，在 postProcessor 中执行关联业务逻辑
- 删除后返回主键 - 提供 postProcessor 的可能性，在 postProcessor 中执行关联业务逻辑
- 单据新增、修改、删除都要有 postProcessor 。新增后同步生成相关的其他单据修改后同步修改相关的其他单据数据，删除后同步删除相关的其他单据数据
- serviceImpl 执行 dao 方法之前要对传入的实例对象加工，例如根据当前基础资料补全信息（一般用于信息冗余，将此时此刻的基础资料中的名称填充到单据数据表中）然后写入表中。这种设计在多人协同开发时容易引起误解，可以采用下面折中方式：单据中只保存基础资料的唯一键，创建字段保存单据进度、状态数据
- 由于调用 dao 方法前后都有可能添加业务逻辑所以 serviceImpl 方法要使用 Transaction
- 上面的设计原则参考“呼叫系统”https://gitee.com/chanchaw/callcenter.git
数据库设计
单据类型
# mysql8.2版本使用 utf8mb4_0900_ai_ci
create table bill_type
(
id varchar(50) not null comment '单据类型编号' primary key,
bill_type_name varchar(50) not null comment '单据类型名称',
access_mode int null comment '1增加库存，-1减少库存，0不影响库存',
allow_manual tinyint(1) default 1 null comment '1允许手动制作，0只能生成',
storage_id varchar(50) null comment '所属仓库编号',
inout_type int default 1 null comment '在收发存汇总表中体现的栏目(本期入库:1;本期出库:-1;不体现：0)',
constraint bill_type_bill_type_name_uindex
unique (bill_type_name)
)
comment '单据类型'
COLLATE='utf8mb4_0900_ai_ci'
ENGINE=InnoDB;
单表
安装使用字段 state 而不是 status 为避免同 mysql,java 的保留字冲突，同样的，排序序号不使用 order 而是采用 seq，并且使用数据类型 float，并不使用整数类型，为之后重置排序时计算中间值方便。
注意，使用 MySQL8.2 之后使用排序规则 utf8mb4_0900_ai_ci
create table sys_user
(
id bigint auto_increment comment '自增主键' primary key,
username varchar(100) default '' null comment '登录账号，为保证和SrpingSecurity一致',
password varchar(100) default '' null comment '登录密码密文，为保证和SpringSecurity一致',
full_name varchar(100) default '' null comment '登录账号的姓名，人名',
pwd varchar(100) default '' null comment '明文密码',
non_locked int default 1 null comment '未被锁定,为适应SpringSecurity',
non_expired int default 1 null comment '账号未过期',
non_password_expired int default 1 null comment '密码未过期',
terminal varchar(10) default '111' null comment '可使用的终端，从左到右顺序表示：PC，触摸屏，PDA。3个1表示该账号可以登录到3个终端。长度设计为10，即最多可区分10种不同的终端设备',
email varchar(100) default '' null comment 'email地址',
employee_sid varchar(100) default '' null comment '员工编号=employee.sid，单据中默认填充该员工编号',
user_grade varchar(100) default '' null comment '员工、部门主管、资材课、工场长、副总经理、总经理',
data_grade int default 0 null comment '数据级别，默认0表示正常数据，1业务数据异常需要通知使用者，2请求异常需要报警开发者',
category varchar(100) default '' null comment '分类，备用',
alias varchar(100) default '' null comment '别名',
code varchar(100) default '' null comment '编码',
state int default 1 null comment '状态，默认1有效，0停用',
is_delete int default 0 null comment '删除标识，默认0未删除，1表示删除。mybatis-flex默认使用该名称作为逻辑删除的标识',
remark varchar(200) default '' null comment '备注',
sys_remark varchar(100) default '' null comment '系统备注，系统在做自动化操作时用于说明业务逻辑',
seq float default 0 null comment '排序序号',
extra_info json null comment '附加信息',
create_time datetime default CURRENT_TIMESTAMP null comment '创建时间,DB自动填充',
create_user varchar(100) default '' null comment '创建人',
update_time datetime null on update CURRENT_TIMESTAMP comment '最后一次修改时间',
update_user varchar(100) default '' null comment '修改人'
)
# 5.7版本没有 utf8mb4_0900_ai_ci，要使用 utf8mb4_general_ci
comment '用户表'
COLLATE='utf8mb4_0900_ai_ci'
ENGINE=InnoDB;
主从表
下面是明细表，去掉字段 parent_id 则为主表的设计。采用逻辑删除的设计，所有数据都不做真实的删除，标记 state=-1 作为删除
create table exam_paper_main
(
`id` INT auto_increment comment '自增主键' primary key,
`bill_date` datetime default CURRENT_TIMESTAMP not null comment '单据日期，表示业务发生的日期，默认填充当天，用户可修改',
`bill_code` varchar(100) default '' null comment '单据编号',
`seq` float default 0 null comment '排序序号',
`state` INT(11) default 1 NULL comment '状态，默认1有效，0作废，2已审核，3已驳回',
`is_delete` INT(11) NULL DEFAULT '0' COMMENT '删除标识，默认0未删除，1表示删除。mybatis-flex默认使用该名称作为逻辑删除的标识',
`remark` varchar(300) default '' null comment '备注',
`sys_remark` varchar(100) default '' null comment '系统备注，系统在做自动化操作时用于说明业务逻辑',
`create_time` datetime default CURRENT_TIMESTAMP null comment '创建时间',
`create_user` varchar(100) default '' null comment '创建人',
`update_time` datetime null on update CURRENT_TIMESTAMP comment '最后一次修改时间',
`update_user` varchar(100) default '' null comment '最后一次修改人'
)
comment '考试|试卷|明细'
COLLATE='utf8mb4_general_ci'
ENGINE=InnoDB
;
create table exam_paper_detail
(
`id` INT auto_increment comment '自增主键' primary key,
`parent_id` INT default 0 null comment '外键=主表.id',
`seq` float default 0 null comment '排序序号',
`state` INT(11) default 1 NULL comment '状态，默认1有效，0作废，2已审核，3已驳回',
`is_delete` INT(11) NULL DEFAULT '0' COMMENT '删除标识，默认0未删除，1表示删除。mybatis-flex默认使用该名称作为逻辑删除的标识',
`remark` varchar(300) default '' null comment '备注',
`sys_remark` varchar(100) default '' null comment '系统备注，系统在做自动化操作时用于说明业务逻辑',
`create_time` datetime default CURRENT_TIMESTAMP null comment '创建时间',
`create_user` varchar(100) default '' null comment '创建人',
`update_time` datetime null on update CURRENT_TIMESTAMP comment '最后一次修改时间',
`update_user` varchar(100) default '' null comment '最后一次修改人'
)
comment '考试|试卷|明细'
COLLATE='utf8mb4_general_ci'
ENGINE=InnoDB
;