mydocs/
├── apis/          # 接口契约：API 定义、字段说明、兼容性约束
├── codemap/       # 代码地图：功能级 / 项目级代码索引，长期资产
├── context/       # 上下文语料：PRD、设计图、讨论记录、临时资料
└── specs/         # 任务 Spec：每个需求一份，核心资产

create_codemap:
  mode: feature
  scope: 用户权限模块
  goal: 梳理权限校验链路

create_codemap:
  mode: project
  scope: order-service
  goal: 输出项目总图与主流程

# Code Map: 权限校验模块

## Scope
权限校验的完整链路，从请求入口到最终鉴权判定。

## Entry Points
- `PermissionFilter.java:L28` — HTTP 请求拦截入口
- `RpcPermissionInterceptor.java:L15` — RPC 调用拦截入口

## Core Logic Chain
1. `PermissionFilter.doFilter()` -> `AuthService.checkAccess()`
2. `AuthService.checkAccess()` -> `PermissionDAO.queryUserPermission()`
3. `LegacyAuthAdapter.java:L33` 存在历史兼容逻辑

## Dependencies
- 数据库：`t_user_permission`
- RPC：`UserCenterService.getUserRole()`
- 缓存：Redis key `perm:{userId}:{resourceId}`

## Risks / Unknowns
- `RpcPermissionInterceptor` 的调用方不明确，可能已废弃
- `LegacyAuthAdapter` 的兼容逻辑是否需要继续保留

build_context_bundle:
  input: ./mydocs/context/raw/permission-refactor

# Context Bundle: 权限模块重构

## Source Index
| 文件 | 类型 | 关键信息 |
|---|---|---|
| prd-v2.md | 需求文档 | 细粒度授权需求 |
| security-spec.md | 约束文档 | 权限变更必须写审计日志 |
| dingtalk-discussion.md | 讨论记录 | 第一期只做接口级，字段级放第二期 |

## Requirement Facts
- 统一权限校验入口
- 第一期支持接口级授权
- 权限变更必须写审计日志

## Constraints
- 不能影响超级管理员逻辑
- 必须兼容 `LegacyAuthAdapter` 至少 3 个月
- 鉴权延迟小于 5ms

## Open Questions
- [ ] 字段级权限第二期做，接口设计是否预留扩展？
- [ ] `LegacyAuthAdapter` 三个月后是否确定下线？

sdd_bootstrap:
  task: 权限模块重构
  goal: 统一权限校验入口，支持接口级细粒度授权
  requirement: docs/prd/permission-v2.md
  codemap_ref: mydocs/codemap/permission-check.md
  context_ref: mydocs/context/2026-06-07_permission-refactor_context_bundle.md

请进入 Research 阶段。基于首版 Spec，逐条核查以下事实：

1. 权限校验入口在哪里？有几个入口？
2. 当前授权逻辑如何实现？
3. 有没有历史遗留特殊处理？
4. 哪些地方可能影响兼容性？

要求：
- 每个结论必须给出文件路径、函数名和行号。
- 不确定项显式列出。
- 所有新发现回写 Spec 的 Research Findings。

## Research Findings

1. 权限校验入口有 2 个：
   - `PermissionFilter.java:L28` — HTTP 请求拦截入口
   - `RpcPermissionInterceptor.java:L15` — RPC 调用拦截入口

2. 授权逻辑位于：
   - `AuthService.java:L45-L78`
   - 通过 `PermissionDAO.queryUserPermission()` 查询权限

3. 历史兼容逻辑：
   - `LegacyAuthAdapter.java:L33`
   - 兼容旧版角色映射，是否仍需保留待确认

## Open Questions
- `RpcPermissionInterceptor` 是否仍有调用方？
- “细粒度授权”第一期是否只到接口级？

请进入 Innovate 阶段。基于 Research Findings 给出 2～3 个方案。

每个方案必须包含：
- 核心思路
- 需要修改的文件
- 优点
- 缺点
- 风险点
- 工作量估算

不要直接写代码。人确认方案后再进入 Plan。

## Option A: 统一入口 + 策略模式

### 核心思路
新增 `UnifiedPermissionGateway`，HTTP 和 RPC 入口都委托给统一网关，网关内部按请求类型选择策略。

### 修改文件
- `PermissionFilter.java`
- `RpcPermissionInterceptor.java`
- `UnifiedPermissionGateway.java`
- `UnifiedPermissionGatewayTest.java`

### 优点
- 入口统一，后续维护成本低
- 权限策略集中，方便扩展

### 缺点
- 改动面较大
- 需要完整回归 HTTP 和 RPC 两条链路

### 风险
- RPC 拦截器调用方尚未确认

### 工作量
约 2 天

## Option B: 适配器模式 + 渐进迁移
...

## Innovate
Skipped.

Reason: 单点修改，边界清晰，不需要多方案对比。

请进入 Plan 阶段。基于已选方案 A，输出原子级实施清单。

要求：
1. 精确到文件路径和函数签名。
2. 标明执行顺序和依赖关系。
3. 标明每一步的验证方式。
4. 不要写代码。

## Implementation Checklist

- [ ] 1. 新建 `src/main/java/com/example/permission/UnifiedPermissionGateway.java`
  - `public class UnifiedPermissionGateway implements PermissionChecker`
  - `public boolean checkPermission(PermissionContext ctx)`
  - `private PermissionStrategy resolveStrategy(RequestType type)`
  - 验证：新增单元测试覆盖 HTTP / RPC 两类请求

- [ ] 2. 修改 `src/main/java/com/example/filter/PermissionFilter.java`
  - 将 `doFilter()` 中的权限校验逻辑委托给 `UnifiedPermissionGateway`
  - 保留原异常处理逻辑
  - 验证：HTTP 无权限场景返回原错误码

- [ ] 3. 修改 `src/main/java/com/example/rpc/RpcPermissionInterceptor.java`
  - 将 `invoke()` 中的权限校验逻辑委托给 `UnifiedPermissionGateway`
  - 验证：RPC 鉴权失败时抛出原异常类型

- [ ] 4. 新建 `src/test/java/com/example/permission/UnifiedPermissionGatewayTest.java`
  - 覆盖 HTTP 请求、RPC 请求、无权限、超级管理员四种场景

## Execution Order
1 -> 2 -> 3 -> 4

## Risks
- RPC 拦截器调用方未完全确认，执行前需要人工确认是否仍在线上链路中。

Plan Approved.

Plan Approved.

请进入 Execute 阶段，严格按照 Plan 逐步执行。
要求：
- 每完成一步报告进度。
- 如果发现 Plan 有问题，立即停止并说明原因。
- 编译错误、类型不匹配可以修复。
- 任何逻辑变更必须回到 Plan 阶段重新审批。

## Execute Log

- [x] Step 1: 已创建 `UnifiedPermissionGateway.java`
  - 实现 `checkPermission()`
  - 实现 `resolveStrategy()`

- [x] Step 2: 已修改 `PermissionFilter.java`
  - HTTP 权限校验委托给统一网关
  - 原异常处理逻辑保留

- [ ] Step 3: 进行中

请进入 Review 阶段。对照 Spec 逐条验收：

1. Spec 中的目标行为是否全部落地？
2. 实际改动是否偏离 Plan？
3. 有没有隐性破坏、边界条件遗漏或安全风险？
4. 测试是否覆盖关键路径？
5. Review 结论写入 Spec 的 Review Verdict。

## Review Matrix

| 检查轴 | 结果 | 说明 |
|---|---|---|
| Spec 达成率 | PASS | 4/4 个目标行为已实现 |
| Plan-Execution Diff | PASS | 实际改动未偏离 Plan |
| 代码质量与弱点 | FAIL | `UnifiedPermissionGateway.java:L52` 缺少空指针守卫 |

## High Risk Issues

1. `UnifiedPermissionGateway.java:L52`
   - 问题：`ctx` 可能为空，当前代码会触发 NPE
   - 建议：添加 `Objects.requireNonNull(ctx, "ctx")`
   - 处理：回到 Plan 阶段补充修复步骤

## Verdict
NO-GO

请执行 archive，将当前功能的规格、方案、关键决策和实现逻辑沉淀下来。
输出：
1. Human 视角版：给人阅读和交接。
2. LLM 视角版：给下一次大模型恢复上下文。

mydocs/specs/archive/
├── 2026-06-07_permission-refactor_human.md
└── 2026-06-07_permission-refactor_llm.md

# Spec: <任务名>

## 目标
要达成什么结果。

## 范围
改哪些模块，不改哪些模块。

## 约束
兼容性、性能、安全、接口、上线窗口等限制。

## 风险
不确定项、历史逻辑、可能影响的调用方。

## Checklist
- [ ] 验收点 1
- [ ] 验收点 2

## Research Findings
## Innovate Options
## Selected Decision
## Plan Checklist
## Execute Log
## Review Verdict
## Archive Summary

# AI 编程工作指南

## 基本规则

- 使用中文交流。
- No Spec, No Code：没有 Spec，不准改代码。
- No Approval, No Execute：没有明确批准，不准进入 Execute。
- Spec is Truth：代码和 Spec 冲突时，先对齐 Spec。
- Reverse Sync：发现 Bug 或需求变化，先更新 Spec，再修改代码。

## Skill 使用约定

- 默认使用 `sdd-riper-one`。
- 任务简单、边界清晰、改动很小时，可以使用 `sdd-riper-one-light`。
- 极小修改可不启用完整流程，但必须说明修改范围和验证方式。

## 执行规则

- 代码修改前必须提交 Plan 并等待确认。
- 文档修改可以直接执行，但影响行为的文档变更要同步到 Spec。
- 修改文件时优先小步提交，避免整文件重写。
- 不做与当前任务无关的重构。
- 多文件改动时，先完成核心链路的最小可用修改，再补齐周边逻辑。
- 如果连续两轮只搜索、不修改，必须停止并说明准备改哪些文件、为什么。

## 命令边界

- 未经确认，不主动运行编译、打包、部署、迁移等高开销或高风险命令。
- 未经确认，不主动安装、升级、删除依赖或修改锁文件。
- 对批量删除、覆盖、重置、迁移、外部写操作，必须等待确认。

## Git 边界

- 严格尊重 `.gitignore`。
- 不主动使用 `git add -f` 或 `git add --force`。
- 不执行 `git clean`，尤其不要执行 `git clean -fdx`。
- 被忽略文件默认不提交，除非明确指定路径。

## Spec 同步

- 影响需求、接口、行为、约束、流程或实现决策时，执行后必须同步更新 Spec。
- 纯格式化、注释调整、机械性改动可不更新 Spec。