# SPARKProject

**Repository Path**: obslight/sparkproject

## Basic Information

- **Project Name**: SPARKProject
- **Description**: No description available
- **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-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SPARK 项目模板

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

## 模板包含什么

- Vue 3 + TypeScript + Vite 的 Web 应用骨架
- Pinia 状态管理、Vue Router 路由与鉴权守卫
- Element Plus 中文环境、自动按需导入、统一设计 Token 与浅色/深色/跟随系统主题
- 环境变量驱动的 API 地址和本地代理
- 统一 HTTP 通信层：Axios 仅作为 `platform/core` 私有实现，认证会话、Token 轮换、单飞刷新、401 重放、统一错误与 HTTP 国密都由公共运行时处理
- lowcode 后端 primary 响应：普通 REST 统一按 `AjaxResult { Code, Message, Result, Type, Extras, Time }` 解释；专用文件 GM 默认关闭并等待后端三个阻塞闭环，SSE 按后端证据保持在普通 HTTP GM 之外
- 认证闭环：刷新失败清理会话、统一未授权事件、安全站内重定向
- 多租户登录：公共租户目录、租户偏好、`strUser/strPwd/entName` 登录契约与刷新恢复
- 多应用运行上下文：登录后加载应用目录，应用切换隔离导航缓存、动态路由、页签和 SSE
- 独立的 `core` 包：公共 HTTP/API 端口、core 私有 Axios、响应解包、URL、凭据会话、JWT 过期判断、HTTP SM4-GCM 与平台检测
- 独立的 `qyapi` 包：低代码表协议、过滤 DSL、分页、批量 CRUD、行列权限、table definition/query view/service 与通用 HTTP transport
- 独立的 `qyapi-ui` 包：字段元数据适配、可视化 FilterBuilder、递归条件组和可注册值函数编辑器
- 独立的 `organization-ui` 包：人员/组织选择、注入式 QYAPI/REST 数据源、远程搜索、分页和移动端全屏
- 独立的 `navigation` 包：异构菜单字段归一、Top/Left 合并、树查询、缓存与动态路由输入
- 独立的 `realtime` 包：包内唯一 `createSseTransport`，应用使用高层 Hub/Client/POST-stream 门面，复用完整 SSE 状态机、解析、心跳与重连
- 独立的 `design-tokens` 包：跨应用共享的颜色、布局、圆角、动效和主题偏好字段
- 独立的 `ui-contracts` 与 `ui` 包：框架无关 UI 数据契约、工作区页签状态、可访问页签栏、轮播、列表页壳、全屏弹窗、图片懒加载、文件预览、富文本编辑器与状态标签
- 独立的 `ui-taro` 包与真实 Taro 4.1.9 消费应用：共用 BannerItem/QYAPI 适配、轮播、图片懒加载和跨端设计 Token
- 独立的 `graph-ui`、`report-ui`、`ai-ui`：canonical 数据契约、注入式运行时、流式消息和重型依赖按需加载
- 自动包体积预算：LogicFlow、SheetJS、富文本和 Stimulsoft 必须独立分块；Web 首屏与 MDM 启动闭包不得携带重型运行时
- `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` 留空时，认证失效会返回应用内对应角色的登录页；生产部署需要统一认证时再填写完整地址。

运行迁移后的 SPARK 项目管理首波应用：

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

默认地址为 `http://localhost:5573`。应用复用元数据平台认证、动态导航和数据空间模型；项目页不包含源项目后端代码。客户承载 PMP 业务，机构、子机构、机构角色和用户仅作为后端权限主体，并通过机构客户映射建立授权范围。

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

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

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

## 新项目接入顺序

Vue 业务项目以 `apps/web` 为通用起点；Taro 跨端项目以 `apps/taro` 为起点。
`apps/metadatamanagement` 和 `apps/zcppc` 是复杂领域应用，只作为实现参考。

先选择接入方式：

- 独立产品：在模板副本中保留 `apps/web` 作为产品入口，修改根包名、应用包名和应用身份。
- 新增 workspace 应用：复制 `apps/web` 到 `apps/<application-code>`，使用唯一 npm 包名，并保留
  `app/config/pages/widgets/features/shared` 六层结构。

按以下顺序完成接入：

1. 确定稳定的应用编码、npm 包名、运行端、部署标识和 `architectureProfile`。同步更新
   `workspace.catalog.json`；如果修改已有包名或路径，还要同步根 `package.json` 中的过滤脚本和所有引用方。
2. 为应用保留独立的 `.env.example`、本机 `.env.local`、`public/runtime-config.json` 和
   `src/config` 入口。填写标题、后端地址、认证、租户、应用目录、导航和 SSE 字段；浏览器可读取的配置中不得放密码、Token、私钥或数据库凭据。
3. 先打通“配置加载 → 登录/会话恢复 → 应用目录 → 动态导航 → 一个业务页面”的最小闭环，
   再逐步替换或删除示例页面。
4. 在 `features/<业务>` 或 `shared/api` 中增加命名业务 API 门面。应用只声明业务 endpoint、
   输入输出和用例编排，不直接接触 Axios、`fetch`、`EventSource`、拦截器或 Token。
5. QYAPI 页面通过 `@spark-template/qyapi` 消费查询、保存和后端最终权限，通过
   `@spark-template/qyapi-ui` 映射字段及按钮状态；页面不得自行归并角色权限或重建查询上下文。
6. 品牌色、间距和布局统一修改 `packages/ui/base/tokens` 中的语义 Token，不新增应用私有的
   第二套品牌变量；图、报表和 AI 等重型 UI 保持动态导入。
7. 新增 workspace 应用时同步补齐应用测试、根目录开发/构建快捷脚本和 `scripts/doctor.mjs`。
   如进入统一发布链，还要登记 `scripts/build-release.mjs`、所有发布 Profile；需要独立包体预算时同步更新预算检查。
8. 先运行应用相关测试，再执行 `pnpm doctor`、`pnpm check:structure` 和
   `pnpm check:architecture`；提交前执行完整 `pnpm check`。
9. 发布时验证构建产物、`release-manifest.json`、后端应用目录和租户授权一致，确保未发布应用
   不会保留可点击入口。

## 目录

```text
apps/web/                 Vue Web 主模板
  src/config/             应用默认值、构建环境和运行时配置入口
  src/app/                组装入口、路由和全局生命周期
  src/pages/              路由页面
  src/widgets/            页面级复合 UI
  src/features/           认证、导航、主题、SSE 等完整功能切片
  src/shared/             业务 API 门面、运行配置、诊断和基础 UI
apps/zcppc/               完整竞价应用示例（公共端、商户端、平台端）
apps/spark-pmp/           复用元数据平台后端的数智化项目管理应用
apps/taro/                Taro 4.1.9 跨端公共 UI 真实消费应用
deploy/profiles/          full、metadata-only、portal-only、zcppc-only 发布开关
packages/platform/        core、config、navigation、realtime 运行底座
packages/data/            QYAPI、PMP canonical 模型、DSL、权限和 transport
packages/ui/base/         数据契约、Token、Vue 与 Taro 基础组件
packages/ui/domain/       QYAPI、人员与组织领域 UI
packages/ui/optional/     图编辑、报表、AI 等按需重型 UI
workspace.catalog.json    AI 可读的包名、路径、职责和关键词目录
skills/                   仓库版本化的 SPARK Codex 技能唯一源码
AGENTS.md                 AI 任务路由、依赖边界和修改规则
docs/foundation.md        主题、导航、SSE、字段统一总方案
docs/extraction-report.md 三项目提取依据与排除项
docs/qyapi.md             QYAPI 协议、示例和迁移指南
docs/api-governance-blueprint.md 后端 API SSOT、core HTTP/SSE 双出口与分批迁移计划
docs/api-protocol-governance.json endpoint 引用、重复资源 owner 与安全 profile 机器治理表
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)，API 收口见 [后端 API SSOT 与双 Transport 治理蓝图](docs/api-governance-blueprint.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)。lowcode primary 响应、HTTP GM、实验性文件 GM 与 SSE 例外的后端证据见 [后端通信修补说明](docs/lowcode-jdk17-backend-transport-patch-plan.md)；SSE 前端边界见 [SSE 实时通信指南](docs/realtime.md)。