sql数据流，amdin业务逻辑接入

2026-02-05 10:11:09 +08:00
parent 859372ca5b
commit ac670cf5d8
81 changed files with 3547 additions and 1472 deletions
--- a/docs/project_spec/AGENT_PROJECT_SPEC.md
+++ b/docs/project_spec/AGENT_PROJECT_SPEC.md
@@ -0,0 +1,325 @@
+# Agent 项目规范文档（uni-app / uvue / uts）
+
+## 0. 文档目标与适用范围
+
+- **目标**：统一项目目录、命名、依赖边界、数据库（SQL/RLS/RPC）安全策略与准入流程，使 Agent 在改动代码/SQL 时遵循一致的工程约束与安全基线。
+- **适用范围**：
+  - 前端：`pages/`、`components/`、`layouts/`、`services/`、`utils/`、`types/`、`uni_modules/`、`static/`
+  - 文档与数据库：`docs/`、`docs/sql/`、模块内 `test/` SQL
+
+---
+
+## 1. 项目核心结构与职责边界
+
+### 1.1 页面与路由
+
+- **权威路由配置**：根目录 `pages.json`
+- **分包规则**：
+  - `tabBar`：主入口页面（消费者端）
+  - `subPackages`：按模块分包（consumer 非 tab 页、delivery、analytics、admin、merchant、service 等模块）
+- **页面目录**：`pages/`
+  - `pages/user/`：登录/注册/用户中心等公共页面
+  - `pages/mall/<module>/`：各业务模块（consumer/delivery/analytics/admin/merchant/service...）
+- **规则**：
+  - `pages/` 内只放页面（路由入口）与页面级组合逻辑
+  - 可复用 UI/逻辑必须下沉到 `components/` / `services/` / `utils/` / `types/`
+
+### 1.2 布局
+
+- **目录**：`layouts/`
+- **规则**：
+  - layout 只负责结构与 slot/容器
+  - layout 不直接写重业务数据请求（可触发初始化但不承担领域逻辑）
+
+### 1.3 组件
+
+- **目录**：`components/`
+- **推荐分层（可渐进迁移）**：
+  - `components/base/`：无业务语义基础组件（按钮、弹窗、表单控件、空状态等）
+  - `components/biz/<domain>/`：带业务语义组件（订单卡片、SKU 选择器等）
+  - `components/integration/<vendor>/`：第三方/平台集成组件（如 supabase、analytics SDK 外观层）
+- **规则**：
+  - 组件不得直接读写数据库或拼接 SQL
+  - 网络/数据访问必须通过 `services/`（数据访问唯一入口）
+
+### 1.4 服务层（数据访问唯一入口）
+
+- **目录**：`services/`
+- **职责**：
+  - RPC/API 调用封装
+  - 鉴权、token 注入、错误标准化处理
+  - 数据转换（DTO -> ViewModel 允许在这里或页面层，但必须统一口径）
+- **规则**：
+  - 页面/组件不得直接访问底层 client（如 supabase client），必须经 `services/` 统一出口
+
+### 1.5 工具与类型
+
+- **目录**：
+  - `utils/`：纯工具函数（尽量无 IO、无全局状态）
+  - `types/`：全局类型、领域模型、DTO、服务返回类型
+- **规则**：
+  - `utils/` 不反向依赖业务模块目录
+  - `types/` 不依赖运行时代码（保持纯类型）
+
+### 1.6 插件/可替换模块
+
+- **目录**：`uni_modules/`
+- **定位**：可独立发布/可替换的插件能力（组件、uts sdk、集成适配等）
+- **规则**：
+  - 不把所有业务通用代码塞到 `uni_modules/`；业务通用优先 `services/utils/components`
+
+---
+
+## 2. 路径别名与引用规范
+
+### 2.1 当前事实
+
+- `tsconfig.json` 已配置：`@/* -> ./*`
+
+### 2.2 统一引用建议（Agent 必须遵循）
+
+- 默认使用 `@/` 前缀引用项目内代码（例如 `@/services/...`、`@/components/...`）
+- 不强制引入 `@components`、`@uni_modules` 这类新 alias，除非后续明确要落地到配置文件；当前以目录语义规范为准
+
+---
+
+## 3. 依赖方向（强约束）
+
+为避免循环依赖与业务污染，依赖方向必须满足：
+
+- `pages` -> 可依赖 `components/services/utils/types/layouts`
+- `components` -> 可依赖 `services/utils/types`
+- `layouts` -> 可依赖 `components/utils/types`（避免重业务）
+- `services` -> 只依赖 `utils/types`（不得依赖 pages/components）
+- `utils` -> 不依赖业务目录
+- `types` -> 不依赖运行时代码
+
+---
+
+## 4. 命名与文件组织规范
+
+- **目录名**：全小写，必要时用连字符（全仓统一一种风格）
+- **组件文件**：`PascalCase.uvue`
+- **服务文件**：统一 `xxxService.uts`
+- **SQL 文件**：
+  - 测试阶段：模块 `test/` 下自由命名，但必须含用途前缀
+  - 权威阶段：进入 `docs/sql/` 后必须按分层目录 + 版本号命名（见第 6 节）
+
+---
+
+## 5. 数据库/权限权威口径（与前端联动）
+
+本项目数据库权限与前端路由/页面访问形成闭环。以下为强制口径：
+
+- **角色字段唯一权威**：`public.ak_users.role`
+- **analytics/admin 的全局数据访问**：必须通过 RPC 完成，避免直接开放业务表全局权限
+- **前端必须做客户端守卫**：
+  - 访问 analytics/admin 页面入口时，必须校验登录与角色（例如 `ensureRole(['admin','analytics'])`）
+  - 客户端守卫只用于“快速失败”，最终权限以数据库侧为准
+
+---
+
+## 6. SQL 两阶段工作流（模块测试 -> 权威入库）
+
+### 6.1 阶段 A：模块内测试 SQL（非权威）
+
+- **位置**：各模块目录 `test/`
+  - 例：`pages/mall/analytics/test/*.sql`
+- **允许**：快速迭代、验证思路、临时脚本
+- **禁止**：高危破坏性操作（见 7.3）
+
+### 6.2 阶段 B：入库到 `docs/sql/`（权威）
+
+- **位置**：`docs/sql/`
+- **入库准入条件**：
+  - 必须通过 Agent 安全评估（输出评审报告）
+  - 必须符合本项目角色/RLS/RPC 安全口径（见 7.2；并强制对照 `docs/sql/11_roles_and_permissions_strategy.md`）
+  - 建议至少 1 人人工确认后再合并
+
+### 6.3 `docs/sql/` 分层（权威目录结构）
+
+为保证可审计、可复用与最小风险暴露，进入权威目录的 SQL 必须按“对象类型”拆分归档，禁止将多种对象（表 + RLS + RPC + GRANT 等）长期混放在同一个文件中。
+
+- `docs/sql/00_meta/`：规范/策略/说明类（如角色与权限策略）
+- `docs/sql/10_schema/`：表/类型/索引等 DDL
+  - 建议进一步按域分组：`docs/sql/10_schema/<domain>/...`
+- `docs/sql/20_rls/`：RLS enable + policies（按表/域拆分）
+  - 建议进一步按域分组：`docs/sql/20_rls/<domain>/...`
+- `docs/sql/30_rpc/`：RPC/函数（尤其 analytics）
+  - 建议进一步按域分组：`docs/sql/30_rpc/<domain>/...`
+- `docs/sql/40_grants/`：显式授权（GRANT/REVOKE）
+  - 仅允许最小权限；对 `anon/authenticated` 的任何授权必须附带评审结论
+- `docs/sql/90_archive/`：历史/废弃（只读，不再作为引用口径）
+
+**对象拆分规则（入库必选一类）**：
+
+- **表/类型/索引**：只放 DDL（`CREATE/ALTER TABLE/TYPE/INDEX`），归入 `10_schema`
+- **RLS 策略**：只放 `ALTER TABLE ... ENABLE ROW LEVEL SECURITY` 及 `CREATE POLICY/ALTER POLICY/DROP POLICY`，归入 `20_rls`
+- **函数/RPC**：只放 `CREATE OR REPLACE FUNCTION ...`（含 `SECURITY DEFINER` 等），归入 `30_rpc`
+- **授权**：只放 `GRANT/REVOKE`，归入 `40_grants`
+
+**例外（允许同文件）**：
+
+- 同一对象的“紧耦合小变更”可以同文件（例如同一个函数的创建 + 注释/owner 设置），但不得混入其他对象类型。
+
+### 6.4 权威 SQL 入库步骤（从模块 test/ 迁移）
+
+当模块内 `test/` SQL 验证通过、准备进入 `docs/sql/` 时，必须按以下步骤执行：
+
+- **步骤 0：目录存在性检查（必须）**
+  - 若以下目录不存在，Agent 必须创建；若已存在则复用，禁止新建“近似重复目录”。
+  - 目录清单：
+    - `docs/sql/00_meta/`
+    - `docs/sql/10_schema/`
+    - `docs/sql/20_rls/`
+    - `docs/sql/30_rpc/`
+    - `docs/sql/40_grants/`
+    - `docs/sql/90_archive/`
+  - 如采用域分组（`<domain>`），对应的 `docs/sql/<layer>/<domain>/` 目录同样遵循“无则创建，有则复用”。
+
+- **步骤 1：对象识别与拆分**
+  - 将 SQL 按对象类型拆分为：schema / rls / rpc / grants（必要时再细分 domain）
+
+- **步骤 2：命名与归档路径确定**
+  - 表/DDL：`docs/sql/10_schema/<domain>/<object>_v<version>.sql`
+  - RLS：`docs/sql/20_rls/<domain>/<table>_rls_v<version>.sql`
+  - RPC：`docs/sql/30_rpc/<domain>/<rpc_name>_v<version>.sql`
+  - Grants：`docs/sql/40_grants/<domain>/<scope>_grants_v<version>.sql`
+
+- **步骤 3：安全评审（Agent 必须输出评审报告）**
+  - 评审必须强制对照 `docs/sql/11_roles_and_permissions_strategy.md`
+  - 结论为 `OK` 方可入库
+
+- **步骤 4：入库与引用口径**
+  - 入库后，模块 `test/` 中对应脚本仅保留为测试/回归用途（不得再作为权威引用）
+
+---
+
+## 7. Agent SQL 安全评估制度（准入制）
+
+### 7.1 评估结论（必须输出其一）
+
+- `Reject`：拒绝入库
+- `High`：高风险，必须整改后复评
+- `OK`：可入库
+
+### 7.2 项目强制安全要求（RPC/analytics）
+
+所有 `rpc_analytics_*`（及类似特权 RPC）必须满足：
+
+- `SECURITY DEFINER`
+- `SET search_path = public`（固定 search_path）
+- 函数入口显式鉴权：
+  - `get_current_user_role() IN ('admin','analytics')` 才允许执行
+- 返回字段最小化（只返回统计必要字段/聚合结果）
+
+**强制参照文档**：所有 SQL 评审必须对照并满足 `docs/sql/11_roles_and_permissions_strategy.md` 中的角色定义、RLS 分层、RPC 安全闭环要求。
+
+### 7.3 硬阻断（出现任意一条：Reject）
+
+- **裸放权**：对 `anon/authenticated` 大范围 `GRANT` 且无等价约束
+- **破坏性操作**：
+  - `DROP TABLE/SCHEMA/ROLE/EXTENSION`
+  - `TRUNCATE`
+  - 大范围 `DELETE/UPDATE` 无可靠 `WHERE`
+- **不安全的 SECURITY DEFINER**：
+  - 无入口鉴权
+  - 未固定 `search_path`
+- **绕过 RLS 的不透明入口**：绕过后无角色校验/无最小返回字段
+
+### 7.4 高风险需整改（High）
+
+- RLS 覆盖不全（业务需要写但未覆盖 `INSERT/UPDATE/DELETE`）
+- policy 条件过宽（如 `USING (true)`）
+- RPC 返回敏感字段
+- 无分页/无 LIMIT 约束造成全量泄露或性能风险
+
+---
+
+## 8. Agent SQL 评审报告模板（固定输出）
+
+### SQL 安全评审报告
+
+- **对象**：`<文件路径>`
+- **目标**：`<此 SQL 的目的>`
+- **结论**：`Reject | High | OK`
+- **涉及对象**：
+  - 表/视图/函数：`...`
+  - 角色/权限：`...`
+  - RLS：是否启用/修改；覆盖哪些操作
+  - `SECURITY DEFINER`：是/否；入口鉴权：是/否；`search_path` 固定：是/否
+- **与项目口径一致性（强制对照 docs/sql/11）**：
+  - admin/analytics 是否仅通过 RPC 获取全局数据：是/否
+- **风险点列表**：
+  - `等级` + `定位（片段/行号）` + `原因`
+- **整改建议**：
+  - 可执行修改建议清单
+- **准入建议**：
+  - 是否允许进入 `docs/sql/`：是/否；若否：进入条件
+
+---
+
+## 9. 与现有 SQL/文档目录的边界（避免双真相）
+
+仓库存在多处 SQL/迁移相关目录（如 `mall_sql/`、`doc_mall/`）。必须明确：
+
+- **权威策略/权威脚本口径**：以 `docs/sql/` 为准
+- 其他目录若属于迁移脚本仓/历史产物：
+  - 必须标注用途（迁移工具、一次性脚本、报告存档）
+  - 不允许出现与 `docs/sql/` 并行的“第二份权威定义”
+
+---
+
+## 10. 操作文档（强制）
+
+任何会对项目产生可观察影响的操作，Agent 必须同步编写“操作文档”，将操作过程与结果可描述化、可审计化。
+
+### 10.1 何时必须写操作文档
+
+- 修改/新增/删除任何代码文件（`.uvue/.uts/.ts/.js/.json/.scss` 等）
+- 修改 `pages.json`、`manifest.json`、`package.json`、`tsconfig.json` 等配置
+- 新增/调整 SQL（包括模块 `test/` 与 `docs/sql` 权威入库）
+- 任何涉及权限/鉴权/RLS/RPC/GRANT 的变更
+
+### 10.2 操作文档存放位置（从当前操作目录向上查找）
+
+存放规则：从“当前正在操作的目录”开始，逐层向上寻找 `docs/` 目录，直到“当前模块根目录”为止。
+
+- 若在某一层找到 `docs/`：将操作文档写入该 `docs/` 下的 `ops/` 子目录。
+- 若一路向上直到模块根目录仍未找到 `docs/`：Agent 必须在模块根目录创建 `docs/ops/` 并写入。
+- 若目标 `docs/ops/` 不存在：Agent 必须创建；若存在则复用。
+
+**模块根目录判定**（满足任一即可认为到达模块根）：
+
+- 存在 `pages.json`（项目根）
+- 或进入了业务模块目录（例如 `pages/mall/analytics/`、`pages/mall/admin/`、`pages/user/`）的顶层
+- 或进入了公共模块目录（例如 `services/`、`components/`、`utils/`、`types/`、`uni_modules/<name>/`）的顶层
+
+### 10.3 公共模块 vs 业务模块 的归档规则
+
+- **业务模块操作**：文档归档到该业务模块自己的 `docs/ops/`
+  - 例：操作发生在 `pages/mall/analytics/...`，则优先归档到 `pages/mall/analytics/docs/ops/`
+- **公共模块操作**：文档归档到对应公共模块自己的 `docs/ops/`
+  - 例：操作发生在 `services/...`，则归档到 `services/docs/ops/`
+  - 例：操作发生在 `uni_modules/<name>/...`，则归档到 `uni_modules/<name>/docs/ops/`
+
+### 10.4 操作文档命名规范
+
+- 文件名：`YYYY-MM-DD__<scope>__<short-title>.md`
+- `scope` 建议值：
+  - `analytics` / `admin` / `consumer` / `merchant` / `delivery` / `user`
+  - `services` / `components` / `utils` / `types` / `uni_modules-<name>`
+
+### 10.5 操作文档最小内容模板
+
+- **摘要**：做了什么
+- **动机**：为什么要做
+- **影响范围**：涉及哪些模块/页面/接口/权限
+- **变更清单**：
+  - 新增文件：...
+  - 修改文件：...
+  - 删除文件：...
+- **兼容性与风险**：可能的副作用、回滚风险
+- **回滚方案**：如何撤销、恢复到原状态
+- **验证方式**：如何验证改动正确（手工步骤/测试点）
+- **关联文档**：例如 `docs/sql/11_roles_and_permissions_strategy.md` 或对应评审报告