# 一平node.js脚手架

**Repository Path**: zero_0001/yiping-nodejs-cli

## Basic Information

- **Project Name**: 一平node.js脚手架
- **Description**: 一平node.js脚手架是一平软件推出的基于阿里midway框架的后端服务框架。提供了基础的后台功能，包括员工管理、部门管理、角色管理、菜单管理、商品、订单管理等。
- **Primary Language**: TypeScript
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 7
- **Forks**: 1
- **Created**: 2025-01-01
- **Last Updated**: 2026-01-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 一平nodejs脚手架

#### 介绍
一平nodejs脚手架是一平软件架构团队，基于渐进式理念研发的 Node.js 框架，通过自研的业务代码,搭配Midwayjs的依赖注入容器及各种上层模块，组合出适用于不同场景的解决方案。提供了基础的后台功能，包括员工管理、部门管理、角色管理、菜单管理、商品、订单管理等。致力于为用户提供简单、易用、可靠的 Node.js 服务端研发体验

本系统适配的前端web系统为: 一平react脚手架 https://gitee.com/zero_0001/yiping-react-cli

#### 预览

地址: http://test.zero9.work/public/index.html

用户名: admin

密码: aaaa1111

#### 作者

<img src="https://zero9.work/static/media/img/q.jpg" width="256" />


#### 软件架构
软件目录结构基于midway.js确定的基础结构。<br/>
业务代码处于src目录中。<br/>
config -- 基础配置<br/>
controller -- 接收并处理请求<br/>
controller-buyer-uni -- 接收并处理uni-app端会员请求<br/>
controller-staff-web -- 接收并处理web后台员工端请求<br/>
entity -- 实体model类<br/>
job -- 定时任务<br/>
module -- 非midway框架的约定目录，为本项目自约定目录，放公共模块<br/>
service -- 服务层，会被controller层调用<br/>
socket -- webSocket请求层<br/>

#### 代码对应的用户角色
buyer -- 买家用户、消费者用户、软件直接面对的终端用户
staff -- 管理员用户、卖方用户，是一般系统中不可替代的基本角色

#### controller层结构
用户角色->使用设备->业务场景代码

例如：
用户角色(buyer)->使用设备(uni)->业务场景(frontPage用户不需要登录可以看到的界面)

#### 使用设备层区分

使用设备一般分为
uni: 移动端（手机、平板设备等)
web: PC端
screen: 大屏


#### 使用说明

1.  下载项目代码
2.  cnpm i 安装依赖
3.  编写业务代码
4.  npm run dev在开发模式下运行项目
5.  开发完成后，npm run build可以在生产环境下进行构建
6.  pm2 start ./bootstrap.js 可以在pm2中运行

#### module中内置模块

area -- 地区管理<br/>
auth -- 权限、菜单管理<br/>
bpm -- 工作流<br/>
common -- 基本、通用功能<br/>
content -- 内容管理（文章、栏目）<br/>
dataSource -- 数据源管理<br/>
dict -- 字典管理<br/>
errorCode -- 错误码管理<br/>
file -- 文件管理--已作废<br/>
form -- 表单管理<br/>
inventory -- 库存管理<br/>
job -- 任务管理<br/>
log -- 日志管理<br/>
mobile -- 移动端管理<br/>
notify -- 站内信管理<br/>
oa -- 部门、员工管理<br/>
partyApi -- 第三方API<br/>
purchase -- 采购管理<br/>
socket -- webSocket管理<br/>
tenant -- 租户管理<br/>
tradeOrder -- 商城管理<br/>

module中各个model对象，因为和数据库表结构相关，原本是放置在module各个模块中，但出现了在npm run build后，在pm2运行时，typeorm无法加载相关entity的问题，所以后续统一放置在了src/entity目录下。

核心模块主要分为如下几个部分：
1. 用户、角色、权限、部门、岗位管理
2. 内容管理(简化版cms)，文章、栏目管理
3. 商品、订单管理
4. 物料采购、库存、领用管理

/api/buyer/uni/frontPage/goods/goods/page.json 获得商品分页列表
/api/buyer/uni/userCenter/trade/tradeOrder/buy.json?data=%7B%22data%22:%7B%22goodsId%22:%221%22,%22selectedNum%22:1%7D%7D&shopId=1 商品下单
data=
{"data":{"goodsId":"1","selectedNum":1}} 进行encodeURIComponent 编码
goodsId: 商品id
selectedNum: 购买数量
shopId写死为1

/api/buyer/uni/userCenter/trade/tradeOrder/wxpayTransactionsNative.json?id=XXX 此订单，在微信支付端形成微信订单，返回格式如下：
"code":0,"message":"","data":{"status":200,"data":{"code_url":"weixin://wxpay/bizpayurl?pr=uC3LmsNz1"}},"msg":""}

其中，需要把code_url，在页面中形成二维码进行显示

/api/buyer/uni/userCenter/trade/tradeOrder/getById.json?id=XXX 查询一个订单的状态

其中data.tradeState === 'SUCCESS' 是订单支付成功的状态

{
  "code": 0,
  "message": "",
  "data": {
    "id": "2025103117290984815890",
    "trade_state": "SUCCESS",
    ,...
  },
  "msg": ""
}

/api/staff/web/userCenter/trade/tradeOrder/auditRefund.json?id=XXX 对一个订单进行全额退款

开发规范: 

任何标识符, 默认只由大小写英文字母及数字组成, 不包含其它文本. 数据库中的标识符命名允许出现_下划线.

代码中的命名严禁使用拼音与英文混合的方式, 更不允许直接使用中文的方式

标识符默认使用lowerCamelCase风格, 必须遵从驼峰形式. 有特别约定的除外. 单词默认使用单数形式.

常量命名全部大写, 单词间用下划线隔开

不允许出现任何魔法值（即未经定义的常量）直接出现在代码中

不要使用一个常量类维护所有常量, 应该按常量功能进行归类, 分开维护

尽量不要在接口里定义变量, 如果一定要定义变量, 肯定是与接口方法相关, 并且是整个应用的基础常量

接口类中的方法和属性不要加任何修饰符号（public 也不要加）, 保持代码的简洁性, 并加上有效的注释

可变参数必须放置在参数列表的最后.

IDE的text file encoding设置为UTF-8; IDE中文件的换行符使用Unix格式, 不要使用windows格式

方法体内的执行语句组、变量的定义语句组、不同的业务逻辑之间或者不同的语义之间插入一个空行

所有的枚举类型字段必须要有注释, 说明每个数据项的用途

专有名词与关键字保持英文原文即可

注释掉的代码尽量要配合说明, 而不是简单的注释掉

好的命名、代码结构是自解释的, 注释力求精简准确、表达到位 

数据库规约

表名、字段名必须使用小写字母或数字；禁止出现数字开头, 禁止两个下划线中间只出现数字

表名不使用复数名词

禁用保留字

库名与应用名称尽量一致

表必备一字段：id varchar(128) uuid

如果修改字段含义或对字段表示的状态追加时, 需要及时更新字段注释

字段允许适当冗余, 以提高性能, 但是必须考虑数据同步的情况

单表行数超过500万行或者单表容量超过2GB, 才推荐进行分库分表

合适的字符存储长度, 不但节约数据库表空间、节约索引存储, 更重要的是提升检索速度

如果有order by的场景, 请注意利用索引的有序性

不要使用count(列名)或count(常量)来替代count(*)

在代码中写分页查询逻辑时, 若count为0应直接返回, 避免执行后面的分页语句

不得使用外键, 一切外键概念必须在应用层解决

禁止使用存储过程, 存储过程难以调试和扩展, 更没有移植性

推荐尽量少用else, if-else的方式可以改写成： if(condition){ … return obj; } // 接着写else的业务逻辑代码; 如果非得使用if()…else if()…else…方式表达逻辑, 请勿超过3层, 超过请使用状态设计模式

循环体中的语句要考量性能, 以下操作尽量移至循环体外处理, 如获取数据库连接, 进行不必要的try-catch操作 这一条值得说一下, 因为有些代码会走得比较深, 写着写着就忘了它处于循环体的内部了. 所以保持一个谨慎的心态比较重要.

方法中需要进行参数校验的场景： 1） 调用频次低的方法. 2） 执行时间开销很大的方法, 参数校验时间几乎可以忽略不计, 但如果因为参数错误导致中间执行回退, 或者错误, 那得不偿失. 3） 需要极高稳定性和可用性的方法. 4） 对外提供的开放接口, 不管是RPC/API/HTTP接口. 5） 敏感权限入口.

方法中不需要参数校验的场景： 1） 极有可能被循环调用的方法, 不建议对参数进行校验. 但在方法说明里必须注明外部参数检查 2） 底层的方法调用频度都比较高, 一般不校验. 毕竟是像纯净水过滤的最后一道, 参数错误不太可能到底层才会暴露问题. 3） 被声明成private只会被自己代码所调用的方法, 如果能够确定调用方法的代码传入参数已经做过检查或者肯定不会有问题, 此时可以不校验参数

如代码中涉及到目录路径，统一使用"/"，而不使用"\"
controller:
page.json: 读取分页列表数据