# PROJECT KNOWLEDGE BASE

**Generated:** 2026-05-26
**Commit:** 4913d1c
**Branch:** develop

## OVERVIEW

**craftlabs-authorization-sdk** — 创飞客户端授权 SDK 工作区。多语言 monorepo：Java (Maven) 封装授权 API + Rust (Cargo) native cdylib + Vue 3 交付管理后台 + Spring Boot 后端服务。37k+ 行源码，活跃开发中。

## STRUCTURE

```
./
├── java/                     # Maven 多模块 SDK (core, bitanswer, selfhosted, tests)
├── native/                   # Rust Cargo workspace (craft-core cdylib, CLI tool)
├── services/                 # Spring Boot 后端服务
│   ├── delivery-platform-api/    # 商业交付管理 API (153 Java 文件)
│   └── license-webhook-ingress/ # Webhook 回调入口 (小)
├── web/
│   └── delivery-platform-ui/     # Vue 3 前端 (47 src 文件)
├── schemas/                  # craftlabs-auth-config JSON Schema
├── examples/                 # 示例配置 (java/cpp/python/vc)
├── docs/                     # 产品/流程/工程架构文档
│   └── engineering/              # 系统架构、工程边界、并行迭代
└── engineering/              # 工作区 manifest, 规划工程占位
```

## WHERE TO LOOK

| Task | Location | Notes |
|------|----------|-------|
| SDK 授权核心逻辑 (Java) | `java/craftlabs-auth-core/src/` | config, internal 模块 |
| 比特安索集成 | `java/craftlabs-auth-bitanswer/` | 单一 Java 文件 |
| 自托管授权提供者 | `java/craftlabs-auth-selfhosted/` | 同上 |
| Rust native C ABI | `native/craft-core/src/` | lib.rs 导出 craft_* 函数 |
| 安全反调试/混淆 | `native/craft-core/src/security/` | anti_debug, obfuscation |
| CLI 工具 | `native/craftlabs-auth-cli/src/` | status/activate/check/info 命令 |
| 平台后端 Controller | `services/delivery-platform-api/` | 按领域分包 (contract, license, device 等) |
| 平台持久层 | `services/delivery-platform-api/` | persistence/ 下每实体一对 (POJO+Mapper) |
| 平台 DTO | `services/delivery-platform-api/` | web/dto/ 下 47 个请求/响应类 |
| Webhook 回调 | `services/license-webhook-ingress/` | webhook 入口 + persistence |
| 前端视图 | `web/delivery-platform-ui/src/views/` | Vue 3 组件 (38 文件) |
| 数据库迁移 | `services/delivery-platform-api/` | src/main/resources/db/migration/ |
| JSON Schema | `schemas/` | craftlabs-auth-config 校验 |
| CI/CD (Gitea Actions) | `GITEA_CI_CD.md` | act_runner 配置 |

## CONVENTIONS

- **Java**: Spring Boot 3.x, MyBatis-Plus, Maven multi-module. 每实体一对 `Entity` + `Mapper` 接口。控制器统一 `@RestController` + `@RequestMapping("/api/v1/...")`. 异常处理统一 `ApiExceptionHandler`.
- **Rust**: cdylib 导出 `craft_*` C ABI。`Provider` trait 模式。安全模块独立 `security/` 子树。
- **Vue**: Vue 3 + Composition API (`<script setup>`). 视图集中 `src/views/`.
- **SQL**: Flyway 迁移在 `db/migration/`, 前缀 `V{version}__{description}.sql`.
- **发布**: SDK 发版生成 SHA256SUMS + 可选 GPG 签名, 见 `java/RELEASING.md` + `scripts/sdk-release-checksums.sh`.

## ANTI-PATTERNS (THIS PROJECT)

- **不要** 把 SDK jar 打进平台 Fat JAR (bootstrap 唯一 repackage)
- **不要** 在客户端 SDK 中依赖平台后端代码 (运行时解耦)
- **不要** 混用 JNI 和 JNA 桥接 — 当前已迁移到 JNA

## COMMANDS

```bash
# Java SDK 构建 (JDK 17+)
mvn -f java/pom.xml clean verify

# Rust native 构建 (Rust 1.70+)
cargo build --manifest-path native/craft-core/Cargo.toml --release

# 前端
cd web/delivery-platform-ui && npm install && npm run build
```

## NOTES

- 平台后端/前端按架构设计为独立工程，本仓库含源码仅为过渡期方便迭代。正式部署时按 `engineering/planned/` 规范开独立仓。
- native/craft-core 曾用 JNI bridge，现已迁移至 JNA (commit 027ecbd)。
- 有三轨并行迭代：后端/前端/SDK，详见 `docs/engineering/PARALLEL_ITERATION_INDEX.md`。