AI-Secretary/docs/specs/05_权限日志失败记录.md

05_权限日志失败记录

1. 模块目标

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

2. 第一版做什么

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

3. 第一版不做

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

4. 核心流程

权限校验：

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

失败记录：

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

操作日志：

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

5. 数据对象

本模块主要使用：

1. users
2. failure_records
3. operation_logs
4. model_call_logs
5. feishu_events

字段以 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. 人工确认、修改、取消草稿。
6. 老板点击补充/重说。
7. 程经理确认复杂事项。
8. 创建事项、创建提醒。
9. 发送通知、补发通知、通知失败。
10. 接收反馈，尤其是有问题反馈。
11. 定时提醒触发成功或失败。
12. 失败记录处理。
13. 背景摘要或老板风格提示词版本启用。

10. 给 AI 的测试样例

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

11. Review 重点

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