57 lines
4.4 KiB
Markdown
57 lines
4.4 KiB
Markdown
|
# WWJCloud 框架里程碑 0.1.1
|
|||
|
|
|
|||
|
|
## 一、全局评估（当前基线）
|
|||
|
|
- 分层清晰：config（配置与适配）、core（通用基础/抽象）、vendor（第三方适配）、common（业务域），依赖方向 App→common→core→vendor 合规。
|
|||
|
|
- 配置中心落地：ConfigCenterService 统一读取与开关（如 swagger.enabled、swagger.token），控制器与 UI 解耦；动态配置具备基础能力。
|
|||
|
|
- API 文档输出：仅输出 JSON，三端点分组（全量/admin/frontend），鉴权改为 Bearer Token（swagger.token）。
|
|||
|
|
- 观测与健康：Winston 日志、Terminus 健康（/healthz /readyz /startupz）、Metrics 基础可用。
|
|||
|
|
- 任务与事件：Outbox（events）表、调度与重试字段/索引齐备；队列/事件基础设施在位。
|
|||
|
|
- 安全基线：全局守卫、RBAC；文档 JSON 受 Token 保护；Throttler 可用。
|
|||
|
|
- 启动可观测：启动成功日志输出后端基地址与文档 JSON 三路由，便于联调。
|
|||
|
|
|
|||
|
|
## 二、风险与待确认
|
|||
|
|
- 动态配置能力的“变更通知/缓存 TTL/审计记录”需在进入多域前补完细节。
|
|||
|
|
- CI 质量门禁需在 PR 阶段强制（ESLint/TS/coverage/e2e 阈值）。
|
|||
|
|
- DB 初始化要强制走 migration，避免纯 SQL 造成偏差。
|
|||
|
|
- 文档 JSON 的密钥管理建议生产具备轮换机制。
|
|||
|
|
- Nginx 反代模板建议固化（由 1Panel 管理也可）。
|
|||
|
|
|
|||
|
|
## 三、绿通项（已完成，可直接使用）
|
|||
|
|
- Swagger JSON 鉴权与分组输出（/api-json、/api/admin-json、/api/frontend-json）。
|
|||
|
|
- events 表（含 site_id、trace_id 等）完整建表与索引 SQL。
|
|||
|
|
- 启动成功日志输出（服务地址与三条 JSON 路由）。
|
|||
|
|
- 文档站联调（实时直连 + 备用离线脚本，带 Token）。
|
|||
|
|
- 移除循环依赖隐患（Swagger 纳入 config 核心模块，barrel 不再导出 swagger module）。
|
|||
|
|
|
|||
|
|
## 四、网关（Kong）结论
|
|||
|
|
- 单体阶段：不必须启用；1Panel/Nginx 反代 + 后端限流/鉴权足够。
|
|||
|
|
- 多应用授权/域名授权阶段：建议引入网关统一鉴权/配额/策略，后端专注业务授权与审计。现有改造路径已预留。
|
|||
|
|
|
|||
|
|
## 五、PHP 框架迁移前置调整
|
|||
|
|
- 数据与命名：表/字段/DTO/错误码与 PHP 对齐；返回格式统一。
|
|||
|
|
- 鉴权与越权：管理端统一 JwtAuthGuard + RolesGuard；`site_id` 租户隔离在业务流全链路透传与校验。
|
|||
|
|
- 配置迁移：PHP 配置项映射到 ConfigCenterService 键（camelCase），环境变量 UPPER_SNAKE_CASE；生产设置 swagger.token。
|
|||
|
|
- 依赖与集成：异步任务/事件对齐 Queue + Outbox（只传 ID、支持幂等重试）；vendor 适配上传/存储/短信/支付。
|
|||
|
|
- 测试与门禁：将 PHP 关键路径用例迁为 e2e/集成测试；CI 强制 ESLint/TS/coverage/e2e 阈值。
|
|||
|
|
- 文档对齐：PHP 接口文档合流至当前 Swagger JSON 输出，docs 站读取三份 JSON。
|
|||
|
|
|
|||
|
|
## 六、是否定稿 core/vendor/config，进入 common 层？
|
|||
|
|
- 结论：可以。core/vendor/config 已达“可用基线”，足以支撑 common 层建设与业务迁移。
|
|||
|
|
- core：健康、拦截器/守卫/HTTP、队列与事件抽象、指标与 tracing 框架就绪。
|
|||
|
|
- vendor：第三方适配器骨架可用，按业务逐步补实现。
|
|||
|
|
- config：配置中心、控制器出口、Swagger JSON 鉴权与分组稳定；Barrel 导出已规避循环。
|
|||
|
|
|
|||
|
|
## 七、近期执行建议（进入 common）
|
|||
|
|
- 业务域落地顺序：IAM（用户/角色/权限）→ Settings → Upload → Notification → Schedule。
|
|||
|
|
- 分层落地：Controller（路由+DTO）→ AppService（编排）→ Core（规则）→ Infra（持久化）；全链路 `site_id` 隔离。
|
|||
|
|
- 测试覆盖：补关键用例（认证登录、权限越权、租户隔离、上传、事件投递/消费）单测/集成/e2e。
|
|||
|
|
- 质量门禁：开启 ESLint/TS/coverage≥阈值 与 e2e 关键路径门禁。
|
|||
|
|
- Nginx 反代模板：固化到仓库 docs（HTTPS/超时/限流/大包/真实 IP 透传）。
|
|||
|
|
|
|||
|
|
## 八、版本说明（0.1.1）
|
|||
|
|
- 特性：Swagger JSON 分组与鉴权、配置中心接入、events 表与索引、启动可观测日志、docs 联调脚本支持 Token。
|
|||
|
|
- 破坏性变更：移除旧 swagger integrations 引用与循环依赖；文档 JSON 访问需携带 Bearer Token。
|
|||
|
|
- 升级指引：
|
|||
|
|
1) 数据库执行 `events` 建表 SQL（含 site_id/trace_id 等）；
|
|||
|
|
2) 配置中心设置 `swagger.token`；
|
|||
|
|
3) docs 侧按需携带 Bearer Token（脚本已内置或通过环境变量）。
|