# 分销模块全量修复与数据库构建报告

## 摘要
本次对 Admin 侧分销模块（Distribution Module）进行了深度的端到端修复，补齐了“事业部管理”、“代理商管理”及“代理商申请”三个子模块完全缺失的数据库表结构、行级安全策略（RLS）以及管理端 RPC 接口。同时重构了前端 3 个核心页面，彻底解决了该部分此前全量 Mock 的问题。

## 动机
分销模块作为商城核心功能之一，此前在管理端仅完成了 UI 静态展示，数据层完全处于 Mock 状态。为了实现业务闭环，必须补齐底层 Schema，并按照项目安全规范（SECURITY DEFINER RPC）落地管理端接口，确保数据真实可操作且权限受控。

## 影响范围
- **模块**：后台管理系统 - 分销模块
- **页面**：事业部列表、代理商管理、事业部申请
- **接口**：新增 8 个 `rpc_admin_...` 接口
- **权限**：增加了分销全模块的 RLS 策略，限制普通用户仅能查看个人关联数据

## 变更清单

### 数据库 SQL
- **新增 Schema** (docs/sql/10_schema/distribution/):
  - `ak_distribution_divisions_v1.sql`
  - `ak_distribution_agents_v1.sql`
  - `ak_distribution_agent_applications_v1.sql`
- **新增 RLS** (docs/sql/20_rls/distribution/):
  - `ml_distribution_rls_v1.sql`
- **新增 RPC** (docs/sql/30_rpc/distribution/):
  - `rpc_admin_get_division_list_v1.sql`
  - `rpc_admin_save_division_v1.sql`
  - `rpc_admin_delete_division_v1.sql`
  - `rpc_admin_get_agent_list_v1.sql`
  - `rpc_admin_save_agent_v1.sql`
  - `rpc_admin_delete_agent_v1.sql`
  - `rpc_admin_get_agent_apply_list_v1.sql`
  - `rpc_admin_process_agent_apply_v1.sql`

### 前端代码
- **修改服务层**：`services/admin/distributionService.uts` (完成 RPC 封装与类型定义扩展)
- **重构页面**：
  - `pages/mall/admin/distribution/division/list.uvue` (去 Mock，接入真实数据)
  - `pages/mall/admin/distribution/division/agent.uvue` (去 Mock，接入真实数据)
  - `pages/mall/admin/distribution/division/apply.uvue` (去 Mock，接入真实数据)

## 兼容性与风险
- **风险**：事业部负责人和代理商必须在 `ak_users` 表中存在，手动输入错误的 UID 将导致外键约束报错。
- **副作用**：启用 RLS 后，若未通过 RPC 调用直接操作表，非 admin 角色将无法看到统计数据。

## 回滚方案
1. **数据库**：依次 DROP 刚才创建的 8 个 RPC 函数及 3 张业务表。
2. **代码**：使用 `git checkout` 恢复 `distributionService.uts` 及 3 个 `.uvue` 页面。

## 验证方式
1. **功能验证**：
   - 确认管理员在“事业部申请”页点击“同意”后，对应的用户应自动出现在“代理商管理”列表中。
   - 确认事业部和代理商列表中的“启用”状态切换能实时更新数据库。
2. **安全验证**：确认非 admin 角色调用管理端 RPC 会触发 `permission denied` 报错。

## 关联规范
- 遵循 `AGENT_PROJECT_SPEC.md` 规范。
- 遵循统一的 RPC 入口鉴权（admin/analytics 角色）。