collab-ledger/docs/backend-feature-development.md

后端业务功能开发规范

本文是本项目 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 还是其他模块，再按相似模块的命名、路由、分页、异常、权限、导出和测试风格实现。

目录结构

路由入口放在：

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

业务代码放在：

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

共享能力放在：

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

数据库 schema 维护在：

backend/prisma/schema.prisma

初始化 SQL 维护在：

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。

权限、日志和错误

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

requirePermission("system:user:list")

业务错误使用 ApiError 和 ErrorCodes：

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

接口返回使用统一响应：

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 通过。