You need to open the vscode command: TypeScript: Select TypeScript Version, then choose the typescript version mathed the package.json.
pnpm db:check # 预检:schema 中声明的表 vs 数据库实际表
pnpm db:sync:safe # generate → 扫描破坏性操作 → migrate(推荐日常用)
pnpm db:sync # 直接 generate + migrate(不带安全检查,老脚本保留)
pnpm db:rename <old> <new> # 双写迁移:把旧表无损重命名为新表
pnpm db:rename --column <t> <old> <new> # 双写迁移:字段重命名读取 src/db/schema/*.ts 里的 mysqlTable('xxx', ...) / createTable('xxx', ...),对比数据库实际表:
- schema 有但库没有 → 新增(安全)
- 库有但 schema 没有 → 消失(破坏性,会被 DROP)
- 改名(表名变化)→ Drizzle 会 DROP 旧表 + CREATE 新表,数据丢失
三层护栏:
drizzle-kit generate生成迁移 SQL- 扫描所有
drizzle/<timestamp>_*/migration.sql,匹配以下正则即拒绝执行:DROP TABLE/TRUNCATE TABLEALTER TABLE ... DROP [COLUMN]
- 检查通过 →
drizzle-kit migrate
强制执行破坏性操作:pnpm db:sync:safe --force(请先备份数据)。
无损重命名表 / 字段。会生成一个 drizzle/manual_<ts>_<old>_to_<new>.sql 模板,包含三阶段:
- 阶段 1:
CREATE TABLE new LIKE old+INSERT INTO new SELECT * FROM old - 阶段 2:应用层双写(一段时间)
- 阶段 3:DROP 旧表
字段重命名走 ADD COLUMN + UPDATE + 应用层切换 + DROP COLUMN,或 ALTER TABLE ... CHANGE(瞬间)。
如果mysql 的参数为undefined、无字段两种情况则设计为自动过滤,不会进入 mysql; 如果参数为 null,则认为是有意义值,会进入 mysql。
项目通过 src/common/interceptors/serialize.interceptor.ts 对所有 HTTP 响应做统一处理,包括:
- 自动附加
timestamp:在每个标准响应体(包含code/msg/data)上添加服务端响应时间。 - 自动格式化时间戳字段:递归地把响应中名为
add_time/upd_time的Date(或可解析为日期的字符串/数字)转换为YYYY-MM-DD HH:mm:ss格式。 - 自动过滤
@Exclude字段:递归移除被src/common/decorators/exclude.decorator.ts中@Exclude()装饰器标记的字段。
- Service 层不应再手动调用
formatTimestamps:时间戳格式化由拦截器统一处理,Service 直接返回R.success(...)即可。 - Service 不再需要继承
BaseSqlService:原BaseSqlService.formatTimestamps()已被拦截器取代,类已删除。 - 内部 service 之间的调用(如
AuthService -> UserService)不会经过拦截器,因此可以安全地基于原始Date字段或未脱敏字段做业务判断。响应给客户端前的格式化与脱敏由拦截器兜底。
所有表通过 createTable() 创建,自动追加公共字段:is_del、add_time、upd_time、add_user、del_user。
业务表主键统一为自增 int id。
| 表名 | 文件 | 用途 |
|---|---|---|
user |
user.ts |
用户账号(openid、username、tel、email、avatar、gender、birth …) |
role |
role.ts |
角色 |
user_role |
user-role.ts |
用户-角色关联表 |
doc |
doc.ts |
文档/目录 |
doc_history |
doc-history.ts |
文档历史版本 |
org |
org.ts |
组织(公司/企业) |
org_structure |
org-structure.ts |
组织架构(部门,树形结构,pid 自引用) |
org_member |
org-member.ts |
组织成员(员工) |
base_countries |
base-countries.ts |
国家/地区(ISO 3166-1,基础数据,无公共字段) |
base_province |
base-province.ts |
省份(基础数据,无公共字段) |
base_city |
base-city.ts |
城市(基础数据,无公共字段) |
base_area |
base-area.ts |
区县(基础数据,无公共字段) |
base_street |
base-street.ts |
乡镇/街道(基础数据,无公共字段) |
存储组织(公司/企业)基础信息。
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
id |
int PK | auto | 主键 |
name |
varchar(255) | '' |
组织名称 |
short_name |
varchar(255) | '' |
组织简称 |
code |
varchar(255) | '' |
组织编码 / 统一社会信用代码 |
logo |
varchar(255) | '' |
组织 logo |
tel |
varchar(255) | '' |
联系电话 |
email |
varchar(255) | '' |
联系邮箱 |
address |
varchar(255) | '' |
组织地址 |
status |
tinyint | 1 |
状态:1 启用 0 停用 |
条件唯一索引:code(非空时全局唯一)。
支持树形结构,通过 pid 自引用,pid = 0 表示顶级架构节点。
通过 oid 关联组织,删除组织时级联删除其下架构节点。
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
id |
int PK | auto | 主键 |
oid |
int FK→org.id |
0 |
所属组织 id,级联删除 |
pid |
int | 0 |
父节点 id,0 表示顶级 |
name |
varchar(255) | '' |
节点名称(如:技术部 / 前端组) |
code |
varchar(255) | '' |
节点编码 |
leader |
varchar(255) | '' |
负责人姓名 |
通过 oid 关联组织,通过 sid 关联组织架构节点;成员离职/转岗时 sid 可置 0(set default)。
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
id |
int PK | auto | 主键 |
oid |
int FK→org.id |
0 |
所属组织 id,级联删除 |
sid |
int FK→org_structure.id |
0 |
所属架构节点 id,0 表示未分配;节点删除时回退默认 |
code |
varchar(255) | '' |
成员工号/编号 |
name |
varchar(255) | '' |
成员姓名 |
tel |
varchar(255) | '' |
手机号 |
email |
varchar(255) | '' |
邮箱 |
avatar |
varchar(255) | '' |
头像 |
gender |
tinyint | 0 |
性别:0 未知 1 男 2 女 |
position |
varchar(255) | '' |
职位 |
status |
tinyint | 1 |
状态:1 在职 0 离职 |
条件唯一索引:code(工号)、tel(手机号)均为非空时全局唯一。
org (1) ──< org_structure (树形,pid 自引用)
org (1) ──< org_member
org_structure (1) ──< org_member
利用 MySQL 唯一索引自动忽略 NULL 的特性,通过 CASE WHEN … = '' OR … IS NULL THEN NULL ELSE … END 实现:
- 空字符串 / NULL → CASE 返回 NULL → 不参与唯一约束 → 可重复
- 非空值 → CASE 返回原值 → 唯一约束生效 → 必须唯一
参考实现见 user.ts 中的 userConditionalIndexes。
基础数据表,直接使用 mysqlTable 而非 createTable,无 is_del/add_time/upd_time/add_user/del_user 公共字段。
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
id |
int unsigned PK | auto | 主键 |
alpha2_code |
char(2) | — | ISO 3166-1 二位字母代码(唯一) |
alpha3_code |
char(3) | — | ISO 3166-1 三位字母代码(唯一) |
numeric_code |
char(3) | — | ISO 3166-1 三位数字代码(唯一) |
country_name |
varchar(100) | — | 国家/地区全称 |
country_short_name |
varchar(50) | — | 国家/地区简称 |
country_english_name |
varchar(100) | — | 国家/地区英文名称 |
索引:alpha2_code / alpha3_code / numeric_code 唯一索引;country_name / country_english_name 普通索引。
基础数据表,无公共字段。
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
id |
int PK | auto | 主键 |
province_id |
int | — | 行政区划业务 id(前 2 位编码,唯一) |
province_name |
varchar(40) | — | 省份名称 |
wm |
varchar(10) | '' |
首字母/五笔简码 |
基础数据表,无公共字段。
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
id |
int PK | auto | 主键 |
city_id |
int | — | 行政区划业务 id(前 4 位编码,唯一) |
city_name |
varchar(50) | — | 城市名称 |
pid |
int | 0 |
父级 province.id,0 表示顶级 |
基础数据表,无公共字段。
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
id |
int PK | auto | 主键 |
area_id |
int | — | 行政区划业务 id(6 位编码,唯一) |
area_name |
varchar(50) | — | 区县名称 |
pid |
int | 0 |
父级 city.id,0 表示顶级 |
基础数据表,无公共字段、无外键。注意 father 是 varchar(6) 存储 6 位行政区划代码,与 base_area.id(int) 类型不同,不做 FK 约束。
| 字段 | 类型 | 默认 | 说明 |
|---|---|---|---|
id |
int PK | auto | 主键 |
street_name |
varchar(60) | '' |
街道/乡镇名称 |
father |
varchar(6) | '' |
父级区县 6 位行政区划代码 |
street_id |
varchar(50) | '' |
街道/乡镇 9 位行政区划代码 |
关联关系(逻辑层面,不加 FK):
base_province (1) ──< base_city (1) ──< base_area (1) ──< base_street
BaseModule 提供行政区划查询接口,支持获取国家、省份、城市、区县、街道等数据。
| 接口 | 方法 | 参数 | 说明 |
|---|---|---|---|
/base/countries |
GET | 无 | 获取所有国家列表 |
/base/provinces |
GET | 可选 countryId |
获取省份列表(默认中国) |
/base/cities |
GET | provinceId |
获取某省份下的城市列表 |
/base/areas |
GET | cityId |
获取某城市下的区县列表 |
/base/streets |
GET | areaId |
获取某区县下的街道列表 |
# 获取所有国家
curl http://localhost:3000/base/countries
# 获取省份列表(默认中国)
curl http://localhost:3000/base/provinces
# 获取某省份下的城市列表(provinceId 为省份的数据库 ID)
curl http://localhost:3000/base/cities?provinceId=1
# 获取某城市下的区县列表(cityId 为城市的数据库 ID)
curl http://localhost:3000/base/areas?cityId=1
# 获取某区县下的街道列表(areaId 为区县的数据库 ID)
curl http://localhost:3000/base/streets?areaId=1{
"code": 200,
"msg": "success",
"data": [
{
"id": 1,
"provinceId": 110000,
"provinceName": "北京市",
"wm": "BJS"
}
],
"timestamp": "2026-09-03 13:25:00"
}行政区划数据遵循以下层级关系:
国家 (countries)
└── 省份 (provinces) - 通过 base_province.id 关联
└── 城市 (cities) - 通过 base_city.pid 关联省份
└── 区县 (areas) - 通过 base_area.pid 关联城市
└── 街道 (streets) - 通过 base_street.father 关联区县的6位行政区划代码
OrgModule 提供组织(公司/企业)、组织架构(部门)、组织成员(员工)的完整 CRUD 接口,统一挂载在 /org 前缀下。
| 接口 | 方法 | 参数 | 说明 |
|---|---|---|---|
/org |
POST | CreateOrgDto |
创建组织 |
/org |
GET | 无 | 查询所有组织 |
/org/page |
GET | page, limit |
分页查询组织 |
/org/:id |
GET | id |
查询组织详情 |
/org/:id |
PATCH | id, UpdateOrgDto |
更新组织 |
/org/:id |
DELETE | id |
删除组织(软删除) |
| 接口 | 方法 | 参数 | 说明 |
|---|---|---|---|
/org/structure |
POST | CreateStructureDto |
创建组织架构节点 |
/org/structure |
GET | 无 | 查询所有组织架构节点 |
/org/structure/page |
GET | page, limit |
分页查询 |
/org/structure/tree |
GET | oid |
按组织ID查询,返回树形结构 |
/org/structure/:id |
GET | id |
查询节点详情 |
/org/structure/:id |
PATCH | id, UpdateStructureDto |
更新节点 |
/org/structure/:id |
DELETE | id |
删除节点(软删除,存在子节点时拒绝) |
| 接口 | 方法 | 参数 | 说明 |
|---|---|---|---|
/org/member |
POST | CreateMemberDto |
创建组织成员 |
/org/member |
GET | 无 | 查询所有成员 |
/org/member/page |
GET | page, limit |
分页查询 |
/org/member/list |
GET | oid |
按组织ID查询所有成员 |
/org/member/active |
GET | oid |
按组织ID查询在职成员 |
/org/member/structure/:sid |
GET | sid |
按架构节点查询成员 |
/org/member/tel/:tel |
GET | tel |
按手机号查询成员 |
/org/member/:id |
GET | id |
查询成员详情 |
/org/member/:id |
PATCH | id, UpdateMemberDto |
更新成员 |
/org/member/:id |
DELETE | id |
删除成员(软删除) |
组织 DTO:CreateOrgDto / UpdateOrgDto
name(必填):组织名称shortName(可选):组织简称code(可选):组织编码/统一社会信用代码(非空时全局唯一)logo/tel/email/address(可选):联系信息status(可选):1 启用 / 0 停用
组织架构 DTO:CreateStructureDto / UpdateStructureDto
oid(创建时必填):所属组织IDpid(可选):父节点ID,0 表示顶级节点name(必填):节点名称(如:技术部 / 前端组)code(可选):节点编码leader(可选):负责人姓名
组织成员 DTO:CreateMemberDto / UpdateMemberDto
oid(创建时必填):所属组织IDsid(可选):所属架构节点ID,0 表示未分配code(可选):成员工号(非空时全局唯一)name(创建时必填):成员姓名tel(可选):手机号(非空时全局唯一)email/avatar(可选):联系信息gender(可选):0 未知 / 1 男 / 2 女position(可选):职位status(可选):1 在职 / 0 离职
# 创建组织
curl -X POST http://localhost:3000/org \
-H "Content-Type: application/json" \
-d '{"name": "示例公司", "code": "91110000XXXXXXXXXX", "status": 1}'
# 创建组织架构节点
curl -X POST http://localhost:3000/org/structure \
-H "Content-Type: application/json" \
-d '{"oid": 1, "pid": 0, "name": "技术部", "leader": "张三"}'
# 按组织查询树形架构
curl 'http://localhost:3000/org/structure/tree?oid=1'
# 创建组织成员
curl -X POST http://localhost:3000/org/member \
-H "Content-Type: application/json" \
-d '{"oid": 1, "name": "李四", "code": "EMP001", "tel": "13800138000", "gender": 1}'
# 按组织查询在职成员
curl 'http://localhost:3000/org/member/active?oid=1'
# 更新成员(如转岗)
curl -X PATCH http://localhost:3000/org/member/1 \
-H "Content-Type: application/json" \
-d '{"sid": 2, "position": "高级工程师"}'