Aistudio 密码 逻辑全抽离,UI 抽象化,存储契约化

写入文档

在这种架构下，Web、PWA、React Native 以及 Edge Worker 共享同一个“大脑” (Action Layer)，改变的仅仅是“神经传导方式”（tRPC、HTTP 或直接本地调用）和“记忆介质”（D1、Supabase 或 SQLite）。


文档 1：技术架构与零硬编码规范 (ARCH_STANDARDS.md)
codeMarkdown
# 技术架构与零硬编码规范 (Architecture & Decoupling Standards)

## 1. 核心分层架构：动作契约化
系统不再区分传统的 Hooks 和 Services，而是统一抽象为 **API 层 (Action Layer)**。UI 仅通过契约调用动作，不关心是本地执行还是远程执行。

### 1.1 分层职责
*   **表现层 (React/RN UI)**: 纯视图。通过统一的 API 客户端发起动作，接收 `Result` 对象。
*   **API 层 (Actions/Procedures)**: 【契约中心】定义所有可执行的操作（如 `getUser`, `updateHealthLog`）。
    *   **tRPC 实现**: 用于 Web/PWA，提供端到端类型安全的远程调用，直接连接 Cloudflare Workers。
    *   **HTTP/REST 实现**: 用于兼容性场景或第三方集成。
    *   **Local 实现**: 用于 React Native 或 PWA 离线模式，直接在本地运行业务逻辑。
*   **持久层 (Storage Adapters)**: 【存储契约】API 层不直接操作数据库，而是调用 `StorageAdapter` 实现增删改查。

## 2. 存储适配器模式 (Storage Adapter Pattern)
为了支持从 Supabase 到 Cloudflare D1 的无缝迁移，存储层必须契约化：
*   **实现类**: `SupabaseAdapter`, `D1Adapter`, `SqliteAdapter` (RN/Local)。
*   **原则**: 业务逻辑仅通过 `IStorageAdapter` 接口操作数据，屏蔽具体厂商 SDK。

## 3. 渲染策略：流量驱动型 SSG (Analytics-Driven)
*   **90/10 法则**: Astro 构建时获取 Cloudflare 流量统计，仅预渲染前 10% 的高频页面。
*   **动态回退**: 剩余 90% 页面由 Edge Worker 通过 API 层进行 SSR 渲染，并缓存至 KV。

## 4. 零硬编码准则 (Zero Hardcoding Policy)
*   **配置化**: 所有的 API Endpoint、存储提供商标识、功能开关必须存储在 `AppConfig` 中。
*   **设计令牌 (Design Tokens)**: 样式必须使用 Token（如 `theme.spacing.md`），以便 Web (Tailwind) 与 RN (StyleSheet) 共享一套视觉逻辑。
*   **文案国际化**: 严禁在 API 返回值或 UI 中硬编码中文/英文，必须通过 i18n ID 引用。

---

## 5. RN 迁移就绪清单
- [ ] API 层是否实现了双端适配（tRPC 远程 / Local 运行）？
- [ ] 所有的样式是否基于 Token 抽象，而非硬编码 CSS？
- [ ] 是否存在逻辑层直接引用 `window` 或 `localStorage` 的情况？
文档 2：类型安全最佳实践 (TYPE_SAFETY.md)
codeMarkdown
# 类型安全最佳实践 (Type Safety Guidelines)## 1. 契约优先：tRPC & Zod 集成
系统架构的核心是 **“类型即契约”**。

*   **定义端**: 使用 Zod 定义输入输出的 Schema。
*   **消费端**: 通过 tRPC 自动推导客户端 API 的入参和出参类型，实现 0 API 文档化开发。
*   **跨平台**: 同一套 Zod Schema 必须同时用于 Web 端的 tRPC 和 RN 端的本地逻辑校验。

## 2. 结果对象模式 (Result Pattern)
为了统一处理本地错误、网络错误和业务错误，API 层必须返回：
```typescript
type Result<T, E = AppError> = 
  | { ok: true; data: T; source: 'server' | 'cache' | 'local' } 
  | { ok: false; error: E };
UI 强制处理: 表现层通过判断 ok 状态进行渲染，杜绝未捕获异常。
3. 零 any 原则与类型守卫
禁止 any: 外部输入（如 URL 参数、存储读取）默认为 unknown。
运行时检查: 必须通过类型谓词 (Type Predicates) 或 Zod 解析后才能进入业务逻辑。
4. 存储层类型契约
codeTypeScript
interface IStorageAdapter {
  // 使用泛型 T 确保从存储获取的对象符合领域模型定义
  query<T>(collection: string, params: QueryParams): Promise<Result<T[]>>;
  
  auth: {
    getSession(): Promise<Result<Session | null>>;
  };
}
5. 样式与 Token 类型化
codeTypeScript
// 定义全局统一的设计 Token 类型type ColorToken = keyof typeof DesignSystem.colors;
type SpacingToken = keyof typeof DesignSystem.spacing;

// UI 组件 Props 必须引用这些 Token 类型，而非 string
6. 类型安全检查清单
所有的 API 动作是否都有对应的 Zod 校验？
结果对象是否包含了 source 字段以支持移动端离线感知？
是否在 API 层之外的地方引用了数据库厂商的类型？（应使用自定义的 Entity 类型）
所有的枚举值是否都使用了 as const 或 enum 进行类型化？

写入文档
# 单体应用向 Monorepo 架构迁移指南 (Monorepo Migration Guide)

当项目从典型的单体（Monolithic）结构向更严谨的 Monorepo 结构演进时，本指南提供了标准化的迁移路径与最佳实践。

---

## 1. 迁移原则 (Principles)
*   **应用与库的分离**：`apps/` 存放可独立部署的程序；`packages/` 存放被依赖的逻辑库。
*   **功能归位**：服务端入口应属于具体的应用环境，核心业务逻辑应抽离为独立包。
*   **最小化路径风险**：通过代理入口保持兼容，逐步完成深度重构。

---

## 2. 迁移步骤 (Step-by-Step)

### 第一步：目录结构重构
1.  **创建包目录**：在 `/packages` 下创建标准化的子目录，如下：
    *   `ui/`：存放 React/Vue 通用组件。
    *   `core/`：核心模块 (db, payment, utils)。
    *   `api/`：站点感知的 Hono 业务 API。
    *   `auth/`：独立认证 Worker。
    *   `video-service/`：异步任务 Worker。
    *   `types/`：共享 TypeScript 类型。
    *   `config/`：共享构建配置 (ESLint, Prettier)。
2.  **规划边界**：确定哪些是独立的应用（部署单位），哪些是共享的逻辑依赖。

### 第二步：逻辑迁移 (Service Extraction)
将业务逻辑按职能分包：
1.  **提取逻辑**：将原根目录下的逻辑（如 `/server.ts`）抽离核心渲染逻辑。
2.  **移至包中**：将抽离的代码放入 `packages/api/src/` 中，通过 `export` 暴露初始化函数。
3.  **保持纯净**：包内的逻辑应尽量减少对外部硬依赖的引用，通过参数注入运行配置。

### 第三步：调整应用入口 (Application Refactoring)
1.  **代理入口**：在对应的应用下（如 `/apps/web/server.ts`）保留一个轻量级代理入口，仅负责调用 `packages/api` 导出的方法。
2.  **更新路径**：修复所有在被迁移文件中的相对导入路径（使用 `../../` 等方式精确回溯）。
3.  **配置更新**：
    *   更新 `package.json` 中的 `scripts` 执行路径（例如：从 `tsx server.ts` 更新为 `tsx apps/web/server.ts`）。
    *   确保构建工具和 IDE 路径映射正确。

### 第四步：基础设施适配
1.  **重启服务**：执行 `restart_dev_server` 清理旧缓存。
2.  **验证环境**：检查 `Vite` 中间件路径配置（`dist/client` 等静态路径）是否依然指向正确。

---

## 3. 注意事项 (Critical Directives)
*   **绝对路径与相对路径**：迁移后需要仔细排查 `import` 路径错误。
*   **依赖循环**：避免 `apps/web` 引用 `packages/api` 的同时，`packages/api` 又试图引用 `apps/web` 下的非共享组件。
*   **CI/CD 一致性**：如果在 CI 中存在自定义构建脚本，必须同步更新其入口路径。

---

## 4. 迁移检查清单 (Migration Checklist)
- [ ] 逻辑包是否已实现与运行环境（Browser/Node）的部分解耦？
- [ ] 应用入口代理脚本是否足够轻量（建议<10行）？
- [ ] `package.json` 中的 `scripts` 是否已更新为对应的应用子目录路径？
- [ ] 所有测试用例是否已指向新的文件位置？