mirror of https://github.com/hpd840321/craftlabs-authorization-sdk.git synced 2026-06-09 10:00:30 +08:00

Files

T

huangping 1333cb38d6 docs: add AGENTS.md, code audit reports, and implementation plans

Added hierarchical AGENTS.md files for root, java, native, services, web modules. Added comprehensive audit reports covering PRD progress, UI audit, full version gap analysis, code audit findings, and ONLYOFFICE status.

Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>

2026-05-27 08:37:24 +08:00

3.9 KiB

Raw Blame History

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

# 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。

3.9 KiB Raw Blame History Unescape Escape