opc-backup/.claude/memory/MASTER.md

# 总约束（MASTER）

> 全局、跨项目、不可违背。冲突优先级：**项目内 AGENTS.md/README.md 的具体规则 > 本总约束 > 本项目 CLAUDE.md 概述**。
> 每次开发改动前先读本文件（经 /memory）。

## 1. 目录分桶（不可混放）

- `code/` 一切可运行代码 / 代码仓库
- `design/` 项目设计与架构文档
- `materials/` 课程内容、政策研究、园区数据等非代码资料
- `reference/` 参考源（独立仓库，根忽略）

## 2. 仓库纪律

- 主仓库（`opc`）只管 `design/ materials/` 与根文档、全局规范；**不跟踪各 `code/*` 子项目代码，保留文件夹**。
- `code/*` 各为独立仓库（组织 Pine）；`reference/*` 独立仓库。
- 任一子项目改动，在**各自仓库**内分批提交，不得混入根仓库或其它仓库。

## 3. git 提交约定

- 用**中文**、按**功能分批**提交，避免多文件一次提交。
- 提交信息不允许包含 `Co-Authored-By: Claude <noreply@anthropic.com>`。
- 先询问用户验证，通过后再提交。
- 上线/部署相关提交由用户手动执行（`backend-deploy-by-user`）。

## 4. 进程管理铁律

- **AI 绝对禁止启动/重启/停止任何前后端服务进程**（server-core :8090、park-desktop :10085、s2s :8765、vite、Tauri 等）。
- 需要时先通知用户，由用户亲自操作。AI 只做改代码、编译检查、接口测试（仅在服务已运行且不重启前提下）。

## 5. 凭据卫生

- `*.env*`、`*.local` 含密钥/凭据，默认 gitignore，勿提交。
- `.claude/settings.local.json` 为本地配置，勿提交。

## 6. 记忆纪律（本 skill 强制）

- 每次开发/改动**前**调用 `/memory` 载入记忆。
- 每次改动**后**：校验 → 提交 → 更新 `ports/<port>.md` 与 `CURRENT.md`。
- 记忆必须用 `path:line` 锚点，可直接定位。
- 计划变化同步 `LONG-TERM / SHORT-TERM`；规则变化同步本文件或对应 `projects/<port>.md`。

## 7. 后端架构标准（server-core）

- FastAPI **四层架构**（接口→业务→领域→基础设施），禁止反向依赖。
- server-core 与算力调度经**内部 IP/loopback** 交互；对外算力统一走服务端 `/api/v1`。

## 8. UI 基调

- 前端设计不偏离 `code/agent-desktop/console/` 主基调；admin-portal 用 shadcn/ui（遵循 `design/installation.md`）。
- 培训网站/小程序遵循自身「暗色粒子品牌语言」，但整体以 console 为基准。

## 9. 待办 / 已知落差（重要，随时更新）

- server-core 现状为「身份/门户演示」内核：无 `dispatcher.py`、无 `app/training` 子应用（设计与实现不符，待阶段2重构入口）。
- 8 个 RBAC 既有失败测试（权限种子问题）**非本次引入**，待排查。
- 若干 `/admin/*`（课程/活动/报名/测评/园区）与算力管理端点属阶段2-4，尚未实现。

## 10. 项目仓库映射表（迁移 → OPC-Hub 组织）

> 组织 `OPC-Hub` 已建；迁移**按规范名仓库**（server-core/agent-desktop/…，即新名 repo，含四层重构）→ `OPC-Hub/<同名>.git`。
> 原则：① 先把各项目最新代码（含我在旧仓库的改动）**合并/port 进规范名仓库**再转让；② **保留 Pine 旧仓库作备份**；③ 迁后全线用 OPC-Hub，不再碰 Pine。
> 主远端 `origin`=infoepoch，副远端 `infoepoch_lan`。`Pine/*` 旧名仓库（PineAgents/PineAgentsServer/PineAgentsWeb/DPM/opc）作备份保留，不迁移。

| 项目（规范名） | 被迁仓库 | 来源（Pine） | 目标（OPC-Hub） | 状态 |
|------|------|------|------|------|
| server-core | server-core | `Pine/server-core` | `OPC-Hub/server-core` | ✅ `b90539a`（port 四层+阶段0-1） |
| agent-desktop | agent-desktop | `Pine/agent-desktop` | `OPC-Hub/agent-desktop` | ✅ `f44b12f`（并 TaskSquare） |
| web-official | web-official | `Pine/web-official` | `OPC-Hub/web-official` | ✅ `d33b25f` |
| park-desktop | park-desktop | `Pine/park-desktop` | `OPC-Hub/park-desktop` | ✅ `63dc6b8`（并 admin UI+vision_yolo） |
| compute-engine | compute-engine | `Pine/compute-engine` | `OPC-Hub/compute-engine` | ✅ `6880ae7` |
| training | training | `Pine/training` | `OPC-Hub/training` | ✅ `3c9a13a` |
| admin-portal | admin-portal | （无，新建） | `OPC-Hub/admin-portal` | ✅ `258bccf`（新建+推送） |

> 其它（reference/ 下 PinePixel、cloud-opc；bark-notify 临时）**不在**迁移范围。
> **全部 7 个 code/ 仓库已迁至 OPC-Hub**；各本地克隆已改指 `OPC-Hub/<同名>.git`（origin=infoepoch + infoepoch_lan），工作树 clean。所有 `Pine/<同名>` 旧仓库与旧名（PineAgents/PineAgentsServer/PineAgentsWeb/DPM/opc 等）**作备份保留**，不再作为日常使用。
> Gitea 管理 token 存于仓库外自动记忆（勿入库）：[[gitea-opchub-token]]。

## 11. 仓库迁移执行记录（2026-08-24 全部完成）

- **server-core**：port 阶段0-1 至四层仓库 → 推 Pine/server-core → transfer OPC-Hub（`b90539a`）→ 本地全新克隆。
- **agent-desktop**：并 TaskSquare 改（4 文件）→ 推 Pine/agent-desktop(`f44b12f`) → transfer。
- **park-desktop**：并 admin 新 UI+vision_yolo（6 文件）→ 推 Pine/park-desktop(`63dc6b8`) → transfer。
- **compute-engine / training / web-official**：transfer（web-official 采纳新仓库部署文档版）。
- **admin-portal**：新建 OPC-Hub/admin-portal（`POST /orgs/OPC-Hub/repos`）+ 推送本地。
- 所有 `Pine/*` 备份保留；本地 7 clone 均改指 `OPC-Hub/<同名>.git`。