feat: 实现 Ora Cloud 阶段一权威核心架构并补齐各模块 README 架构文档

[wanglongan587]

1. 提交功能概述 (Features Delivered)

本 PR 提交了 Ora Cloud 阶段一的权威核心服务端架构实现，并建立了对齐 Ora 桌面端规范的全模块架构文档体系。主要包含以下关键能力：

1. 权威云端核心与领域聚合 (Authoritative Cloud Core & Aggregates)：
   • 采用 Go (Gin) 构建权威云端后端服务，将租户 (Tenant)、用户 (User)、项目 (Project)、工作区 (Workspace)、任务 (Task)、沙箱实例 (Sandbox Instance)、执行节点 (Workspace Node)、会话 (Session)、持久化操作 (Operation) 与副作用 (Effect) 等领域实体落地为完备的业务状态机。
   • 确立 PostgreSQL 17 为系统唯一的权威持久化实现，所有状态流转均受数据库级强一致性外键与条件约束保护。
2. 有序向前数据库迁移体系 (Ordered Schema Migrations)：
   • 引入嵌入式版本化 SQL 迁移 (0001_core.sql 至 0004_effect_intent_and_ticket_scope.sql)。
   • 启动时对迁移脚本计算 SHA256 校验和并进行严格校验（防篡改与防历史漂移），生产服务启动时严禁自动运行 DDL 或变更表结构。
3. 两层安全身份验证与信任体系 (Two-tier Authentication & Trust)：
   • 结合非对称加密（Ed25519/RS256）设计服务层与用户层分离的双重 JWT 机制：网关凭据负责识别调用来源角色，用户凭据负责识别最终操作人，二者在路由边界强绑定，防止伪造身份。
4. 接口幂等重放与并发防护 (Idempotency & Concurrency Protection)：
   • 基于 Idempotency-Key 与请求体哈希值，实现针对租户和用户维度的安全幂等控制（相同请求安全重放历史响应，相异请求返回冲突拒绝）。
   • 实体变更引入严格的版本号 (version) 乐观并发控制，控制器工作流引入租约与递增纪元号 (epoch) 隔离。
5. 配套工具链与端到端测试套件 (Tooling & Test Suites)：
   • cloudctl：限制性运维管理 CLI，负责数据库迁移 (migrate)、原子初始化租户与管理员 (bootstrap)、安全注册基础设施凭证引用 (credential-ref)。
   • simulator：端到端本地模拟环境，在内存与磁盘中提供 Substrate 存储、Git 仓库夹具以及 Controller 执行调度替身。
   • openapi 与 checkformat：代码即契约（自动生成并校验 api/openapi.json）与严格的格式检查门禁。
   • integration：基于真实 PostgreSQL 隔离 Schema 的全链路集成测试与并发竞争检查。
6. 全模块 README.md 架构文档与根目录索引 (Module Architecture Documentation)：
   • 参照 D:\project\desktop（Ora 桌面端）规范，为 cmd/*、internal/*、pkg、integration 等 18 个模块建立了专业技术英文文档，明确各模块的职责范围、并发规则与所有权边界，并在根目录 README.md 中同步建立了完整的架构导航。

---

2. 解决的问题与动机 (Problem Statement & Motivation)

1. 解决原有脚手架缺乏工业级一致性与生产边界的问题：
   • 此前仓库仅包含简单的示例用户 CRUD 模板，缺乏云端多租户组织隔离、事务一致性、生命周期状态流转和执行契约，无法支撑企业级开发工作区与 AI Agent 会话托管。
2. 解决执行面与控制面职责不清的问题：
   • 明确了“云端权威核心只负责状态、授权与调度规划，实际的代码拉取、工作区挂载、容器执行均由外部 Controller/Substrate 异步执行”的架构切分，防止后端直接引入长耗时的网络或进程任务导致系统崩溃。
3. 解决架构规范碎片化与协作认知成本高的问题：
   • 缺乏模块级职责说明会导致后续迭代出现“路由层写数据库逻辑”、“事务跨网络调用造成连接池耗尽”等架构劣化。通过补全各模块文档，确立了清晰的单向依赖与设计规则。

---

3. 方案设计理由与考量 (Design Rationale & Considerations)

1. 事务级全局咨询锁保证状态机串行安全性：
   • 在阶段一的单集群控制面中，采用数据库事务级咨询锁 (pg_advisory_xact_lock) 来串行化核心聚合根的写入，彻底规避了高并发下复杂状态转移竞态（Race Condition）的问题。
   • 绝对不变量：数据库事务仅局限在纯 SQL 执行区间，绝对不在事务内持有网络请求、外部进程调用或磁盘 I/O。
2. 深度防御型的输入校验与错误隔离：
   • HTTP 传输层严格限定请求体上限为 64KB，防止恶意大包造成拒绝服务攻击。
   • 采用显式字段白名单机制，未知 JSON 字段直接拒绝，杜绝非预期的参数注入。
   • 内部数据库错误与堆栈细节全由服务端结构化日志记录，对外统一映射为稳定的 Fault 错误结构，彻底杜绝数据表名、SQL 语句或凭据泄露风险。
3. 代码驱动的单一可信源 (Single Source of Truth)：
   • 路由实现、OpenAPI 契约生成与 OpenAPI JSON 文件强关联，杜绝接口实现与接口文档脱节的“双重事实”问题。

---

4. 权衡与取舍 (Trade-offs & Sacrifices)

1. 写吞吐量 vs 状态转移强一致性：
   • 取舍：阶段一为了确保多实体联动（如项目创建联动主工作区与存储配置）的状态机绝对可靠，采用了数据库事务级咨询锁串行化写操作，牺牲了一定的并发写吞吐量。
   • 理由：控制面操作（创建项目、启停工作区）本身属于中低频调用，确保状态一致性和零竞态远比单节点每秒数千次写吞吐更重要；后续可无缝平滑迁移至分租户细粒度锁。
2. 自动化热变更 vs 生产环境稳定性：
   • 取舍：放弃了框架常见的“服务启动时 AutoMigrate 自动修改表结构”，强制要求线上数据库变更必须通过独立的运维命令行 cloudctl migrate 预先执行，服务启动仅做只读校验和核验。
   • 理由：避免了线上多实例并发启动时执行 DDL 导致的死锁或表级排他锁事故，符合严格的企业级发布标准。
3. 内存即时态 vs 外部持久化：
   • 取舍：后端进程自身保持无状态，不在内存中持久化业务实体；跨请求的运行状态完全委托给 PostgreSQL。
   • 理由：确保实例随时可重启、水平扩展，即使服务异常崩溃也不会遗失未落盘的业务数据。

---

5. 专业术语通俗解释 (Terminology Explained)

为了让不同背景的工程师与审阅者都能顺畅理解本次提交的核心设计，特将文中所涉关键术语解释如下：

• 聚合根 (Aggregate Root)：
  • 软件工程 / 领域驱动设计 (DDD) 术语。指一组紧密关联的业务实体的管理者与代表（例如“项目”是聚合根，它下面的“工作区”和“存储配置”是其子实体）。外部修改必须通过聚合根进行统一校验，防止子实体状态出现混乱。
• 幂等性 (Idempotency)：
  • 分布式系统 / 计算机术语。指“无论执行多少次，产生的结果都与执行一次完全相同”的特性。例如网络闪断导致客户端重发创建请求，服务端通过 Idempotency-Key 识别出这是同一请求，直接返回之前创建好的对象，而不会重复创建出两个相同的项目。
• 乐观并发控制 / 乐观锁 (Optimistic Concurrency Control, OCC)：
  • 数据库 / 软件工程术语。一种假设不会经常发生并发冲突的策略。在修改数据时不加锁，而是随数据带上一个版本号（version）。写入时检查当前数据库里的版本号是否还是之前的版本，如果是则加一保存；如果版本已被别人改过，则拒绝写入（返回 409 冲突），让调用者重试。
• 数据库咨询锁 (Advisory Lock)：
  • PostgreSQL 数据库特性。一种由应用程序根据特定业务含义主动申请的锁，它独立于具体的某张数据表或数据行，随事务提交或回滚自动释放。本次用于对关键控制面事务加一把统一的互斥锁，确保同一时间只有一个核心操作在推进状态。
• 纪元 / 栅栏令牌 (Epoch & Fencing Token)：
  • 操作系统 / 分布式系统概念。指一个单调递增的版本代数或租约期数。当旧的控制器由于网络卡顿延迟响应，而新的控制器已被选举产生并赋予了更高的 Epoch 时，数据库将拒绝带有旧 Epoch 的写操作，从而防止出现两个系统同时写入同一份数据的“脑裂 (Split-Brain)”现象。
• DDL (Data Definition Language) & AutoMigrate：
  • 数据库术语。数据定义语言，指创建表、修改表结构、删除表的 SQL 语句（如 CREATE TABLE）。AutoMigrate 是部分 ORM 框架提供的自动改表功能。本方案在生产中禁用自动改表，改用显式、可复现、带校验和的向前迁移脚本。
• 双重凭据机制 (Two-tier Credentials)：
  • 系统安全概念。把“访问系统的服务端程序身份（如 API 网关）”和“坐在电脑前发操作的人（最终用户）”分为两个独立的 JWT 令牌分别校验，且强制要求两个身份存在合法绑定，防止中间人伪造用户或网关越权。
• 执行替身 / 测试双工 (Test Double / Simulator)：
  • 软件测试术语。在本地或测试环境中，用一个轻量、受控的模拟组件（如内存中的文件系统、本地 Git 仓库）代替真实的复杂重型基础设施（如 Kubernetes 集群、远程云存储），从而能够秒级执行完整端到端测试。

---

6. 关联 Issue 说明 (Related Issues)

• 提交前已检索 ora-space/cloud 上的 Issue 列表，当前上游主仓库无对应待关闭的开放 Issue（No matching open issues found）。
• 如后续有对应 Tracking Issue，可在合并时使用 Closes #<issue_id> 进行自动关联合并。

---

7. 代码与文档同步保证 (Code & Documentation Sync)

• 本次提交前严格执行了代码格式验证 (task format:check)、静态检查 (task lint) 以及所有单元与契约测试 (task test:unit、internal/contract 契约比对测试全部通过)。
• 根目录 README.md 与全部 18 个模块的 README.md 已全面同步并包含双向跳转索引。
• Commit 信息严格遵守规范，未包含任何 Co-authored-by 等额外无关信息。