契约层概览

contracts/ 是 Java、Python、前端 对齐的「唯一真相源」。

目录

路径	说明
openapi/rbac-api.yaml	REST API：路径、请求体、响应体
sql/schema.sql	MySQL RBAC 表结构

修改流程

1. 改 rbac-api.yaml 或 schema.sql
2. 同步 server-java Controller / Service
3. 同步 server-python router / service
4. 同步 packages/shared/types、api-client
5. 同步 admin 页面（若涉及 UI）
6. 更新本文档（若行为变化）

核心约定

• API 前缀：/api/v1
• JSON 字段：camelCase
• 认证：Authorization: Bearer <accessToken>
• 统一响应：{ code, message, data }
• 成功时 code === 0

与各包关系

contracts/openapi  →  server-java / server-python 实现
                  →  packages/shared/types（手写对齐，可未来 codegen）
contracts/sql      →  docker-compose 初始化
                  →  Java Entity / Python SQLAlchemy Model

相关文档

• OpenAPI 约定
• 数据库表结构
• API 响应规范