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 为唯一权威对齐实现。