fischer
/
fischerX
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
fischerX/.trae/specs/initialize-fischerx-foundation/spec.md

10 KiB
Raw Blame History

FischerX 开发底座初始化 Spec

Why

Fischer公司需要一个适配国内运行环境的开发底座，类似John Rush的Mars Stack/Mars Foundation理念，用于快速构建业务模块，降低开发成本，提升开发效率。当前项目为全新项目，需要先明确整体架构和未来使用方式，然后根据国内环境逐一完善功能模块。

What Changes

  • 创建完整的Monorepo项目架构
  • 搭建基础开发框架（前端、后端、数据库）
  • 实现核心基础模块（用户管理、认证授权、权限控制、文件存储）
  • 集成国内云服务和第三方服务（阿里云、微信支付、支付宝等）
  • 建立完整的开发文档和规范体系
  • 配置CI/CD流程和基础设施

Impact

  • Affected specs: 全新项目，无现有spec
  • Affected code: 全新项目，需要从零开始构建

ADDED Requirements

Requirement: 项目架构设计

系统SHALL采用Monorepo架构，支持多应用、多包的统一管理。

Scenario: Monorepo架构搭建

  • WHEN 项目初始化时
  • THEN 系统应创建以下目录结构：
    • apps/：应用层（web、admin、mobile、miniapp）
    • packages/：共享包（core、ui、utils、types、config）
    • services/：后端服务（api、worker、realtime）
    • infra/：基础设施配置
    • docs/：文档目录
    • tools/：开发工具（包含CLI工具）

Scenario: 技术栈选择

  • WHEN 选择技术栈时
  • THEN 系统应采用以下技术组合（推荐Node.js全栈方案）：
    • 前端：Next.js 14+ + TypeScript + Tailwind CSS + Shadcn UI
    • 后端：NestJS + Prisma + PostgreSQL
    • 缓存：Redis
    • 消息队列：RabbitMQ
    • 存储：阿里云OSS
    • 部署：Docker + Kubernetes + 阿里云ACK

Requirement: 底座使用方式设计

系统SHALL提供灵活的底座使用方式，支持多种业务场景。

Scenario: Monorepo模式使用（适合同一团队的多项目）

  • WHEN Fischer公司内部开发新业务系统时
  • THEN 系统应支持：
    • 在FischerX Monorepo中创建新应用（apps/）
    • 自动继承packages中的共享包（core、ui、utils等）
    • 共享基础设施配置和CI/CD流程
    • 统一维护和升级核心功能

Scenario: 独立项目模式使用（适合不同客户的项目）

  • WHEN 为客户开发定制系统时
  • THEN 系统应支持：
    • 从FischerX模板创建独立项目
    • 复制核心包到新项目（packages/core、packages/ui等）
    • 自由定制业务功能，不影响其他项目
    • 选择性更新底座功能

Scenario: API服务模式使用（适合轻量级集成）

  • WHEN 需要快速集成底座功能时
  • THEN 系统应支持：
    • 部署FischerX作为共享服务（auth-service、file-service等）
    • 新业务系统通过API调用底座功能
    • 使用客户端SDK简化集成（@fischerx/client-sdk）
    • 统一维护底座服务，自动升级

Scenario: CLI工具支持

  • WHEN 开发者需要创建新项目或应用时
  • THEN 系统应提供CLI工具（fischerx-cli），支持：
    • 创建新应用：fischerx-cli create-app <app-name> --type=web|admin|mobile|miniapp
    • 初始化独立项目：fischerx-cli init <project-name> --template=standalone|monorepo|lightweight
    • 部署共享服务：fischerx-cli deploy-service --services=<service-list>
    • 更新底座版本：fischerx-cli update --scope=core|ui|all
    • 生成业务模块：fischerx-cli generate-module <module-name> --template=crud|cms|ecommerce

Scenario: 核心功能共享策略

  • WHEN 设计底座功能模块时
  • THEN 系统应明确区分：
    • 核心共享功能（packages/core）：用户管理、认证授权、权限控制、文件存储、消息通知
    • 可选共享功能（packages/ui、packages/utils）：UI组件、工具函数、类型定义
    • 业务独立功能（apps//src）：业务逻辑、特定UI、定制功能
    • 配置化驱动：通过配置而非代码实现业务定制

Scenario: 版本管理和更新策略

  • WHEN 底座功能更新时
  • THEN 系统应支持：
    • Monorepo模式：自动更新所有应用
    • 独立项目模式：选择性更新（通过CLI工具）
    • API服务模式：自动更新所有调用方
    • 版本兼容性检查和迁移指南

Requirement: 用户管理模块

系统SHALL提供完整的用户管理功能，支持国内主流认证方式。

Scenario: 用户注册登录

  • WHEN 用户需要注册或登录时
  • THEN 系统应支持以下认证方式：
    • 手机号验证码登录（阿里云短信）
    • 微信登录（OAuth）
    • 支付宝登录（OAuth）
    • 传统邮箱密码登录

Scenario: 实名认证

  • WHEN 用户需要进行实名认证时
  • THEN 系统应集成阿里云实名认证服务，支持：
    • 身份证信息验证
    • 人脸识别验证
    • 身份证OCR识别

Requirement: 权限控制模块

系统SHALL提供基于RBAC的权限控制机制。

Scenario: 角色权限管理

  • WHEN 管理员需要配置权限时
  • THEN 系统应支持：
    • 角色创建和管理
    • 权限分配和继承
    • 资源访问控制
    • 动态权限检查

Scenario: 权限验证

  • WHEN 用户访问受保护资源时
  • THEN 系统应验证用户权限，拒绝未授权访问

Requirement: 认证授权模块

系统SHALL提供安全的认证授权机制。

Scenario: JWT Token管理

  • WHEN 用户登录成功时
  • THEN 系统应生成JWT Token，包含：
    • 用户基本信息
    • 权限信息
    • 过期时间
    • 签名验证

Scenario: Session管理

  • WHEN 用户活跃时
  • THEN 系统应管理用户会话，支持：
    • 会话创建和销毁
    • 会话刷新
    • 多设备登录管理
    • 登录状态同步

Requirement: 文件存储模块

系统SHALL提供统一的文件存储服务，适配国内云存储。

Scenario: 对象存储集成

  • WHEN 用户上传文件时
  • THEN 系统应支持：
    • 阿里云OSS存储
    • 腾讯云COS存储（备选）
    • MinIO私有化部署（备选）
    • 文件上传、下载、删除
    • 图片处理（压缩、裁剪、水印）
    • CDN加速

Scenario: 文件访问控制

  • WHEN 用户访问文件时
  • THEN 系统应验证访问权限，生成临时访问URL

Requirement: 支付系统模块

系统SHALL集成国内主流支付渠道。

Scenario: 微信支付集成

  • WHEN 用户选择微信支付时
  • THEN 系统应支持：
    • 扫码支付
    • H5支付
    • 小程序支付
    • 订单创建和查询
    • 退款处理

Scenario: 支付宝支付集成

  • WHEN 用户选择支付宝支付时
  • THEN 系统应支持：
    • 扫码支付
    • H5支付
    • 订单创建和查询
    • 退款处理

Requirement: 消息通知模块

系统SHALL提供多渠道消息通知服务。

Scenario: 短信通知

  • WHEN 需要发送短信通知时
  • THEN 系统应集成阿里云短信服务，支持：
    • 验证码发送
    • 通知短信发送
    • 营销短信发送（需审核）
    • 发送记录查询

Scenario: 推送通知

  • WHEN 需要发送推送通知时
  • THEN 系统应支持：
    • 小程序推送
    • App推送（阿里云移动推送）
    • 站内消息推送

Requirement: 内容审核模块

系统SHALL提供内容审核服务，满足国内合规要求。

Scenario: 文本审核

  • WHEN 用户提交文本内容时
  • THEN 系统应调用阿里云内容审核服务，检测：
    • 敏感词过滤
    • 政治敏感内容
    • 色情暴力内容
    • 广告垃圾内容

Scenario: 图片审核

  • WHEN 用户上传图片时
  • THEN 系统应调用阿里云图片审核服务，检测：
    • 色情图片
    • 暴力图片
    • 政治敏感图片
    • 广告图片

Requirement: 监控告警模块

系统SHALL提供完善的监控告警体系。

Scenario: 性能监控

  • WHEN 系统运行时
  • THEN 系统应监控：
    • 应用性能指标（响应时间、吞吐量）
    • 资源使用情况（CPU、内存、磁盘）
    • 错误率和异常情况
    • 用户行为数据

Scenario: 告警通知

  • WHEN 监控指标异常时
  • THEN 系统应发送告警通知：
    • 邀请相关人员
    • 提供告警详情
    • 建议处理方案

Requirement: 开发文档体系

系统SHALL提供完整的开发文档。

Scenario: 架构文档

  • WHEN 开发者需要了解架构时
  • THEN 系统应提供：
    • 整体架构设计文档
    • 模块划分说明
    • 技术选型说明
    • 数据流图

Scenario: API文档

  • WHEN 开发者需要调用API时
  • THEN 系统应提供：
    • API接口文档
    • 参数说明
    • 返回值说明
    • 错误码说明
    • 示例代码

Scenario: 开发指南

  • WHEN 新开发者加入时
  • THEN 系统应提供：
    • 快速开始指南
    • 开发规范文档
    • 最佳实践指南
    • 常见问题解答

Requirement: CI/CD流程

系统SHALL建立自动化CI/CD流程。

Scenario: 代码提交

  • WHEN 开发者提交代码时
  • THEN 系统应自动执行：
    • 代码规范检查
    • 类型检查
    • 单元测试
    • 构建验证

Scenario: 自动部署

  • WHEN 代码合并到主分支时
  • THEN 系统应自动部署：
    • 开发环境部署
    • 测试环境部署
    • 生产环境部署（需审批）

Requirement: 国内环境适配

系统SHALL全面适配国内运行环境。

Scenario: 云服务适配

  • WHEN 使用云服务时
  • THEN 系统应优先使用国内云服务：
    • 阿里云（首选）
    • 腾讯云（备选）
    • 华为云（备选）

Scenario: 网络环境适配

  • WHEN 部署应用时
  • THEN 系统应优化国内网络：
    • 使用国内CDN加速
    • 配置国内DNS解析
    • 多地域部署（华北、华东、华南）

Scenario: 合规性适配

  • WHEN 系统上线时
  • THEN 系统应满足国内合规要求：
    • ICP备案
    • 数据本地化存储
    • 实名认证要求
    • 内容审核要求
    • 数据安全法要求

MODIFIED Requirements

无修改需求（全新项目）

REMOVED Requirements

无删除需求（全新项目）