API 文档（Knife4j）

TaskFlow 使用 @nestjs/swagger 生成 OpenAPI，并用 Knife4j 作为 UI（nestjs-knife4j-plus）。

推荐：网关一处切换 Sys / Acc

入口	地址
Knife4j（左上角下拉切换 Sys / Acc）	http://localhost:3000/doc.html
说明页	http://localhost:3000/api-doc

网关从 Sys、Acc 拉取 /api-docs-json，并在文档里把路径加上 /api/sys、/api/acc 前缀，调试时与真实调用一致。

前提：pnpm dev:backend 时 Gateway + Sys + Acc 都要启动；若下拉某组报 503，说明对应进程未起或 SWAGGER_ENABLED=false。

各服务独立文档（仅一组）

进程	Knife4j	说明
Sys	http://localhost:3001/doc.html	仅「Sys」一组
Acc	http://localhost:3002/doc.html	仅「Acc」一组

调试鉴权

在 Knife4j「调试」中配置：

• Authorization：Bearer <JWT>
• X-Site-Id：记账站点（Acc 接口）

响应经网关为 { code, message, data }，code === 0 成功。

开关

backend/.env：

SWAGGER_ENABLED=true   # 开发
# SWAGGER_ENABLED=false  # 生产务必关闭

未设置时：非 production 默认开启。

实现位置

文件	作用
backend/src/libs/shared/swagger/setup-gateway-knife4j.swagger.ts	网关双分组 Knife4j
backend/src/apps/gateway/openapi/gateway-openapi-proxy.service.ts	聚合下游 OpenAPI
backend/src/libs/shared/swagger/setup-knife4j.swagger.ts	Sys/Acc 单服务文档
backend/src/libs/shared/swagger/api-common.dto.ts	通用 SiteIdBodyDto、SiteEntityIdDto、PageResultMetaDto
backend/src/libs/shared/swagger/acc-site.decorator.ts	Acc：@ApiAccPostPage / @ApiAccPostWrite 等
backend/src/libs/shared/swagger/sys-api.decorator.ts	Sys：@ApiSysPostPage / @ApiSysPostOp 等

新增接口时：DTO 字段加 @ApiProperty，Controller 方法挂上述装饰器；勿用匿名 { siteId, id } 作 body（Knife4j 会显示 No Data）。

已补文档的模块：

• Sys：认证、站点、当前用户、用户管理、角色、权限、字典、部门、日志、系统配置、PC 通知、上传、公共文件、小程序记账、清单计价
• Acc：入/出库、生产、往来、商品、结算、库存、首页、工种、导入、收件箱、运维巡检

生产环境

勿对公网暴露 /doc.html；或 SWAGGER_ENABLED=false。