Nova

面向香港及大中华区的 B2B SaaS 公司秘书管理平台

---

🚀 项目简介

Nova 是一个企业级的公司秘书服务管理平台，提供从客户签约、委托处理、财务跟踪到合规申报的全生命周期管理。专为香港及大中华区市场设计，满足本地法规和业务需求。

核心业务模块：

• 👥 CliModule - 客户管理（UserAccount、Company、AssociatedPerson）
• 🏢 OrgModule - 组织架构（Employee、Department）
• 💰 FinModule - 财务管理（Invoice、PurchaseOrder、Transaction）
• 📋 EngModule - 委托管理（Matter、Project、Submission）
• 🛍️ SvcModule - 服务产品（Package、Product、FormTemplate）
• ⚙️ MgtModule - 管理系统（配置、审计、监控）

技术特色：

• 💎 NovFramework: 自研业务框架（NovCore、NovForm、NovChat、NovNotification）
• ⚡ Livewire 3: 全栈式 Reactive PHP UI，无需 JavaScript
• 🧪 Pest 4: 现代化测试驱动开发，支持浏览器自动化
• 🐳 Docker + Sail: 开箱即用开发环境，一键启动
• 🌏 多语言: 支持繁体中文（zh_HK）、英文（en_GB）、简体中文

---

📦 技术栈

类别	技术	版本	用途
后端	PHP	8.2+	核心语言
	Laravel	12.x	Web 框架
	Laravel Reverb	1.x	实时通信
	Laravel AI	^0.1.5	AI 集成
	Laravel MCP	^0.5.6	AI 工具服务
前端	Livewire	3.x	服务器驱动 UI
	Volt	1.7.x	单文件组件
	Tailwind CSS	4.x	样式框架
	DaisyUI	5.x	组件库
业务框架	Spatie Model States	^2.12	状态机
	Lorisleiva Actions	^2.9	业务操作
	Spatie Permission	^6.21	权限管理
开发工具	Laravel Sail	1.52.x	Docker 环境
	Laravel Pint	1.25.x	代码格式化
	Pest	4.x	测试框架
	Playwright	1.58.x	E2E 测试
	PHPStan	2.1.x	静态分析

---

🏗️ 架构亮点

Monorepo 结构

nova/
├── app/
│   ├── CliModule/      # 客户管理
│   ├── OrgModule/      # 组织架构
│   ├── FinModule/      # 财务管理
│   ├── EngModule/      # 委托管理
│   ├── SvcModule/      # 服务产品
│   ├── MgtModule/      # 管理系统
│   ├── NovCore/        # 核心框架（NovAction/NovState）
│   ├── NovForm/        # 动态表单系统
│   ├── NovChat/        # 即时通讯
│   └── NovNotification/# 通知系统
├── packages/           # 可复用包（如 NovForge）
├── docs/               # 详细文档（194+ 文档）
└── AGENTS.md           # AI 助手指南

核心设计模式

• Domain-Driven Design (DDD): 模块化按业务域划分，每个模块独立自治
• State-Action Pattern: NovAction + NovState 统一业务操作模式，清晰的状态流转
• Dynamic Forms: NovForm 提供可配置表单系统，支持 FieldTemplate、FormSection
• Real-time: Reverb + NovChat 实现即时通讯、通知推送
• Notifications: 三通道通知（站内、Email、Toast）统一管理

详细架构请见 docs/architecture/business.md。

---

🚦 快速开始

前置要求

• Docker & Docker Compose
• Git
• Node.js 20+ (用于前端构建)

1. 克隆项目

git clone https://github.com/your-org/nova.git
cd nova

2. 启动开发环境

# 启动 Sail 容器（首次会自动构建）
vendor/bin/sail up -d

# 安装 PHP 依赖
vendor/bin/sail composer install

# 安装前端依赖
vendor/bin/sail npm install

# 生成应用密钥
vendor/bin/sail artisan key:generate

3. 配置环境

# 复制环境文件
# 选择对应环境的模板文件并复制到 .env：
#   - 本地开发: cp .env.example .env
#   - 沙箱环境: cp docker/sandbox-cn/.env.example .env
#   - 生产环境: cp docker/production-hk/.env.example .env

# 编辑 .env，设置数据库连接（Sail 默认已配置）
# DB_CONNECTION=pgsql
# DB_HOST=pgsql
# DB_PORT=5432
# DB_DATABASE=nova
# DB_USERNAME=sail
# DB_PASSWORD=password

4. 初始化数据库

# 运行迁移
vendor/bin/sail artisan migrate

# 填充基础数据（可选）
vendor/bin/sail artisan db:seed

# 填充测试数据（开发环境）
vendor/bin/sail artisan db:seed --class=TestDataSeeder

5. 启动开发服务器

# Sail 已包含 Nginx + PHP + PostgreSQL + Redis
# 访问应用: http://localhost

# 前端热重载（新终端）
vendor/bin/sail npm run dev

6. 运行测试

# 所有测试 (Pest 4, 注意: 并行已禁用)
vendor/bin/sail artisan test

# 质量门禁检查 (提交前必须通过)
vendor/bin/sail bin pint          # 代码格式化
vendor/bin/sail artisan phpstan   # 静态分析 (level 1)

# 特定测试组
vendor/bin/sail artisan test --group=Unit
vendor/bin/sail artisan test --group=Integration

# 浏览器 E2E 测试 (Playwright, 需ChromeDriver)
vendor/bin/sail npm run test  # 或 vendor/bin/sail playwright test

当前测试状态 (2025-03-12):

• ✅ 质量门禁已建立: Pint 100%, PHPStan level 1 (0 errors)
• ⚠️ 已知限制:
  • 5个 IssueCommandsTest 单元测试失败 (Mock绑定问题)
  • Feature测试套件自动发现故障 (0个测试可运行)
  • PHPStan level 3: 207 errors (过高, 降级为level 1)
• 📊 测试覆盖率: 未测量

详细测试质量改进报告见: .sisyphus/plans/archive/test-quality-improvement/FINAL_REPORT.md

```bash
# 所有测试 (Pest 4)
vendor/bin/sail artisan test

# 带覆盖率报告
vendor/bin/sail artisan test --coverage

# 特定测试
vendor/bin/sail artisan test --filter=UserAccountTest

# 浏览器 E2E 测试 (Playwright)
vendor/bin/sail npm run test  # 或 vendor/bin/sail playwright test

---

配置管理

文件结构

• .env - 核心配置（运行时必需，gitignore）
• .env.local - 本地覆盖（仅开发环境，gitignore）
• docker/sandbox-cn/.env.example - 沙箱环境模板
• docker/production-hk/.env.example - 香港生产环境模板

首次设置

1. 选择环境，复制对应模板到 .env：

   # 沙箱（开发测试）
   cp docker/sandbox-cn/.env.example .env
   
   # 生产（香港）- 仅在服务器部署时使用
   cp docker/production-hk/.env.example .env
   

2. 编辑 .env，修改以下关键项：

   APP_KEY=base64:...          # 运行 `php artisan key:generate`
   APP_URL=http://你的域名
   DB_DATABASE=nova
   DB_USERNAME=sail
   DB_PASSWORD=你的强密码
   

3. 启动容器（沙箱环境）：

   docker compose -f docker-compose.sandbox.cn.yml up -d
   

环境切换

• 开发：APP_ENV=local + .env.local 覆盖调试设置
• 沙箱：APP_ENV=local（或 staging）
• 生产：APP_ENV=production + APP_DEBUG=false

Sail vs Docker

• 本地开发：使用 vendor/bin/sail up（依赖 .env + .env.local）
• 沙箱测试：使用 docker compose -f docker-compose.sandbox.cn.yml
• 生产：不使用 Docker（直接部署）或使用 docker-compose.prod.*.yml

环境变量优先级

1. Shell 环境变量（最高）
2. .env.local（开发时覆盖）
3. .env（基础配置）

Git Hooks Setup

Nova uses Husky v9+ for Git hooks. After cloning the repository, run the setup script to install hooks:

bash scripts/setup-husky.sh

This creates symbolic links from .husky/ to .git/hooks/ and ensures hooks are executable.

What the hooks do:

• pre-commit: Runs code style checks (Pint), static analysis (PHPStan), and domain constraint validation
• commit-msg: Validates commit message format using commitlint

Manual verification:

# Check hooks are linked
ls -l .git/hooks/pre-commit .git/hooks/commit-msg

# Test a commit (bypass hooks with --no-verify if needed)
git commit -m "test"

See docs/security/env-protection.md for Git safety best practices.

---

📚 文档

注意: 文档已迁移至 docs/ 统一目录，所有文档现在通过 docs/INDEX.md 导航。

核心文档

文档	说明
📖 完整文档索引	所有项目文档的导航中心（194+ 文档）
🏗️ 架构设计	系统架构、设计决策、业务规则
📦 模块开发	如何开发新模块、编码规范
🧪 测试策略	测试规范、覆盖率要求
🔄 NovAction 迁移	老代码迁移到新框架指南

模块文档

模块	文档	说明
NovCore	app/NovCore/README.md	核心框架（状态-操作模式）
NovForm	app/NovForm/README.md	动态表单系统
NovChat	app/NovChat/README.md	即时通讯
NovNotification	app/NovNotification/README.md	通知系统
CliModule	app/CliModule/README.md	客户管理模块
OrgModule	app/OrgModule/README.md	组织架构模块
FinModule	app/FinModule/README.md	财务管理模块
EngModule	app/EngModule/README.md	委托管理模块
SvcModule	app/SvcModule/README.md	服务产品模块

AI 开发助手

• 🤖 AGENTS.md - 为 AI 助手提供的项目上下文（技能激活、规范、架构）

---

🤝 贡献指南

我们欢迎社区贡献！请遵循：

1. Fork & Branch: 基于 feature/first 分支创建功能分支
2. 遵循规范: 遵守项目的 Laravel 规范 和 NovCore 约定
3. 测试驱动: 新功能必须包含测试，确保覆盖率不下降
4. 代码格式: 提交前运行 vendor/bin/sail bin pint
5. 更新文档: 修改代码时同步更新相关文档（docs/ 或模块 docs/）
6. PR 描述: 清晰说明变更内容和原因，关联 Issue

详细指南见 CONTRIBUTING.md（待创建）。

---

🔄 版本历史

• v0.2.0 (2025-02-25): 架构重构、模块独立化、Pest 4、Playwright、PostgreSQL 支持
• v0.1.1 (2025-09-03): 初始版本，基础认证和模块框架

完整变更见 CHANGELOG.md。

---

📄 许可证

MIT License。详见 LICENSE 文件。

---

📞 支持与联系

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• 邮件: dev@example.com
• 文档: docs/INDEX.md

---

Made with ❤️ by Nova Team
面向香港及大中华区的企业级解决方案