# 05_权限日志失败记录

## 1. 模块目标

权限、日志和失败记录模块负责保证第一版闭环可控、可追溯、可复盘。权限必须在后端校验，关键操作必须写日志，AI、飞书、调度和业务失败必须形成失败记录。

## 2. 第一版做什么

1. 定义老板、程经理、普通员工、管理员 / AI 团队四类角色。
2. 控制事项、提醒、草稿、反馈、失败记录的可见范围和操作范围。
3. 记录关键操作日志。
4. 记录 AI 解析失败、模型调用失败、AI 记忆读写失败、草稿转换失败、人员映射缺失、飞书通知失败、回调失败、定时触发失败、用户反馈有问题等失败。
5. 支持管理员 / AI 团队查看和处理失败记录。
6. 对敏感信息做日志边界约束。

## 3. 第一版不做

1. 不做复杂组织架构。
2. 不做细粒度多级权限。
3. 不做复杂审批流。
4. 不做独立失败看板或复杂 BI。
5. 不把飞书身份直接等同于业务权限。
6. 不把密钥、token、完整手机号、完整邮箱写入普通日志。

## 4. 核心流程

权限校验：

```text
请求进入 DRF view
-> permission class 做入口校验
-> serializer 做参数校验
-> service 做业务权限和状态校验
-> 通过后执行业务动作
```

失败记录：

```text
业务或外部调用失败
-> 写 failure_records
-> 保留关联对象和失败类型
-> 管理员 / AI 团队处理
-> 填写处理结果
-> 写 operation_logs
```

操作日志：

```text
关键动作发生
-> 记录 actor、action、target_type、target_id
-> 记录操作渠道和结果摘要
-> 避免记录敏感明文
```

## 5. 数据对象

本模块主要使用：

1. `users`
2. `failure_records`
3. `operation_logs`
4. `model_call_logs`
5. `feishu_events`
6. `secretary_messages`
7. `bot_contexts`

字段以 `docs/contracts/数据对象约定.md` 为准。

## 6. 接口需求

主要接口：

1. `GET /api/users/me`
2. `GET /api/failure-records`
3. `GET /api/failure-records/{id}`
4. `PATCH /api/failure-records/{id}`
5. `POST /api/failure-records/{id}/resolve`
6. `GET /api/notifications`
7. `GET /api/notifications/{id}`
8. `GET /api/feedbacks`

接口格式以 `docs/contracts/API接口约定.md` 为准。

## 7. 权限规则

1. 普通员工只能看自己作为接收人、创建人或反馈人的记录。
2. 老板能看自己发起、创建或接收的记录。
3. 程经理能看自己发起、负责、待确认，以及第一批试用管理范围内的记录。
4. 管理员 / AI 团队能看失败记录、通知记录、人员映射和必要操作日志。
5. 普通员工不能给别人创建事项或提醒。
6. 反馈人必须是事项或提醒接收人。
7. 飞书登录用户必须匹配到启用状态的平台用户后才能进入平台。

## 8. 状态流转

失败记录状态以 `docs/contracts/状态流转约定.md` 为准。核心约束：

1. 新失败进入 `pending`。
2. 处理中进入 `processing`。
3. 填写处理结果后进入 `resolved`。
4. 确认不处理可进入 `cancelled`。
5. 失败记录状态变化必须写操作日志。

## 9. 必须写日志的动作

1. 飞书登录成功或失败。
2. 机器人收到老板消息。
3. 非老板私聊机器人。
4. AI 生成草稿、解析失败。
5. AI 追问、普通记录、上下文回顾和 BotContext 变化。
6. 人工确认、修改、取消草稿。
7. 老板点击补充/重说。
8. 程经理确认复杂事项。
9. 创建事项、创建提醒。
10. 发送通知、补发通知、通知失败。
11. 接收反馈，尤其是有问题反馈。
12. 定时提醒触发成功或失败。
13. AI 记忆读写失败、草稿转换失败和失败记录处理。
14. 背景摘要或老板风格提示词版本启用。

## 10. 给 AI 的测试样例

1. 普通员工创建给别人的事项，应被拒绝并写权限失败日志。
2. 普通员工创建给别人的提醒，应被拒绝。
3. 非接收人提交反馈，应被拒绝。
4. 管理员处理失败记录时，必须留下处理结果。
5. 日志中不得包含完整手机号、完整邮箱、飞书 token 或密钥。
6. 未匹配平台用户的飞书登录应失败并写失败记录。
7. PostgreSQL AI 记忆读写失败时，应写 `memory_store_failed`，不得继续依赖内存确认草稿。

## 11. Review 重点

1. 后端权限是否完整。
2. 状态流转是否可追踪。
3. 失败记录是否包含关联对象、失败类型和处理结果。
4. 日志是否记录操作人和渠道。
5. 敏感信息是否被脱敏。