wwjcloud/docs/ARCHITECTURE-BASELINE-AND-COMMON-GUIDE.md

架构基线与 Common 层开发指引（Config/Core/Common）

适用范围：本项目已定版的三层架构（config/core/common），以及与 Java/Spring Boot 与 PHP/ThinkPHP 的对标关系与实践规则。目标：在不自创业务的前提下，指导 AI 基于真实 PHP 代码与数据库结构高一致地开发 common 层模块。

---

1. 三层职责与使用方式

1.1 Config 层（配置中心与环境治理）

• 职责
  • 环境与配置集中管理（env.* 与模块化配置）
  • 外部服务与框架能力的参数化（DB、Redis、JWT、队列等）
• 使用规则
  • 严禁编写业务逻辑，仅做“配置与适配”
  • 新增配置项：优先读取 env，统一通过 ConfigService 暴露
  • 敏感配置不可写死；可按需对接密钥服务
• 参考位置
  • 项目：wwjcloud/src/config
  • 环境文件：wwjcloud/env.*

1.2 Core 层（基础能力与横切关注）

• 职责
  • 全局管道/拦截器/过滤器/守卫基线
  • 观测与日志、链路追踪（X-Trace-Id）、统一响应/异常
  • 限流、CORS、Swagger 文档、调度与事件
• 使用规则
  • 仅提供通用规则与“可复用能力”，不承载具体业务
  • 全局基线已启用：
    • 参数校验：Global ValidationPipe
    • 统一响应：ResponseInterceptor（含 traceId）
    • 统一异常：HttpExceptionFilter（含 traceId）
    • 链路追踪：TracingInterceptor + X-Trace-Id 贯通
    • 速率限制：ThrottlerGuard（按需配置）
    • CORS：app.enableCors()
    • 文档：Swagger（/adminapi 与 /api 分文档）
• 参考位置
  • 全局注册：wwjcloud/src/app.module.ts
  • 启动入口：wwjcloud/src/main.ts
  • Swagger 拆分：wwjcloud/src/config/modules/swagger/swaggerService.ts
  • Tracing/响应/异常：wwjcloud/src/core/**/*

1.3 Common 层（业务域模块化实现）

• 职责
  • 面向具体业务域（如 user/order/payment）
  • 内部完整分层：Controller → Service → Repository/Entity → DTO
  • 与 PHP 项目代码与数据库 100% 一致
• 使用规则
  • 文件结构示例（以 user 为例）：
    • src/common/user/
      • user.module.ts（模块）
      • controllers/（管理端/前台可分 adminapi/ 与 api/）
      • services/
      • entity/
      • dto/
      • guards/（可选）
    • 管理端路由前缀：/adminapi；前台：/api
  • Controller 只做：路由与 DTO 校验，禁止写业务
  • Service 编排业务流程（必要时开启应用层事务）
  • Repository/Entity 与数据库字段 100% 对齐（禁止新增字段）
  • DTO/验证规则与 PHP 验证器一致

---

2. 三框架对标对照（轻量/功能/性能）

2.1 总览对比

维度	Java / Spring Boot	NestJS（本项目基线）	PHP / ThinkPHP
轻量/启动	中等偏重、启动慢但稳定	轻量、启动快、按需模块	最轻、FPM 请求模型
功能完备度	企业级最全（安全/事务/监控）	Web/微服务常用能力齐全	Web 基础能力齐全
性能取向	高吞吐、高并发、CPU 密集强	低延迟 I/O 强、BFF/聚合强	请求短、实现快
并发模型	线程池	事件循环 + 异步 I/O	多进程/请求
可观测性	Actuator/Micrometer	健康/日志/Tracing 已落地	需组合/扩展
安全基线	Spring Security 完备	守卫/装饰器灵活	中间件/验证器为主

2.2 分层对比（config/core/common）

能力项	Spring Boot	NestJS（本项目）	ThinkPHP
Config	profiles + 强类型绑定	env + ConfigModule（已启用）	env + config/*.php
Core	Validation/Advice/Actuator	ValidationPipe/Filter/Interceptor/Throttler/CORS/Swagger（已启用）	Validate/中间件
Common	分包+组件化	业务域模块自治（强约束对齐 PHP/DB）	app/{模块}

2.3 性能视角（工程实践）

场景	Spring Boot	NestJS	ThinkPHP
API 聚合/BFF	可做，线程开销更高	强项	适合后台接口
CPU 密集	强项	建议 offload 至 worker/微服务	不推荐
I/O 密集	稳定	强项	常规
冷启动/弹性	相对慢	快	快

---

3. AI 开发 Common 层的使用方法（强约束版）

目标：严格遵循 PHP 源码与数据库结构，使用 NestJS 特性实现相同业务语义；禁止自创和假设。

3.1 约束来源（必须核对）

• 数据库表结构：/sql/wwjcloud.sql（唯一权威）
• PHP 控制器：/niucloud-php/niucloud/app/adminapi/controller/
• PHP 服务层：/niucloud-php/niucloud/app/service/
• PHP 模型：/niucloud-php/niucloud/app/model/
• PHP 验证器：/niucloud-php/niucloud/app/validate/

3.2 开发流程（S1 → S10）

• S1 需求分析体
  • 定位对应的 PHP 控制器/服务/验证器/模型与数据库表
  • 输出：模块边界、路由表（/adminapi 与 /api）、DTO 字段清单、实体字段清单
• S2 架构治理体
  • 校验目录与依赖：common/{module}/ 按 Controller→Service→Entity→DTO 组织
  • 确保依赖方向：App(Controller) → Service → Infra/Repository → Entity
• S3 基建接入体
  • 若涉及 Redis/队列/事务：按 core 规范接入（事务仅在应用层开启，共享 EntityManager）
• S4 开发执行体
  • Controller：只做路由/DTO 校验；响应交给全局拦截器统一处理
  • Service：编排业务，与 PHP 服务层一致；必要时开启事务（禁止在 Core 开启）
  • Entity/Repository：字段与 /sql/wwjcloud.sql 100% 对齐（禁止新增字段）
  • 接入守卫：管理端统一 JwtAuthGuard + RolesGuard（或 AdminCheckTokenGuard）
• S5 安全基线体（开发阶段）
  • 检查：site_id 隔离、越权、敏感字段输出、/adminapi 守卫
• S6 质量门禁体
  • ESLint/TS 0 报错；覆盖率与 e2e 关键路径通过
• S7 规范审计体
  • 命名/路由/守卫/事务/事件/队列 与 PHP/DB 对齐
• S5 安全基线体（提测前）
  • 重点接口越权与敏感输出复检
• S9 性能优化体
  • 建议缓存、批处理、异步化，识别 N+1 与大对象
• S10 命名规范体
  • 文件/类/方法/变量命名符合既定规范
• S8 上线管控体
  • 变更说明、部署步骤、灰度与回滚预案

3.3 模块落地清单（逐项核对）

• 路由前缀：管理端 /adminapi；前台 /api（与 PHP 对齐）
• 守卫：管理端控制器默认 JwtAuthGuard + RolesGuard（或 AdminCheckTokenGuard）
• DTO：字段与 PHP 验证器一致；使用 class-validator + ValidationPipe
• 实体：字段/类型/索引与 wwjcloud.sql 100% 一致；禁止新增字段
• 服务：方法名与 PHP 服务层一致；流程一致；必要时开启事务（应用层）
• 统一响应：无需手工封装，交由 ResponseInterceptor；traceId 自动注入
• 异常处理：只抛出 HttpException/自定义异常；由 HttpExceptionFilter 统一处理
• 日志与链路：无需重复生成 traceId；使用 request.traceId（已在 Core 透传）
• 文档：自动生成 Swagger，按 /adminapi 与 /api 拆分

3.4 命名与目录规范（强规则）

• 目录名：camelCase；文件名：camelCase.ts
• 类名：PascalCase；接口名：IPascalCase；DTO：PascalCase + Dto
• API 命名：camelCase；HTTP 方法规范化
• 数据库命名：snake_case（表/字段/索引/外键）
• PHP 业务命名优先（在不违反 Nest 规范前提下）

3.5 事务/队列/事件（基线约束）

• 事务：仅在 Application（Service 层）开启；多仓储共享同一 EntityManager；Core 不直接操作事务对象
• 队列：仅入队关键 ID，处理器放在 Infrastructure；按队列名分域
• 事件：统一 DomainEventService，事件名 domain.aggregate.action；默认 DB Outbox，可切 Kafka
• Redis：短缓存/限流/幂等（SETNX+TTL）按需接入

3.6 提交与验收

• PR 必须通过：构建、单测/集成/e2e
• 审计项：字段/命名/路由/守卫/事务/队列/事件 与 PHP/DB 对齐
• 命名规范：严格执行大厂标准，提交命名检查报告

---

4. 实操模板（创建首个 common 模块时）

• 选定 PHP 源：定位对应 controller/service/validate/model 与 wwjcloud.sql 表
• 创建目录：src/common/{module}/（module 使用业务域名，camelCase）
• 落地文件：
  • {module}.module.ts
  • controllers/{module}.controller.ts（必要时 adminapi/ 与 api/ 分目录）
  • services/{module}.service.ts
  • entity/{Entity}.entity.ts（名称与 PHP 模型一致的业务语义）
  • dto/{Operation}{Entity}Dto.ts（如 CreateUserDto）
• 接入守卫：管理端默认接入鉴权与角色守卫
• 编写测试：单测/集成/e2e 涵盖关键路径（校验/守卫/事务）
• 运行验收：确保全局拦截器/过滤器与 traceId 链路正常

---

5. 关键基线位置（便于检索）

• 全局模块注册：src/app.module.ts
• 启动入口：src/main.ts（CORS/Swagger）
• Swagger 拆分：src/config/modules/swagger/swaggerService.ts
• 链路追踪：src/core/tracing/tracingInterceptor.ts
• 统一响应：src/core/http/interceptors/responseInterceptor.ts
• 统一异常：src/core/http/filters/httpExceptionFilter.ts
• HTTP 日志：src/core/interceptors/httpLoggingInterceptor.ts
• 安全守卫（示例）：src/core/security/guards/adminCheckToken.guard.ts

---

结论：

• Config/Core 已定版、与 Spring Boot/ThinkPHP 对标的核心能力就绪，traceId 与统一响应/异常/限流/CORS/Swagger 等基线已贯通。
• 按本文档清单可直接开始 common 层业务模块开发，严格以 PHP 源码与 wwjcloud.sql 为唯一权威对齐实现。