Files

lanyuanxiaoyao 34071a421a refactor: 品牌重塑 my-app → Alfred·阿福

将项目从模板标识 my-app 全部替换为产品标识 Alfred·阿福，
去掉所有模板措辞，文档语态转为产品视角。

核心标识替换：
- name: my-app → alfred
- title: My App → Alfred·阿福
- subtitle: Bun 全栈应用 → 智能信息处理中枢
- description: 全栈开发框架 → 基于 AI 的信息综合处理平台
- 日志路径: my-app.log → alfred.log
- 构建产物: dist/my-app → dist/alfred（由 APP.name 自动适配）

文档更新：
- README.md 重写为产品介绍
- docs/README.md 去掉模板段落
- docs/user/ 从模板使用指南改为产品手册
- docs/development/ 标识替换 + 去模板措辞
- openspec/config.yaml 去模板项目描述
- LICENSE 填入 Copyright 2025 lanyuanxiaoyao

2026-05-27 09:38:57 +08:00

3.8 KiB

Raw Blame History

后端开发

本文档说明 alfred 后端的 API、配置加载、日志、版本管理和后端测试开发约定。

适用场景：修改 src/server/、src/shared/api.ts、后端测试、配置契约、API 响应或日志模块。

库使用优先级

优先级	来源	典型用途
1	Bun 内置 API	Bun.serve、Bun.file、Bun.YAML、Bun.spawn
2	es-toolkit	类型判断、深度比较、并发控制
3	标准 Web API	Headers、fetch、AbortController
4	主流三方库	pino、@sinclair/typebox、ajv
5	自行实现	仅在以上都无法满足时

新增依赖前必须先检查上述每一层是否已有可用方案。

API 路由开发

路由文件位于 src/server/routes/，每个端点一个文件。路由通过 server.ts 的 Bun.serve({ routes }) 声明式注册。

新增路由步骤：

在 src/server/routes/ 下创建 .ts
实现 handler 函数并 export
在 server.ts 的 routes 对象中注册路径和 method handler
在 tests/server/ 中添加对应测试

共享工具

helpers.ts 提供跨路由共用的响应工具：

createApiError(error, status) — 构造 API 错误体
createHeaders(mode, init) — 创建响应 Headers
jsonResponse(body, options) — JSON 响应构造

middleware.ts 提供 API 参数校验函数：

validateIdParam(idStr, mode) — 校验 ID 参数格式
validatePagination(pageParam, pageSizeParam, mode) — 校验分页参数
validateTimeRange(from, to, mode) — 校验时间范围参数

类型规范

共享类型以 src/shared/api.ts 为唯一源头
应用常量以 src/shared/app.ts 为唯一源头
版本号以 package.json.version 为唯一源头
前端不得 import src/server/ 下的任何文件
严格联合类型优先于宽类型

配置契约

配置加载流程固定为：unknown -> AuthoringConfig -> NormalizedConfig -> ValidatedConfig -> ServerConfig。

Ajv 保持严格拒绝模式：allErrors: true、不启用类型强制转换、不注入默认值、不自动删除未知字段。

新增或修改配置字段时必须同步更新 TypeBox schema fragments、config.schema.json、测试和对应用户文档。

日志模块

后端运行时代码统一通过 Logger 接口输出日志，禁止直接使用 console.*。

实现	用途
PinoLoggerWrapper	生产运行时
ConsoleFallbackLogger	配置加载失败前的降级日志
NoopLogger	静默丢弃日志
MemoryLogger	测试替身

敏感信息会自动 redact authorization、cookie、password 等字段。

版本管理

项目使用 package.json.version 作为版本号唯一来源。

版本获取方式：

开发模式：src/server/version.ts 运行时从 package.json 读取
生产模式：scripts/build.ts 在构建时将版本号烘焙为字面量注入

版本升迁命令：

bun run version:patch   # 升迁 patch 版本
bun run version:minor   # 升迁 minor 版本
bun run version:major   # 升迁 major 版本
bun run version:set     # 显式设置版本号

后端测试

变更类型	测试重点
API 路由	tests/server/app.test.ts 集成行为
配置 schema	schema 导出、合法/非法配置
helpers/middleware	单元测试

更新触发条件

修改后端 API、共享类型、配置契约、日志模块、版本管理或后端测试规范时，必须更新本文档。

3.8 KiB Raw Blame History Unescape Escape