OPC-Starter 🚀

一人公司启动器 - AI-Friendly React Boilerplate

专为使用 Cursor、Qoder 等 AI Coding 工具的开发者设计的现代化 React 启动模板。

✨ 特性

• 🤖 AI Coding 友好 - 完整的 BMAD 方法论支持，AI 可理解的代码结构
• ⚡ 现代化技术栈 - React 19 + TypeScript 5.9 + Vite 7 + Tailwind CSS 4.1
• 🔐 开箱即用认证 - Supabase Auth 集成
• 🏢 组织架构管理 - 多层级团队、成员权限
• 🤖 Agent Studio - A2UI 动态 UI 协议，自然语言驱动
• 📦 数据同步 - IndexedDB 缓存 + Supabase Realtime
• 🎨 精美 UI 组件 - 基于 Radix UI + shadcn/ui 风格

🚀 快速开始

AI / Cursor Cloud 最短路径（推荐）

默认推荐 MSW Mock 模式，不依赖真实 Supabase，最适合 AI Coding 工具快速启动、复现和回归：

git clone https://github.com/your-username/opc-starter.git
cd opc-starter
npm --prefix app install
VITE_ENABLE_MSW=true npm run dev:test

启动后浏览器打开 http://localhost:5173，你将看到登录页面。使用以下测试账号登录：

登录成功后即可进入 OPC-Starter 仪表盘，开始体验所有功能。

说明

• 常用 npm 命令可直接在仓库根目录运行，适合从 /workspace 起步的 AI 工具。
• 需要真实后端时，再配置 app/.env.local 并执行 npm run dev。
• MSW 测试账号统一来自 app/cypress/fixtures/users.json。

环境要求

• Node.js >= 20.x
• npm >= 10.x
• Supabase 账户（仅真实后端模式需要）

安装

git clone https://github.com/your-username/opc-starter.git
cd opc-starter

# 安装应用依赖
npm --prefix app install

# 推荐：本地 mock 模式
VITE_ENABLE_MSW=true npm run dev:test

# 可选：真实 Supabase 模式
cp app/env.local.example app/.env.local
npm run dev

环境变量

真实 Supabase 模式下，在 app/.env.local 中配置：

VITE_SUPABASE_URL=your_supabase_url
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
VITE_DASHSCOPE_API_KEY=your_dashscope_api_key  # 可选，用于 Agent LLM

常见问题

npm install 失败 (ECONNRESET)

如果 package-lock.json 引用了无法访问的内部镜像源，删除后重试：

cd app
rm -rf node_modules package-lock.json
npm install --registry https://registry.npmjs.org/

浏览器白屏 / 控制台出现 ERR_NAME_NOT_RESOLVED

原因：浏览器 localStorage 中残留了上次会话的过期 Token，Supabase 客户端尝试向 placeholder.supabase.co 发起真实请求。

修复方法：清除浏览器站点数据后刷新页面。

• Chrome：F12 → Application → Storage → Clear site data
• 或访问 chrome://settings/content/all?searchSubpage=localhost，删除 localhost 数据

控制台出现 WebSocket 连接警告

MSW 模式下，Supabase Realtime 的 WebSocket 连接会因为没有对应的 Mock Handler 而产生警告，这属于预期行为，不影响任何功能。

📁 项目结构

opc-starter/
├── app/                     # 应用主目录
│   ├── src/
│   │   ├── auth/            # 认证模块
│   │   ├── components/      # React 组件
│   │   │   ├── agent/       # Agent Studio (A2UI)
│   │   │   ├── business/    # 业务组件
│   │   │   ├── layout/      # 布局组件
│   │   │   ├── organization/ # 组织架构组件
│   │   │   └── ui/          # 基础 UI 组件
│   │   ├── hooks/           # 自定义 Hooks
│   │   ├── lib/             # 库封装
│   │   │   ├── agent/       # Agent 核心逻辑
│   │   │   ├── reactive/    # 响应式数据层
│   │   │   └── supabase/    # Supabase 客户端
│   │   ├── pages/           # 页面组件
│   │   ├── services/        # 服务层
│   │   │   └── data/        # DataService (同步核心)
│   │   ├── stores/          # Zustand 状态管理
│   │   ├── types/           # TypeScript 类型
│   │   └── utils/           # 工具函数
│   └── supabase/
│       ├── functions/       # Edge Functions
│       └── setup.sql        # 数据库 Schema
├── _bmad/                   # BMAD 方法论配置
├── docs/                    # 项目文档
└── AGENTS.md               # AI Coding 指南

🛠️ 技术栈

🤖 AI Coding 支持

本项目专为 AI Coding 工具优化：

• AGENTS.md - AI 开发规范指南，Cursor/Qoder 可直接解析
• BMAD 方法论 - 结构化的 AI 辅助开发流程
• 类型安全 - 完整的 TypeScript 类型定义，便于 AI 理解
• 模块化架构 - 清晰的目录结构和职责划分
• 根目录代理脚本 - 可直接在仓库根目录执行 npm run dev:test、npm run ai:check

AI 迭代地图

AI 质量入口

# 核心校验（lint + type-check + unit test + build）
npm run ai:check

# 完整校验（额外包含 E2E）
./scripts/quality_check.sh

使用 Cursor

1. 用 Cursor 打开项目
2. 阅读 AGENTS.md 了解项目规范
3. 使用 @file 引用相关文件开始开发

📖 文档

• 架构说明
• 设计系统说明

🗺️ 路线图

• [x] v1.0.0 - 基础 Boilerplate 发布
• [x] v1.1.0 - 主题系统 (深色/浅色模式)
• [ ] v1.2.0 - 多 LLM Provider 支持 (OpenAI, Claude, Gemini)
• [ ] v1.3.0 - 国际化 (i18n)

🤝 贡献

欢迎贡献！请查看 CONTRIBUTING.md 了解详情。

📄 许可证

AGPL-3.0 © OPC-Starter Contributors

Made with ❤️ for Solo Entrepreneurs and AI-Assisted Developers