# PC 企业微信扫码登录实施计划

## 1. Preconditions

- [ ] 只读核对企微自建应用已开启“企业微信授权登录”。
- [ ] 只读核对 OA 公网域名已配置为 OAuth 可信域名或 Web 网页授权回调域名，且回调地址仍指向现有 `/api/auth/wecom/callback`。
- [x] 不在代码、日志、Trellis 或聊天中输出 CorpID、AgentID、Secret、真实 userid、code 或 state。
- [x] 用户批准本 PRD、设计和实施计划后，才运行 `task.py start` 并修改产品代码。

## 2. Backend Implementation

- [x] 在配置层增加默认关闭的 `WECOM_PC_WEB_LOGIN_ENABLED`，同步示例环境、部署检查和运行时 readiness 合同。
- [x] 扩展企微公开配置响应，分别返回工作台 `loginUrl` 与 PC `pcLoginUrl`，避免语义混用。
- [x] 在 `/wecom/login` 增加固定白名单 `entrySource`，拒绝 `pc_qr + bind/onboard`。
- [x] 增加企微托管 Web 登录 URL 构造函数，复用现有 CorpID、AgentID 和回调地址。
- [x] 为 `pc_qr` 写入短期 HttpOnly/SameSite=Lax 浏览器关联 cookie，并把白名单入口与 nonce 写入签名 state。
- [x] callback 在外部兑换前验证 state、entrySource、时效和 cookie nonce，并在终止路径清除 cookie；不把无状态 cookie 误报为服务端一次性 nonce 存储。
- [x] 成功审计增加脱敏 `entrySource`，保持既有 `bindingSource`、映射和会话合同。

## 3. Frontend Implementation

- [x] 扩展企微配置类型并在普通浏览器登录页展示“企业微信扫码登录”按钮。
- [x] 复用既有 returnTo 和设备指纹 URL 工具跳转服务端入口。
- [x] 企微 WebView 继续展示工作台一键进入；PC 开关关闭或配置缺失时保持密码/邮箱验证码入口可用。
- [x] 不安装、不加载 `@wecom/jssdk`，不加入第三方 script/iframe。

## 4. Automated Validation

### Backend focused tests

- [x] 配置 ready/disabled/misconfigured 与 `pcLoginUrl` 合同。
- [x] 托管页 URL 的 host/path、`CorpApp`、CorpID、AgentID、回调和签名 state。
- [x] `entrySource` 默认、白名单和非法组合。
- [x] state 篡改、过期、缺 code、非法 returnTo。
- [x] cookie 缺失、篡改、nonce 不匹配、回调后清除、正常浏览器重复回调，以及企微重复 code 不创建第二会话。
- [x] 成功、未映射、冲突、OA/企微停用以及审计脱敏。
- [x] 工作台、bind、onboard 回归。

建议命令：

```bash
cd server && npm test -- tests/unit/routes/wecomAuth.test.js tests/unit/routes/auth.login.test.js
cd server && npm run prisma:validate
```

### Frontend focused tests

- [x] 普通浏览器显示 PC 企微按钮并构造安全跳转。
- [x] 企微 WebView 不重复显示 PC 入口。
- [x] 配置关闭/失败时既有登录方式仍可用。
- [x] 既有错误提示不再要求用户先用密码绑定。

建议命令：

```bash
cd client && npm run typecheck
cd client && npm run build
```

### Project gates

```bash
node scripts/qa/check-process-contract.mjs --baseline --json
node scripts/qa/audit-docs.mjs --check-registry
node scripts/qa/check-trellis-governance.mjs
python3 ./.trellis/scripts/task.py validate 07-30-pc-wecom-qr-login
git diff --check
```

## 5. Review and Documentation

- [x] 认证改动完成后做只读安全/权限 review，不由 reviewer 修改代码。
- [x] 若实现形成稳定合同，更新 `.trellis/spec/hyb-oa/wecom-boundary.md`。
- [x] 仅在确有操作差异时更新现有管理员手册、部署 checklist/runbook；不新建平行文档。
- [ ] commit 使用中文并引用 `07-30-pc-wecom-qr-login`。

## 6. Production Gate

- [ ] 企微后台设置、生产环境配置、部署与真实扫码分别取得明确批准。
- [ ] 部署后公网 `/ready`、前端构建标识、现有工作台登录及既有密码/邮箱验证码冒烟通过。
- [ ] 开启 PC 开关后，由一名已映射 active 员工完成真实 PC 扫码或企微桌面端快速登录，并安全回跳原页面。
- [ ] 确认审计有 `entrySource=pc_qr` 且无敏感字段。
- [ ] 验证关闭 PC 开关后按钮消失、其他登录方式不受影响。

## 7. Interrupt and Rollback

- 真人报销链若出现阻断问题，本任务保持小步提交并可随时中断，优先处理真实业务阻断。
- 生产首选回滚：关闭 `WECOM_PC_WEB_LOGIN_ENABLED` 并重建/重启受控服务。
- 若后端回归异常，回滚本任务应用版本；不得删除既有企微绑定或会话数据。

## 8. Local Evidence (2026-07-30)

- 聚焦后端：`wecomAuth.test.js` 与 `check-wecom-runtime-ready.test.js` 共 37 项通过；补充重放断言后 `wecomAuth.test.js` 26 项通过。
- 完整后端：169 个测试文件、1091 项通过。
- Prisma schema validate 通过。
- 前端 typecheck、生产 build 通过；`wecom-entry.spec.ts` 2 项通过。
- 流程合同、文档审计（仅 22 个既有未注册文档 warning）、Trellis governance、task validate、敏感内容扫描和 `git diff --check` 通过。
- 未执行企微后台写入、生产环境配置、部署或真实扫码；对应 Production Gate 保持未勾选。