# OIP-Lite

**Repository Path**: nanayin/OIP-Lite

## Basic Information

- **Project Name**: OIP-Lite
- **Description**: 前端轻量
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-10-12
- **Last Updated**: 2026-10-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OIP-Lite

> **文档版本**：v1.1 | **更新**：2026-09-26 | **状态**：详细设计
>
> OIP（开放互联协议）**轻量端** —— 微信小程序原生 + TypeScript 的极简实现。
> 能力等级：**L1 基础可互操作**（OIP.md / OIP-Frontend-Design.md §11.1）。
>
> **关联**：[English](README.en.md) · [AGENTS.md](AGENTS.md) · [docs/OIP-Lite-Design.md](docs/OIP-Lite-Design.md)

## 它是什么

OIP-Lite 是奥集能 V6 架构中 HCI 端的**轻量端**形态（OIP-Frontend-Design.md §1.1），
面向「小程序框架或 WebView 嵌入」场景，核心约束是**离线缓存与受限环境适配**。

它不是 oiocns-uniapp 的简化版，而是按 OIP 协议面**重新对齐**的实现：
所有用户操作最终映射为 OIP 协议定义的权利操作，不直连数据核、不私建通道。

## 技术栈

| 项 | 取值 | 依据 |
| --- | --- | --- |
| 运行时 | 微信小程序原生（WXML / WXSS / JSON / TS 四件套） | `project.config.json` |
| 语言 | TypeScript 5.4+，仅作类型检查（`tsc --noEmit`），运行期由开发者工具编译 | `package.json` · `miniprogram/tsconfig.json` |
| 编译插件 | 微信开发者工具内置 TypeScript 编译（`setting.useCompilerPlugins: ["typescript"]`） | `project.config.json` |
| 基础库 | `libVersion: 3.5.0` | `project.config.json` |
| 渲染 | `renderer: "webview"`，`lazyCodeLoading: "requiredComponents"` | `miniprogram/app.json` |
| 包体 | **零运行时依赖**：`setting.nodeModules: false`，且 `packOptions.ignore` 排除 `package.json` | `project.config.json` |
| TS 目标 | `target: ES2018` / `module: ESNext` / `strict: true` | `miniprogram/tsconfig.json` |
| 工具链 | Python 3（协议面生成校验与静态一致性自检，纯标准库实现） | `tools/check_consistency.py` |

`node_modules/` 仅供本地类型检查使用，不进入小程序包体。

## 目录结构

```
OIP-Lite/
├── miniprogram/                小程序根目录（project.config.json 的 miniprogramRoot）
│   ├── app.ts / app.json        应用入口与全局配置（pages / tabBar / window）
│   ├── app.wxss                 全局样式
│   ├── state.ts                 全局运行态
│   ├── sitemap.json             索引配置
│   ├── tsconfig.json            TypeScript 配置（noEmit）
│   ├── protocol/                协议面生成物（@generated，勿手改）+ 派生层 index.ts
│   ├── domain/                  L1 领域层：vet / did / work / relation / asset / event / result
│   ├── infra/                   基础设施：storage（带新鲜度）/ http / gateway（REST + Mock 双模）/ mock
│   ├── provider/                L2：OIP State Provider 三契约（vet-store / did-auth / event-sync）
│   ├── services/                L2：业务服务（work / relation / asset）
│   ├── pages/                   L5 表现层：9 个页面
│   ├── components/              共用组件：vet-card（VET 卡片）、status-view（四态容器）
│   ├── config/                  配置注入层（env.ts）与功能开关（feature.ts）
│   ├── styles/                  设计令牌（tokens.wxss，派生自 oiocns-uniapp 的 oip_tokens 原始层）
│   ├── typings/                 微信小程序类型声明（wx.d.ts）
│   └── utils/                   守卫与格式化（guard / format）
├── tools/check_consistency.py   静态一致性自检（纯标准库）
├── docs/OIP-Lite-Design.md      本仓详细设计
├── package.json                 本地校验脚本与 TypeScript 开发依赖
└── project.config.json          微信开发者工具团队共享配置（入库）
```

分层依据 OIP-Frontend-Design.md §2.1（L1 领域 → L2 服务 → L5 表现），
**依赖方向单向向下**：页面 → 服务 → Provider → 基础设施 → 领域。

## 快速开始

### 在微信开发者工具中运行

```bash
# 1. 用微信开发者工具导入：目录选 OIP-Lite，appid 选「测试号」或填入自己的 appid
# 2. 直接编译预览 —— 默认启用内置 Mock 数据源，无需后端即可跑通全部页面
```

开发者工具读取 `project.config.json`（团队共享配置，入库）；窗口布局等本地差异写入
`project.private.config.json`（不入库）。

默认账号：任意 DID + 任意口令（Mock 模式）。预填 `did:oip:org_alpha:employee_zhang`。

### 接入真实节点

修改 `miniprogram/config/env.ts` 的 `DEFAULTS`：

```ts
OIP_REST_ENDPOINT: "https://your-node.example.com/oip/v1",
OIP_NODE_DID: "did:oip:node:your-org:xxxx",
OIP_USE_MOCK: false,
// 微信快捷登录的提供方标识（须与 OIP-Login 的 providers[].idp_namespace / app_id 一致）；
// 留空则微信快捷登录诚实降级，不发出注定 4041 的请求。
OIP_LOGIN_IDP_NAMESPACE: "wechat.open",
OIP_LOGIN_APP_ID: "wx-app-1",
```

或在「我的」页关闭「内置 Mock 数据源」开关（运行期覆盖，落本地存储）。
切换后需重新登录——Mock 签发的会话对真实节点无效。

真实节点下登录入口的当前边界（未接线者一律诚实降级，不伪造成功）：

| 入口 | 通道 | 说明 |
| --- | --- | --- |
| 账号口令 | `POST /oip/v1/auth/login`（`method: "password"`） | 节点对外部凭据的签发面未接线，返回 `OIP_5031`，页面上原样呈现 |
| 微信快捷登录 | OIP-Login `login/authorize-url` + `login/poll` | 小程序无法内嵌浏览器完成跳转，授权链接需在已登录的桌面端打开；`login/complete` 需 DID 私钥签名的 Proof，本端不具备 |
| 注册 | `POST /api/v1/did/person`（前门匿名通道 → 权威面 `target.create`） | 只创建主体与 DID 文档，不签发会话 |
| 忘记密码 | — | 权威面无找回端点，入口只给出指引 |

## 命令

以下脚本定义于 `package.json`，均需在仓库根目录执行：

| 命令 | 实际执行 | 说明 |
| --- | --- | --- |
| `npm install` | — | 安装 `typescript`（仅本地校验用，不进入小程序包体） |
| `npm run typecheck` | `tsc --noEmit -p miniprogram/tsconfig.json` | TypeScript 类型检查 |
| `npm run check:consistency` | `python3 tools/check_consistency.py` | 静态一致性自检 |
| `npm run protocol:check` | `python3 ../OIP/tools/gen_protocol.py --check` | 协议面漂移校验 |
| `npm run protocol:gen` | `python3 ../OIP/tools/gen_protocol.py` | 重新生成协议面产物 |
| `npm run verify` | 上述三者串联 | 一键门禁：协议面漂移 + 静态一致性 + TS 类型，三者全绿才算通过 |

### 静态一致性自检

校验 `app.json` 页面四件套、tabBar、`usingComponents` 路径、wxml 标签声明、
TS 相对 import 可解析性、协议面生成物头部：

```bash
python3 tools/check_consistency.py
```

### 协议面产物

协议面（错误码 / 事件主题 / 内核六元组 / CloudEvents 字段）由
`OIP/spec/*.json` 经生成器产出，**禁止手工编辑**：

```bash
python3 ../OIP/tools/gen_protocol.py --check   # 校验是否漂移
python3 ../OIP/tools/gen_protocol.py           # 重新生成
```

## 功能

`miniprogram/app.json` 声明 9 个页面，其中 4 个为 tabBar 一级入口：

| 页面 | 路径 | tabBar 入口 | 说明 |
| --- | --- | --- | --- |
| 权利夹 | `pages/wallet/index` | 是 | VET 列表，按生命周期筛选；VET 详情完整呈现**内核六元组** |
| 待办 | `pages/todo/index` | 是 | 工作流任务列表与审批；审批提交服务端 PDP 裁决 |
| 关系 | `pages/relation/index` | 是 | 人员 / 群组 / 组织只读浏览（含搜索） |
| 我的 | `pages/mine/index` | 是 | 身份、协议面自报、数据源切换、退出登录 |
| 登录 | `pages/login/index` | — | DID 登录（Mock 模式接受任意 DID + 口令） |
| 权利详情 | `pages/vet-detail/index` | — | 单个 VET 的内核六元组与委托链 |
| 办事详情 | `pages/work-detail/index` | — | 任务详情与审批提交 |
| 数据空间 | `pages/asset/index` | — | 数据胶囊只读浏览，标注授权来源与派生客体约束 |
| 智能体 | `pages/agent/index` | — | L2/L3 能力说明页（默认不在一级入口；需服务端 L2/L3 能力） |

## 与 OIP 其他仓库的关系

本仓是 OIP 工作区的 L6 人机交互端之一，与其他仓库**零代码级依赖**，通过 HTTP 经
OIP-GoInOne 前门耦合。工作区内的相对路径（纯文本）：

| 路径 | 关系 |
| --- | --- |
| `../OIP` | 协议与设计文档仓：`../OIP/spec/protocol.json`、`../OIP/spec/events.json` 是协议面单一真相源；`../OIP/tools/gen_protocol.py` 是本仓协议面产物的生成器 |
| `../OIP/docs/OIP.md` | 架构总纲：本仓的定位与分层依据 |
| `../OIP/docs/OIP-Frontend-Design.md` | L6 前端契约：节点发现、Hub 方法、错误码、能力等级 |
| `../OIP-IoT` | L1 物联网网关，经前门路由（本仓不直连） |
| `../OIP-Mobile` | L6 移动端（Flutter），与本仓同层不同形态 |
| `../OIP-Desktop` / `../OIP-Web` | L6 PC 本地终端与 Web 端，与本仓同层不同形态 |
| `../OIP-GoInOne` | 统一接入前门：认证、路由、上行转发 |

## 设计约束（实现时严格遵守）

- **协议面单一来源**：错误码等常量由生成器产出，本仓只派生不手写（OIP.md §1.6 原则 12）。
- **默认拒绝**：未显式授权一律拒绝；前端缓存 NEVER 作为放行依据，权利行使回源由服务端裁决。
- **主体标识主权**：DID 不由微信等外部账号派生；外部账号是**证据**不是主体。
- **四态覆盖**：所有数据加载型视图覆盖 加载中 / 空 / 失败 / 成功，**静默失败不可接受**。
- **品牌克制**：每视图至多 1 个品牌 CTA，动效 ≤ 300ms，最小交互区 88rpx（≈44px）。

详细架构见 [`docs/OIP-Lite-Design.md`](./docs/OIP-Lite-Design.md)。

## 许可

MIT（与其他 OIP 代码仓一致）。