# SPARKProject

**Repository Path**: obslight/sparkproject

## Basic Information

- **Project Name**: SPARKProject
- **Description**: 从 360manager、zcppc、zcpproject 与 metadatamanagement 四个现有项目中提炼的通用工程底座。
- **Primary Language**: Unknown
- **License**: AFL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-13
- **Last Updated**: 2026-07-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SPARK 项目模板

这是从 `360manager`、`zcppc`、`zcpproject` 与 `metadatamanagement` 四个现有项目中提炼的通用工程底座。`apps/web` 是无业务绑定的主模板；`apps/zcppc` 是独立的完整竞价应用示例。仓库不包含真实账号、密码、密钥、来源项目依赖目录或构建产物。

技能套件、技能治理运行时和网页技能工作台已由独立的 `SPARKSkillset` 仓库负责。本仓仅通过 `scripts/spark-skillset-host.mjs` 提供只读发现、预检和固定检查接口，不再承载技能开发源码或技能工厂应用。

## 模板包含什么

- Vue 3 + TypeScript + Vite 的 Web 应用骨架
- Pinia 状态管理、Vue Router 路由与鉴权守卫
- Element Plus 中文环境、自动按需导入、统一设计 Token 与浅色/深色/跟随系统主题
- 环境变量驱动的 API 地址和本地代理
- Axios 请求层：令牌注入、响应头令牌同步、单飞刷新、401 处理、统一错误
- 认证闭环：刷新失败清理会话、统一未授权事件、安全站内重定向
- 多租户登录：公共租户目录、租户偏好、`strUser/strPwd/entName` 登录契约与刷新恢复
- 多应用运行上下文：登录后加载应用目录，应用切换隔离导航缓存、动态路由、页签和 SSE
- 独立的 `core` 包：响应解包、URL、Token Store、JWT 过期判断、平台检测
- 独立的 `qyapi` 包：低代码表协议、过滤 DSL、分页、批量 CRUD、行列权限、Web/Taro transport
- 独立的 `qyapi-ui` 包：字段元数据适配、可视化 FilterBuilder、递归条件组和可注册值函数编辑器
- 独立的 `organization-ui` 包：人员/组织选择、注入式 QYAPI/REST 数据源、远程搜索、分页和移动端全屏
- 独立的 `navigation` 包：异构菜单字段归一、Top/Left 合并、树查询、缓存与动态路由输入
- 独立的 `realtime` 包：完整 SSE 状态机、解析、心跳、重连、事件 Hub、Web/Taro transport
- 独立的 `design-tokens` 包：跨应用共享的颜色、布局、圆角、动效和主题偏好字段
- 独立的 `ui-contracts` 与 `ui` 包：框架无关 UI 数据契约、轮播、列表页壳、全屏弹窗、图片懒加载、文件预览、富文本编辑器与状态标签
- 独立的 `ui-taro` 包与真实 Taro 4.1.9 消费应用：共用 BannerItem/QYAPI 适配、轮播、图片懒加载和跨端 Token
- 独立的 `graph-ui`、`report-ui`、`ai-ui`：canonical 数据契约、注入式运行时、流式消息和重型依赖按需加载
- 自动包体积预算：LogicFlow、SheetJS 和富文本运行时必须独立分块且不得进入 Web 首屏
- `SPARK 蓝 / 中楚暖棕` 两套可切换视觉预设，共享同一组 `--spark-*` Token 字段
- 完整 `zcppc` 竞价应用：公共门户、竞买人、商户、平台端、QYAPI 动态导航与 SSE
- 参照 SPARK_AppWorks 的动态导航 UI：折叠侧栏、移动抽屉、页头、面包屑与键盘可访问页签
- 可视化外观设置：侧栏/页头优先、单页/多页签、面包屑、页脚和偏好迁移
- SSE 运行状态指示、错误提示与手动重连入口
- 强类型运行配置、开发诊断面板与 `pnpm run doctor` 模板体检
- 首屏主题预初始化、Vue 错误边界与全局未捕获异常诊断
- 首页、登录页、受保护工作台和 404 页面示例
- 未实现动态菜单自动挂载占位页，可先验收整棵真实导航，再逐页替换业务组件
- `app / pages / widgets / features / shared` 单向依赖结构与自动架构检查
- pnpm workspace、严格 TypeScript、lint/type-check/build 一键校验

## 快速开始

```powershell
Copy-Item apps/web/.env.example apps/web/.env.local
pnpm install
pnpm dev
```

默认开发地址为 `http://localhost:5173`。后端代理目标由 `VITE_API_PROXY_TARGET` 控制；生产环境推荐只配置 `VITE_API_BASE_URL`，业务代码始终使用相对 API 路径。

运行完整竞价应用：

```powershell
Copy-Item apps/zcppc/.env.example apps/zcppc/.env.local
pnpm dev:zcppc
```

默认地址为 `http://localhost:5373`。只在 `.env.local` 中填写本机代理配置，该文件不会进入版本库。`VITE_EXTERNAL_LOGIN_URL` 留空时，认证失效会返回应用内对应角色的登录页；生产部署需要统一认证时再填写完整地址。

运行 Taro H5 示例或同时构建 H5/微信小程序：

```powershell
pnpm dev:taro
pnpm build:taro
```

H5 默认地址为 `http://localhost:5473`；构建产物分别位于 `apps/taro/dist/h5` 与 `apps/taro/dist/weapp`。

## 新项目接入顺序

1. 修改根目录 `package.json` 和 `apps/web/package.json` 的项目名。
2. 从 `.env.example` 创建各环境文件，填写标题、后端地址及认证路径。
3. 在 `apps/web/src/features/<业务>/api.ts` 增加业务 API；跨功能基础设施放入 `shared`，页面不直接调用 Axios。
4. 配置租户、应用目录与动态导航端点；`VITE_NAV_FALLBACK_APP_ID/VITE_NAV_FALLBACK_ROOT_ID` 只作为无应用目录时的兜底值。
5. 在 `packages/ui/base/tokens/src/theme.css` 调整品牌色与设计令牌，不要新增另一套应用级变量。
6. 删除示例页面或把它们替换成业务页面。
7. 提交前执行 `pnpm check`。

## 目录

```text
apps/web/                 Vue Web 主模板
  src/config/             应用默认值、构建环境和运行时配置入口
  src/app/                组装入口、路由和全局生命周期
  src/pages/              路由页面
  src/widgets/            页面级复合 UI
  src/features/           认证、导航、主题、SSE 等完整功能切片
  src/shared/             API 客户端、诊断和基础 UI
apps/zcppc/               完整竞价应用示例（公共端、商户端、平台端）
apps/taro/                Taro 4.1.9 跨端公共 UI 真实消费应用
deploy/profiles/          full、portal-only、zcppc-only 发布开关
packages/platform/        core、config、navigation、realtime 运行底座
packages/data/            QYAPI 协议、DSL、权限和 transport
packages/ui/base/         数据契约、Token、Vue 与 Taro 基础组件
packages/ui/domain/       QYAPI、人员与组织领域 UI
packages/ui/optional/     图编辑、报表、AI 等按需重型 UI
workspace.catalog.json    AI 可读的包名、路径、职责和关键词目录
AGENTS.md                 AI 任务路由、依赖边界和修改规则
docs/foundation.md        主题、导航、SSE、字段统一总方案
docs/extraction-report.md 三项目提取依据与排除项
docs/qyapi.md             QYAPI 协议、示例和迁移指南
docs/navigation.md        动态导航接入、字段映射和跨端边界
docs/realtime.md          SSE 状态机、订阅、传输与排错指南
docs/configuration.md     环境配置、诊断与模板体检
docs/project-configuration.md 多项目配置分层、字段规范、部署和迁移方案
docs/configuration-blueprint.md 配置实施矩阵、迭代状态和验收门
docs/ui-component-blueprint.md 公共 UI 分层、数据适配、Token 与迭代矩阵
docs/ui-taro.md            Taro 公共 UI 属性、数据边界、Token 与构建指南
docs/organization-ui.md    人员/组织契约、数据源和迁移指南
docs/heavy-ui.md           图编辑、报表、AI、Token 与包体积预算
docs/architecture.md      目录职责、依赖方向和新增代码落位规则
docs/taro-adaptation.md   Taro/小程序复用说明
```

整体规划见 [公共底座方案](docs/foundation.md)，结构约束见 [项目架构指南](docs/architecture.md)，公共包入口见 [公共包地图](packages/README.md)，公共组件见 [UI 组件实施蓝图](docs/ui-component-blueprint.md) 和 [重型 UI 公共层](docs/heavy-ui.md)，配置见 [配置与诊断指南](docs/configuration.md)、[多项目统一配置方案](docs/project-configuration.md) 和 [配置实施蓝图](docs/configuration-blueprint.md)，发布开关见 [应用发布 Profile](deploy/README.md)，详细取舍见 [提取报告](docs/extraction-report.md)，QYAPI 接入见 [QYAPI 指南](docs/qyapi.md)。