神山秘境代码质量综合审计报告（修正版）

🗄 已归档快照（2026-09-13 文档时效治理）：本文件为历史阶段设计快照，最新口径以 docs/contracts/api-v1.3-matrix.md、docs/plans/2026-09-14-白标化内核抽取-两实例对比.md 及 TASKS 现行为准。设计思路仍可参考，数据与结论已过时。

审计日期: 2026-09-07

审计范围: 服务器最新代码（FETCH_HEAD = a1f80bf，1261 commits ahead of 本地快照）

审计性质: 只查问题，不修复代码

工作区: /Users/yujiaxinmeiti/Desktop/kailash-worktrees/xiaoyu-real-gz5gz9/

一、项目真实状态

维度	数据
后端	FastAPI + PostgreSQL，51 个路由文件，287 个 API 端点
数据库	47 个迁移文件，76 张表，110+ 外键，50+ 索引
小程序	WXML + TypeScript（miniprogram/），120 个页面，mockMode=false
B端H5	React + Vite（b-workbench/），23 个路由，零 mock
协作	3 个 AI 代理（小冈/阿仁/小齐）+ 1 个人类（刘总），WIP-192
福钥系统	核心创新，完整实现（冻结/抵扣/结算）

二、问题总览

严重度	后端	数据库	前端(C端)	B端H5	合计
🔴 Critical	3	—	—	—	3
🟠 Major	5	5	7	2	19
🟡 Minor	5	4	3	3	15
⚪ Info	2	—	2	1	5
合计	15	9	12	6	42

三、Critical（3 项，需立即处理）

C-1: JWT_SECRET 硬编码默认值

位置: config.py:11
问题: 默认值 "dev-secret-change-me"，若生产环境未设置 JWT_SECRET 环境变量，攻击者可用该密钥伪造任意用户 JWT
修复: 启动时校验 APP_ENV=prod 时 JWT_SECRET != 默认值，否则拒绝启动

C-2: APP_ENV 默认值为 "dev"

位置: config.py:17
问题: 未配置时默认 dev 模式，导致：① 所有登录走 dev_id 路径（无需微信 code2Session）② mock-pay 可用（任何人可免费支付）
修复: 生产环境启动时校验 APP_ENV 必须为已知值

C-3: dev_id 登录无速率限制

位置: auth.py:16-17
问题: 配合 C-2，可在生产环境批量创建任意用户身份
修复: 生产环境彻底禁用 dev_id 路径；dev 环境增加频率限制

四、Major（19 项）

后端 Major（5 项）

#	位置	问题
B-1	`main.py:28`	CORS 默认 `["*"]`，生产环境未配置时任何域名可跨域访问
B-2	`utils.py:45-67`	密码兼容裸 MD5/SHA1/SHA256，长期未登录用户的弱哈希密码永远不升级
B-3	`admin.py:9-17`	`_require_admin` 含多余的 `phone is None` 前置检查，未绑手机号的管理员会被误拦
B-4	`miniapp_site.py:89-101`	站点配置 PUT 端点允许 staff 角色修改全站配置（权限过宽）
B-5	`miniapp_orders.py:758-790`	支付端点无金额服务端校验（当前 mock-pay 阶段风险有限，接真实支付时需修复）

数据库 Major（5 项）

#	位置	问题
D-1	001 baseline	`credit_journal.direction` 无 CHECK 约束（财务流水必须约束 in/out）
D-2	001 baseline	多表缺关键索引：`credit_journal(merchant_id)`、`guides(is_active,sort_order)`、`transport_routes(is_active)`、`health_records(user_id,created_at)`
D-3	025 迁移	`DROP CONSTRAINT` 和 `ADD CONSTRAINT` 之间有无约束窗口（并发写入可能插入无效状态）
D-4	001 baseline	`user_wallets.balance` 缺 `CHECK (balance >= 0)` 非负约束
D-5	全局	`package_items`(001) 与 `package_components`(005) 功能重叠，`settlement_ledger` 与 `settlement_records` 并存，可能有废弃表

前端(C端) Major（7 项）

#	位置	问题
F-1	`request.ts:53-59`	401 未清 token 未跳登录页，用户 token 过期后陷入连续失败
F-2	`request.ts:47-63`	弱网场景无任何自动重试（高原转山信号极差）
F-3	`request.ts:20-28`	unwrap 只认 `{code,data}` 信封，不认 `{ok,data}` 信封，部分接口拿到包装对象而非 data
F-4	`order.ts:89-93`	mockPay 指向 admin 路径，无环境守卫，生产包暴露 staging 专用接口
F-5	`content-b.ts:310-327`	`wx.uploadFile` 使用相对路径，不经过 API_BASE_URL 拼接且不携带 Authorization
F-6	`scene-cards.ts:82-155`	默认场景卡 statusBar.text = '接口未建，诚实降级' 会直接展示给用户
F-7	`guest-archive.ts:15-38`	客人档案页硬编码假数据直接渲染给用户

B端H5 Major（2 项）

#	位置	问题
W-1	`FeatureFlags.ts:44-52`	Feature Flags 接口未建，100ms setTimeout 伪异步 + 本地默认值回退
W-2	`auth.ts:72`	Token 前端缓存 30 天 vs 后端 TTL 24h，过期后用户请求失败才跳登录

五、Minor（15 项）

后端 Minor（5 项）

#	位置	问题
b-1	`security.py:12`	`datetime.utcnow()` 在 Python 3.12 已弃用，应迁移 `now(timezone.utc)`
b-2	`auth.py:31,89`	登录端点无速率限制，无暴力破解防护
b-3	`miniapp_orders.py:211-214`	核销码指纹复用 jwt_secret 作为 HMAC 密钥
b-4	`auth.py:89-114`	密码登录未检查用户 status 是否 active
b-5	6+ 文件	`_require_admin` 重复定义，实现不一致（见 B-3）

数据库 Minor（4 项）

#	位置	问题
d-1	001 baseline	`health_records.blood_oxygen/heart_rate` 缺业务合理性 CHECK
d-2	044 迁移	`kora_route_waypoints/segments` 缺 `updated_at`
d-3	008 迁移	`refund_policies` 种子数据插入保护不完善
d-4	001 baseline	id 类型混用（integer vs bigint），status 字段长度不统一

前端(C端) Minor（3 项）

#	位置	问题
f-1	`auth.ts:87-107`	login 函数无 token 过期时间管理
f-2	`app.ts:9-12`	onLaunch 无登录态预检
f-3	多处 services	错误处理策略不一致（throw vs return 空值 vs return null）

B端H5 Minor（3 项）

#	位置	问题
w-1	`App.tsx:38-45`	React 组件内直接读 `window.location`，绕过 Router
w-2	`Network.ts:51-58`	401 时 `window.location.reload()` 强刷，体验粗暴
w-3	`Network.ts`	无 500/502/503 等服务端错误处理

六、设计亮点（值得保持）

后端

token_version 即时吊销: 每次请求校验 JWT 中的 token_version 与数据库比对，冻结用户即时生效
bcrypt + rehash-on-verify: 新密码 cost=12，旧格式透明升级
订单行锁 (FOR UPDATE): 支付/取消/退款操作使用行级锁防并发
is_test 全链路隔离: 测试数据通过布尔列 + 部分索引与生产隔离
迁移幂等: IF NOT EXISTS / ADD COLUMN IF NOT EXISTS 全覆盖
80+ 个认证端点零遗漏: 逐个审查全部 51 个路由文件，所有写入端点均有认证

数据库

026 核销码迁移: DROP + 重建逻辑清晰，partial unique index 设计精妙
033 分销域: 全事务包裹，索引/COMMENT/配置键齐全
044 转山路线: 文档化程度极高，回滚 SQL/验证 SQL 齐全
76 张表 110+ 外键: 以 users 和 merchants 为核心辐射，关系完整

前端

mockMode 双重守卫: 全局开关 + 调用方 mock 回调，生产包 mockMode=false
零 wx.cloud.callFunction: 全部走 HTTP，与云函数完全解耦
OpenAPI 类型自动生成: npm run gen:api 保障前后端契约一致
诚实降级: 大部分页面接口失败返回空态而非假数据

七、修复优先级路线图

P0 — 立即（3 项，安全底线）

config.py: APP_ENV 和 JWT_SECRET 生产环境校验（fail-closed）
main.py: 生产环境拒绝 CORS * 通配符
前端 request.ts: 401 拦截清 token + 跳登录页

P1 — 一周内（功能正确性）

request.ts: unwrap 兼容 {ok,data} 信封
request.ts: 弱网自动重试 1 次
前端 uploadPilgrimageImage: 修复 API_BASE_URL 拼接
admin.py: 移除 _require_admin 的 phone 前置检查
统一 _require_admin 实现（消除重复）
credit_journal.direction: 补 CHECK 约束
guest-archive.ts: 接入真实 API 或诚实降级

P2 — 两周内（性能与质量）

数据库补充索引（D-2 清单）
user_wallets.balance: 补非负 CHECK
health_records: 补生理数据范围 CHECK
b-workbench FeatureFlags: 实现后端接口
b-workbench 登录: 实现微信正式登录（WIP-181）
scene-cards.ts: 修正面向用户的文案
清理废弃表（package_items/settlement_ledger/package_order_events）

P3 — 持续

批量清理存量弱哈希密码
登录端点加速率限制
后端日志体系统一
全局异常处理中间件
Dockerfile 切换非 root 用户

八、测试覆盖率现状

层	现有测试	缺口
后端（287 端点）	0	100% 无覆盖
数据库（76 表）	0	迁移无回滚测试
前端 C端（120 页）	0	无自动化测试
B端 H5（23 路由）	0	无自动化测试
契约测试	OpenAPI 类型生成	但无运行时校验

建议先补的三类测试（投入产出比最高）：

订单状态机条件更新的并发测试
认证链路测试（JWT 签发/验证/吊销/token_version）
前后端契约回归测试

*注：本报告基于远端最新代码（a1f80bf），工作区路径 /Users/yujiaxinmeiti/Desktop/kailash-worktrees/xiaoyu-real-gz5gz9/*