hyb-oa/.trellis/tasks/07-30-pc-wecom-qr-login/implement.md

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

1. Preconditions

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

2. Backend Implementation

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

3. Frontend Implementation

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

4. Automated Validation

Backend focused tests

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

建议命令：

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

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

建议命令：

cd client && npm run typecheck
cd client && npm run build

Project gates

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

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

6. Production Gate

• 企微后台“企业微信授权登录”和回调域名核验取得明确批准并完成。
• 生产部署已单独获批并完成；未同步或覆盖生产 .env，PC 扫码开关保持关闭。
• 生产配置开启 PC 扫码功能取得另行批准。
• 真实 PC 扫码或企微桌面端快速登录验收取得另行批准。
• 部署后公网 /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 保持未勾选。

9. Production Deployment Evidence (2026-07-30)

• 45dc206 与功能提交 fb164eb 已推送；生产发布来源为 fb164eb6903d，来源已进入 upstream，工作树干净。
• 部署前 PC 扫码开关为未设置或关闭，且已完成一次自动异机备份；发布使用 existing 数据模式和 SYNC_ENV=0，未同步、回显或覆盖生产配置。
• Prisma 62 个迁移均为最新；配置种子保留生产 3 条既有审批规则，未重置管理员密码。
• external deps、runtime smoke、公网 /ready、12 位构建标识和公网前端资源扫描通过；企微公开配置明确 pcWebLoginEnabled=false 且 pcLoginUrl=null，直接请求 PC 入口失败关闭。
• 公网真实浏览器只读核验确认密码和邮箱验证码标签存在、工作台入口提示存在、PC 扫码按钮数量为 0；未输入凭据或触发验证码。页面仅有既有 favicon 404，不影响登录入口。
• 自动备份三组 timer 和 WARCH3 timer 已刷新到新构建，4 个 timer 均为 enabled/active；发布后自动备份与新鲜度检查通过。
• 运行时依赖审计显示客户端无高危/严重，服务端无严重但仍有 16 个高危告警；本任务没有改动任何依赖或锁文件，该存量风险另行治理，不在认证任务中盲目执行破坏性升级。
• 未执行企微后台设置、生产开关开启或真实扫码；任务保持 in_progress。