opc-backup/CLAUDE.md

# 云超服 / PineAgents — 项目总览（工作区根目录）

本目录是 **云南省 OPC 超级个体综合服务平台（云超服，Cloud 超服）** 与相关配套业务（园区大屏展播、OPC 培训体系、资料搜集）的工作区根目录。

> **整体不是单一 monorepo**，而是「多个独立 git 仓库 + 若干根仓库跟踪内容」的组合。请勿在根目录 `git init`，也不要把独立仓库并入根仓库。
>
> **目录规范（分桶）**：本项目严格按「代码 / 设计文档 / 资料内容」三桶分层，**不得把代码与设计、资料混放在一起**：
> - `code/` → 一切可运行代码 / 代码仓库
> - `design/` → 项目设计与架构文档
> - `materials/` → 课程内容、政策研究、园区数据等非代码资料

---

## 一、业务背景与合作关系

- **甲方 / 作者**：云南派音人工智能科技有限公司（AI 开发专家团队），入驻 **昆明市大学生创业园**。
- **园区运营方**：昆明市大学生创业园是**唯一一个政府直属的创业园区**（直属昆明市人社局），由**云南浙青创投资有限公司**运营。
- **合作**：派音与浙青创联合开发了**云南省超级个体服务平台（云超服）**，并合作开展一系列 OPC 培训、运营、扶持项目。
- **获客逻辑**：以园区为基础开展公益课 / 交流沙龙引流 → 最终导向双方合作的线上线下课程（见 `materials/培训计划/`）。
- 合作背景详见 `materials/培训计划/课程体系0.1/项目背景.md` 与 `商业模式审查与完善.md`。

---

## 二、目录布局

### 顶层分桶

| 桶 | 说明 | 跟踪方式 |
|----|------|----------|
| `code/` | **所有代码 / 代码仓库**（见下） | 混合（部分根仓库跟踪，部分独立仓库） |
| `design/` | **项目设计与架构文档**（见下） | 根仓库 |
| `materials/` | **资料 / 课程内容 / 政策研究 / 园区数据** | 根仓库（园区数据资料已忽略） |
| `reference/` | 参考源（`PinePixel/` 园区像素可视化、`cloud-opc/` OPC 前端骨架） | 独立仓库（含 .git，根仓库忽略） |
| `CLAUDE.md` / `README.md` / `.gitignore` / `.claude/` | 根级文档与配置 | 根仓库 |

### `code/` — 代码仓库

| 子目录 | 说明 | Git |
|--------|------|-----|
| `code/PineAgents/` | 云超服**核心**。前端 / 桌面端 / CLI 端，含 `console/`（PC 后台 UI 基调来源）。 | 独立仓库（忽略） |
| `code/PineAgentsServer/` | 云超服**总后端**。FastAPI 演示后端（认证转发、登录注册），uv 管理。 | 独立仓库（忽略） |
| `code/PineAgentsWeb/` | 云超服**网页展示端**。Vite + React SPA，项目身份 `pineagents-web`。 | 独立仓库（忽略） |
| `code/dpm/` | **园区大屏媒体轮播系统（DPM）**。Tauri + React 大屏 + FastAPI 后端。 | 独立仓库（忽略） |
| `code/bark-notify/` | **Bark 手机推送工具**（Python，uv，零第三方依赖）。 | 根仓库 |
| `code/opc-training/` | **OPC 培训系统代码**（`miniprogram/` 小程序、`website/` 三端 Web、`server/` FastAPI 后端）。 | 根仓库 |

### `design/` — 项目设计与架构文档

| 子目录 | 说明 |
|--------|------|
| `design/云超服平台/` | 云超服平台设计文档（含 `DESIGN.md` 顶层总览、系统方案、身份体系、全量方案、架构推演、Creative-Cards、`任务类别.json`）。 |
| `design/dpm/` | DPM 大屏系统文档（部署、更新、语音、MQTT 手册、ESP32）。 |

### `materials/` — 资料 / 内容

| 子目录 | 说明 |
|--------|------|
| `materials/培训计划/` | **OPC 培训课程体系**（课程内容、模板、知识库、配套件；代码已移至 `code/opc-training/`）。 |
| `materials/搜集资料/` | **云南 OPC 政策与研究资料**（政策汇总、创业伙伴调研方案、网页存档）。 |
| `materials/园区数据资料/` | 园区原始数据资料（PDF / 定稿压缩包 / 表格），**已 gitignore**。 |

---

## 三、关键约定（必须遵守）

1. **UI 风格基调**：凡涉及前端设计，**必须不偏离 `code/PineAgents/console/` 的主基调**（见其 `src/styles`、主题与组件体系）。不得另起一套视觉语言。培训网站/小程序遵循自身「暗色粒子品牌语言」（见 `materials/培训计划/课程体系0.1/知识库/`），但整体观感仍以 console 为基准。
2. **文档位置**：云超服平台架构 / 系统设计 / 设计规范文档放 `design/云超服平台/`；DPM 系统文档放 `design/dpm/`；培训课程内容放 `materials/培训计划/`；大屏/培训系统代码放 `code/`。
3. **代码与内容分离**：新增代码一律入 `code/`，新增设计文档入 `design/`，新增资料/内容入 `materials/`，**不得混放**。
4. **参考源**：园区像素可视化参考 `reference/PinePixel/`；OPC 平台前端骨架参考 `reference/cloud-opc/`。
5. **Git 远端规范**：独立仓库远端遵循 `git@<host>:Pine/<ProjectName>.git`。两个主机：`infoepoch`（生产 Gitea，47.108.226.213）与 `infoepoch_lan`（局域网 Gitea，192.168.1.3）。新项目默认同时注册，主远端命名 `origin`。
6. **进程管理铁律**：**AI 绝对禁止启动 / 重启 / 停止任何前后端服务进程**（PineAgentsServer :8090、DPM 后端 :10085、s2s 语音 :8765、vite、Tauri 等）。需要时先通知用户，由用户亲自操作。AI 只做改代码、编译检查、接口测试（仅在服务已运行且不重启的前提下）。参见各子项目 `AGENTS.md`。
7. **凭据卫生**：`*.env*`、`*.local` 含密钥 / MQTT 凭据，默认加入 `.gitignore`，勿提交。DPM 的 `backend/.env` 与根 `.env.local` 尤其要注意。
8. **工作流**：改动代码后先询问用户验证，通过后按功能分批用**中文**提交，避免多文件一次提交。

---

## 四、各子项目说明与常用操作

### 1) 云超服平台（code/PineAgents / PineAgentsServer / PineAgentsWeb）

- **PineAgentsServer** 是主后端认证转发的来源：`code/PineAgents/src/pineagents/app/routers/auth.py` 将 `/api/auth/*` 转发到 PineAgentsServer（`PINEAGENTS_DEMO_BASE_URL` 默认 `http://127.0.0.1:8090`）。
- 登录身份：多身份 / 多端口账号模型（OPC 端、运营管理端、政务端、甲方企业端、服务商端、创业载体端），见 `design/云超服平台/身份体系与端口权限设计方案.md`。

```bash
# PineAgentsServer（uv 管理）
cd code/PineAgentsServer && uv sync && uv run uvicorn app.main:app --port 8090 --reload

# PineAgents console（yarn）
cd code/PineAgents/console && yarn dev

# PineAgentsWeb（pnpm / npm）
cd code/PineAgentsWeb && pnpm install && pnpm run dev
```

### 2) 园区大屏系统 DPM（`code/dpm/`，独立仓库）

**数字标牌 / 园区展播大屏控制**，服务昆明市大学生创业园：数据大屏、数字孪生 3D、AI 助手、语音助手、媒体轮播、企业展示墙，浏览器后台可远程控制。

- **架构**：数据走 REST（FastAPI `:10085`），控制走 **MQTT（EMQX）**，SSE `/api/events` 作回退；桌面壳为 Tauri 2。
- **后端**：`code/dpm/backend/`（FastAPI + uv），入口 `backend/main.py` → `app/main.py`；模块 `app/routers.py`（REST）、`app/mqtt.py`、`app/sim_engine.py`（模拟引擎）、`app/storage.py`（JSON 持久化）、`app/llm.py` + `app/tools.py` + `app/rag.py`（DashScope AI）、`app/asr.py`、`app/s2s_bridge.py`（实时语音 :8765）、`app/vision_yolo.py`（手势识别）。
- **前端**：`code/dpm/src/`（React 19 + Vite + Tailwind + three.js + MQTT + Tauri）。路由 `/`（数据）、`/twin`、`/ai`、`/screen`、`/voice`、`/wall`；**`/admin` 是后端 Jinja 页面，非 React 路由**。
- **文档**：权威说明 `code/dpm/backend/README.md`；系统/运维文档见 `design/dpm/`。
- **进程规则**：见 `code/dpm/AGENTS.md` —— AI 禁止启动/重启后端 / vite / Tauri。

```bash
cd code/dpm
yarn dev            # 前端 vite
cd backend && uv sync && cp .env.example .env && uv run python main.py   # 后端 :10085
docker compose up -d --build                                            # Docker（后端 + EMQX）
```

### 3) OPC 培训课程体系（`materials/培训计划/` 内容 + `code/opc-training/` 代码）

课程产品为「诊断 + 陪跑 + OPC 体系设计」三件套，线上标准服务（¥499–1299）与线下深度服务（¥1980–3980）两个独立付费产品。权威产品规格见 `materials/培训计划/课程体系0.1/课程产品体系.md`（三阶标准服务体系旧版文件已标注「已纠正」，以 0.1 为准）。

- **代码**（`code/opc-training/`）：`miniprogram/`（Taro+React 微信小程序）、`website/`（Vite+React 三端 Web）、`server/`（FastAPI+SQLite 后端 :8091）、`sync-server.sh`。见 `code/opc-training/README.md`。
- **内容**（`materials/培训计划/课程体系0.1/`）：`核心模板/`（T01–06）、`交付SOP/`（S01–03）、`课程设计/`（01–04）、`运营工具/`、`宣传与运营/`、`知识库/`、`自我认知工具/`、`OPC创业测评/`。
- **小程序↔网页同步约束**：C 端任一功能在网页改动后必须同步到小程序（共用 OPC 测评/政策/报名等模块），见 `materials/培训计划/课程体系0.1/小程序同步约束.md`。
- 顶层 `materials/培训计划/配套件/` 是另一套并行的课程配套模板包（作业、Prompt、政策手册、分班定制、结业四件套、直播/工作坊大纲），以 `00_索引与使用说明.md` 为入口。

```bash
# 小程序
cd code/opc-training/miniprogram && yarn dev:weapp
# 后端（uv）
cd code/opc-training/server && uv run uvicorn app.main:app --port 8091 --reload
# 网站
cd code/opc-training/website && pnpm dev
```

### 4) 云南 OPC 资料搜集（`materials/搜集资料/`）

- `政策汇总.md` — 云南 OPC 政策权威汇总（v2026-08-20）：省级核心政策、云岭创业贷、创业赛事、风险提示，含官方来源链接。
- `云南OPC创业伙伴深度调研方案.md` — 面向园区视察的调研方案（抽样 / 问卷 / 深度访谈 / 6+1 维度）。
- `网页文章/` — 网页存档（OPC 真实案例拆解、省人社厅政策通知）。

### 5) Bark 推送工具（`code/bark-notify/`）

Python（uv，零第三方依赖）发送 Bark 手机推送。入口 `bark-notify`，默认服务器 `http://47.108.226.213:10086`、设备 key 经 `BARK_DEVICE_KEY` 覆盖。用于部署 / 服务器告警通知。

---

## 五、设计文档索引（`design/`）

### `design/云超服平台/`
- `DESIGN.md` — 云超服平台**顶层系统设计总览**（简洁版）。
- `云南省OPC超级个体综合服务平台（云超服）系统设计方案.md` — **主设计文档**（平台定位、三端政务协同、AI 智能体、服务生态）。
- `云超服平台全量方案设计.md` — 构建蓝图（身份体系、六端口管理功能、状态机、数据模型、接口设计）。
- `身份体系与端口权限设计方案.md` — 多身份 / 六端口账号与 RBAC + 数据范围模型。
- `架构初步设计.md` — 分阶段架构推演。
- `Creative-Cards-DESIGN.md` — Creative Cards 组件设计规范。
- `任务类别.json` — 任务撮合分类数据（种子/参考数据）。

### `design/dpm/`
- `win-deploy.md`（Windows 部署 / 地址覆盖）、`update-check.md`（更新接口）、`voice-integration-plan.md`（实时语音）、`mqtt-commands.md`（MQTT 控制手册）、`esp32-ir-control.md`（ESP32 遥控）。

---

## 六、目录规范速查

| 放什么 | 放哪里 |
|--------|--------|
| 可运行代码 / 代码仓库 | `code/` |
| 云超服设计 / 架构文档 | `design/云超服平台/` |
| DPM 大屏系统文档 | `design/dpm/` |
| 培训课程内容 / 模板 / 知识库 | `materials/培训计划/` |
| 培训系统代码（小程序/网站/后端） | `code/opc-training/` |
| 云南 OPC 政策 / 调研资料 | `materials/搜集资料/` |
| 园区原始数据资料 | `materials/园区数据资料/`（gitignore） |
| 参考源（像素可视化 / 前端骨架） | `reference/` |

> 各子项目内部文档以各自的 `README.md` / `CLAUDE.md` / `AGENTS.md` 为准；本文件仅描述整体结构与跨项目约定。对 DPM 大屏系统，权威说明以 `code/dpm/backend/README.md` 为准。