# 后端业务功能开发规范

本文是本项目 Hono 后端新增或修改业务功能时的权威规范。后端代码位于 `backend`，基于 Hono、Prisma、Redis 和统一响应/错误协议实现。

## 架构原则

后端业务代码按 `Route -> Feature Service -> Prisma/Redis/shared Service` 组织。

优先参考这些现有模块：

- `backend/src/routes/modules/system-user.ts`
- `backend/src/routes/modules/system-role.ts`
- `backend/src/routes/modules/system-menu.ts`
- `backend/src/routes/modules/system-notice.ts`
- `backend/src/features/system/system.service.ts`
- `backend/src/features/collaboration/collaboration.service.ts`

Route 只负责 HTTP 层编排，不直接堆业务规则。复杂查询或业务流程放到 `features/<domain>` 下的 service 中。不要把 Prisma 原始记录直接作为跨模块业务契约扩散，面向前端的响应应在 service 中整理为稳定 DTO 形态。

## 开发准备

开发新后端业务功能前，应先确认需求所属领域、涉及的数据表、接口范围、权限标识和相似模块。

开始编码前必须先做一次相似模块调研，确认目标功能最接近 `user`、`role`、`menu`、`notice`、`config`、`collaboration` 还是其他模块，再按相似模块的命名、路由、分页、异常、权限、导出和测试风格实现。

## 目录结构

路由入口放在：

```text
backend/src/routes/modules/<module>.ts
```

业务代码放在：

```text
backend/src/features/<domain>/
├── <domain>.service.ts
├── <domain>.schemas.ts
└── public-config.ts
```

共享能力放在：

```text
backend/src/shared/
├── auth/
├── cache/
├── config/
├── db/
├── hono/
└── http/
```

数据库 schema 维护在：

```text
backend/prisma/schema.prisma
```

初始化 SQL 维护在：

```text
backend/sql/init.sql
```

## 各层职责

Route 负责 HTTP 层：

- 声明 Hono 路由和 HTTP 方法。
- 使用 `requireAuth`、`requirePermission` 做认证和权限控制。
- 使用 `zValidator` 校验请求体或查询参数。
- 调用 Feature Service。
- 使用 `ok()`、`page()` 或下载响应工具返回统一响应。

Feature Service 负责编排业务用例：

- 分页查询、详情查询、导出查询、新增、修改、删除。
- 处理业务校验和状态变化。
- 调用 Prisma、Redis 或 shared service 完成持久化和缓存操作。
- 将数据库记录转换为前端响应对象。
- 业务失败时抛出 `ApiError`，不要返回布尔值让 Route 解释。

Shared 层只放跨模块复用能力：

- 认证、权限、会话和当前用户。
- Prisma 和 Redis 客户端。
- 统一响应、错误处理、下载、Excel。
- 菜单、配置等跨模块辅助逻辑。

## 开发流程

1. 检索并阅读一个最相似的 Hono 模块，确认命名、路由、分页、异常、权限和导出风格。
2. 确认数据库表结构，必要时更新 `prisma/schema.prisma` 和初始化 SQL。
3. 在 `features/<domain>` 中实现业务函数，保持函数职责单一。
4. 在 `routes/modules/<module>.ts` 中添加路由，接入认证、权限、校验和统一响应。
5. 如功能出现在后台菜单，补充权限标识和 `backend/sql/init.sql` 菜单数据。
6. 如需要字典数据，优先使用 `features/system/system-dictionary.ts` 中的枚举式配置，不要默认创建字典管理表。
7. 增加聚焦测试或至少运行 TypeScript 检查；高风险改动应补充接口级验证。
8. 运行 `pnpm --dir backend typecheck`。

## 权限、日志和错误

权限码必须和前端菜单或按钮权限保持一致，格式参考现有系统功能：

```ts
requirePermission("system:user:list")
```

业务错误使用 `ApiError` 和 `ErrorCodes`：

```ts
throw new ApiError(ErrorCodes.failed, "操作失败");
```

接口返回使用统一响应：

```ts
return c.json(ok(result));
return c.json(page(result.records, result.total));
```

导出接口优先使用 `createWorkbookResponse()`。

## 验收清单

- Route 只有 HTTP 编排逻辑。
- 业务校验位于 Feature Service，不散落在前端或 Route。
- 查询返回稳定 DTO，分页返回统一 `page()` 响应。
- 写请求使用 zod schema 校验。
- 权限码、菜单 SQL、前端 API 调用保持一致。
- `pnpm --dir backend typecheck` 通过。