向AssppWeb贡献代码：编码规范、导入顺序与PR审查规则的完整开发者路线图

向AssppWeb贡献代码编码规范、导入顺序与PR审查规则的完整开发者路线图【免费下载链接】AssppWeb项目地址: https://gitcode.com/gh_mirrors/as/AssppWebAssppWeb 是一款在 App Store 之外获取并安装 iOS 应用的网页工具支持 Apple ID 登录、应用搜索、许可证获取与 IPA 编译安装。本文是面向新手贡献者的完整路线图先讲清项目结构与 TypeScript 编码规范再拆解九级导入顺序规则最后汇总 PR 审查时的每一条硬性检查项帮助你的代码一次性通过评审 快速上手克隆仓库并了解项目结构如果你是第一次参与开发先克隆仓库git clone https://gitcode.com/gh_mirrors/as/AssppWeb项目采用多端单体仓库 Docker 多阶段构建核心目录如下目录职责backend/Node.js/Express 服务端TypeScriptESM提供 Wisp 盲代理与 Bag 代理frontend/React 19 Vite Tailwind CSS 4 单页应用e2e/Playwright 端到端测试pnpmcloudflare/Cloudflare Workers Containers 部署入口references/ApplePackage/Swift 参考实现是 Apple 协议行为的唯一事实来源构建与运行入口见 compose.yml 和 Dockerfile前后端依赖与脚本分别在 frontend/package.json 与 backend/package.json 中声明。 最重要的架构约束零信任。服务端是一个盲 TCP 代理永远看不到任何 Apple 凭证。任何 PR 都不得破坏这条边界——协议改动前务必对照 Swift 参考实现。TypeScript 编码规范4 条基本约定项目所有代码使用 TypeScript规范统一而克制规范项要求示例缩进2 空格const x 1分号必须保留const x 1;引号字符串统一单引号hello命名类型/接口用 PascalCase变量/函数用 camelCaseSoftware/accountHash()前后端都遵循这套风格后端是 ESM 模块backend/package.json 中type: module用tsx跑开发、tsc做生产构建前端由 Vite 驱动。错误处理风格同样固定提前 return 减少嵌套、异步操作一律try/catch、Express 统一错误中间件集中处理。导入顺序规则九级分类法逐层解析这是 AssppWeb 最容易被 PR 审查驳回的细节。每个前端文件顶部的 import 必须严格按以下 9 级顺序排列级别分类典型示例1React / 库导入useState、useNavigate、useTranslation2布局组件PageContainer3通用组件AppIcon、Alert、Spinner、Modal、CountrySelect4同功能目录内的兄弟组件Download/中的DownloadItem5Hooks / 状态存储useAccounts、useSettingsStore6Apple 协议 / API 模块authenticate、purchaseApp、apiPost7工具函数accountHash、getErrorMessage8配置countryCodeMap、storeIdToCountry9类型导入永远最后type Software审查中高频出现的三类错误提交前请自查❌ 把 Hooks/Stores 写到了布局/通用组件之前❌ 把配置写到了工具函数之前❌ 类型导入夹在中间而不是放在最后PR 审查规则6 类硬性检查项逐条解读以下规则的目标是防止代码库在 PR 合并后腐化每一条都会在审查中被逐文件核对。导入顺序验证合并任何前端 PR 前审查者会检查每一个被修改文件的 import 是否完全符合上述九级顺序。transition-colors 使用政策transition-colors加在静态容器上会导致深色模式加载时可见的闪色。只允许用在交互元素上按钮、链接、表单输入、导航项。卡片容器、Alert、Badge、Modal、空状态占位等一律禁用唯一例外是侧边栏等布局骨架可保留transition-colors duration-200以获得主题切换动画。共享图标规范所有导航与主题图标统一放在 frontend/src/components/common/icons.tsx禁止在组件内重复内联 SVG 图标。深色模式颜色配对明暗两套色值必须成对出现标准配对为主文本text-gray-900 dark:text-white、卡片bg-white dark:bg-gray-900、页面bg-gray-50 dark:bg-gray-950、卡片边框border-gray-200 dark:border-gray-800。防代码重复同一 UI 模式出现 3 次以上必须抽取到components/common/现有共享组件Alert、Modal、Spinner、CountrySelect、AppIcon、Badge、ProgressBar、icons。新增共享组件后记得同步更新 AGENTS.md。带鉴权的 API 下载设置了ACCESS_PASSWORD时a href或window.open访问/api/会因缺少X-Access-Token头返回 401。正确做法是用fetch()authHeaders()下载后通过 blob URL 触发保存仅/auth/*、/install/*等公开路由允许普通链接。测试与验证提交 PR 前的完整流程单元测试后端与前端均使用 Vitest分别在 Node 和 jsdom 环境下运行cd backend npx vitest run cd frontend npx vitest runE2E 测试Playwright端到端测试覆盖 Wisp 代理、账户添加、搜索映射、下载 API 等核心链路cd e2e pnpm test # 本地运行需 Docker 起在 8080 端口 bash e2e/docker-test.sh # 完整流程构建 测试 零信任校验⚠️ 测试凭据TEST_EMAIL、TEST_PASSWORD等只放在环境变量中严禁提交进仓库。提交 PR 前的最终自检清单缩进 2 空格、分号、单引号、命名规范全部达标每个被改动文件都符合九级导入顺序静态容器上没有transition-colors明暗色值成对、图标来自共享icons.tsx重复模式已抽取到components/common/后端单元测试 前端单元测试全部通过没有改动破坏服务端永不见 Apple 凭证的零信任边界新增共享组件已同步更新 AGENTS.md祝你的第一个 PR 顺利合并欢迎成为 AssppWeb 的共建者 【免费下载链接】AssppWeb项目地址: https://gitcode.com/gh_mirrors/as/AssppWeb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考