#核心概念

AppKernia 的价值不只来自技术栈，更来自三端共同遵守的边界。

#三端契约链

一项接口改动从数据库与服务端规则出发，经 OpenAPI 同步到两个生成客户端，再由 Admin 与 Mobile 的页面和测试共同验证。

接口改动不是只修改一个 Handler。涉及字段、权限或数据范围时，服务端实现、OpenAPI、数据库、权限 Seed、生成 Client 和集成测试必须沿这条链同步。任何一端出现“临时手写 DTO”，都可能让编译通过却在运行时漂移。

#职责边界

#一次请求如何流动

客户端提供请求上下文，但可信的用户、租户、权限和数据范围都在服务端解析；SQL 层落实隔离，客户端只依据稳定状态码更新界面。

1. 客户端带上 Accept-Language；Mobile 还发送公开的 X-AppID，受保护请求携带对应 Audience 的身份凭据。
2. API 解析 Locale、Session、App 与 Tenant，从服务端身份上下文决定权限和数据范围。
3. Application 执行业务规则，Repository/sqlc 在 SQL 层落实租户过滤与事务。
4. 响应使用稳定业务错误码和 Content-Language；客户端只按稳定码决定状态，不解析文案。
5. 必要的写操作同步形成审计或安全事件，异步工作交给 Worker。

• 总体架构：Mobile、Admin、API、Worker 与 PostgreSQL 如何协作。
• 认证与会话：Access Token、Refresh Token 轮换与 Audience 隔离。
• 权限与多租户：菜单、权限、数据范围和 SQL 过滤的职责。
• 国际化：zh-CN / en-US 的统一契约。
• 安全模型：秘密、上传、日志、重试与扩展的红线。